runfiles libraries: fix tests and comments
- Update all runfiles libraries to have the same
header comment format, including the build rule
to depend on the namespace / header / module to
import
- Fix runfiles_test.cc to include the right files
(recent refactoring commit has split
src/main/cpp/util/path.cc from
file_[platform].cc)
- Change exported variable
_rlocation_isabs_pattern in runfiles.bash to be
upper-case, so it is visibly a variable and not
a function.
See https://github.com/bazelbuild/bazel/issues/4460
Change-Id: I17e18308506ab9f5c9f410ef6bc6b9df912d42a9
Closes #5481.
Change-Id: I17e18308506ab9f5c9f410ef6bc6b9df912d42a9
PiperOrigin-RevId: 202291629
diff --git a/tools/cpp/runfiles/runfiles.h b/tools/cpp/runfiles/runfiles.h
index b2bfe30..cfb1f30 100644
--- a/tools/cpp/runfiles/runfiles.h
+++ b/tools/cpp/runfiles/runfiles.h
@@ -14,30 +14,39 @@
// Runfiles lookup library for Bazel-built C++ binaries and tests.
//
-// Usage:
+// USAGE:
+// 1. Depend on this runfiles library from your build rule:
//
-// #include "tools/cpp/runfiles/runfiles.h"
+// cc_binary(
+// name = "my_binary",
+// ...
+// deps = ["@bazel_tools//tools/cpp/runfiles"],
+// )
//
-// using bazel::tools::cpp::runfiles::Runfiles;
+// 2. Include the runfiles library.
//
-// int main(int argc, char** argv) {
-// std::string error;
-// std::unique_ptr<Runfiles> runfiles(Runfiles::Create(argv[0], &error));
-// if (runfiles == nullptr) {
-// ... // error handling
-// }
-// std::string path = runfiles->Rlocation("io_bazel/src/bazel");
-// if (!path.empty()) {
-// std::ifstream data(path);
-// if (data.is_open()) {
-// ... // use the runfile
+// #include "tools/cpp/runfiles/runfiles.h"
//
-// The code above creates a Runfiles object and retrieves a runfile path.
+// using bazel::tools::cpp::runfiles::Runfiles;
//
-// The Runfiles::Create function uses the runfiles manifest and the runfiles
-// directory from the RUNFILES_MANIFEST_FILE and RUNFILES_DIR environment
-// variables. If not present, the function looks for the manifest and directory
-// near argv[0], the path of the main program.
+// 3. Create a Runfiles object and use rlocation to look up runfile paths:
+//
+// int main(int argc, char** argv) {
+// std::string error;
+// std::unique_ptr<Runfiles> runfiles(Runfiles::Create(argv[0],
+// &error)); if (runfiles == nullptr) {
+// ... // error handling
+// }
+// std::string path =
+// runfiles->Rlocation("my_workspace/path/to/my/data.txt");
+// ...
+//
+// The code above creates a Runfiles object and retrieves a runfile path.
+//
+// The Runfiles::Create function uses the runfiles manifest and the
+// runfiles directory from the RUNFILES_MANIFEST_FILE and RUNFILES_DIR
+// environment variables. If not present, the function looks for the
+// manifest and directory near argv[0], the path of the main program.
//
// To start child processes that also need runfiles, you need to set the right
// environment variables for them:
