Google Git
Sign in
pigweed/third_party/github/bazel-contrib/rules_nodejs/refs/tags/0.11.3/./docs/node/node.html
blob: fe16778d9eb3f4fa0236b05cd61a5d92cd6f9c0b [file] [log] [blame]
<!--
Documentation generated by Skydoc
-->
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width initial-scale=1" />
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>Executing programs</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,600,700" type="text/css">
<link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
<link rel="stylesheet" href="https://code.getmdl.io/1.1.1/material.green-light_blue.min.css">
<script defer src="https://code.getmdl.io/1.1.1/material.min.js"></script>
<link rel="stylesheet" href="/rules_nodejs/main.css">
</head>
<body>
<div class="mdl-layout mdl-js-layout mdl-layout--fixed-drawer
mdl-layout--fixed-header">
<header class="mdl-layout__header">
<div class="mdl-layout__header-row">
<span class="mdl-layout-title">Executing programs</span>
</div>
</header>
<div class="mdl-layout__drawer">
<span class="mdl-layout-title">Bazel</span>
<nav class="drawer-nav">
<ul class="drawer-nav">
<li><a href="/rules_nodejs/index.html">Overview</a></li>
<li>
<a href="/rules_nodejs/common/check_bazel_version.html">Check Bazel version</a>
<ul>
<li><a href="/rules_nodejs/common/check_bazel_version.html#overview">Overview</a></li>
</ul>
</li>
<li>
<a href="/rules_nodejs/jasmine_node_test/jasmine_node_test.html">NodeJS testing</a>
<ul>
<li><a href="/rules_nodejs/jasmine_node_test/jasmine_node_test.html#overview">Overview</a></li>
</ul>
</li>
<li>
<a href="/rules_nodejs/node/node.html">Executing programs</a>
<ul>
<li><a href="/rules_nodejs/node/node.html#overview">Overview</a></li>
<li>
<a href="/rules_nodejs/node/node.html#nodejs_binary">
nodejs_binary
</a>
</li>
<li>
<a href="/rules_nodejs/node/node.html#nodejs_test">
nodejs_test
</a>
</li>
</ul>
</li>
<li>
<a href="/rules_nodejs/node/node_repositories.html">Install NodeJS & Yarn</a>
<ul>
<li><a href="/rules_nodejs/node/node_repositories.html#overview">Overview</a></li>
</ul>
</li>
<li>
<a href="/rules_nodejs/npm_install/npm_install.html">Install npm packages</a>
<ul>
<li><a href="/rules_nodejs/npm_install/npm_install.html#overview">Overview</a></li>
</ul>
</li>
<li>
<a href="/rules_nodejs/npm_package/npm_package.html">npm packaging</a>
<ul>
<li><a href="/rules_nodejs/npm_package/npm_package.html#overview">Overview</a></li>
<li>
<a href="/rules_nodejs/npm_package/npm_package.html#npm_package">
npm_package
</a>
</li>
</ul>
</li>
<li>
<a href="/rules_nodejs/rollup/rollup_bundle.html">Rollup bundling</a>
<ul>
<li><a href="/rules_nodejs/rollup/rollup_bundle.html#overview">Overview</a></li>
<li>
<a href="/rules_nodejs/rollup/rollup_bundle.html#rollup_bundle">
rollup_bundle
</a>
</li>
</ul>
</li>
</ul>
</nav>
</div>
<main class="mdl-layout__content">
<div class="page-content">
<h1>Executing programs</h1>
<nav class="toc">
<h2><a href="#overview">Overview</a></h2>
<h2>Rules</h2>
<ul>
<li><a href="#nodejs_binary">nodejs_binary</a></li>
<li><a href="#nodejs_test">nodejs_test</a></li>
</ul>
<h2>Macros</h2>
<ul>
<li><a href="#nodejs_binary_macro">nodejs_binary_macro</a></li>
<li><a href="#nodejs_test_macro">nodejs_test_macro</a></li>
</ul>
</nav>
<hr>
<h2 id="overview">Overview</h2>
<p>These rules run the node binary with the given sources.</p>
<p>They support module mapping: any targets in the transitive dependencies with
a <code>module_name</code> attribute can be <code>require</code>d by that name.</p>
<hr>
<h2 id="nodejs_binary_macro">nodejs_binary_macro</h2>
<pre>nodejs_binary_macro(<a href="#nodejs_binary_macro.name">name</a>, <a href="#nodejs_binary_macro.data">data</a>, <a href="#nodejs_binary_macro.args">args</a>, <a href="#nodejs_binary_macro.visibility">visibility</a>, <a href="#nodejs_binary_macro.tags">tags</a>, <a href="#nodejs_binary_macro.testonly">testonly</a>)</pre>
<p>This macro exists only to wrap the nodejs_binary as an .exe for Windows.</p>
<p>This is exposed in the public API at <code>//:defs.bzl</code> as <code>nodejs_binary</code>, so most
users loading <code>nodejs_binary</code> are actually executing this macro.</p>
<h3 id="nodejs_binary_macro_args">Attributes</h3>
<table class="params-table">
<colgroup>
<col class="col-param" />
<col class="col-description" />
</colgroup>
<tbody>
<tr id="nodejs_binary_macro.name">
<td><code>name</code></td>
<td>
<p><code><a href="https://bazel.build/docs/build-ref.html#name">Name</a>; Required</code></p>
<p>name of the label</p>
</td>
</tr>
<tr id="nodejs_binary_macro.data">
<td><code>data</code></td>
<td>
<p><code>List of strings; Optional</code></p>
<p>runtime dependencies</p>
</td>
</tr>
<tr id="nodejs_binary_macro.args">
<td><code>args</code></td>
<td>
<p><code>List of strings; Optional</code></p>
<p>applied to the wrapper binary</p>
</td>
</tr>
<tr id="nodejs_binary_macro.visibility">
<td><code>visibility</code></td>
<td>
<p><code>Unknown; Optional</code></p>
<p>applied to the wrapper binary</p>
</td>
</tr>
<tr id="nodejs_binary_macro.tags">
<td><code>tags</code></td>
<td>
<p><code>List of strings; Optional</code></p>
<p>applied to the wrapper binary</p>
</td>
</tr>
<tr id="nodejs_binary_macro.testonly">
<td><code>testonly</code></td>
<td>
<p><code>Integer; Optional</code></p>
<p>applied to nodejs_binary and wrapper binary
**kwargs: passed to the nodejs_binary</p>
</td>
</tr>
</tbody>
</table>
<hr>
<h2 id="nodejs_test_macro">nodejs_test_macro</h2>
<pre>nodejs_test_macro(<a href="#nodejs_test_macro.name">name</a>, <a href="#nodejs_test_macro.data">data</a>, <a href="#nodejs_test_macro.args">args</a>, <a href="#nodejs_test_macro.visibility">visibility</a>, <a href="#nodejs_test_macro.tags">tags</a>)</pre>
<p>This macro exists only to wrap the nodejs_test as an .exe for Windows.</p>
<p>This is exposed in the public API at <code>//:defs.bzl</code> as <code>nodejs_test</code>, so most
users loading <code>nodejs_test</code> are actually executing this macro.</p>
<h3 id="nodejs_test_macro_args">Attributes</h3>
<table class="params-table">
<colgroup>
<col class="col-param" />
<col class="col-description" />
</colgroup>
<tbody>
<tr id="nodejs_test_macro.name">
<td><code>name</code></td>
<td>
<p><code><a href="https://bazel.build/docs/build-ref.html#name">Name</a>; Required</code></p>
<p>name of the label</p>
</td>
</tr>
<tr id="nodejs_test_macro.data">
<td><code>data</code></td>
<td>
<p><code>List of strings; Optional</code></p>
<p>runtime dependencies</p>
</td>
</tr>
<tr id="nodejs_test_macro.args">
<td><code>args</code></td>
<td>
<p><code>List of strings; Optional</code></p>
<p>applied to the wrapper binary</p>
</td>
</tr>
<tr id="nodejs_test_macro.visibility">
<td><code>visibility</code></td>
<td>
<p><code>Unknown; Optional</code></p>
<p>applied to the wrapper binary</p>
</td>
</tr>
<tr id="nodejs_test_macro.tags">
<td><code>tags</code></td>
<td>
<p><code>List of strings; Optional</code></p>
<p>applied to the wrapper binary
**kwargs: passed to the nodejs_test</p>
</td>
</tr>
</tbody>
</table>
<hr>
<h2 id="nodejs_binary">nodejs_binary</h2>
<pre>nodejs_binary(<a href="#nodejs_binary.name">name</a>, <a href="#nodejs_binary.data">data</a>, <a href="#nodejs_binary.bootstrap">bootstrap</a>, <a href="#nodejs_binary.entry_point">entry_point</a>, <a href="#nodejs_binary.install_source_map_support">install_source_map_support</a>, <a href="#nodejs_binary.node">node</a>, <a href="#nodejs_binary.node_modules">node_modules</a>, <a href="#nodejs_binary.templated_args">templated_args</a>)</pre>
<p>Runs some JavaScript code in NodeJS.</p>
<h3 id="nodejs_binary_args">Attributes</h3>
<table class="params-table">
<colgroup>
<col class="col-param" />
<col class="col-description" />
</colgroup>
<tbody>
<tr id="nodejs_binary.name">
<td><code>name</code></td>
<td>
<p><code><a href="https://bazel.build/docs/build-ref.html#name">Name</a>; Required</code></p>
<p>A unique name for this rule.</p>
</td>
</tr>
<tr id="nodejs_binary.data">
<td><code>data</code></td>
<td>
<p><code>List of <a href="https://bazel.build/docs/build-ref.html#labels">labels</a>; Optional; Default is []</code></p>
<p>Runtime dependencies which may be loaded during execution.</p>
</td>
</tr>
<tr id="nodejs_binary.bootstrap">
<td><code>bootstrap</code></td>
<td>
<p><code>List of strings; Optional; Default is []</code></p>
<p>JavaScript modules to be loaded before the entry point.
For example, Angular uses this to patch the Jasmine async primitives for
zone.js before the first <code>describe</code>.</p>
</td>
</tr>
<tr id="nodejs_binary.entry_point">
<td><code>entry_point</code></td>
<td>
<p><code>String; Required</code></p>
<p>The script which should be executed first, usually containing a main function.
This attribute expects a string starting with the workspace name, so that it's not ambiguous
in cases where a script with the same name appears in another directory or external workspace.</p>
</td>
</tr>
<tr id="nodejs_binary.install_source_map_support">
<td><code>install_source_map_support</code></td>
<td>
<p><code>Boolean; Optional; Default is True</code></p>
<p>Install the source-map-support package.
Enable this to get stack traces that point to original sources, e.g. if the program was written
in TypeScript.</p>
</td>
</tr>
<tr id="nodejs_binary.node">
<td><code>node</code></td>
<td>
<p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Optional; Default is @nodejs//:node</code></p>
<p>The node entry point target.</p>
</td>
</tr>
<tr id="nodejs_binary.node_modules">
<td><code>node_modules</code></td>
<td>
<p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Optional; Default is @//:node_modules</code></p>
<p>The npm packages which should be available to <code>require()</code> during
execution.</p>
</td>
</tr>
<tr id="nodejs_binary.templated_args">
<td><code>templated_args</code></td>
<td>
<p><code>List of strings; Optional; Default is []</code></p>
<p>Arguments which are passed to every execution of the program.
To pass a node startup option, prepend it with <code>--node_options=</code>, e.g.
<code>--node_options=--preserve-symlinks</code></p>
</td>
</tr>
</tbody>
</table>
<hr>
<h2 id="nodejs_test">nodejs_test</h2>
<pre>nodejs_test(<a href="#nodejs_test.name">name</a>, <a href="#nodejs_test.data">data</a>, <a href="#nodejs_test.bootstrap">bootstrap</a>, <a href="#nodejs_test.entry_point">entry_point</a>, <a href="#nodejs_test.expected_exit_code">expected_exit_code</a>, <a href="#nodejs_test.install_source_map_support">install_source_map_support</a>, <a href="#nodejs_test.node">node</a>, <a href="#nodejs_test.node_modules">node_modules</a>, <a href="#nodejs_test.templated_args">templated_args</a>)</pre>
<p>Identical to <code>nodejs_binary</code>, except this can be used with <code>bazel test</code> as well.
When the binary returns zero exit code, the test passes; otherwise it fails.</p>
<p><code>nodejs_test</code> is a convenient way to write a novel kind of test based on running
your own test runner. For example, the <code>ts-api-guardian</code> library has a way to
assert the public API of a TypeScript program, and uses <code>nodejs_test</code> here:
<a href="https://github.com/angular/angular/blob/master/tools/ts-api-guardian/index.bzl">https://github.com/angular/angular/blob/master/tools/ts-api-guardian/index.bzl</a></p>
<p>If you just want to run a standard test using a test runner like Karma or Jasmine,
use the specific rules for those test runners, e.g. <code>jasmine_node_test</code>.</p>
<p>To debug a Node.js test, we recommend saving a group of flags together in a "config".
Put this in your <code>tools/bazel.rc</code> so it's shared with your team:</p>
<pre><code># Enable debugging tests with --config=debug
test:debug --test_arg=--node_options=--inspect-brk --test_output=streamed --test_strategy=exclusive --test_timeout=9999 --nocache_test_results
</code></pre>
<p>Now you can add <code>--config=debug</code> to any <code>bazel test</code> command line.
The runtime will pause before executing the program, allowing you to connect a
remote debugger.</p>
<h3 id="nodejs_test_args">Attributes</h3>
<table class="params-table">
<colgroup>
<col class="col-param" />
<col class="col-description" />
</colgroup>
<tbody>
<tr id="nodejs_test.name">
<td><code>name</code></td>
<td>
<p><code><a href="https://bazel.build/docs/build-ref.html#name">Name</a>; Required</code></p>
<p>A unique name for this rule.</p>
</td>
</tr>
<tr id="nodejs_test.data">
<td><code>data</code></td>
<td>
<p><code>List of <a href="https://bazel.build/docs/build-ref.html#labels">labels</a>; Optional; Default is []</code></p>
<p>Runtime dependencies which may be loaded during execution.</p>
</td>
</tr>
<tr id="nodejs_test.bootstrap">
<td><code>bootstrap</code></td>
<td>
<p><code>List of strings; Optional; Default is []</code></p>
<p>JavaScript modules to be loaded before the entry point.
For example, Angular uses this to patch the Jasmine async primitives for
zone.js before the first <code>describe</code>.</p>
</td>
</tr>
<tr id="nodejs_test.entry_point">
<td><code>entry_point</code></td>
<td>
<p><code>String; Required</code></p>
<p>The script which should be executed first, usually containing a main function.
This attribute expects a string starting with the workspace name, so that it's not ambiguous
in cases where a script with the same name appears in another directory or external workspace.</p>
</td>
</tr>
<tr id="nodejs_test.expected_exit_code">
<td><code>expected_exit_code</code></td>
<td>
<p><code>Integer; Optional; Default is 0</code></p>
<p>The expected exit code for the test. Defaults to 0.</p>
</td>
</tr>
<tr id="nodejs_test.install_source_map_support">
<td><code>install_source_map_support</code></td>
<td>
<p><code>Boolean; Optional; Default is True</code></p>
<p>Install the source-map-support package.
Enable this to get stack traces that point to original sources, e.g. if the program was written
in TypeScript.</p>
</td>
</tr>
<tr id="nodejs_test.node">
<td><code>node</code></td>
<td>
<p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Optional; Default is @nodejs//:node</code></p>
<p>The node entry point target.</p>
</td>
</tr>
<tr id="nodejs_test.node_modules">
<td><code>node_modules</code></td>
<td>
<p><code><a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; Optional; Default is @//:node_modules</code></p>
<p>The npm packages which should be available to <code>require()</code> during
execution.</p>
</td>
</tr>
<tr id="nodejs_test.templated_args">
<td><code>templated_args</code></td>
<td>
<p><code>List of strings; Optional; Default is []</code></p>
<p>Arguments which are passed to every execution of the program.
To pass a node startup option, prepend it with <code>--node_options=</code>, e.g.
<code>--node_options=--preserve-symlinks</code></p>
</td>
</tr>
</tbody>
</table>
</div>
<footer class="mdl-mini-footer">
<div class="mdl-mini-footer__left-section">
<div class="mdl-logo">Bazel</div>
<ul class="mdl-mini-footer__link-list">
<li><a href="https://bazel.build">Home</a></li>
<li><a href="https://github.com/bazelbuild">GitHub</a></li>
</ul>
</div>
</footer>
</main>
</div>
</body>
</html>