Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add more info on custom toolchains #3396

Merged
merged 2 commits into from
Apr 11, 2022
Merged

Add more info on custom toolchains #3396

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3aa18b0
Update index.for_docs.bzl
mari-crl Apr 7, 2022
fa0bfa8
Use relative URL and update docs
mari-crl Apr 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 17 additions & 3 deletions docs/Toolchains.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ API docs for [Toolchain](https://docs.bazel.build/versions/main/toolchains.html)

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 you can also register your own toolchains. See [node_toolchain](./Core.md#node_toolchain)
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

Expand All @@ -34,10 +34,24 @@ The workaround is to perform the npm_install inside a docker container so that i

Follow https://github.com/bazelbuild/rules_nodejs/issues/506 for updates on support for node-gyp cross-compilation.

## node_toolchain
## Registering a custom toolchain

See <./Core.md#node_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`
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add an example of this. I can't find this documented elsewhere.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree an example would be nice, and if Cockroach wants to fund it then we could make the time to write one.



## cypress_toolchain
Expand Down
20 changes: 17 additions & 3 deletions toolchains/index.for_docs.bzl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ API docs for [Toolchain](https://docs.bazel.build/versions/main/toolchains.html)

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 you can also register your own toolchains. See [node_toolchain](./Core.md#node_toolchain)
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

Expand All @@ -28,10 +28,24 @@ The workaround is to perform the npm_install inside a docker container so that i

Follow https://github.com/bazelbuild/rules_nodejs/issues/506 for updates on support for node-gyp cross-compilation.

## node_toolchain
## Registering a custom toolchain

See <./Core.md#node_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`
"""

load("//toolchains/cypress:cypress_repositories.bzl", _cypress_repositories = "cypress_repositories")
Expand Down