js_run_binary.md

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")

js_run_binary

js_run_binary(name, tool, env, srcs, outs, out_dirs, args, chdir, stdout, stderr, exit_code_out,
              silent_on_success, copy_srcs_to_bin, include_transitive_sources, include_declarations,
              include_npm_linked_packages, log_level, mnemonic, progress_message,
              execution_requirements, stamp, patch_node_fs, kwargs)

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.

PARAMETERS

Name	Description	Default Value
name	Target name	none
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.	none
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 binary or test in, relative to the workspace. This overrides the chdir value if set on the js_binary tool target. By default, Bazel always runs in the workspace root. To run in the directory containing the js_run_binary under the source tree, use chdir = package_name() (or if you're in a macro, use native.package_name()). To run in the output directory where the js_run_binary writes outputs, use chdir = "$(RULEDIR)" 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.	None
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	None
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	None
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	None
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.	True
copy_srcs_to_bin	When True, all srcs files are copied to the output tree that are not already there.	True
include_transitive_sources	see js_filegroup documentation	True
include_declarations	see js_filegroup documentation	False
include_npm_linked_packages	see js_filegroup documentation	True
log_level	Set the logging level of the js_binary tool. This overrides the log level set on the js_binary tool target.	None
mnemonic	A one-word description of the action, for example, CppCompile or GoLink.	"JsRunBinary"
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.	None
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.	None
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-typed stamp 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.	0
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.	True
kwargs	Additional arguments	none