API docs for Toolchain support.
When you call nodejs_register_toolchains() in your WORKSPACE file it will setup a node toolchain for executing tools on all currently supported platforms.
If you have an advanced use-case and want to use a version of node not supported by this repository, you can also register your own toolchains.
Sometimes your target platform (where your software runs) is different from the host platform (where you run Bazel) or execution platform (where Bazel actions run). The most common case is developing a docker image on MacOS, which will execute in a Linux container.
Our toolchain support is conditional on the execution platform, as it's meant for running nodejs tools during the build. It is not needed for this use case. Instead, simply select the nodejs you want to include in the runtime.
For example, rules_docker has a nodejs_image rule, which takes a node_repository_name attribute indicating
which nodejs binary you want to include in the image. nodejs_linux_amd64 is the value you'd use.
Bazel Toolchains are intended to support cross-compilation, e.g. building a linux binary from mac or windows. Most JavaScript use cases produce platform-independent code, but the exception is native modules which use node-gyp. Any native modules will still be fetched and built, by npm/yarn, for your host platform, so they will not work on the target platform. The workaround is to perform the npm_install inside a docker container so that it produces modules for the target platform.
Follow #506 for updates on support for node-gyp cross-compilation.
To run a custom toolchain (i.e., to run a node binary not supported by the built-in toolchains), you'll need four things:
- A rule which can build or load a node binary from your repository
(a checked-in binary or a build using a relevant
rules_foreign_ccbuild rule will do nicely). - A
node_toolchainrule which depends on your binary defined in step 1 as itstarget_tool. - A
toolchainrule that depends on yournode_toolchainrule defined in step 2 as itstoolchainand on@rules_nodejs//nodejs:toolchain_typeas itstoolchain_type. Make sure to define appropriate platform restrictions as described in the documentation for thetoolchainrule. - A call to the
register_toolchainsfunction in yourWORKSPACEthat refers to thetoolchainrule defined in step 3.
Examples of steps 2-4 can be found in the documentation for node_toolchain.
If necessary, you can substitute building the node binary as part of the build with using a locally installed version by skipping step 1 and replacing step 2 with:
- A
node_toolchainrule which has the path of the system binary as itstarget_tool_path
USAGE
cypress_toolchain(name, cypress_bin, cypress_bin_path, cypress_files)
Defines a cypress toolchain.
For usage see https://docs.bazel.build/versions/main/toolchains.html#defining-toolchains.
ATTRIBUTES
(Name, mandatory): A unique name for this target.
(Label): A hermetically downloaded cypress executable binary for the target platform.
Defaults to None
(String): Path to an existing cypress executable for the target platform.
Defaults to ""
(Label): A hermetically downloaded cypress filegroup of all cypress binary files for the target platform. Must be set when cypress_bin is set.
Defaults to None
USAGE
configure_esbuild_toolchains(name, platforms)
Configures esbuild toolchains for a list of supported platforms
PARAMETERS
unused
Defaults to ""
dict of platforms to configure toolchains for
Defaults to {}
USAGE
cypress_repositories(name, version, linux_urls, linux_sha256, darwin_urls, darwin_sha256, darwin_arm64_urls, darwin_arm64_sha256, windows_urls, windows_sha256)
Repository rule used to install cypress binary.
PARAMETERS
Name of the external workspace where the cypress binary lives
Version of cypress binary to use. Should match package.json
(Optional) URLs at which the cypress binary for linux distros of linux can be downloaded. If omitted, https://cdn.cypress.io/desktop will be used.
Defaults to []
(Optional) SHA-256 of the linux cypress binary
Defaults to ""
(Optional) URLs at which the cypress binary for darwin can be downloaded. If omitted, https://cdn.cypress.io/desktop will be used.
Defaults to []
(Optional) SHA-256 of the darwin cypress binary
Defaults to ""
(Optional) URLs at which the cypress binary for darwin arm64 can be downloaded. If omitted, https://cdn.cypress.io/desktop will be used (note: as of this writing (11/2021), Cypress does not have native arm64 builds, and this URL will link to the x86_64 build to run under Rosetta).
Defaults to []
(Optional) SHA-256 of the darwin arm64 cypress binary
Defaults to ""
(Optional) URLs at which the cypress binary for windows distros of linux can be downloaded. If omitted, https://cdn.cypress.io/desktop will be used.
Defaults to []
(Optional) SHA-256 of the windows cypress binary
Defaults to ""
USAGE
esbuild_repositories(npm_repository, name, npm_args, kwargs)
Helper for fetching and setting up the esbuild versions and toolchains
This uses Bazel's downloader (via http_archive) to fetch the esbuild package
from npm, separately from any npm_install/yarn_install in your WORKSPACE.
To configure where the download is from, you make a file containing a rewrite rule like
rewrite (registry.nodejs.org)/(.*) artifactory.build.internal.net/artifactory/$1/$2
You can find some documentation on the rewrite patterns in the Bazel sources: UrlRewriterConfig.java
Then use the --experimental_downloader_config Bazel option to point to your file.
For example if you created .bazel_downloader_config you might add to your .bazelrc file:
common --experimental_downloader_config=.bazel_downloader_config
PARAMETERS
the name of the repository where the @bazel/esbuild package is installed by npm_install or yarn_install.
currently unused
Defaults to ""
additional args to pass to the npm install rule
Defaults to []
additional named parameters to the npm_install rule