diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 6cde22d0be..d1caf57d3a 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -20,7 +20,6 @@ jobs: uses: bazel-contrib/.github/.github/workflows/bazel.yaml@v6 with: folders: '[".", "e2e/headers", "e2e/smoke", "e2e/nodejs_host", "e2e/conflicting_toolchains"]' - # stardoc generated docs fail on diff_test with Bazel 6.4.0 so don't test against it in root repository exclude: | [ {"bazelversion": "6.4.0", "os": "macos-latest"}, diff --git a/.github/workflows/update-nodejs-versions.yml b/.github/workflows/update-nodejs-versions.yml index c4d4dc8344..29492c6b28 100644 --- a/.github/workflows/update-nodejs-versions.yml +++ b/.github/workflows/update-nodejs-versions.yml @@ -28,11 +28,7 @@ jobs: with: node-version: "14.x" - uses: pnpm/action-setup@v4 - - name: Run update-nodejs-versions - run: | - npm run update-nodejs-versions - bazel run docs:update - + - run: npm run update-nodejs-versions - name: Create Pull Request uses: peter-evans/create-pull-request@v3 with: diff --git a/.prettierignore b/.prettierignore index 26a5be297f..bd5535a603 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,2 +1 @@ -docs/*.md pnpm-lock.yaml diff --git a/MODULE.bazel b/MODULE.bazel index 68049239cf..acaa2ef1d4 100644 --- a/MODULE.bazel +++ b/MODULE.bazel @@ -49,3 +49,5 @@ register_toolchains("@nodejs_toolchains//:darwin_arm64_toolchain") register_toolchains("@nodejs_toolchains//:windows_amd64_toolchain_target") register_toolchains("@nodejs_toolchains//:windows_amd64_toolchain") + +bazel_dep(name = "aspect_bazel_lib", version = "2.19.3", dev_dependency = True) diff --git a/README.md b/README.md index bbe4587b20..9fa13a9fae 100644 --- a/README.md +++ b/README.md @@ -19,5 +19,5 @@ See the 5.x branch for the prior state of the repo. ## Documentation -Comprehensive documentation for installing and using the rules, including generated API docs: +Comprehensive documentation for installing and using the rules: https://bazel-contrib.github.io/rules_nodejs/ diff --git a/WORKSPACE b/WORKSPACE index 13728f4bdb..43c6327019 100644 --- a/WORKSPACE +++ b/WORKSPACE @@ -73,27 +73,6 @@ load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace") bazel_skylib_workspace() -# Stardoc -load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories") - -stardoc_repositories() - -load("@rules_jvm_external//:repositories.bzl", "rules_jvm_external_deps") - -rules_jvm_external_deps() - -load("@rules_jvm_external//:setup.bzl", "rules_jvm_external_setup") - -rules_jvm_external_setup() - -load("@io_bazel_stardoc//:deps.bzl", "stardoc_external_deps") - -stardoc_external_deps() - -load("@stardoc_maven//:defs.bzl", stardoc_pinned_maven_install = "pinned_maven_install") - -stardoc_pinned_maven_install() - # Buildifier load("@buildifier_prebuilt//:deps.bzl", "buildifier_prebuilt_deps") diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel deleted file mode 100644 index bb6f2b63ff..0000000000 --- a/docs/BUILD.bazel +++ /dev/null @@ -1,63 +0,0 @@ -# Copyright 2017 The Bazel Authors. All rights reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -load("@bazel_skylib//rules:diff_test.bzl", "diff_test") -load("@bazel_skylib//rules:write_file.bzl", "write_file") -load("//tools/stardoc:index.bzl", "stardoc") - -stardoc( - name = "core", - bzl_library_target = "//nodejs:index.for_docs", -) - -_READMES = { - "Core": "//docs:core-docgen.md", -} - -[ - diff_test( - name = "check_" + k.lower(), - failure_message = "Please run: bazel run //docs:update", - file1 = k + ".md", - file2 = v, - ) - for [ - k, - v, - ] in _READMES.items() -] - -write_file( - name = "gen_update", - out = "update.sh", - content = [ - "#!/usr/bin/env bash", - "cd $BUILD_WORKSPACE_DIRECTORY", - ] + [ - "cp -fv bazel-bin/{1} docs/{0}.md".format( - k, - v.replace(":", "/"), - ) - for [ - k, - v, - ] in _READMES.items() - ], -) - -sh_binary( - name = "update", - srcs = ["update.sh"], - data = _READMES.values(), -) diff --git a/docs/Core.md b/docs/Core.md deleted file mode 100644 index a998810d4d..0000000000 --- a/docs/Core.md +++ /dev/null @@ -1,270 +0,0 @@ - -# rules_nodejs Bazel module - -Features: -- A [Toolchain](https://docs.bazel.build/versions/main/toolchains.html) - that fetches a hermetic copy of node and npm - independent of what's on the developer's machine. -- Core [Providers](https://docs.bazel.build/versions/main/skylark/rules.html#providers) to allow interop between JS rules. - -## UserBuildSettingInfo - -**USAGE** - -
-UserBuildSettingInfo(value)
-
- - - -**FIELDS** - -

value

- - - - - -## nodejs_repositories - -**USAGE** - -
-nodejs_repositories(name, node_download_auth, node_repositories, node_urls, node_version,
-                    node_version_from_nvmrc, include_headers, kwargs)
-
- -To be run in user's WORKSPACE to install rules_nodejs dependencies. - -This rule sets up node, npm, and npx. The versions of these tools can be specified in one of three ways - -### Simplest Usage - -Specify no explicit versions. This will download and use the latest Node.js that was available when the -version of rules_nodejs you're using was released. - -### Forced version(s) - -You can select the version of Node.js to download & use by specifying it when you call node_repositories, -using a value that matches a known version (see the default values) - -### Using a custom version - -You can pass in a custom list of Node.js repositories and URLs for node_repositories to use. - -#### Custom Node.js versions - -To specify custom Node.js versions, use the `node_repositories` attribute - -```python -nodejs_repositories( - node_repositories = { - "10.10.0-darwin_amd64": ("node-v10.10.0-darwin-x64.tar.gz", "node-v10.10.0-darwin-x64", "00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e"), - "10.10.0-linux_amd64": ("node-v10.10.0-linux-x64.tar.xz", "node-v10.10.0-linux-x64", "686d2c7b7698097e67bcd68edc3d6b5d28d81f62436c7cf9e7779d134ec262a9"), - "10.10.0-windows_amd64": ("node-v10.10.0-win-x64.zip", "node-v10.10.0-win-x64", "70c46e6451798be9d052b700ce5dadccb75cf917f6bf0d6ed54344c856830cfb"), - }, -) -``` - -These can be mapped to a custom download URL, using `node_urls` - -```python -nodejs_repositories( - node_version = "10.10.0", - node_repositories = {"10.10.0-darwin_amd64": ("node-v10.10.0-darwin-x64.tar.gz", "node-v10.10.0-darwin-x64", "00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e")}, - node_urls = ["https://mycorpproxy/mirror/node/v{version}/{filename}"], -) -``` - -A Mac client will try to download node from `https://mycorpproxy/mirror/node/v10.10.0/node-v10.10.0-darwin-x64.tar.gz` -and expect that file to have sha256sum `00b7a8426e076e9bf9d12ba2d571312e833fe962c70afafd10ad3682fdeeaa5e` - -See the [the repositories documentation](repositories.html) for how to use the resulting repositories. - -### Using a custom node.js. - -To avoid downloads, you can check in a vendored node.js binary or can build one from source. -See [toolchains](./toolchains.md). - - -**PARAMETERS** - - -

name

- -Unique name for the repository rule - - - -

node_download_auth

- -Auth to use for all url requests. - -Example: { "type": "basic", "login": "<UserName>", "password": "<Password>" } - -Defaults to `{}` - -

node_repositories

- -Custom list of node repositories to use - -A dictionary mapping Node.js versions to sets of hosts and their corresponding (filename, strip_prefix, sha256) tuples. -You should list a node binary for every platform users have, likely Mac, Windows, and Linux. - -By default, if this attribute has no items, we'll use a list of all public Node.js releases. - -Defaults to `{}` - -

node_urls

- -List of URLs to use to download Node.js. - -Each entry is a template for downloading a node distribution. - -The `{version}` parameter is substituted with the `node_version` attribute, -and `{filename}` with the matching entry from the `node_repositories` attribute. - -Defaults to `["https://nodejs.org/dist/v{version}/{filename}"]` - -

node_version

- -The specific version of Node.js to install - -Defaults to `"20.19.2"` - -

node_version_from_nvmrc

- -The .nvmrc file containing the version of Node.js to use. - -If set then the version found in the .nvmrc file is used instead of the one specified by node_version. - -Defaults to `None` - -

include_headers

- -Set headers field in NodeInfo provided by this toolchain. - -This setting creates a dependency on a c++ toolchain. - -Defaults to `False` - -

kwargs

- -Additional parameters - - - - -## nodejs_toolchain - -**USAGE** - -
-nodejs_toolchain(name, node, node_path, npm, npm_path, npm_srcs, headers, kwargs)
-
- -Defines a node toolchain for a platform. - -You can use this to refer to a vendored nodejs binary in your repository, -or even to compile nodejs from sources using rules_foreign_cc or other rules. - -First, in a BUILD.bazel file, create a nodejs_toolchain definition: - -```starlark -load("@rules_nodejs//nodejs:toolchain.bzl", "nodejs_toolchain") - -nodejs_toolchain( - name = "toolchain", - node = "//some/path/bin/node", -) -``` - -Next, declare which execution platforms or target platforms the toolchain should be selected for -based on constraints. - -```starlark -toolchain( - name = "my_nodejs", - exec_compatible_with = [ - "@platforms//os:linux", - "@platforms//cpu:x86_64", - ], - toolchain = ":toolchain", - toolchain_type = "@rules_nodejs//nodejs:toolchain_type", -) -``` - -See https://bazel.build/extending/toolchains#toolchain-resolution for more information on toolchain -resolution. - -Finally in your `WORKSPACE`, register it with `register_toolchains("//:my_nodejs")` - -For usage see https://docs.bazel.build/versions/main/toolchains.html#defining-toolchains. -You can use the `--toolchain_resolution_debug` flag to `bazel` to help diagnose which toolchain is selected. - - -**PARAMETERS** - - -

name

- -Unique name for this target - - - -

node

- -Node.js executable - -Defaults to `None` - -

node_path

- -Path to Node.js executable file - -This is typically an absolute path to a non-hermetic Node.js executable. - -Only one of `node` and `node_path` may be set. - -Defaults to `""` - -

npm

- -Npm JavaScript entry point - -Defaults to `None` - -

npm_path

- -Path to npm JavaScript entry point. - -This is typically an absolute path to a non-hermetic npm installation. - -Only one of `npm` and `npm_path` may be set. - -Defaults to `""` - -

npm_srcs

- -Additional source files required to run npm. - -Not necessary if specifying `npm_path` to a non-hermetic npm installation. - -Defaults to `[]` - -

headers

- -cc_library that contains the Node/v8 header files - -Defaults to `None` - -

kwargs

- -Additional parameters - - - - diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 8c0174266c..0000000000 --- a/docs/README.md +++ /dev/null @@ -1,14 +0,0 @@ -# Authoring the docsite - -The docsite is a mix of stardoc generated markdown and hand written markdown. -The files marked with -``` - - ``` - -Should be edited by modifying the docs in the source `.bzl` files. diff --git a/docs/index.md b/docs/index.md index f93d9cc552..0fe15fcf38 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,10 +8,7 @@ toc: true The `@rules_nodejs` Bazel module contains a toolchain that fetches a hermetic node and npm (independent of what's on the developer's machine). It is currently useful for Bazel Rules developers who want to make their own JavaScript support, and -is maintained by community volunteers from [Aspect](https://aspect.dev). - - [Install and setup](install.md) - - [Rules API](Core.md) - - [Toolchains](Toolchains.md) +is maintained by community volunteers from [Aspect](https://aspect.dev). - [Install and setup](install.md) - [Toolchains](Toolchains.md) ## Deprecated modules @@ -36,4 +33,3 @@ In many cases, there are trade-offs. We try not to make these decisions for you, The JS ecosystem is also full of false equivalence arguments. The first question we often get is "What's better, Webpack or Bazel?". This is understandable, since most JS tooling is forced to provide a single turn-key experience with an isolated ecosystem of plugins, and humans love a head-to-head competition. Instead Bazel just orchestrates calling these tools. - diff --git a/docs/install.md b/docs/install.md index 6491313495..8746c8e429 100644 --- a/docs/install.md +++ b/docs/install.md @@ -45,4 +45,3 @@ Specifying `node_urls` is optional. If omitted, the default values will be used. You can use your own Node.js binary rather than fetching from the internet. You could check in a binary file, or build Node.js from sources. -To use See [`nodejs_toolchain`](./Core.md#nodejs_toolchain) for docs. diff --git a/nodejs/BUILD.bazel b/nodejs/BUILD.bazel index e66eda2d1b..5278f960f1 100644 --- a/nodejs/BUILD.bazel +++ b/nodejs/BUILD.bazel @@ -1,4 +1,4 @@ -load("@bazel_skylib//:bzl_library.bzl", "bzl_library") +load("@aspect_bazel_lib//:bzl_library.bzl", "bzl_library") load("//nodejs/private:nodejs_toolchains_repo.bzl", "PLATFORMS") load("//nodejs/private:user_build_settings.bzl", "user_args") @@ -11,8 +11,11 @@ exports_files([ bzl_library( name = "index.for_docs", - srcs = glob(["*.bzl"]) + ["@bazel_tools//tools:bzl_srcs"], + srcs = glob(["*.bzl"]), deps = [ + "//nodejs:providers.bzl", + "//nodejs:repositories.bzl", + "//nodejs:toolchain.bzl", "//nodejs/private:bzl", "//nodejs/private/providers:bzl", "@bazel_skylib//lib:paths", diff --git a/nodejs/private/BUILD.bazel b/nodejs/private/BUILD.bazel index d87c26f227..0f3a96a020 100644 --- a/nodejs/private/BUILD.bazel +++ b/nodejs/private/BUILD.bazel @@ -1,4 +1,4 @@ -load("@bazel_skylib//:bzl_library.bzl", "bzl_library") +load("@aspect_bazel_lib//:bzl_library.bzl", "bzl_library") bzl_library( name = "bzl", diff --git a/nodejs/private/providers/BUILD.bazel b/nodejs/private/providers/BUILD.bazel index e609a263df..1296559711 100644 --- a/nodejs/private/providers/BUILD.bazel +++ b/nodejs/private/providers/BUILD.bazel @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -load("@bazel_skylib//:bzl_library.bzl", "bzl_library") +load("@aspect_bazel_lib//:bzl_library.bzl", "bzl_library") bzl_library( name = "bzl", diff --git a/repositories.bzl b/repositories.bzl index e3ee509872..5b75069dfc 100644 --- a/repositories.bzl +++ b/repositories.bzl @@ -37,17 +37,11 @@ def rules_nodejs_dev_dependencies(): urls = ["https://github.com/bazelbuild/bazel-skylib/releases/download/1.7.1/bazel-skylib-1.7.1.tar.gz"], ) - http_archive( - name = "io_bazel_stardoc", - sha256 = "fabb280f6c92a3b55eed89a918ca91e39fb733373c81e87a18ae9e33e75023ec", - urls = ["https://github.com/bazelbuild/stardoc/releases/download/0.7.1/stardoc-0.7.1.tar.gz"], - ) - http_archive( name = "aspect_bazel_lib", - sha256 = "40ba9d0f62deac87195723f0f891a9803a7b720d7b89206981ca5570ef9df15b", - strip_prefix = "bazel-lib-2.14.0", - url = "https://github.com/aspect-build/bazel-lib/releases/download/v2.14.0/bazel-lib-v2.14.0.tar.gz", + sha256 = "db7da732db4dece80cd6d368220930950c9306ff356ebba46498fe64e65a3945", + strip_prefix = "bazel-lib-2.19.3", + url = "https://github.com/bazel-contrib/bazel-lib/releases/download/v2.19.3/bazel-lib-v2.19.3.tar.gz", ) http_archive( diff --git a/tools/stardoc/BUILD.bazel b/tools/stardoc/BUILD.bazel deleted file mode 100644 index 801dc3c4ef..0000000000 --- a/tools/stardoc/BUILD.bazel +++ /dev/null @@ -1 +0,0 @@ -exports_files(glob(["templates/*.vm"])) diff --git a/tools/stardoc/index.bzl b/tools/stardoc/index.bzl deleted file mode 100644 index 7c11e3ea52..0000000000 --- a/tools/stardoc/index.bzl +++ /dev/null @@ -1,16 +0,0 @@ -"Wrap stardoc to set our repo-wide defaults" - -load("@aspect_bazel_lib//lib:docs.bzl", _stardoc = "stardoc_with_diff_test") - -_PKG = "@rules_nodejs//tools/stardoc" - -def stardoc(name, **kwargs): - _stardoc( - name = name, - aspect_template = _PKG + ":templates/aspect.vm", - header_template = _PKG + ":templates/header.vm", - func_template = _PKG + ":templates/func.vm", - provider_template = _PKG + ":templates/provider.vm", - rule_template = _PKG + ":templates/rule.vm", - **kwargs - ) diff --git a/tools/stardoc/templates/README.md b/tools/stardoc/templates/README.md deleted file mode 100644 index b8b2b0b7b2..0000000000 --- a/tools/stardoc/templates/README.md +++ /dev/null @@ -1,2 +0,0 @@ -We have our own stardoc templates as a workaround for -https://github.com/bazelbuild/skydoc/issues/216 diff --git a/tools/stardoc/templates/aspect.vm b/tools/stardoc/templates/aspect.vm deleted file mode 100644 index a9748011d9..0000000000 --- a/tools/stardoc/templates/aspect.vm +++ /dev/null @@ -1,33 +0,0 @@ -#[[##]]# ${aspectName} - -**USAGE** - -
-${util.aspectSummary($aspectName, $aspectInfo)}
-
- -$aspectInfo.getDocString() - -**ASPECT ATTRIBUTES** - -#if (!$aspectInfo.getAttributeList().isEmpty()) -#foreach ($aspectAttribute in $aspectInfo.getAspectAttributeList()) -

${aspectAttribute}

-#end -#end - -**ATTRIBUTES** - -#if (!$aspectInfo.getAttributeList().isEmpty()) -#foreach ($attribute in $aspectInfo.getAttributeList()) -

${attribute.name}

- -(*${util.attributeTypeString($attribute)}, {util.mandatoryString($attribute)}*) -#if(!$attribute.docString.isEmpty()) $attribute.docString.trim() #else - #end - -#if( !$attribute.defaultValue.isEmpty() ) -Defaults to `$attribute.defaultValue` -#end - -#end -#end diff --git a/tools/stardoc/templates/func.vm b/tools/stardoc/templates/func.vm deleted file mode 100644 index 74ee239356..0000000000 --- a/tools/stardoc/templates/func.vm +++ /dev/null @@ -1,26 +0,0 @@ -#[[##]]# ${funcInfo.functionName} - -**USAGE** - -
-${util.funcSummary($funcInfo)}
-
- -$funcInfo.docString - -**PARAMETERS** - -#if (!$funcInfo.getParameterList().isEmpty()) -#foreach ($param in $funcInfo.getParameterList()) - -

${param.name}

- -#if (!$param.docString.isEmpty()) -${util.htmlEscape($param.docString.trim())} -#end - -#if( !$param.defaultValue.isEmpty() ) -Defaults to `$param.defaultValue`#end - -#end -#end diff --git a/tools/stardoc/templates/header.vm b/tools/stardoc/templates/header.vm deleted file mode 100644 index 5eb774768e..0000000000 --- a/tools/stardoc/templates/header.vm +++ /dev/null @@ -1,7 +0,0 @@ - -${moduleDocstring} diff --git a/tools/stardoc/templates/provider.vm b/tools/stardoc/templates/provider.vm deleted file mode 100644 index 2c3f742208..0000000000 --- a/tools/stardoc/templates/provider.vm +++ /dev/null @@ -1,20 +0,0 @@ -#[[##]]# ${providerName} - -**USAGE** - -
-${util.providerSummary($providerName, $providerInfo)}
-
- -${providerInfo.docString} - -**FIELDS** - -#if (!$providerInfo.fieldInfoList.isEmpty()) -#foreach ($field in $providerInfo.fieldInfoList) -

${field.name}

- -#if(!$field.docString.isEmpty()) $field.docString.trim() #else - #end - -#end -#end diff --git a/tools/stardoc/templates/rule.vm b/tools/stardoc/templates/rule.vm deleted file mode 100644 index aee2b9853f..0000000000 --- a/tools/stardoc/templates/rule.vm +++ /dev/null @@ -1,28 +0,0 @@ -#[[##]]# ${ruleName} - -**USAGE** - -
-${util.ruleSummary($ruleName, $ruleInfo)}
-
- -$ruleInfo.docString - -**ATTRIBUTES** - -#if (!$ruleInfo.getAttributeList().isEmpty()) -#foreach ($attribute in $ruleInfo.getAttributeList()) - -

${attribute.name}

- -(*${util.attributeTypeString($attribute)}#if( $attribute.mandatory ), mandatory#end*)#if (!$attribute.docString.isEmpty()): ${attribute.docString.trim()}#end -#if (!$attribute.getProviderNameGroupList().isEmpty()) - The dependencies of this attribute must provide: ${util.attributeProviders($attribute)} -#end - -#if( !$attribute.defaultValue.isEmpty() ) - -Defaults to `$attribute.defaultValue`#end - -#end -#end