From 9af2a3305bc0871ee83da48afec4fb2e953a8d37 Mon Sep 17 00:00:00 2001 From: Cedric Barreteau Date: Fri, 29 Nov 2024 11:09:39 -0500 Subject: [PATCH] Improve documentation for string parameter macros - Split the section out of `build_rule.md` for accessibility - Add documentation for missing macro types - Add examples - Fix misleading statement in `cheatsheet.md` --- docs/concepts/build_rule.md | 37 +----- docs/concepts/string_parameter_macros.md | 144 +++++++++++++++++++++++ docs/users/cheatsheet.md | 3 +- 3 files changed, 149 insertions(+), 35 deletions(-) create mode 100644 docs/concepts/string_parameter_macros.md diff --git a/docs/concepts/build_rule.md b/docs/concepts/build_rule.md index 7149ad60fcd2a..f5165b1a24435 100644 --- a/docs/concepts/build_rule.md +++ b/docs/concepts/build_rule.md @@ -130,37 +130,6 @@ editing its source code. ## String parameter macros It is also possible to expand references to other rules within the `cmd`, using -builtin `string parameter macros`. All build rules expanded in the command are -automatically considered to be dependencies of the `genrule()`. - -Note that the paths returned by these macros are _relative_ paths. Using -relative paths ensures that your builds are _hermetic_, that is, they are -reproducible across different machine environments. - -`$(classpath //path/to:target)` - -Expands to the transitive classpath of the specified build rule, provided that -the rule has a Java classpath. If the rule does not have (or contribute to) a -classpath, then an exception is thrown and the build breaks. - -`$(exe //path/to:target)` - -Expands a build rule that results in an executable to the commands necessary to -run that executable. For example, a `java_binary()` might expand to a call to -`java -jar path/to/target.jar` . Files that are executable (perhaps generated by -a `genrule()`) are also expanded. If the build rule does not generate an -executable output, then an exception is thrown and the build breaks. - -If the `$(exe my_dependency)` dependency should actually be built with the -target platform, use `$(exe_target my_dependency)` instead, which will stick to -the same platform as the target. - -`$(location //path/to:target)` - -Expands to the location of the output of the specified build rule. This means -that you can refer to the output without needing to be aware of how Buck is -storing data on the disk mid-build. - -``` - -``` +the builtin [`string parameter macros`](string_parameter_macros.md). All build +rules expanded in the command are automatically considered to be dependencies of +the `genrule()`. diff --git a/docs/concepts/string_parameter_macros.md b/docs/concepts/string_parameter_macros.md new file mode 100644 index 0000000000000..47968eb7cd0e3 --- /dev/null +++ b/docs/concepts/string_parameter_macros.md @@ -0,0 +1,144 @@ +--- +id: string_parameter_macros +title: String parameter macros +--- + +# String parameter macros + +Many rule attributes (the ones with type `attrs.arg`) support expanding +references to other rules using a mechanism called string parameter macros. All +expanded build rules are automatically added as dependencies. + +Note that the paths returned by these macros are _relative_ paths. Using +relative paths ensures that your builds are _hermetic_, that is, they are +reproducible across different machine environments. + +## `$(location //path/to:target)` + +Expands to the location of the output of the specified build rule. This means +that you can refer to the output without needing to be aware of how Buck is +storing data on the disk mid-build. + +For example: + +```starlark +cxx_test( + name = "my_test", + srcs = ["main.cpp"], + preprocessor_flags = ["-DTEST_DIR=$(location :test_dir)"], +) + +filegroup( + name = "test_dir", + srcs = [ + "test_files/foo.json", + "test_files/bar.toml", + ], +) +``` + +## `$(source relative/path/to/source)` + +Expands to the location of the specified source. The difference with using +`$(location path/to:export_file_target)` is that the path points to the file in +the source tree, rather than a copy or symlink in `buck-out`. + +For example: + +```starlark +cxx_test( + name = "my_test", + srcs = ["main.cpp"], + preprocessor_flags = ["-DMY_SOURCE_FILE=$(source path/to/my_source_file)"], +) +``` + +## `$(exe //path/to:target)` + +Expands a build rule that results in an executable to the commands necessary to +run that executable as part of the build. + +For example, a `java_binary()` might expand to a call to `java -jar +path/to/target.jar`. Files that are executable (perhaps generated by a +`genrule()`) are also expanded. + +If the build rule does not generate an executable output, then an exception is +thrown and the build breaks. + +If the `$(exe my_dependency)` dependency should actually be built with the +target platform, use `$(exe_target my_dependency)` instead, which will stick to +the same platform as the target. + +## `$(exe_target //path/to:target)` + +Identical to `$(exe //path/to:target)`, except that the target is built using +the target platform, rather than the execution platform. + +This is for example useful to get the paths to executables to be run as part of +tests. For example: + +```starlark +sh_test( + name = "my_test", + args = [ + "$(exe_target //path/to:target_to_test)", + ], + # `my_test.sh` takes a single argument, which is the path to an executable + # to test. + test = "my_test.sh", + visibility = ["//risk/tap_enricher/..."], +) +``` + +## `$(query_targets queryfunction(//path/to:target))` + +Runs a query on the given target and replaces the macro with the matching +targets. + +For example: + +```starlark +my_rule( + name = "example", + # Will be replaced by all dependencies of `some_target`. + foo = "$(query_targets deps(:some_target))" +) +``` + +## `$(query_outputs queryfunction(//path/to:target))` + +Runs a query on the given target and replaces the macro with the outputs of the +matching targets. + +For example: + +```starlark +my_rule( + name = "example", + # Will be replaced by the outputs of all dependencies of `some_target`. + foo = "$(query_outputs deps(:some_target))" +) +``` + +## `$(query_targets_and_outputs [separator] queryfunction(//path/to:target))` + +Runs a query on the given target and replaces the macro with matching targets +and their outputs, which are separated by an optional `separator` (defaults to a +space). + +For example: + +```starlark +my_rule( + name = "example", + # Will be replaced by the space-separated dependencies of `some_target`, as + # well as their outputs. + foo = "$(query_targets_and_outputs deps(:some_target))" +) +``` + +## `$(classpath //path/to:target)` + +Expands to the transitive classpath of the specified build rule, provided that +the rule has a Java classpath. If the rule does not have (or contribute to) a +classpath, then an exception is thrown and the build breaks. diff --git a/docs/users/cheatsheet.md b/docs/users/cheatsheet.md index 05d911ea7f7c5..b96845ec6ba40 100644 --- a/docs/users/cheatsheet.md +++ b/docs/users/cheatsheet.md @@ -84,7 +84,8 @@ $(query_outputs "queryfunction(//:foo)") $(query_targets_and_outputs [SEPARATOR] "queryfunction(//:foo)") ``` -Note, however, that the query macros are supported only for +Note, however, that the query macros are supported only for rule +attributes of type `attrs.arg`, such as [`genrule`](../../prelude/globals/#genrule) and [`apk_genrule`](../../prelude/globals/#apk_genrule).