docs/Toolchains.md - third_party/github/bazel-contrib/rules_nodejs - Git at Google

 <!-- *********************
   DO NOT EDIT THIS FILE
   It is a generated build output from Stardoc.
   Instead you must edit the .bzl file where the rules are declared,
   or possibly a markdown file next to the .bzl file
  ********************* -->
 # Toolchains

 API docs for [Toolchain](https://docs.bazel.build/versions/main/toolchains.html) 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.

 ## Node.js binary for the target platform

 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.

 ## Cross-compilation

 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](https://github.com/nodejs/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 https://github.com/bazelbuild/rules_nodejs/issues/506 for updates on support for node-gyp cross-compilation.

 ## Registering a custom toolchain

 To run a custom toolchain (i.e., to run a node binary not supported by the built-in toolchains), you'll need four things:

 1) 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_cc` build rule](https://bazelbuild.github.io/rules_foreign_cc/) will do nicely).
 2) A [`node_toolchain` rule](Core.html#node_toolchain) which depends on your binary defined in step 1 as its `target_tool`.
 3) A [`toolchain` rule](https://bazel.build/reference/be/platform#toolchain) that depends on your `node_toolchain` rule defined in step 2 as its `toolchain`
    and on `@rules_nodejs//nodejs:toolchain_type` as its `toolchain_type`. Make sure to define appropriate platform restrictions as described in the
    documentation for the `toolchain` rule.
 4) A call to [the `register_toolchains` function](https://bazel.build/rules/lib/globals#register_toolchains) in your `WORKSPACE`
    that refers to the `toolchain` rule defined in step 3.

 Examples of steps 2-4 can be found in the [documentation for `node_toolchain`](Core.html#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:

 2) A `node_toolchain` rule which has the path of the system binary as its `target_tool_path`


 ## cypress_toolchain

 **USAGE**

 <pre>
 cypress_toolchain(<a href="#cypress_toolchain-name">name</a>, <a href="#cypress_toolchain-cypress_bin">cypress_bin</a>, <a href="#cypress_toolchain-cypress_bin_path">cypress_bin_path</a>, <a href="#cypress_toolchain-cypress_files">cypress_files</a>)
 </pre>

 Defines a cypress toolchain.

 For usage see https://docs.bazel.build/versions/main/toolchains.html#defining-toolchains.


 **ATTRIBUTES**


 <h4 id="cypress_toolchain-name">name</h4>

 (*<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory*): A unique name for this target.


 <h4 id="cypress_toolchain-cypress_bin">cypress_bin</h4>

 (*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): A hermetically downloaded cypress executable binary for the target platform.

 Defaults to `None`

 <h4 id="cypress_toolchain-cypress_bin_path">cypress_bin_path</h4>

 (*String*): Path to an existing cypress executable for the target platform.

 Defaults to `""`

 <h4 id="cypress_toolchain-cypress_files">cypress_files</h4>

 (*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>*): 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`


 ## cypress_repositories

 **USAGE**

 <pre>
 cypress_repositories(<a href="#cypress_repositories-name">name</a>, <a href="#cypress_repositories-version">version</a>, <a href="#cypress_repositories-linux_urls">linux_urls</a>, <a href="#cypress_repositories-linux_sha256">linux_sha256</a>, <a href="#cypress_repositories-darwin_urls">darwin_urls</a>, <a href="#cypress_repositories-darwin_sha256">darwin_sha256</a>,
                      <a href="#cypress_repositories-darwin_arm64_urls">darwin_arm64_urls</a>, <a href="#cypress_repositories-darwin_arm64_sha256">darwin_arm64_sha256</a>, <a href="#cypress_repositories-windows_urls">windows_urls</a>, <a href="#cypress_repositories-windows_sha256">windows_sha256</a>)
 </pre>

     Repository rule used to install cypress binary.

 **PARAMETERS**


 <h4 id="cypress_repositories-name">name</h4>

 Name of the external workspace where the cypress binary lives


 <h4 id="cypress_repositories-version">version</h4>

 Version of cypress binary to use. Should match package.json


 <h4 id="cypress_repositories-linux_urls">linux_urls</h4>

 (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 `[]`

 <h4 id="cypress_repositories-linux_sha256">linux_sha256</h4>

 (Optional) SHA-256 of the linux cypress binary

 Defaults to `""`

 <h4 id="cypress_repositories-darwin_urls">darwin_urls</h4>

 (Optional) URLs at which the cypress binary for darwin can be downloaded. If omitted, https://cdn.cypress.io/desktop will be used.

 Defaults to `[]`

 <h4 id="cypress_repositories-darwin_sha256">darwin_sha256</h4>

 (Optional) SHA-256 of the darwin cypress binary

 Defaults to `""`

 <h4 id="cypress_repositories-darwin_arm64_urls">darwin_arm64_urls</h4>

 (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 `[]`

 <h4 id="cypress_repositories-darwin_arm64_sha256">darwin_arm64_sha256</h4>

 (Optional) SHA-256 of the darwin arm64 cypress binary

 Defaults to `""`

 <h4 id="cypress_repositories-windows_urls">windows_urls</h4>

 (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 `[]`

 <h4 id="cypress_repositories-windows_sha256">windows_sha256</h4>

 (Optional) SHA-256 of the windows cypress binary

 Defaults to `""`
	<!-- *********************
	DO NOT EDIT THIS FILE
	It is a generated build output from Stardoc.
	Instead you must edit the .bzl file where the rules are declared,
	or possibly a markdown file next to the .bzl file
	********************* -->
	# Toolchains

	API docs for [Toolchain](https://docs.bazel.build/versions/main/toolchains.html) 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.

	## Node.js binary for the target platform

	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.

	## Cross-compilation

	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](https://github.com/nodejs/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 https://github.com/bazelbuild/rules_nodejs/issues/506 for updates on support for node-gyp cross-compilation.

	## Registering a custom toolchain

	To run a custom toolchain (i.e., to run a node binary not supported by the built-in toolchains), you'll need four things:

	1) 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_cc` build rule](https://bazelbuild.github.io/rules_foreign_cc/) will do nicely).
	2) A [`node_toolchain` rule](Core.html#node_toolchain) which depends on your binary defined in step 1 as its `target_tool`.
	3) A [`toolchain` rule](https://bazel.build/reference/be/platform#toolchain) that depends on your `node_toolchain` rule defined in step 2 as its `toolchain`
	and on `@rules_nodejs//nodejs:toolchain_type` as its `toolchain_type`. Make sure to define appropriate platform restrictions as described in the
	documentation for the `toolchain` rule.
	4) A call to [the `register_toolchains` function](https://bazel.build/rules/lib/globals#register_toolchains) in your `WORKSPACE`
	that refers to the `toolchain` rule defined in step 3.

	Examples of steps 2-4 can be found in the [documentation for `node_toolchain`](Core.html#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:

	2) A `node_toolchain` rule which has the path of the system binary as its `target_tool_path`


	## cypress_toolchain

	USAGE

	<pre>
	cypress_toolchain(<a href="#cypress_toolchain-name">name</a>, <a href="#cypress_toolchain-cypress_bin">cypress_bin</a>, <a href="#cypress_toolchain-cypress_bin_path">cypress_bin_path</a>, <a href="#cypress_toolchain-cypress_files">cypress_files</a>)
	</pre>

	Defines a cypress toolchain.

	For usage see https://docs.bazel.build/versions/main/toolchains.html#defining-toolchains.


	ATTRIBUTES


	<h4 id="cypress_toolchain-name">name</h4>

	(<a href="https://bazel.build/docs/build-ref.html#name">Name</a>, mandatory): A unique name for this target.


	<h4 id="cypress_toolchain-cypress_bin">cypress_bin</h4>

	(<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>): A hermetically downloaded cypress executable binary for the target platform.

	Defaults to `None`

	<h4 id="cypress_toolchain-cypress_bin_path">cypress_bin_path</h4>

	(String): Path to an existing cypress executable for the target platform.

	Defaults to `""`

	<h4 id="cypress_toolchain-cypress_files">cypress_files</h4>

	(<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>): 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`


	## cypress_repositories

	USAGE

	<pre>
	cypress_repositories(<a href="#cypress_repositories-name">name</a>, <a href="#cypress_repositories-version">version</a>, <a href="#cypress_repositories-linux_urls">linux_urls</a>, <a href="#cypress_repositories-linux_sha256">linux_sha256</a>, <a href="#cypress_repositories-darwin_urls">darwin_urls</a>, <a href="#cypress_repositories-darwin_sha256">darwin_sha256</a>,
	<a href="#cypress_repositories-darwin_arm64_urls">darwin_arm64_urls</a>, <a href="#cypress_repositories-darwin_arm64_sha256">darwin_arm64_sha256</a>, <a href="#cypress_repositories-windows_urls">windows_urls</a>, <a href="#cypress_repositories-windows_sha256">windows_sha256</a>)
	</pre>

	Repository rule used to install cypress binary.

	PARAMETERS


	<h4 id="cypress_repositories-name">name</h4>

	Name of the external workspace where the cypress binary lives



	<h4 id="cypress_repositories-version">version</h4>

	Version of cypress binary to use. Should match package.json



	<h4 id="cypress_repositories-linux_urls">linux_urls</h4>

	(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 `[]`

	<h4 id="cypress_repositories-linux_sha256">linux_sha256</h4>

	(Optional) SHA-256 of the linux cypress binary

	Defaults to `""`

	<h4 id="cypress_repositories-darwin_urls">darwin_urls</h4>

	(Optional) URLs at which the cypress binary for darwin can be downloaded. If omitted, https://cdn.cypress.io/desktop will be used.

	Defaults to `[]`

	<h4 id="cypress_repositories-darwin_sha256">darwin_sha256</h4>

	(Optional) SHA-256 of the darwin cypress binary

	Defaults to `""`

	<h4 id="cypress_repositories-darwin_arm64_urls">darwin_arm64_urls</h4>

	(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 `[]`

	<h4 id="cypress_repositories-darwin_arm64_sha256">darwin_arm64_sha256</h4>

	(Optional) SHA-256 of the darwin arm64 cypress binary

	Defaults to `""`

	<h4 id="cypress_repositories-windows_urls">windows_urls</h4>

	(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 `[]`

	<h4 id="cypress_repositories-windows_sha256">windows_sha256</h4>

	(Optional) SHA-256 of the windows cypress binary

	Defaults to `""`