diff options
Diffstat (limited to 'deps/node/deps/npm/html/doc/cli/npm-install.html')
| -rw-r--r-- | deps/node/deps/npm/html/doc/cli/npm-install.html | 374 |
1 files changed, 0 insertions, 374 deletions
diff --git a/deps/node/deps/npm/html/doc/cli/npm-install.html b/deps/node/deps/npm/html/doc/cli/npm-install.html deleted file mode 100644 index 973e0de7..00000000 --- a/deps/node/deps/npm/html/doc/cli/npm-install.html +++ /dev/null @@ -1,374 +0,0 @@ -<!doctype html> -<html> - <title>npm-install</title> - <meta charset="utf-8"> - <link rel="stylesheet" type="text/css" href="../../static/style.css"> - <link rel="canonical" href="https://www.npmjs.org/doc/cli/npm-install.html"> - <script async=true src="../../static/toc.js"></script> - - <body> - <div id="wrapper"> - -<h1><a href="../cli/npm-install.html">npm-install</a></h1> <p>Install a package</p> -<h2 id="synopsis">SYNOPSIS</h2> -<pre><code>npm install (with no args, in package dir) -npm install [<@scope>/]<name> -npm install [<@scope>/]<name>@<tag> -npm install [<@scope>/]<name>@<version> -npm install [<@scope>/]<name>@<version range> -npm install <git-host>:<git-user>/<repo-name> -npm install <git repo url> -npm install <tarball file> -npm install <tarball url> -npm install <folder> - -alias: npm i -common options: [-P|--save-prod|-D|--save-dev|-O|--save-optional] [-E|--save-exact] [-B|--save-bundle] [--no-save] [--dry-run]</code></pre><h2 id="description">DESCRIPTION</h2> -<p>This command installs a package, and any packages that it depends on. If the -package has a package-lock or shrinkwrap file, the installation of dependencies -will be driven by that, with an <code>npm-shrinkwrap.json</code> taking precedence if both -files exist. See <a href="../files/package-lock.json.html">package-lock.json(5)</a> and <a href="../cli/npm-shrinkwrap.html">npm-shrinkwrap(1)</a>.</p> -<p>A <code>package</code> is:</p> -<ul> -<li>a) a folder containing a program described by a <code><a href="../files/package.json.html">package.json(5)</a></code> file</li> -<li>b) a gzipped tarball containing (a)</li> -<li>c) a url that resolves to (b)</li> -<li>d) a <code><name>@<version></code> that is published on the registry (see <code><a href="../misc/npm-registry.html">npm-registry(7)</a></code>) with (c)</li> -<li>e) a <code><name>@<tag></code> (see <code><a href="../cli/npm-dist-tag.html">npm-dist-tag(1)</a></code>) that points to (d)</li> -<li>f) a <code><name></code> that has a "latest" tag satisfying (e)</li> -<li>g) a <code><git remote url></code> that resolves to (a)</li> -</ul> -<p>Even if you never publish your package, you can still get a lot of -benefits of using npm if you just want to write a node program (a), and -perhaps if you also want to be able to easily install it elsewhere -after packing it up into a tarball (b).</p> -<ul> -<li><p><code>npm install</code> (in package directory, no arguments):</p> -<p> Install the dependencies in the local node_modules folder.</p> -<p> In global mode (ie, with <code>-g</code> or <code>--global</code> appended to the command), - it installs the current package context (ie, the current working - directory) as a global package.</p> -<p> By default, <code>npm install</code> will install all modules listed as dependencies - in <code><a href="../files/package.json.html">package.json(5)</a></code>.</p> -<p> With the <code>--production</code> flag (or when the <code>NODE_ENV</code> environment variable - is set to <code>production</code>), npm will not install modules listed in - <code>devDependencies</code>.</p> -<blockquote> -<p>NOTE: The <code>--production</code> flag has no particular meaning when adding a - dependency to a project.</p> -</blockquote> -</li> -<li><p><code>npm install <folder></code>:</p> -<p> Install the package in the directory as a symlink in the current project. - Its dependencies will be installed before it's linked. If <code><folder></code> sits - inside the root of your project, its dependencies may be hoisted to the - toplevel <code>node_modules</code> as they would for other types of dependencies.</p> -</li> -<li><p><code>npm install <tarball file></code>:</p> -<p> Install a package that is sitting on the filesystem. Note: if you just want - to link a dev directory into your npm root, you can do this more easily by - using <code>npm link</code>.</p> -<p> Tarball requirements:</p> -<ul> -<li><p>The filename <em>must</em> use <code>.tar</code>, <code>.tar.gz</code>, or <code>.tgz</code> as -the extension.</p> -</li> -<li><p>The package contents should reside in a subfolder inside the tarball (usually it is called <code>package/</code>). npm strips one directory layer when installing the package (an equivalent of <code>tar x --strip-components=1</code> is run).</p> -</li> -<li><p>The package must contain a <code>package.json</code> file with <code>name</code> and <code>version</code> properties.</p> -<p>Example:</p> -<pre><code>npm install ./package.tgz</code></pre></li> -</ul> -</li> -<li><p><code>npm install <tarball url></code>:</p> -<p> Fetch the tarball url, and then install it. In order to distinguish between - this and other options, the argument must start with "http://" or "https://"</p> -<p> Example:</p> -<pre><code> npm install https://github.com/indexzero/forever/tarball/v0.5.6</code></pre></li> -<li><p><code>npm install [<@scope>/]<name></code>:</p> -<p> Do a <code><name>@<tag></code> install, where <code><tag></code> is the "tag" config. (See - <code><a href="../misc/npm-config.html">npm-config(7)</a></code>. The config's default value is <code>latest</code>.)</p> -<p> In most cases, this will install the version of the modules tagged as - <code>latest</code> on the npm registry.</p> -<p> Example:</p> -<pre><code> npm install sax</code></pre><p> <code>npm install</code> saves any specified packages into <code>dependencies</code> by default. - Additionally, you can control where and how they get saved with some - additional flags:</p> -<ul> -<li><p><code>-P, --save-prod</code>: Package will appear in your <code>dependencies</code>. This is the</p> -<pre><code> default unless `-D` or `-O` are present.</code></pre></li> -<li><p><code>-D, --save-dev</code>: Package will appear in your <code>devDependencies</code>.</p> -</li> -<li><p><code>-O, --save-optional</code>: Package will appear in your <code>optionalDependencies</code>.</p> -</li> -<li><p><code>--no-save</code>: Prevents saving to <code>dependencies</code>.</p> -<p>When using any of the above options to save dependencies to your -package.json, there are two additional, optional flags:</p> -</li> -<li><p><code>-E, --save-exact</code>: Saved dependencies will be configured with an -exact version rather than using npm's default semver range -operator.</p> -</li> -<li><p><code>-B, --save-bundle</code>: Saved dependencies will also be added to your <code>bundleDependencies</code> list.</p> -<p>Further, if you have an <code>npm-shrinkwrap.json</code> or <code>package-lock.json</code> then it -will be updated as well.</p> -<p><code><scope></code> is optional. The package will be downloaded from the registry -associated with the specified scope. If no registry is associated with -the given scope the default registry is assumed. See <code><a href="../misc/npm-scope.html">npm-scope(7)</a></code>.</p> -<p>Note: if you do not include the @-symbol on your scope name, npm will -interpret this as a GitHub repository instead, see below. Scopes names -must also be followed by a slash.</p> -<p>Examples:</p> -<pre><code>npm install sax -npm install githubname/reponame -npm install @myorg/privatepackage -npm install node-tap --save-dev -npm install dtrace-provider --save-optional -npm install readable-stream --save-exact -npm install ansi-regex --save-bundle</code></pre></li> -</ul> -</li> -</ul> -<pre><code>**Note**: If there is a file or folder named `<name>` in the current -working directory, then it will try to install that, and only try to -fetch the package by name if it is not valid.</code></pre><ul> -<li><p><code>npm install [<@scope>/]<name>@<tag></code>:</p> -<p> Install the version of the package that is referenced by the specified tag. - If the tag does not exist in the registry data for that package, then this - will fail.</p> -<p> Example:</p> -<pre><code> npm install sax@latest - npm install @myorg/mypackage@latest</code></pre></li> -<li><p><code>npm install [<@scope>/]<name>@<version></code>:</p> -<p> Install the specified version of the package. This will fail if the - version has not been published to the registry.</p> -<p> Example:</p> -<pre><code> npm install sax@0.1.1 - npm install @myorg/privatepackage@1.5.0</code></pre></li> -<li><p><code>npm install [<@scope>/]<name>@<version range></code>:</p> -<p> Install a version of the package matching the specified version range. This - will follow the same rules for resolving dependencies described in <code><a href="../files/package.json.html">package.json(5)</a></code>.</p> -<p> Note that most version ranges must be put in quotes so that your shell will - treat it as a single argument.</p> -<p> Example:</p> -<pre><code> npm install sax@">=0.1.0 <0.2.0" - npm install @myorg/privatepackage@">=0.1.0 <0.2.0"</code></pre></li> -<li><p><code>npm install <git remote url></code>:</p> -<p> Installs the package from the hosted git provider, cloning it with <code>git</code>. - For a full git remote url, only that URL will be attempted.</p> -<pre><code> <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]</code></pre><p> <code><protocol></code> is one of <code>git</code>, <code>git+ssh</code>, <code>git+http</code>, <code>git+https</code>, or - <code>git+file</code>.</p> -<p> If <code>#<commit-ish></code> is provided, it will be used to clone exactly that - commit. If the commit-ish has the format <code>#semver:<semver></code>, <code><semver></code> can - be any valid semver range or exact version, and npm will look for any tags - or refs matching that range in the remote repository, much as it would for a - registry dependency. If neither <code>#<commit-ish></code> or <code>#semver:<semver></code> is - specified, then the default branch of the repository is used.</p> -<p> If the repository makes use of submodules, those submodules will be cloned - as well.</p> -<p> If the package being installed contains a <code>prepare</code> script, its - <code>dependencies</code> and <code>devDependencies</code> will be installed, and the prepare - script will be run, before the package is packaged and installed.</p> -<p> The following git environment variables are recognized by npm and will be - added to the environment when running git:</p> -<ul> -<li><p><code>GIT_ASKPASS</code></p> -</li> -<li><p><code>GIT_EXEC_PATH</code></p> -</li> -<li><p><code>GIT_PROXY_COMMAND</code></p> -</li> -<li><p><code>GIT_SSH</code></p> -</li> -<li><p><code>GIT_SSH_COMMAND</code></p> -</li> -<li><p><code>GIT_SSL_CAINFO</code></p> -</li> -<li><p><code>GIT_SSL_NO_VERIFY</code></p> -<p>See the git man page for details.</p> -<p>Examples:</p> -<pre><code>npm install git+ssh://git@github.com:npm/cli.git#v1.0.27 -npm install git+ssh://git@github.com:npm/cli#semver:^5.0 -npm install git+https://isaacs@github.com/npm/cli.git -npm install git://github.com/npm/cli.git#v1.0.27 -GIT_SSH_COMMAND='ssh -i ~/.ssh/custom_ident' npm install git+ssh://git@github.com:npm/cli.git</code></pre></li> -</ul> -</li> -<li><p><code>npm install <githubname>/<githubrepo>[#<commit-ish>]</code>:</p> -</li> -<li><p><code>npm install github:<githubname>/<githubrepo>[#<commit-ish>]</code>:</p> -<p> Install the package at <code>https://github.com/githubname/githubrepo</code> by - attempting to clone it using <code>git</code>.</p> -<p> If <code>#<commit-ish></code> is provided, it will be used to clone exactly that - commit. If the commit-ish has the format <code>#semver:<semver></code>, <code><semver></code> can - be any valid semver range or exact version, and npm will look for any tags - or refs matching that range in the remote repository, much as it would for a - registry dependency. If neither <code>#<commit-ish></code> or <code>#semver:<semver></code> is - specified, then <code>master</code> is used.</p> -<p> As with regular git dependencies, <code>dependencies</code> and <code>devDependencies</code> will - be installed if the package has a <code>prepare</code> script, before the package is - done installing.</p> -<p> Examples:</p> -<pre><code> npm install mygithubuser/myproject - npm install github:mygithubuser/myproject</code></pre></li> -<li><p><code>npm install gist:[<githubname>/]<gistID>[#<commit-ish>|#semver:<semver>]</code>:</p> -<p> Install the package at <code>https://gist.github.com/gistID</code> by attempting to - clone it using <code>git</code>. The GitHub username associated with the gist is - optional and will not be saved in <code>package.json</code>.</p> -<p> As with regular git dependencies, <code>dependencies</code> and <code>devDependencies</code> will - be installed if the package has a <code>prepare</code> script, before the package is - done installing.</p> -<p> Example:</p> -<pre><code> npm install gist:101a11beef</code></pre></li> -<li><p><code>npm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit-ish>]</code>:</p> -<p> Install the package at <code>https://bitbucket.org/bitbucketname/bitbucketrepo</code> - by attempting to clone it using <code>git</code>.</p> -<p> If <code>#<commit-ish></code> is provided, it will be used to clone exactly that - commit. If the commit-ish has the format <code>#semver:<semver></code>, <code><semver></code> can - be any valid semver range or exact version, and npm will look for any tags - or refs matching that range in the remote repository, much as it would for a - registry dependency. If neither <code>#<commit-ish></code> or <code>#semver:<semver></code> is - specified, then <code>master</code> is used.</p> -<p> As with regular git dependencies, <code>dependencies</code> and <code>devDependencies</code> will - be installed if the package has a <code>prepare</code> script, before the package is - done installing.</p> -<p> Example:</p> -<pre><code> npm install bitbucket:mybitbucketuser/myproject</code></pre></li> -<li><p><code>npm install gitlab:<gitlabname>/<gitlabrepo>[#<commit-ish>]</code>:</p> -<p> Install the package at <code>https://gitlab.com/gitlabname/gitlabrepo</code> - by attempting to clone it using <code>git</code>.</p> -<p> If <code>#<commit-ish></code> is provided, it will be used to clone exactly that - commit. If the commit-ish has the format <code>#semver:<semver></code>, <code><semver></code> can - be any valid semver range or exact version, and npm will look for any tags - or refs matching that range in the remote repository, much as it would for a - registry dependency. If neither <code>#<commit-ish></code> or <code>#semver:<semver></code> is - specified, then <code>master</code> is used.</p> -<p> As with regular git dependencies, <code>dependencies</code> and <code>devDependencies</code> will - be installed if the package has a <code>prepare</code> script, before the package is - done installing.</p> -<p> Example:</p> -<pre><code> npm install gitlab:mygitlabuser/myproject - npm install gitlab:myusr/myproj#semver:^5.0</code></pre></li> -</ul> -<p>You may combine multiple arguments, and even multiple types of arguments. -For example:</p> -<pre><code>npm install sax@">=0.1.0 <0.2.0" bench supervisor</code></pre><p>The <code>--tag</code> argument will apply to all of the specified install targets. If a -tag with the given name exists, the tagged version is preferred over newer -versions.</p> -<p>The <code>--dry-run</code> argument will report in the usual way what the install would -have done without actually installing anything.</p> -<p>The <code>--package-lock-only</code> argument will only update the <code>package-lock.json</code>, -instead of checking <code>node_modules</code> and downloading dependencies.</p> -<p>The <code>-f</code> or <code>--force</code> argument will force npm to fetch remote resources even if a -local copy exists on disk.</p> -<pre><code>npm install sax --force</code></pre><p>The <code>-g</code> or <code>--global</code> argument will cause npm to install the package globally -rather than locally. See <code><a href="../files/npm-folders.html">npm-folders(5)</a></code>.</p> -<p>The <code>--global-style</code> argument will cause npm to install the package into -your local <code>node_modules</code> folder with the same layout it uses with the -global <code>node_modules</code> folder. Only your direct dependencies will show in -<code>node_modules</code> and everything they depend on will be flattened in their -<code>node_modules</code> folders. This obviously will eliminate some deduping.</p> -<p>The <code>--ignore-scripts</code> argument will cause npm to not execute any -scripts defined in the package.json. See <code><a href="../misc/npm-scripts.html">npm-scripts(7)</a></code>.</p> -<p>The <code>--legacy-bundling</code> argument will cause npm to install the package such -that versions of npm prior to 1.4, such as the one included with node 0.8, -can install the package. This eliminates all automatic deduping.</p> -<p>The <code>--link</code> argument will cause npm to link global installs into the -local space in some cases.</p> -<p>The <code>--no-bin-links</code> argument will prevent npm from creating symlinks for -any binaries the package might contain.</p> -<p>The <code>--no-optional</code> argument will prevent optional dependencies from -being installed.</p> -<p>The <code>--no-shrinkwrap</code> argument, which will ignore an available -package lock or shrinkwrap file and use the package.json instead.</p> -<p>The <code>--no-package-lock</code> argument will prevent npm from creating a -<code>package-lock.json</code> file. When running with package-lock's disabled npm -will not automatically prune your node modules when installing.</p> -<p>The <code>--nodedir=/path/to/node/source</code> argument will allow npm to find the -node source code so that npm can compile native modules.</p> -<p>The <code>--only={prod[uction]|dev[elopment]}</code> argument will cause either only -<code>devDependencies</code> or only non-<code>devDependencies</code> to be installed regardless of the <code>NODE_ENV</code>.</p> -<p>The <code>--no-audit</code> argument can be used to disable sending of audit reports to -the configured registries. See <code><a href="../cli/npm-audit.html">npm-audit(1)</a></code> for details on what is sent.</p> -<p>See <code><a href="../misc/npm-config.html">npm-config(7)</a></code>. Many of the configuration params have some -effect on installation, since that's most of what npm does.</p> -<h2 id="algorithm">ALGORITHM</h2> -<p>To install a package, npm uses the following algorithm:</p> -<pre><code>load the existing node_modules tree from disk -clone the tree -fetch the package.json and assorted metadata and add it to the clone -walk the clone and add any missing dependencies - dependencies will be added as close to the top as is possible - without breaking any other modules -compare the original tree with the cloned tree and make a list of -actions to take to convert one to the other -execute all of the actions, deepest first - kinds of actions are install, update, remove and move</code></pre><p>For this <code>package{dep}</code> structure: <code>A{B,C}, B{C}, C{D}</code>, -this algorithm produces:</p> -<pre><code>A -+-- B -+-- C -+-- D</code></pre><p>That is, the dependency from B to C is satisfied by the fact that A -already caused C to be installed at a higher level. D is still installed -at the top level because nothing conflicts with it.</p> -<p>For <code>A{B,C}, B{C,D@1}, C{D@2}</code>, this algorithm produces:</p> -<pre><code>A -+-- B -+-- C - `-- D@2 -+-- D@1</code></pre><p>Because B's D@1 will be installed in the top level, C now has to install D@2 -privately for itself. This algorithm is deterministic, but different trees may -be produced if two dependencies are requested for installation in a different -order.</p> -<p>See <a href="../files/npm-folders.html">npm-folders(5)</a> for a more detailed description of the specific -folder structures that npm creates.</p> -<h3 id="limitations-of-npms-install-algorithm">Limitations of npm's Install Algorithm</h3> -<p>npm will refuse to install any package with an identical name to the -current package. This can be overridden with the <code>--force</code> flag, but in -most cases can simply be addressed by changing the local package name.</p> -<p>There are some very rare and pathological edge-cases where a cycle can -cause npm to try to install a never-ending tree of packages. Here is -the simplest case:</p> -<pre><code>A -> B -> A' -> B' -> A -> B -> A' -> B' -> A -> ...</code></pre><p>where <code>A</code> is some version of a package, and <code>A'</code> is a different version -of the same package. Because <code>B</code> depends on a different version of <code>A</code> -than the one that is already in the tree, it must install a separate -copy. The same is true of <code>A'</code>, which must install <code>B'</code>. Because <code>B'</code> -depends on the original version of <code>A</code>, which has been overridden, the -cycle falls into infinite regress.</p> -<p>To avoid this situation, npm flat-out refuses to install any -<code>name@version</code> that is already present anywhere in the tree of package -folder ancestors. A more correct, but more complex, solution would be -to symlink the existing version into the new location. If this ever -affects a real use-case, it will be investigated.</p> -<h2 id="see-also">SEE ALSO</h2> -<ul> -<li><a href="../files/npm-folders.html">npm-folders(5)</a></li> -<li><a href="../cli/npm-update.html">npm-update(1)</a></li> -<li><a href="../cli/npm-audit.html">npm-audit(1)</a></li> -<li><a href="../cli/npm-link.html">npm-link(1)</a></li> -<li><a href="../cli/npm-rebuild.html">npm-rebuild(1)</a></li> -<li><a href="../misc/npm-scripts.html">npm-scripts(7)</a></li> -<li><a href="../cli/npm-build.html">npm-build(1)</a></li> -<li><a href="../cli/npm-config.html">npm-config(1)</a></li> -<li><a href="../misc/npm-config.html">npm-config(7)</a></li> -<li><a href="../files/npmrc.html">npmrc(5)</a></li> -<li><a href="../misc/npm-registry.html">npm-registry(7)</a></li> -<li><a href="../cli/npm-dist-tag.html">npm-dist-tag(1)</a></li> -<li><a href="../cli/npm-uninstall.html">npm-uninstall(1)</a></li> -<li><a href="../cli/npm-shrinkwrap.html">npm-shrinkwrap(1)</a></li> -<li><a href="../files/package.json.html">package.json(5)</a></li> -</ul> - -</div> - -<table border=0 cellspacing=0 cellpadding=0 id=npmlogo> -<tr><td style="width:180px;height:10px;background:rgb(237,127,127)" colspan=18> </td></tr> -<tr><td rowspan=4 style="width:10px;height:10px;background:rgb(237,127,127)"> </td><td style="width:40px;height:10px;background:#fff" colspan=4> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=4> </td><td style="width:40px;height:10px;background:#fff" colspan=4> </td><td rowspan=4 style="width:10px;height:10px;background:rgb(237,127,127)"> </td><td colspan=6 style="width:60px;height:10px;background:#fff"> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=4> </td></tr> -<tr><td colspan=2 style="width:20px;height:30px;background:#fff" rowspan=3> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:20px;height:10px;background:#fff" rowspan=4 colspan=2> </td><td style="width:10px;height:20px;background:rgb(237,127,127)" rowspan=2> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:20px;height:10px;background:#fff" rowspan=3 colspan=2> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td><td style="width:10px;height:10px;background:#fff" rowspan=3> </td><td style="width:10px;height:10px;background:rgb(237,127,127)" rowspan=3> </td></tr> -<tr><td style="width:10px;height:10px;background:#fff" rowspan=2> </td></tr> -<tr><td style="width:10px;height:10px;background:#fff"> </td></tr> -<tr><td style="width:60px;height:10px;background:rgb(237,127,127)" colspan=6> </td><td colspan=10 style="width:10px;height:10px;background:rgb(237,127,127)"> </td></tr> -<tr><td colspan=5 style="width:50px;height:10px;background:#fff"> </td><td style="width:40px;height:10px;background:rgb(237,127,127)" colspan=4> </td><td style="width:90px;height:10px;background:#fff" colspan=9> </td></tr> -</table> -<p id="footer">npm-install — npm@6.7.0</p> - |