From f5217370e32178ace5e46ebd42a50d6f92121814 Mon Sep 17 00:00:00 2001 From: Alex Eagle Date: Thu, 10 Sep 2020 09:55:32 -0700 Subject: [PATCH] docs: update docs for release --- docs/Built-ins.html | 175 +++++++++++++++++++++++++++++++++++++++++-- docs/Built-ins.md | 170 +++++++++++++++++++++++++++++++++++++++-- docs/Rollup.html | 17 ++++- docs/Rollup.md | 17 ++++- docs/TypeScript.html | 29 ++++++- docs/TypeScript.md | 29 ++++++- docs/install.html | 4 +- docs/stamping.html | 10 +-- 8 files changed, 421 insertions(+), 30 deletions(-) diff --git a/docs/Built-ins.html b/docs/Built-ins.html index d5ea99779e..970adadca5 100755 --- a/docs/Built-ins.html +++ b/docs/Built-ins.html @@ -369,8 +369,6 @@

Manual install

the local path to a pre-installed NodeJS runtime. If set then also set node_version to the version that of node that is vendored. -Bazel will automatically turn on features such as --preserve-symlinks-main if they -are supported by the node version being used. Label optional @@ -436,8 +434,8 @@

nodejs_binary

Runs some JavaScript code in NodeJS.

-nodejs_binary(name, configuration_env_vars, data, default_env_vars, entry_point, node_modules,
-              templated_args)
+nodejs_binary(name, configuration_env_vars, data, default_env_vars, entry_point,
+              link_workspace_root, node_modules, templated_args)

ATTRIBUTES

@@ -573,6 +571,18 @@

nodejs_binary

+ + + link_workspace_root + + Link the workspace root to the bin_dir to support absolute requires like 'my_wksp/path/to/file'. +If source files need to be required then they can be copied to the bin_dir with copy_to_bin. + + Boolean + optional + + False + node_modules @@ -768,7 +778,7 @@

nodejs_test

 nodejs_test(name, configuration_env_vars, data, default_env_vars, entry_point, expected_exit_code,
-            node_modules, templated_args)
+            link_workspace_root, node_modules, templated_args)

ATTRIBUTES

@@ -915,6 +925,18 @@

nodejs_test

0 + + + link_workspace_root + + Link the workspace root to the bin_dir to support absolute requires like 'my_wksp/path/to/file'. +If source files need to be required then they can be copied to the bin_dir with copy_to_bin. + + Boolean + optional + + False + node_modules @@ -1945,6 +1967,130 @@

generated_file_test

+

js_library

+ +

Groups JavaScript code so that it can be depended on like an npm package.

+ +

Behavior

+ +

This rule doesn’t perform any build steps (“actions”) so it is similar to a filegroup. +However it produces several Bazel “Providers” for interop with other rules.

+ +
+

Compare this to pkg_npm which just produces a directory output, and therefore can’t expose individual +files to downstream targets and causes a cascading re-build of all transitive dependencies when any file +changes

+
+ +

These providers are:

+ + +

js_library also copies any source files into the bazel-out folder. +This is the same behavior as the copy_to_bin rule. +By copying the complete package to the output tree, we ensure that the linker (our npm link equivalent) +will make your source files available in the node_modules tree where resolvers expect them. +It also means you can have relative imports between the files +rather than being forced to use Bazel’s “Runfiles” semantics where any program might need a helper library +to resolve files between the logical union of the source tree and the output tree.

+ +

Usage

+ +

js_library is intended to be used internally within Bazel, such as between two libraries in your monorepo.

+ +
+

Compare this to pkg_npm which is intended to publish your code for external usage outside of Bazel, like +by publishing to npm or artifactory.

+
+ +

The typical example usage of js_library is to expose some sources with a package name:

+ +
ts_project(
+    name = "compile_ts",
+    srcs = glob(["*.ts"]),
+)
+
+js_library(
+    name = "my_pkg",
+    # Code that depends on this target can import from "@myco/mypkg"
+    package_name = "@myco/mypkg",
+    # Consumers might need fields like "main" or "typings"
+    srcs = ["package.json"],
+    # The .js and .d.ts outputs from above will be part of the package
+    deps = [":compile_ts"],
+)
+ +

To help work with “named AMD” modules as required by ts_devserver and other Google-style “concatjs” rules, +js_library has some undocumented advanced features you can find in the source code or in our examples. +These should not be considered a public API and aren’t subject to our usual support and semver guarantees.

+ +
+js_library(name, srcs, package_name, deps, kwargs)
+
+ +

PARAMETERS

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescriptionDefault
name + a name for the target + + +
srcs + the list of files that comprise the package + + [] +
package_name + the name it will be imported by. Should match the "name" field in the package.json file. + + None +
deps + other targets that provide JavaScript code + + [] +
kwargs + used for undocumented legacy features + + +
+

npm_package_bin

Run an arbitrary npm package binary (e.g. a program under node_modules/.bin/*) under Bazel.

@@ -1964,7 +2110,8 @@

npm_package_bin

https://docs.bazel.build/versions/master/skylark/macros.html#full-example

-npm_package_bin(tool, package, package_bin, data, outs, args, output_dir, kwargs)
+npm_package_bin(tool, package, package_bin, data, outs, args, output_dir, link_workspace_root,
+                kwargs)

PARAMETERS

@@ -2081,6 +2228,16 @@

npm_package_bin

False + + + link_workspace_root + + Link the workspace root to the bin_dir to support absolute requires like 'my_wksp/path/to/file'. + If source files need to be required then they can be copied to the bin_dir with copy_to_bin. + + + False + kwargs @@ -2816,6 +2973,12 @@

node_modules_aspect

  • check_bazel_version
  • copy_to_bin
  • generated_file_test
    • +
  • js_library + +
  • npm_package_bin
  • params_file
  • DeclarationInfo
    • diff --git a/docs/Built-ins.md b/docs/Built-ins.md index 4aa32686ef..11b8e1a939 100755 --- a/docs/Built-ins.md +++ b/docs/Built-ins.md @@ -236,8 +236,6 @@ a stronger guarantee of hermeticity which is required for remote execution. the local path to a pre-installed NodeJS runtime. If set then also set node_version to the version that of node that is vendored. -Bazel will automatically turn on features such as --preserve-symlinks-main if they -are supported by the node version being used. Label optional @@ -305,8 +303,8 @@ Each entry is a template, similar to the node_urls attribute, using Runs some JavaScript code in NodeJS. 
    -nodejs_binary(name, configuration_env_vars, data, default_env_vars, entry_point, node_modules,
-              templated_args)
+nodejs_binary(name, configuration_env_vars, data, default_env_vars, entry_point,
+              link_workspace_root, node_modules, templated_args)
    **ATTRIBUTES** @@ -442,6 +440,18 @@ nodejs_binary( + + + link_workspace_root + + Link the workspace root to the bin_dir to support absolute requires like 'my_wksp/path/to/file'. +If source files need to be required then they can be copied to the bin_dir with copy_to_bin. + + Boolean + optional + + False + node_modules @@ -642,7 +652,7 @@ remote debugger. 
     nodejs_test(name, configuration_env_vars, data, default_env_vars, entry_point, expected_exit_code,
-            node_modules, templated_args)
+            link_workspace_root, node_modules, templated_args)
    **ATTRIBUTES** @@ -789,6 +799,18 @@ nodejs_binary( 0 + + + link_workspace_root + + Link the workspace root to the bin_dir to support absolute requires like 'my_wksp/path/to/file'. +If source files need to be required then they can be copied to the bin_dir with copy_to_bin. + + Boolean + optional + + False + node_modules @@ -1848,6 +1870,131 @@ generated_file_test(name, filegroup. +However it produces several Bazel "Providers" for interop with other rules. + +> Compare this to pkg_npm which just produces a directory output, and therefore can't expose individual +> files to downstream targets and causes a cascading re-build of all transitive dependencies when any file +> changes + +These providers are: +- DeclarationInfo so this target can be a dependency of a TypeScript rule +- NpmPackageInfo so this target can interop with rules that expect third-party npm packages +- LinkablePackageInfo for use with our "linker" that makes this package importable (similar to npm link) +- JsModuleInfo so rules like bundlers can collect the transitive set of .js files + +js_library also copies any source files into the bazel-out folder. +This is the same behavior as the copy_to_bin rule. +By copying the complete package to the output tree, we ensure that the linker (our npm link equivalent) +will make your source files available in the node_modules tree where resolvers expect them. +It also means you can have relative imports between the files +rather than being forced to use Bazel's "Runfiles" semantics where any program might need a helper library +to resolve files between the logical union of the source tree and the output tree. + + +### Usage + +js_library is intended to be used internally within Bazel, such as between two libraries in your monorepo. + +> Compare this to pkg_npm which is intended to publish your code for external usage outside of Bazel, like +> by publishing to npm or artifactory. + +The typical example usage of js_library is to expose some sources with a package name: + +{% highlight python %} +ts_project( + name = "compile_ts", + srcs = glob(["*.ts"]), +) + +js_library( + name = "my_pkg", + # Code that depends on this target can import from "@myco/mypkg" + package_name = "@myco/mypkg", + # Consumers might need fields like "main" or "typings" + srcs = ["package.json"], + # The .js and .d.ts outputs from above will be part of the package + deps = [":compile_ts"], +) +{% endhighlight %} + +To help work with "named AMD" modules as required by ts_devserver and other Google-style "concatjs" rules, +js_library has some undocumented advanced features you can find in the source code or in our examples. +These should not be considered a public API and aren't subject to our usual support and semver guarantees. + + +
    +js_library(name, srcs, package_name, deps, kwargs)
+
    + +**PARAMETERS** + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameDescriptionDefault
    name + a name for the target + + +
    srcs + the list of files that comprise the package + + [] +
    package_name + the name it will be imported by. Should match the "name" field in the package.json file. + + None +
    deps + other targets that provide JavaScript code + + [] +
    kwargs + used for undocumented legacy features + + +
    + + + ## npm_package_bin Run an arbitrary npm package binary (e.g. a program under node_modules/.bin/*) under Bazel. @@ -1868,7 +2015,8 @@ https://docs.bazel.build/versions/master/skylark/macros.html#full-example 
    -npm_package_bin(tool, package, package_bin, data, outs, args, output_dir, kwargs)
+npm_package_bin(tool, package, package_bin, data, outs, args, output_dir, link_workspace_root,
+                kwargs)
    **PARAMETERS** @@ -1985,6 +2133,16 @@ npm_package_bin(tool, + link_workspace_root + + Link the workspace root to the bin_dir to support absolute requires like 'my_wksp/path/to/file'. + If source files need to be required then they can be copied to the bin_dir with copy_to_bin. + + + False + kwargs diff --git a/docs/Rollup.html b/docs/Rollup.html index 55834228f9..9d10637083 100755 --- a/docs/Rollup.html +++ b/docs/Rollup.html @@ -291,8 +291,9 @@

    rollup_bundle

    See the Rollup CLI reference

    -rollup_bundle(name, args, config_file, deps, entry_point, entry_points, format, node_context_data,
-              output_dir, rollup_bin, rollup_worker_bin, silent, sourcemap, srcs, supports_workers)
+rollup_bundle(name, args, config_file, deps, entry_point, entry_points, format, link_workspace_root,
+              node_context_data, output_dir, rollup_bin, rollup_worker_bin, silent, sourcemap, srcs,
+              supports_workers)

    ATTRIBUTES

    @@ -450,6 +451,18 @@

    rollup_bundle

    "esm" + + + link_workspace_root + + Link the workspace root to the bin_dir to support absolute requires like 'my_wksp/path/to/file'. +If source files need to be required then they can be copied to the bin_dir with copy_to_bin. + + Boolean + optional + + False + node_context_data diff --git a/docs/Rollup.md b/docs/Rollup.md index 27ed7aab46..c84f1f3abc 100755 --- a/docs/Rollup.md +++ b/docs/Rollup.md @@ -152,8 +152,9 @@ See [the Rollup CLI reference](https://rollupjs.org/guide/en/#command-line-refer 
    -rollup_bundle(name, args, config_file, deps, entry_point, entry_points, format, node_context_data,
-              output_dir, rollup_bin, rollup_worker_bin, silent, sourcemap, srcs, supports_workers)
+rollup_bundle(name, args, config_file, deps, entry_point, entry_points, format, link_workspace_root,
+              node_context_data, output_dir, rollup_bin, rollup_worker_bin, silent, sourcemap, srcs,
+              supports_workers)
    **ATTRIBUTES** @@ -311,6 +312,18 @@ Either this attribute or entry_point must be specified, but not bot "esm" + + + link_workspace_root + + Link the workspace root to the bin_dir to support absolute requires like 'my_wksp/path/to/file'. +If source files need to be required then they can be copied to the bin_dir with copy_to_bin. + + Boolean + optional + + False + node_context_data diff --git a/docs/TypeScript.html b/docs/TypeScript.html index a5a221b4f5..a0182ebc28 100755 --- a/docs/TypeScript.html +++ b/docs/TypeScript.html @@ -720,8 +720,9 @@

    ts_library

     ts_library(name, angular_assets, compiler, data, deps, devmode_module, devmode_target,
            expected_diagnostics, generate_externs, internal_testing_type_check_dependencies,
-           module_name, module_root, node_modules, prodmode_module, prodmode_target, runtime,
-           runtime_deps, srcs, supports_workers, tsconfig, tsickle_typed, use_angular_plugin)
+           link_workspace_root, module_name, module_root, node_modules, prodmode_module,
+           prodmode_target, runtime, runtime_deps, srcs, supports_workers, tsconfig, tsickle_typed,
+           use_angular_plugin)

    ATTRIBUTES

    @@ -854,6 +855,18 @@

    ts_library

    False + + + link_workspace_root + + Link the workspace root to the bin_dir to support absolute requires like 'my_wksp/path/to/file'. + If source files need to be required then they can be copied to the bin_dir with copy_to_bin. + + Boolean + optional + + False + module_name @@ -1166,7 +1179,7 @@

    Issues when running non-sandboxed

    ts_project(name, tsconfig, srcs, args, deps, extends, declaration, source_map, declaration_map, composite, incremental, emit_declaration_only, ts_build_info_file, tsc, validate, - declaration_dir, out_dir, root_dir, kwargs) + declaration_dir, out_dir, root_dir, link_workspace_root, kwargs)

    PARAMETERS

    @@ -1409,6 +1422,16 @@

    Issues when running non-sandboxed

    None + + + link_workspace_root + + Link the workspace root to the bin_dir to support absolute requires like 'my_wksp/path/to/file'. + If source files need to be required then they can be copied to the bin_dir with copy_to_bin. + + + False + kwargs diff --git a/docs/TypeScript.md b/docs/TypeScript.md index bdcd0edeea..8e3cd55702 100755 --- a/docs/TypeScript.md +++ b/docs/TypeScript.md @@ -611,8 +611,9 @@ TypeScript targets and JavaScript for the browser and Closure compiler. 
     ts_library(name, angular_assets, compiler, data, deps, devmode_module, devmode_target,
            expected_diagnostics, generate_externs, internal_testing_type_check_dependencies,
-           module_name, module_root, node_modules, prodmode_module, prodmode_target, runtime,
-           runtime_deps, srcs, supports_workers, tsconfig, tsickle_typed, use_angular_plugin)
+           link_workspace_root, module_name, module_root, node_modules, prodmode_module,
+           prodmode_target, runtime, runtime_deps, srcs, supports_workers, tsconfig, tsickle_typed,
+           use_angular_plugin)
    **ATTRIBUTES** @@ -745,6 +746,18 @@ This value will override the target option in the user supplied tsc False + + + link_workspace_root + + Link the workspace root to the bin_dir to support absolute requires like 'my_wksp/path/to/file'. + If source files need to be required then they can be copied to the bin_dir with copy_to_bin. + + Boolean + optional + + False + module_name @@ -1058,7 +1071,7 @@ observe these problems which require workarounds: 
     ts_project(name, tsconfig, srcs, args, deps, extends, declaration, source_map, declaration_map,
            composite, incremental, emit_declaration_only, ts_build_info_file, tsc, validate,
-           declaration_dir, out_dir, root_dir, kwargs)
+           declaration_dir, out_dir, root_dir, link_workspace_root, kwargs)
    **PARAMETERS** @@ -1299,6 +1312,16 @@ ts_project(name, t None + + + link_workspace_root + + Link the workspace root to the bin_dir to support absolute requires like 'my_wksp/path/to/file'. + If source files need to be required then they can be copied to the bin_dir with copy_to_bin. + + + False + kwargs diff --git a/docs/install.html b/docs/install.html index aba1762426..95858114de 100755 --- a/docs/install.html +++ b/docs/install.html @@ -183,8 +183,8 @@

    Custom installation

    load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 http_archive(
     name = "build_bazel_rules_nodejs",
-    sha256 = "10fffa29f687aa4d8eb6dfe8731ab5beb63811ab00981fc84a93899641fd4af1",
-    urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/2.0.3/rules_nodejs-2.0.3.tar.gz"],
+    sha256 = "b16a03bf63952ae436185c74a5c63bec03c010ed422e230db526af55441a02dd",
+    urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/2.1.0/rules_nodejs-2.1.0.tar.gz"],
 )
 
 load("@build_bazel_rules_nodejs//:index.bzl", "node_repositories")
diff --git a/docs/stamping.html b/docs/stamping.html
index f60f4569b9..51140c6d9a 100755
--- a/docs/stamping.html
+++ b/docs/stamping.html
@@ -233,11 +233,7 @@ 
    Release script
    
 # Call the script with argument "pack" or "publish"
 readonly NPM_COMMAND=${1:-publish}
 # Don't rely on $PATH to have the right version
-readonly BAZEL_BIN=./node_modules/.bin/bazel
-# Use a new output_base so we get a clean build
-# Bazel can't know if the git metadata changed
-readonly TMP=$(mktemp -d -t bazel-release.XXXXXXX)
-readonly BAZEL="$BAZEL_BIN --output_base=$TMP"
+readonly BAZEL=./node_modules/.bin/bazel
 # Find all the npm packages in the repo
 readonly PKG_NPM_LABELS=`$BAZEL query --output=label 'kind("pkg_npm", //...)'`
 # Build them in one command to maximize parallelism
@@ -248,7 +244,9 @@ 
    Release script
    
 done
    -

    See https://www.kchodorow.com/blog/2017/03/27/stamping-your-builds/ for more background.

    +

    See https://www.kchodorow.com/blog/2017/03/27/stamping-your-builds/ for more background. +Make sure you use a “STABLE_” status key, or else Bazel may use a cached npm artifact rather than +building a new one with your current version info.