From e4eae5a778c28ad0168acfb9952f8a93f98a1619 Mon Sep 17 00:00:00 2001 From: Alex Eagle Date: Thu, 13 Sep 2018 16:33:20 -0700 Subject: [PATCH] Update docs for release --- docs/node/node.html | 126 +++++++++++++++++++++++++++++- docs/npm_install/npm_install.html | 40 +++++----- 2 files changed, 146 insertions(+), 20 deletions(-) diff --git a/docs/node/node.html b/docs/node/node.html index a4dd3bf4cb..f971f154f4 100644 --- a/docs/node/node.html +++ b/docs/node/node.html @@ -321,9 +321,70 @@

Attributes

node_modules -

Label; Optional; Default is @//:node_modules

+

Label; Optional

The npm packages which should be available to require() during execution.

+
    This attribute is DEPRECATED. As of version 0.13.0 the recommended approach
+    to npm dependencies is to use fine grained npm dependencies which are setup
+    with the `yarn_install` or `npm_install` rules. For example, in targets
+    that used a `//:node_modules` filegroup,
+
+    ```
+    nodejs_binary(
+      name = "my_binary",
+      ...
+      node_modules = "//:node_modules",
+    )
+    ```
+
+    which specifies all files within the `//:node_modules` filegroup
+    to be inputs to the `my_binary`. Using fine grained npm dependencies,
+    `my_binary` is defined with only the npm dependencies that are
+    needed:
+
+    ```
+    nodejs_binary(
+      name = "my_binary",
+      ...
+      data = [
+          "@npm//:foo",
+          "@npm//:bar",
+          ...
+      ],
+    )
+    ```
+
+    In this case, only the `foo` and `bar` npm packages and their
+    transitive deps are includes as inputs to the `my_binary` target
+    which reduces the time required to setup the runfiles for this
+    target (see https://github.com/bazelbuild/bazel/issues/5153).
+
+    The @npm external repository and the fine grained npm package
+    targets are setup using the `yarn_install` or `npm_install` rule
+    in your WORKSPACE file:
+
+    yarn_install(
+      name = "npm",
+      package_json = "//:package.json",
+      yarn_lock = "//:yarn.lock",
+    )
+
+    For other rules such as `jasmine_node_test`, fine grained
+    npm dependencies are specified in the `deps` attribute:
+
+    ```
+    jasmine_node_test(
+        name = "my_test",
+        ...
+        deps = [
+            "@npm//:jasmine",
+            "@npm//:foo",
+            "@npm//:bar",
+            ...
+        ],
+    )
+    ```
+
@@ -427,9 +488,70 @@

Attributes

node_modules -

Label; Optional; Default is @//:node_modules

+

Label; Optional

The npm packages which should be available to require() during execution.

+
    This attribute is DEPRECATED. As of version 0.13.0 the recommended approach
+    to npm dependencies is to use fine grained npm dependencies which are setup
+    with the `yarn_install` or `npm_install` rules. For example, in targets
+    that used a `//:node_modules` filegroup,
+
+    ```
+    nodejs_binary(
+      name = "my_binary",
+      ...
+      node_modules = "//:node_modules",
+    )
+    ```
+
+    which specifies all files within the `//:node_modules` filegroup
+    to be inputs to the `my_binary`. Using fine grained npm dependencies,
+    `my_binary` is defined with only the npm dependencies that are
+    needed:
+
+    ```
+    nodejs_binary(
+      name = "my_binary",
+      ...
+      data = [
+          "@npm//:foo",
+          "@npm//:bar",
+          ...
+      ],
+    )
+    ```
+
+    In this case, only the `foo` and `bar` npm packages and their
+    transitive deps are includes as inputs to the `my_binary` target
+    which reduces the time required to setup the runfiles for this
+    target (see https://github.com/bazelbuild/bazel/issues/5153).
+
+    The @npm external repository and the fine grained npm package
+    targets are setup using the `yarn_install` or `npm_install` rule
+    in your WORKSPACE file:
+
+    yarn_install(
+      name = "npm",
+      package_json = "//:package.json",
+      yarn_lock = "//:yarn.lock",
+    )
+
+    For other rules such as `jasmine_node_test`, fine grained
+    npm dependencies are specified in the `deps` attribute:
+
+    ```
+    jasmine_node_test(
+        name = "my_test",
+        ...
+        deps = [
+            "@npm//:jasmine",
+            "@npm//:foo",
+            "@npm//:bar",
+            ...
+        ],
+    )
+    ```
+
diff --git a/docs/npm_install/npm_install.html b/docs/npm_install/npm_install.html index bb369435f1..a4f3555d3b 100644 --- a/docs/npm_install/npm_install.html +++ b/docs/npm_install/npm_install.html @@ -132,7 +132,7 @@

Overview

npm_install

- 
npm_install(name, data, node_modules_filegroup, package_json, package_lock_json, prod_only)
+ 
npm_install(name, data, manual_build_file_contents, package_json, package_lock_json, prod_only)

Runs npm install during workspace setup.

@@ -159,16 +159,18 @@

Attributes

- - node_modules_filegroup + + manual_build_file_contents

String; Optional; Default is ''

-

Experimental attribute that can be used to work-around - a bazel performance issue if the default node_modules filegroup - has too many files in it. Use it to define the node_modules - filegroup used by this rule such as - "filegroup(name = "node_modules", srcs = glob([...]))". See - https://github.com/bazelbuild/bazel/issues/5153.

+

Experimental attribute that can be used to override + the generated BUILD.bazel file and set its contents manually. + Can be used to work-around a bazel performance issue if the + default node_modules filegroup has too many files in it. See + https://github.com/bazelbuild/bazel/issues/5153. If + you are running into performance issues due to a large + node_modules filegroup it is recommended to switch to using + fine grained npm dependencies.

@@ -198,7 +200,7 @@

Attributes

yarn_install

- 
yarn_install(name, data, node_modules_filegroup, package_json, prod_only, yarn_lock)
+ 
yarn_install(name, data, manual_build_file_contents, package_json, prod_only, yarn_lock)

Runs yarn install during workspace setup.

@@ -225,16 +227,18 @@

Attributes

- - node_modules_filegroup + + manual_build_file_contents

String; Optional; Default is ''

-

Experimental attribute that can be used to work-around - a bazel performance issue if the default node_modules filegroup - has too many files in it. Use it to define the node_modules - filegroup used by this rule such as - "filegroup(name = "node_modules", srcs = glob([...]))". See - https://github.com/bazelbuild/bazel/issues/5153.

+

Experimental attribute that can be used to override + the generated BUILD.bazel file and set its contents manually. + Can be used to work-around a bazel performance issue if the + default node_modules filegroup has too many files in it. See + https://github.com/bazelbuild/bazel/issues/5153. If + you are running into performance issues due to a large + node_modules filegroup it is recommended to switch to using + fine grained npm dependencies.