Runs a js_binary as a build action.
This macro wraps Aspect bazel-lib's run_binary (https://github.com/aspect-build/bazel-lib/blob/main/lib/run_binary.bzl) and adds attributes and features specific to rules_js's js_binary.
Load this with,
load("@aspect_rules_js//js:defs.bzl", "js_run_binary")
Macros and Functions
js_run_binary
Wrapper around @aspect_bazel_lib run_binary
that adds convienence attributes for using a js_binary
tool.
This rule does not require Bash native.genrule
.
Example usage (generated)
load("@aspect_rules_js//js:defs.bzl", "js_run_binary")
js_run_binary(
# Target name
name = "",
# The tool to run in the action
tool = None,
)
name
Target name
tool
The tool to run in the action.
Should be a js_binary
rule. Use Aspect bazel-lib's run_binary
(https://github.com/aspect-build/bazel-lib/blob/main/lib/run_binary.bzl)
for other *_binary rule types.
env
Environment variables of the action.
Subject to $(location)
and make variable expansion.
srcs
Additional inputs of the action.
These labels are available for $(location)
expansion in args
and env
.
outs
Output files generated by the action.
These labels are available for $(location)
expansion in args
and env
.
out_dirs
Output directories generated by the action.
These labels are not available for $(location)
expansion in args
and env
since
they are not pre-declared labels created via attr.output_list(). Output directories are
declared instead by ctx.actions.declare_directory
.
args
Command line arguments of the binary.
Subject to $(location)
and make variable expansion.
chdir
Working directory to run the build action in.
This overrides the chdir value if set on the js_binary
tool target.
By default, js_binary
tools run in the root of the output tree. For more context on why, please read the
aspect_rules_js README
https://github.com/aspect-build/rules_js/tree/dbb5af0d2a9a2bb50e4cf4a96dbc582b27567155#running-nodejs-programs.
To run in the directory containing the js_run_binary in the output tree, use
chdir = package_name()
(or if you're in a macro, use native.package_name()
).
WARNING: this will affect other paths passed to the program, either as arguments or in configuration files, which are workspace-relative.
You may need ../../
segments to re-relativize such paths to the new working directory.
stdout
set to capture the stdout of the binary to a file, which can later be used as an input to another target
subject to the same semantics as outs
stderr
set to capture the stderr of the binary to a file, which can later be used as an input to another target
subject to the same semantics as outs
exit_code_out
set to capture the exit code of the binary to a file, which can later be used as an input to another target
subject to the same semantics as outs
. Note that setting this will force the binary to exit 0.
If the binary creates outputs and these are declared, they must still be created
silent_on_success
produce no output on stdout nor stderr when program exits with status code 0.
This makes node binaries match the expected bazel paradigm.
use_execroot_entry_point
Use the entry_point
script of the js_binary
tool
that is in the execroot output tree
instead of the copy that is in runfiles.
Runfiles of tool
are all hoisted to srcs
of the underlying run_binary
so they are included as execroot
inputs to the action.
Using the entry point script that is in the execroot output tree means that there will be no conflicting
runfiles node_modules
in the node_modules resolution path which can confuse npm packages such as next and
react that don't like being resolved in multiple node_modules trees. This more closely emulates the
environment that tools such as Next.js see when they are run outside of Bazel.
When True, the js_binary
tool must have copy_data_to_bin
set to True (the default) so that all data files
needed by the binary are available in the execroot output tree. This requirement can be turned off with by
setting allow_execroot_entry_point_with_no_copy_data_to_bin
to True.
copy_srcs_to_bin
When True, all srcs files are copied to the output tree that are not already there.
include_transitive_sources
see js_filegroup
documentation
include_declarations
see js_filegroup
documentation
include_npm_linked_packages
see js_filegroup
documentation
log_level
Set the logging level of the js_binary
tool.
This overrides the log level set on the js_binary
tool target.
mnemonic
A one-word description of the action, for example, CppCompile or GoLink.
progress_message
Progress message to show to the user during the build, for example, "Compiling foo.cc to create foo.o". The message may contain %{label}, %{input}, or %{output} patterns, which are substituted with label string, first input, or output's path, respectively. Prefer to use patterns instead of static strings, because the former are more efficient.
execution_requirements
Information for scheduling the action.
For example,
execution_requirements = {
"no-cache": "1",
},
See https://docs.bazel.build/versions/main/be/common-definitions.html#common.tags for useful keys.
stamp
Whether to include build status files as inputs to the tool. Possible values:
stamp = 0 (default)
: Never include build status files as inputs to the tool. This gives good build result caching. Most tools don't use the status files, so including them in--stamp
builds makes those builds have many needless cache misses. (Note: this default is different from most rules with an integer-typedstamp
attribute.)stamp = 1
: Always include build status files as inputs to the tool, even in --nostamp builds. This setting should be avoided, since it is non-deterministic. It potentially causes remote cache misses for the target and any downstream actions that depend on the result.stamp = -1
: Inclusion of build status files as inputs is controlled by the --[no]stamp flag. Stamped targets are not rebuilt unless their dependencies change.
Default value is 0
since the majority of js_run_binary targets in a build graph typically do not use build
status files and including them for all js_run_binary actions whenever --stamp
is set would result in
invalidating the entire graph and would prevent cache hits. Stamping is typically done in terminal targets
when building release artifacts and stamp should typically be set explicitly in these targets to -1
so it
is enabled when the --stamp
flag is set.
When stamping is enabled, an additional two environment variables will be set for the action:
- BAZEL_STABLE_STATUS_FILE
- BAZEL_VOLATILE_STATUS_FILE
These files can be read and parsed by the action, for example to pass some values to a bundler.
patch_node_fs
Patch the to Node.js fs
API (https://nodejs.org/api/fs.html) for this node program
to prevent the program from following symlinks out of the execroot, runfiles and the sandbox.
When enabled, js_binary
patches the Node.js sync and async fs
API functions lstat
,
readlink
, realpath
, readdir
and opendir
so that the node program being
run cannot resolve symlinks out of the execroot and the runfiles tree. When in the sandbox,
these patches prevent the program being run from resolving symlinks out of the sandbox.
When disabled, node programs can leave the execroot, runfiles and sandbox by following symlinks which can lead to non-hermetic behavior.
allow_execroot_entry_point_with_no_copy_data_to_bin
Turn off validation that the js_binary
tool
has copy_data_to_bin
set to True when use_execroot_entry_point
is set to True.
See use_execroot_entry_point
doc for more info.
kwargs
Additional arguments