diff options
Diffstat (limited to 'deps/npm/html/doc/install.html')
| -rw-r--r-- | deps/npm/html/doc/install.html | 169 |
1 files changed, 169 insertions, 0 deletions
diff --git a/deps/npm/html/doc/install.html b/deps/npm/html/doc/install.html new file mode 100644 index 000000000..c851ae547 --- /dev/null +++ b/deps/npm/html/doc/install.html @@ -0,0 +1,169 @@ +<!doctype html> +<html> + <title>install</title> + <meta http-equiv="content-type" value="text/html;utf-8"> + <link rel="stylesheet" type="text/css" href="./style.css"> + + <body> + <div id="wrapper"> +<h1><a href="../doc/install.html">install</a></h1> <p>Install a package</p> + +<h2 id="SYNOPSIS">SYNOPSIS</h2> + +<pre><code>npm install (with no args in a package dir) +npm install <tarball file> +npm install <tarball url> +npm install <folder> +npm install <name> +npm install <name>@<tag> +npm install <name>@<version> +npm install <name>@<version range></code></pre> + +<h2 id="DESCRIPTION">DESCRIPTION</h2> + +<p>This command installs a package, and any packages that it depends on.</p> + +<p>A <code>package</code> is:</p> + +<ul><li>a) a folder containing a program described by a package.json 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 with (c)</li><li>e) a <code><name>@<tag></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 (b)</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): +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></li><li><p><code>npm install <folder></code>: +Install a package that is sitting in a folder on the filesystem.</p></li><li><p><code>npm install <tarball file></code>: +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>Example:</p><pre><code>npm install ./package.tgz</code></pre></li><li><p><code>npm install <tarball url></code>: +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 <name></code>: +Do a <code><name>@<tag></code> install, where <code><tag></code> is the "tag" config. (See +<code><a href="../doc/config.html">config(1)</a></code>)</p><p>Example:</p><pre><code>npm install sax</code></pre><p><strong>Note</strong>: If there is a file or folder named <code><name></code> 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.</p></li><li><p><code>npm install <name>@<tag></code>: +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</code></pre></li><li><p><code>npm install <name>@<version></code>: +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</code></pre></li><li><p><code>npm install <name>@<version range></code>: +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="../doc/json.html">json(1)</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"</code></pre></li><li><p><code>npm install <git remote url></code>:</p><p>Install a package by cloning a git remote url. The format of the git +url is:</p><pre><code><protocol>://[<user>@]<hostname><separator><path>[#<commit-ish>]</code></pre><p><code><protocol></code> is one of <code>git</code>, <code>git+ssh</code>, <code>git+http</code>, or +<code>git+https</code>. If no <code><commit-ish></code> is specified, then <code>master</code> is +used.</p><p>Examples:</p><pre><code>git+ssh://git@github.com:isaacs/npm.git#v1.0.27 +git+https://isaacs@github.com/isaacs/npm.git +git://github.com/isaacs/npm.git#v1.0.27</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.</p> + +<p>The <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>--global</code> argument will cause npm to install the package globally +rather than locally. See <code><a href="../doc/global.html">global(1)</a></code>.</p> + +<p>The <code>--link</code> argument will cause npm to link global installs into the +local space in some cases.</p> + +<p>See <code><a href="../doc/config.html">config(1)</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>install(where, what, family, ancestors) +fetch what, unpack to <where>/node_modules/<what> +for each dep in what.dependencies + resolve dep to precise version +for each dep@version in what.dependencies + not in <where>/node_modules/<what>/node_modules/* + and not in <family> + add precise version deps to <family> + install(<where>/node_modules/<what>, dep, family)</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.</p> + +<p>See <a href="../doc/folders.html">folders(1)</a> for a more detailed description of the specific +folder structures that npm creates.</p> + +<h3 id="Limitations-of-npm-s-Install-Algorithm">Limitations of npm's Install Algorithm</h3> + +<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="../doc/folders.html">folders(1)</a></li><li><a href="../doc/update.html">update(1)</a></li><li><a href="../doc/link.html">link(1)</a></li><li><a href="../doc/rebuild.html">rebuild(1)</a></li><li><a href="../doc/scripts.html">scripts(1)</a></li><li><a href="../doc/build.html">build(1)</a></li><li><a href="../doc/config.html">config(1)</a></li><li><a href="../doc/registry.html">registry(1)</a></li><li><a href="../doc/folders.html">folders(1)</a></li><li><a href="../doc/tag.html">tag(1)</a></li><li><a href="../doc/rm.html">rm(1)</a></li></ul> +</div> +<p id="footer">install — npm@1.1.0-alpha-2</p> +<script> +;(function () { +var wrapper = document.getElementById("wrapper") +var els = Array.prototype.slice.call(wrapper.getElementsByTagName("*"), 0) + .filter(function (el) { + return el.parentNode === wrapper + && el.tagName.match(/H[1-6]/) + && el.id + }) +var l = 2 + , toc = document.createElement("ul") +toc.innerHTML = els.map(function (el) { + var i = el.tagName.charAt(1) + , out = "" + while (i > l) { + out += "<ul>" + l ++ + } + while (i < l) { + out += "</ul>" + l -- + } + out += "<li><a href='#" + el.id + "'>" + + ( el.innerText || el.text || el.innerHTML) + + "</a>" + return out +}).join("\n") +toc.id = "toc" +document.body.appendChild(toc) +})() +</script> +</body></html> |