diff options
| author | isaacs <i@izs.me> | 2013-07-12 08:55:57 -0700 |
|---|---|---|
| committer | isaacs <i@izs.me> | 2013-07-12 08:56:26 -0700 |
| commit | ff8a4058bfac4f360992cfe7adf04f910282cedc (patch) | |
| tree | b271ef198babbc9c46c33bcda9826fbcc6bf0a6d /deps/npm/html/doc/files | |
| parent | 6d91bd37075a53f42bab01915fa89ba4a4f0a075 (diff) | |
| download | node-ff8a4058bfac4f360992cfe7adf04f910282cedc.tar.gz | |
npm: Upgrade to 1.3.3
Diffstat (limited to 'deps/npm/html/doc/files')
| -rw-r--r-- | deps/npm/html/doc/files/npm-folders.html | 239 | ||||
| -rw-r--r-- | deps/npm/html/doc/files/npm-global.html | 239 | ||||
| -rw-r--r-- | deps/npm/html/doc/files/npm-json.html | 580 | ||||
| -rw-r--r-- | deps/npm/html/doc/files/npmrc.html | 93 | ||||
| -rw-r--r-- | deps/npm/html/doc/files/package.json.html | 580 |
5 files changed, 1731 insertions, 0 deletions
diff --git a/deps/npm/html/doc/files/npm-folders.html b/deps/npm/html/doc/files/npm-folders.html new file mode 100644 index 000000000..00dacef55 --- /dev/null +++ b/deps/npm/html/doc/files/npm-folders.html @@ -0,0 +1,239 @@ +<!doctype html> +<html> + <title>npm-folders</title> + <meta http-equiv="content-type" value="text/html;utf-8"> + <link rel="stylesheet" type="text/css" href="../../static/style.css"> + + <body> + <div id="wrapper"> +<h1><a href="../files/npm-folders.html">npm-folders</a></h1> <p>Folder Structures Used by npm</p> + +<h2 id="DESCRIPTION">DESCRIPTION</h2> + +<p>npm puts various things on your computer. That's its job.</p> + +<p>This document will tell you what it puts where.</p> + +<h3 id="tl-dr">tl;dr</h3> + +<ul><li>Local install (default): puts stuff in <code>./node_modules</code> of the current +package root.</li><li>Global install (with <code>-g</code>): puts stuff in /usr/local or wherever node +is installed.</li><li>Install it <strong>locally</strong> if you're going to <code>require()</code> it.</li><li>Install it <strong>globally</strong> if you're going to run it on the command line.</li><li>If you need both, then install it in both places, or use <code>npm link</code>.</li></ul> + +<h3 id="prefix-Configuration">prefix Configuration</h3> + +<p>The <code>prefix</code> config defaults to the location where node is installed. +On most systems, this is <code>/usr/local</code>, and most of the time is the same +as node's <code>process.installPrefix</code>.</p> + +<p>On windows, this is the exact location of the node.exe binary. On Unix +systems, it's one level up, since node is typically installed at +<code>{prefix}/bin/node</code> rather than <code>{prefix}/node.exe</code>.</p> + +<p>When the <code>global</code> flag is set, npm installs things into this prefix. +When it is not set, it uses the root of the current package, or the +current working directory if not in a package already.</p> + +<h3 id="Node-Modules">Node Modules</h3> + +<p>Packages are dropped into the <code>node_modules</code> folder under the <code>prefix</code>. +When installing locally, this means that you can +<code>require("packagename")</code> to load its main module, or +<code>require("packagename/lib/path/to/sub/module")</code> to load other modules.</p> + +<p>Global installs on Unix systems go to <code>{prefix}/lib/node_modules</code>. +Global installs on Windows go to <code>{prefix}/node_modules</code> (that is, no +<code>lib</code> folder.)</p> + +<p>If you wish to <code>require()</code> a package, then install it locally.</p> + +<h3 id="Executables">Executables</h3> + +<p>When in global mode, executables are linked into <code>{prefix}/bin</code> on Unix, +or directly into <code>{prefix}</code> on Windows.</p> + +<p>When in local mode, executables are linked into +<code>./node_modules/.bin</code> so that they can be made available to scripts run +through npm. (For example, so that a test runner will be in the path +when you run <code>npm test</code>.)</p> + +<h3 id="Man-Pages">Man Pages</h3> + +<p>When in global mode, man pages are linked into <code>{prefix}/share/man</code>.</p> + +<p>When in local mode, man pages are not installed.</p> + +<p>Man pages are not installed on Windows systems.</p> + +<h3 id="Cache">Cache</h3> + +<p>See <code><a href="../cli/npm-cache.html">npm-cache(1)</a></code>. Cache files are stored in <code>~/.npm</code> on Posix, or +<code>~/npm-cache</code> on Windows.</p> + +<p>This is controlled by the <code>cache</code> configuration param.</p> + +<h3 id="Temp-Files">Temp Files</h3> + +<p>Temporary files are stored by default in the folder specified by the +<code>tmp</code> config, which defaults to the TMPDIR, TMP, or TEMP environment +variables, or <code>/tmp</code> on Unix and <code>c:\windows\temp</code> on Windows.</p> + +<p>Temp files are given a unique folder under this root for each run of the +program, and are deleted upon successful exit.</p> + +<h2 id="More-Information">More Information</h2> + +<p>When installing locally, npm first tries to find an appropriate +<code>prefix</code> folder. This is so that <code>npm install foo@1.2.3</code> will install +to the sensible root of your package, even if you happen to have <code>cd</code>ed +into some other folder.</p> + +<p>Starting at the $PWD, npm will walk up the folder tree checking for a +folder that contains either a <code>package.json</code> file, or a <code>node_modules</code> +folder. If such a thing is found, then that is treated as the effective +"current directory" for the purpose of running npm commands. (This +behavior is inspired by and similar to git's .git-folder seeking +logic when running git commands in a working dir.)</p> + +<p>If no package root is found, then the current folder is used.</p> + +<p>When you run <code>npm install foo@1.2.3</code>, then the package is loaded into +the cache, and then unpacked into <code>./node_modules/foo</code>. Then, any of +foo's dependencies are similarly unpacked into +<code>./node_modules/foo/node_modules/...</code>.</p> + +<p>Any bin files are symlinked to <code>./node_modules/.bin/</code>, so that they may +be found by npm scripts when necessary.</p> + +<h3 id="Global-Installation">Global Installation</h3> + +<p>If the <code>global</code> configuration is set to true, then npm will +install packages "globally".</p> + +<p>For global installation, packages are installed roughly the same way, +but using the folders described above.</p> + +<h3 id="Cycles-Conflicts-and-Folder-Parsimony">Cycles, Conflicts, and Folder Parsimony</h3> + +<p>Cycles are handled using the property of node's module system that it +walks up the directories looking for <code>node_modules</code> folders. So, at every +stage, if a package is already installed in an ancestor <code>node_modules</code> +folder, then it is not installed at the current location.</p> + +<p>Consider the case above, where <code>foo -> bar -> baz</code>. Imagine if, in +addition to that, baz depended on bar, so you'd have: +<code>foo -> bar -> baz -> bar -> baz ...</code>. However, since the folder +structure is: <code>foo/node_modules/bar/node_modules/baz</code>, there's no need to +put another copy of bar into <code>.../baz/node_modules</code>, since when it calls +require("bar"), it will get the copy that is installed in +<code>foo/node_modules/bar</code>.</p> + +<p>This shortcut is only used if the exact same +version would be installed in multiple nested <code>node_modules</code> folders. It +is still possible to have <code>a/node_modules/b/node_modules/a</code> if the two +"a" packages are different versions. However, without repeating the +exact same package multiple times, an infinite regress will always be +prevented.</p> + +<p>Another optimization can be made by installing dependencies at the +highest level possible, below the localized "target" folder.</p> + +<h4 id="Example">Example</h4> + +<p>Consider this dependency graph:</p> + +<pre><code>foo ++-- blerg@1.2.5 ++-- bar@1.2.3 +| +-- blerg@1.x (latest=1.3.7) +| +-- baz@2.x +| | `-- quux@3.x +| | `-- bar@1.2.3 (cycle) +| `-- asdf@* +`-- baz@1.2.3 + `-- quux@3.x + `-- bar</code></pre> + +<p>In this case, we might expect a folder structure like this:</p> + +<pre><code>foo ++-- node_modules + +-- blerg (1.2.5) <---[A] + +-- bar (1.2.3) <---[B] + | `-- node_modules + | +-- baz (2.0.2) <---[C] + | | `-- node_modules + | | `-- quux (3.2.0) + | `-- asdf (2.3.4) + `-- baz (1.2.3) <---[D] + `-- node_modules + `-- quux (3.2.0) <---[E]</code></pre> + +<p>Since foo depends directly on <code>bar@1.2.3</code> and <code>baz@1.2.3</code>, those are +installed in foo's <code>node_modules</code> folder.</p> + +<p>Even though the latest copy of blerg is 1.3.7, foo has a specific +dependency on version 1.2.5. So, that gets installed at [A]. Since the +parent installation of blerg satisfies bar's dependency on <code>blerg@1.x</code>, +it does not install another copy under [B].</p> + +<p>Bar [B] also has dependencies on baz and asdf, so those are installed in +bar's <code>node_modules</code> folder. Because it depends on <code>baz@2.x</code>, it cannot +re-use the <code>baz@1.2.3</code> installed in the parent <code>node_modules</code> folder [D], +and must install its own copy [C].</p> + +<p>Underneath bar, the <code>baz -> quux -> bar</code> dependency creates a cycle. +However, because bar is already in quux's ancestry [B], it does not +unpack another copy of bar into that folder.</p> + +<p>Underneath <code>foo -> baz</code> [D], quux's [E] folder tree is empty, because its +dependency on bar is satisfied by the parent folder copy installed at [B].</p> + +<p>For a graphical breakdown of what is installed where, use <code>npm ls</code>.</p> + +<h3 id="Publishing">Publishing</h3> + +<p>Upon publishing, npm will look in the <code>node_modules</code> folder. If any of +the items there are not in the <code>bundledDependencies</code> array, then they will +not be included in the package tarball.</p> + +<p>This allows a package maintainer to install all of their dependencies +(and dev dependencies) locally, but only re-publish those items that +cannot be found elsewhere. See <code><a href="../files/package.json.html">package.json(5)</a></code> for more information.</p> + +<h2 id="SEE-ALSO">SEE ALSO</h2> + +<ul><li><a href="../misc/npm-faq.html">npm-faq(7)</a></li><li><a href="../files/package.json.html">package.json(5)</a></li><li><a href="../cli/npm-install.html">npm-install(1)</a></li><li><a href="../cli/npm-pack.html">npm-pack(1)</a></li><li><a href="../cli/npm-cache.html">npm-cache(1)</a></li><li><a href="../cli/npm-config.html">npm-config(1)</a></li><li><a href="../files/npmrc.html">npmrc(5)</a></li><li><a href="../misc/npm-config.html">npm-config(7)</a></li><li><a href="../cli/npm-publish.html">npm-publish(1)</a></li></ul> +</div> +<p id="footer">npm-folders — npm@1.3.3</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> diff --git a/deps/npm/html/doc/files/npm-global.html b/deps/npm/html/doc/files/npm-global.html new file mode 100644 index 000000000..00dacef55 --- /dev/null +++ b/deps/npm/html/doc/files/npm-global.html @@ -0,0 +1,239 @@ +<!doctype html> +<html> + <title>npm-folders</title> + <meta http-equiv="content-type" value="text/html;utf-8"> + <link rel="stylesheet" type="text/css" href="../../static/style.css"> + + <body> + <div id="wrapper"> +<h1><a href="../files/npm-folders.html">npm-folders</a></h1> <p>Folder Structures Used by npm</p> + +<h2 id="DESCRIPTION">DESCRIPTION</h2> + +<p>npm puts various things on your computer. That's its job.</p> + +<p>This document will tell you what it puts where.</p> + +<h3 id="tl-dr">tl;dr</h3> + +<ul><li>Local install (default): puts stuff in <code>./node_modules</code> of the current +package root.</li><li>Global install (with <code>-g</code>): puts stuff in /usr/local or wherever node +is installed.</li><li>Install it <strong>locally</strong> if you're going to <code>require()</code> it.</li><li>Install it <strong>globally</strong> if you're going to run it on the command line.</li><li>If you need both, then install it in both places, or use <code>npm link</code>.</li></ul> + +<h3 id="prefix-Configuration">prefix Configuration</h3> + +<p>The <code>prefix</code> config defaults to the location where node is installed. +On most systems, this is <code>/usr/local</code>, and most of the time is the same +as node's <code>process.installPrefix</code>.</p> + +<p>On windows, this is the exact location of the node.exe binary. On Unix +systems, it's one level up, since node is typically installed at +<code>{prefix}/bin/node</code> rather than <code>{prefix}/node.exe</code>.</p> + +<p>When the <code>global</code> flag is set, npm installs things into this prefix. +When it is not set, it uses the root of the current package, or the +current working directory if not in a package already.</p> + +<h3 id="Node-Modules">Node Modules</h3> + +<p>Packages are dropped into the <code>node_modules</code> folder under the <code>prefix</code>. +When installing locally, this means that you can +<code>require("packagename")</code> to load its main module, or +<code>require("packagename/lib/path/to/sub/module")</code> to load other modules.</p> + +<p>Global installs on Unix systems go to <code>{prefix}/lib/node_modules</code>. +Global installs on Windows go to <code>{prefix}/node_modules</code> (that is, no +<code>lib</code> folder.)</p> + +<p>If you wish to <code>require()</code> a package, then install it locally.</p> + +<h3 id="Executables">Executables</h3> + +<p>When in global mode, executables are linked into <code>{prefix}/bin</code> on Unix, +or directly into <code>{prefix}</code> on Windows.</p> + +<p>When in local mode, executables are linked into +<code>./node_modules/.bin</code> so that they can be made available to scripts run +through npm. (For example, so that a test runner will be in the path +when you run <code>npm test</code>.)</p> + +<h3 id="Man-Pages">Man Pages</h3> + +<p>When in global mode, man pages are linked into <code>{prefix}/share/man</code>.</p> + +<p>When in local mode, man pages are not installed.</p> + +<p>Man pages are not installed on Windows systems.</p> + +<h3 id="Cache">Cache</h3> + +<p>See <code><a href="../cli/npm-cache.html">npm-cache(1)</a></code>. Cache files are stored in <code>~/.npm</code> on Posix, or +<code>~/npm-cache</code> on Windows.</p> + +<p>This is controlled by the <code>cache</code> configuration param.</p> + +<h3 id="Temp-Files">Temp Files</h3> + +<p>Temporary files are stored by default in the folder specified by the +<code>tmp</code> config, which defaults to the TMPDIR, TMP, or TEMP environment +variables, or <code>/tmp</code> on Unix and <code>c:\windows\temp</code> on Windows.</p> + +<p>Temp files are given a unique folder under this root for each run of the +program, and are deleted upon successful exit.</p> + +<h2 id="More-Information">More Information</h2> + +<p>When installing locally, npm first tries to find an appropriate +<code>prefix</code> folder. This is so that <code>npm install foo@1.2.3</code> will install +to the sensible root of your package, even if you happen to have <code>cd</code>ed +into some other folder.</p> + +<p>Starting at the $PWD, npm will walk up the folder tree checking for a +folder that contains either a <code>package.json</code> file, or a <code>node_modules</code> +folder. If such a thing is found, then that is treated as the effective +"current directory" for the purpose of running npm commands. (This +behavior is inspired by and similar to git's .git-folder seeking +logic when running git commands in a working dir.)</p> + +<p>If no package root is found, then the current folder is used.</p> + +<p>When you run <code>npm install foo@1.2.3</code>, then the package is loaded into +the cache, and then unpacked into <code>./node_modules/foo</code>. Then, any of +foo's dependencies are similarly unpacked into +<code>./node_modules/foo/node_modules/...</code>.</p> + +<p>Any bin files are symlinked to <code>./node_modules/.bin/</code>, so that they may +be found by npm scripts when necessary.</p> + +<h3 id="Global-Installation">Global Installation</h3> + +<p>If the <code>global</code> configuration is set to true, then npm will +install packages "globally".</p> + +<p>For global installation, packages are installed roughly the same way, +but using the folders described above.</p> + +<h3 id="Cycles-Conflicts-and-Folder-Parsimony">Cycles, Conflicts, and Folder Parsimony</h3> + +<p>Cycles are handled using the property of node's module system that it +walks up the directories looking for <code>node_modules</code> folders. So, at every +stage, if a package is already installed in an ancestor <code>node_modules</code> +folder, then it is not installed at the current location.</p> + +<p>Consider the case above, where <code>foo -> bar -> baz</code>. Imagine if, in +addition to that, baz depended on bar, so you'd have: +<code>foo -> bar -> baz -> bar -> baz ...</code>. However, since the folder +structure is: <code>foo/node_modules/bar/node_modules/baz</code>, there's no need to +put another copy of bar into <code>.../baz/node_modules</code>, since when it calls +require("bar"), it will get the copy that is installed in +<code>foo/node_modules/bar</code>.</p> + +<p>This shortcut is only used if the exact same +version would be installed in multiple nested <code>node_modules</code> folders. It +is still possible to have <code>a/node_modules/b/node_modules/a</code> if the two +"a" packages are different versions. However, without repeating the +exact same package multiple times, an infinite regress will always be +prevented.</p> + +<p>Another optimization can be made by installing dependencies at the +highest level possible, below the localized "target" folder.</p> + +<h4 id="Example">Example</h4> + +<p>Consider this dependency graph:</p> + +<pre><code>foo ++-- blerg@1.2.5 ++-- bar@1.2.3 +| +-- blerg@1.x (latest=1.3.7) +| +-- baz@2.x +| | `-- quux@3.x +| | `-- bar@1.2.3 (cycle) +| `-- asdf@* +`-- baz@1.2.3 + `-- quux@3.x + `-- bar</code></pre> + +<p>In this case, we might expect a folder structure like this:</p> + +<pre><code>foo ++-- node_modules + +-- blerg (1.2.5) <---[A] + +-- bar (1.2.3) <---[B] + | `-- node_modules + | +-- baz (2.0.2) <---[C] + | | `-- node_modules + | | `-- quux (3.2.0) + | `-- asdf (2.3.4) + `-- baz (1.2.3) <---[D] + `-- node_modules + `-- quux (3.2.0) <---[E]</code></pre> + +<p>Since foo depends directly on <code>bar@1.2.3</code> and <code>baz@1.2.3</code>, those are +installed in foo's <code>node_modules</code> folder.</p> + +<p>Even though the latest copy of blerg is 1.3.7, foo has a specific +dependency on version 1.2.5. So, that gets installed at [A]. Since the +parent installation of blerg satisfies bar's dependency on <code>blerg@1.x</code>, +it does not install another copy under [B].</p> + +<p>Bar [B] also has dependencies on baz and asdf, so those are installed in +bar's <code>node_modules</code> folder. Because it depends on <code>baz@2.x</code>, it cannot +re-use the <code>baz@1.2.3</code> installed in the parent <code>node_modules</code> folder [D], +and must install its own copy [C].</p> + +<p>Underneath bar, the <code>baz -> quux -> bar</code> dependency creates a cycle. +However, because bar is already in quux's ancestry [B], it does not +unpack another copy of bar into that folder.</p> + +<p>Underneath <code>foo -> baz</code> [D], quux's [E] folder tree is empty, because its +dependency on bar is satisfied by the parent folder copy installed at [B].</p> + +<p>For a graphical breakdown of what is installed where, use <code>npm ls</code>.</p> + +<h3 id="Publishing">Publishing</h3> + +<p>Upon publishing, npm will look in the <code>node_modules</code> folder. If any of +the items there are not in the <code>bundledDependencies</code> array, then they will +not be included in the package tarball.</p> + +<p>This allows a package maintainer to install all of their dependencies +(and dev dependencies) locally, but only re-publish those items that +cannot be found elsewhere. See <code><a href="../files/package.json.html">package.json(5)</a></code> for more information.</p> + +<h2 id="SEE-ALSO">SEE ALSO</h2> + +<ul><li><a href="../misc/npm-faq.html">npm-faq(7)</a></li><li><a href="../files/package.json.html">package.json(5)</a></li><li><a href="../cli/npm-install.html">npm-install(1)</a></li><li><a href="../cli/npm-pack.html">npm-pack(1)</a></li><li><a href="../cli/npm-cache.html">npm-cache(1)</a></li><li><a href="../cli/npm-config.html">npm-config(1)</a></li><li><a href="../files/npmrc.html">npmrc(5)</a></li><li><a href="../misc/npm-config.html">npm-config(7)</a></li><li><a href="../cli/npm-publish.html">npm-publish(1)</a></li></ul> +</div> +<p id="footer">npm-folders — npm@1.3.3</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> diff --git a/deps/npm/html/doc/files/npm-json.html b/deps/npm/html/doc/files/npm-json.html new file mode 100644 index 000000000..a8e0f6279 --- /dev/null +++ b/deps/npm/html/doc/files/npm-json.html @@ -0,0 +1,580 @@ +<!doctype html> +<html> + <title>package.json</title> + <meta http-equiv="content-type" value="text/html;utf-8"> + <link rel="stylesheet" type="text/css" href="../../static/style.css"> + + <body> + <div id="wrapper"> +<h1><a href="../files/package.json.html">package.json</a></h1> <p>Specifics of npm's package.json handling</p> + +<h2 id="DESCRIPTION">DESCRIPTION</h2> + +<p>This document is all you need to know about what's required in your package.json +file. It must be actual JSON, not just a JavaScript object literal.</p> + +<p>A lot of the behavior described in this document is affected by the config +settings described in <code><a href="../misc/npm-config.html">npm-config(7)</a></code>.</p> + +<h2 id="DEFAULT-VALUES">DEFAULT VALUES</h2> + +<p>npm will default some values based on package contents.</p> + +<ul><li><p><code>"scripts": {"start": "node server.js"}</code></p><p>If there is a <code>server.js</code> file in the root of your package, then npm +will default the <code>start</code> command to <code>node server.js</code>.</p></li><li><p><code>"scripts":{"preinstall": "node-waf clean || true; node-waf configure build"}</code></p><p>If there is a <code>wscript</code> file in the root of your package, npm will +default the <code>preinstall</code> command to compile using node-waf.</p></li><li><p><code>"scripts":{"preinstall": "node-gyp rebuild"}</code></p><p>If there is a <code>binding.gyp</code> file in the root of your package, npm will +default the <code>preinstall</code> command to compile using node-gyp.</p></li><li><p><code>"contributors": [...]</code></p><p>If there is an <code>AUTHORS</code> file in the root of your package, npm will +treat each line as a <code>Name <email> (url)</code> format, where email and url +are optional. Lines which start with a <code>#</code> or are blank, will be +ignored.</p></li></ul> + +<h2 id="name">name</h2> + +<p>The <em>most</em> important things in your package.json are the name and version fields. +Those are actually required, and your package won't install without +them. The name and version together form an identifier that is assumed +to be completely unique. Changes to the package should come along with +changes to the version.</p> + +<p>The name is what your thing is called. Some tips:</p> + +<ul><li>Don't put "js" or "node" in the name. It's assumed that it's js, since you're +writing a package.json file, and you can specify the engine using the "engines" +field. (See below.)</li><li>The name ends up being part of a URL, an argument on the command line, and a +folder name. Any name with non-url-safe characters will be rejected. +Also, it can't start with a dot or an underscore.</li><li>The name will probably be passed as an argument to require(), so it should +be something short, but also reasonably descriptive.</li><li>You may want to check the npm registry to see if there's something by that name +already, before you get too attached to it. http://registry.npmjs.org/</li></ul> + +<h2 id="version">version</h2> + +<p>The <em>most</em> important things in your package.json are the name and version fields. +Those are actually required, and your package won't install without +them. The name and version together form an identifier that is assumed +to be completely unique. Changes to the package should come along with +changes to the version.</p> + +<p>Version must be parseable by +<a href="https://github.com/isaacs/node-semver">node-semver</a>, which is bundled +with npm as a dependency. (<code>npm install semver</code> to use it yourself.)</p> + +<p>Here's how npm's semver implementation deviates from what's on semver.org:</p> + +<ul><li>Versions can start with "v"</li><li>A numeric item separated from the main three-number version by a hyphen +will be interpreted as a "build" number, and will <em>increase</em> the version. +But, if the tag is not a number separated by a hyphen, then it's treated +as a pre-release tag, and is <em>less than</em> the version without a tag. +So, <code>0.1.2-7 > 0.1.2-7-beta > 0.1.2-6 > 0.1.2 > 0.1.2beta</code></li></ul> + +<p>This is a little bit confusing to explain, but matches what you see in practice +when people create tags in git like "v1.2.3" and then do "git describe" to generate +a patch version.</p> + +<h2 id="description">description</h2> + +<p>Put a description in it. It's a string. This helps people discover your +package, as it's listed in <code>npm search</code>.</p> + +<h2 id="keywords">keywords</h2> + +<p>Put keywords in it. It's an array of strings. This helps people +discover your package as it's listed in <code>npm search</code>.</p> + +<h2 id="homepage">homepage</h2> + +<p>The url to the project homepage.</p> + +<p><strong>NOTE</strong>: This is <em>not</em> the same as "url". If you put a "url" field, +then the registry will think it's a redirection to your package that has +been published somewhere else, and spit at you.</p> + +<p>Literally. Spit. I'm so not kidding.</p> + +<h2 id="bugs">bugs</h2> + +<p>The url to your project's issue tracker and / or the email address to which +issues should be reported. These are helpful for people who encounter issues +with your package.</p> + +<p>It should look like this:</p> + +<pre><code>{ "url" : "http://github.com/owner/project/issues" +, "email" : "project@hostname.com" +}</code></pre> + +<p>You can specify either one or both values. If you want to provide only a url, +you can specify the value for "bugs" as a simple string instead of an object.</p> + +<p>If a url is provided, it will be used by the <code>npm bugs</code> command.</p> + +<h2 id="license">license</h2> + +<p>You should specify a license for your package so that people know how they are +permitted to use it, and any restrictions you're placing on it.</p> + +<p>The simplest way, assuming you're using a common license such as BSD or MIT, is +to just specify the name of the license you're using, like this:</p> + +<pre><code>{ "license" : "BSD" }</code></pre> + +<p>If you have more complex licensing terms, or you want to provide more detail +in your package.json file, you can use the more verbose plural form, like this:</p> + +<pre><code>"licenses" : [ + { "type" : "MyLicense" + , "url" : "http://github.com/owner/project/path/to/license" + } +]</code></pre> + +<p>It's also a good idea to include a license file at the top level in your package.</p> + +<h2 id="people-fields-author-contributors">people fields: author, contributors</h2> + +<p>The "author" is one person. "contributors" is an array of people. A "person" +is an object with a "name" field and optionally "url" and "email", like this:</p> + +<pre><code>{ "name" : "Barney Rubble" +, "email" : "b@rubble.com" +, "url" : "http://barnyrubble.tumblr.com/" +}</code></pre> + +<p>Or you can shorten that all into a single string, and npm will parse it for you:</p> + +<pre><code>"Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)</code></pre> + +<p>Both email and url are optional either way.</p> + +<p>npm also sets a top-level "maintainers" field with your npm user info.</p> + +<h2 id="files">files</h2> + +<p>The "files" field is an array of files to include in your project. If +you name a folder in the array, then it will also include the files +inside that folder. (Unless they would be ignored by another rule.)</p> + +<p>You can also provide a ".npmignore" file in the root of your package, +which will keep files from being included, even if they would be picked +up by the files array. The ".npmignore" file works just like a +".gitignore".</p> + +<h2 id="main">main</h2> + +<p>The main field is a module ID that is the primary entry point to your program. +That is, if your package is named <code>foo</code>, and a user installs it, and then does +<code>require("foo")</code>, then your main module's exports object will be returned.</p> + +<p>This should be a module ID relative to the root of your package folder.</p> + +<p>For most modules, it makes the most sense to have a main script and often not +much else.</p> + +<h2 id="bin">bin</h2> + +<p>A lot of packages have one or more executable files that they'd like to +install into the PATH. npm makes this pretty easy (in fact, it uses this +feature to install the "npm" executable.)</p> + +<p>To use this, supply a <code>bin</code> field in your package.json which is a map of +command name to local file name. On install, npm will symlink that file into +<code>prefix/bin</code> for global installs, or <code>./node_modules/.bin/</code> for local +installs.</p> + +<p>For example, npm has this:</p> + +<pre><code>{ "bin" : { "npm" : "./cli.js" } }</code></pre> + +<p>So, when you install npm, it'll create a symlink from the <code>cli.js</code> script to +<code>/usr/local/bin/npm</code>.</p> + +<p>If you have a single executable, and its name should be the name +of the package, then you can just supply it as a string. For example:</p> + +<pre><code>{ "name": "my-program" +, "version": "1.2.5" +, "bin": "./path/to/program" }</code></pre> + +<p>would be the same as this:</p> + +<pre><code>{ "name": "my-program" +, "version": "1.2.5" +, "bin" : { "my-program" : "./path/to/program" } }</code></pre> + +<h2 id="man">man</h2> + +<p>Specify either a single file or an array of filenames to put in place for the +<code>man</code> program to find.</p> + +<p>If only a single file is provided, then it's installed such that it is the +result from <code>man <pkgname></code>, regardless of its actual filename. For example:</p> + +<pre><code>{ "name" : "foo" +, "version" : "1.2.3" +, "description" : "A packaged foo fooer for fooing foos" +, "main" : "foo.js" +, "man" : "./man/doc.1" +}</code></pre> + +<p>would link the <code>./man/doc.1</code> file in such that it is the target for <code>man foo</code></p> + +<p>If the filename doesn't start with the package name, then it's prefixed. +So, this:</p> + +<pre><code>{ "name" : "foo" +, "version" : "1.2.3" +, "description" : "A packaged foo fooer for fooing foos" +, "main" : "foo.js" +, "man" : [ "./man/foo.1", "./man/bar.1" ] +}</code></pre> + +<p>will create files to do <code>man foo</code> and <code>man foo-bar</code>.</p> + +<p>Man files must end with a number, and optionally a <code>.gz</code> suffix if they are +compressed. The number dictates which man section the file is installed into.</p> + +<pre><code>{ "name" : "foo" +, "version" : "1.2.3" +, "description" : "A packaged foo fooer for fooing foos" +, "main" : "foo.js" +, "man" : [ "./man/foo.1", "./man/foo.2" ] +}</code></pre> + +<p>will create entries for <code>man foo</code> and <code>man 2 foo</code></p> + +<h2 id="directories">directories</h2> + +<p>The CommonJS <a href="http://wiki.commonjs.org/wiki/Packages/1.0">Packages</a> spec details a +few ways that you can indicate the structure of your package using a <code>directories</code> +hash. If you look at <a href="http://registry.npmjs.org/npm/latest">npm's package.json</a>, +you'll see that it has directories for doc, lib, and man.</p> + +<p>In the future, this information may be used in other creative ways.</p> + +<h3 id="directories-lib">directories.lib</h3> + +<p>Tell people where the bulk of your library is. Nothing special is done +with the lib folder in any way, but it's useful meta info.</p> + +<h3 id="directories-bin">directories.bin</h3> + +<p>If you specify a "bin" directory, then all the files in that folder will +be used as the "bin" hash.</p> + +<p>If you have a "bin" hash already, then this has no effect.</p> + +<h3 id="directories-man">directories.man</h3> + +<p>A folder that is full of man pages. Sugar to generate a "man" array by +walking the folder.</p> + +<h3 id="directories-doc">directories.doc</h3> + +<p>Put markdown files in here. Eventually, these will be displayed nicely, +maybe, someday.</p> + +<h3 id="directories-example">directories.example</h3> + +<p>Put example scripts in here. Someday, it might be exposed in some clever way.</p> + +<h2 id="repository">repository</h2> + +<p>Specify the place where your code lives. This is helpful for people who +want to contribute. If the git repo is on github, then the <code>npm docs</code> +command will be able to find you.</p> + +<p>Do it like this:</p> + +<pre><code>"repository" : + { "type" : "git" + , "url" : "http://github.com/isaacs/npm.git" + } + +"repository" : + { "type" : "svn" + , "url" : "http://v8.googlecode.com/svn/trunk/" + }</code></pre> + +<p>The URL should be a publicly available (perhaps read-only) url that can be handed +directly to a VCS program without any modification. It should not be a url to an +html project page that you put in your browser. It's for computers.</p> + +<h2 id="scripts">scripts</h2> + +<p>The "scripts" member is an object hash of script commands that are run +at various times in the lifecycle of your package. The key is the lifecycle +event, and the value is the command to run at that point.</p> + +<p>See <code><a href="../misc/npm-scripts.html">npm-scripts(7)</a></code> to find out more about writing package scripts.</p> + +<h2 id="config">config</h2> + +<p>A "config" hash can be used to set configuration +parameters used in package scripts that persist across upgrades. For +instance, if a package had the following:</p> + +<pre><code>{ "name" : "foo" +, "config" : { "port" : "8080" } }</code></pre> + +<p>and then had a "start" command that then referenced the +<code>npm_package_config_port</code> environment variable, then the user could +override that by doing <code>npm config set foo:port 8001</code>.</p> + +<p>See <code><a href="../misc/npm-config.html">npm-config(7)</a></code> and <code><a href="../misc/npm-scripts.html">npm-scripts(7)</a></code> for more on package +configs.</p> + +<h2 id="dependencies">dependencies</h2> + +<p>Dependencies are specified with a simple hash of package name to version +range. The version range is EITHER a string which has one or more +space-separated descriptors, OR a range like "fromVersion - toVersion"</p> + +<p><strong>Please do not put test harnesses in your <code>dependencies</code> hash.</strong> See +<code>devDependencies</code>, below.</p> + +<p>Version range descriptors may be any of the following styles, where "version" +is a semver compatible version identifier.</p> + +<ul><li><code>version</code> Must match <code>version</code> exactly</li><li><code>=version</code> Same as just <code>version</code></li><li><code>>version</code> Must be greater than <code>version</code></li><li><code>>=version</code> etc</li><li><code><version</code></li><li><code><=version</code></li><li><code>~version</code> See 'Tilde Version Ranges' below</li><li><code>1.2.x</code> See 'X Version Ranges' below</li><li><code>http://...</code> See 'URLs as Dependencies' below</li><li><code>*</code> Matches any version</li><li><code>""</code> (just an empty string) Same as <code>*</code></li><li><code>version1 - version2</code> Same as <code>>=version1 <=version2</code>.</li><li><code>range1 || range2</code> Passes if either range1 or range2 are satisfied.</li><li><code>git...</code> See 'Git URLs as Dependencies' below</li></ul> + +<p>For example, these are all valid:</p> + +<pre><code>{ "dependencies" : + { "foo" : "1.0.0 - 2.9999.9999" + , "bar" : ">=1.0.2 <2.1.2" + , "baz" : ">1.0.2 <=2.3.4" + , "boo" : "2.0.1" + , "qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0" + , "asd" : "http://asdf.com/asdf.tar.gz" + , "til" : "~1.2" + , "elf" : "~1.2.3" + , "two" : "2.x" + , "thr" : "3.3.x" + } +}</code></pre> + +<h3 id="Tilde-Version-Ranges">Tilde Version Ranges</h3> + +<p>A range specifier starting with a tilde <code>~</code> character is matched against +a version in the following fashion.</p> + +<ul><li>The version must be at least as high as the range.</li><li>The version must be less than the next major revision above the range.</li></ul> + +<p>For example, the following are equivalent:</p> + +<ul><li><code>"~1.2.3" = ">=1.2.3 <1.3.0"</code></li><li><code>"~1.2" = ">=1.2.0 <1.3.0"</code></li><li><code>"~1" = ">=1.0.0 <1.1.0"</code></li></ul> + +<h3 id="X-Version-Ranges">X Version Ranges</h3> + +<p>An "x" in a version range specifies that the version number must start +with the supplied digits, but any digit may be used in place of the x.</p> + +<p>The following are equivalent:</p> + +<ul><li><code>"1.2.x" = ">=1.2.0 <1.3.0"</code></li><li><code>"1.x.x" = ">=1.0.0 <2.0.0"</code></li><li><code>"1.2" = "1.2.x"</code></li><li><code>"1.x" = "1.x.x"</code></li><li><code>"1" = "1.x.x"</code></li></ul> + +<p>You may not supply a comparator with a version containing an x. Any +digits after the first "x" are ignored.</p> + +<h3 id="URLs-as-Dependencies">URLs as Dependencies</h3> + +<p>Starting with npm version 0.2.14, you may specify a tarball URL in place +of a version range.</p> + +<p>This tarball will be downloaded and installed locally to your package at +install time.</p> + +<h3 id="Git-URLs-as-Dependencies">Git URLs as Dependencies</h3> + +<p>Git urls can be of the form:</p> + +<pre><code>git://github.com/user/project.git#commit-ish +git+ssh://user@hostname:project.git#commit-ish +git+ssh://user@hostname/project.git#commit-ish +git+http://user@hostname/project/blah.git#commit-ish +git+https://user@hostname/project/blah.git#commit-ish</code></pre> + +<p>The <code>commit-ish</code> can be any tag, sha, or branch which can be supplied as +an argument to <code>git checkout</code>. The default is <code>master</code>.</p> + +<h2 id="devDependencies">devDependencies</h2> + +<p>If someone is planning on downloading and using your module in their +program, then they probably don't want or need to download and build +the external test or documentation framework that you use.</p> + +<p>In this case, it's best to list these additional items in a +<code>devDependencies</code> hash.</p> + +<p>These things will be installed whenever the <code>--dev</code> configuration flag +is set. This flag is set automatically when doing <code>npm link</code> or when doing +<code>npm install</code> from the root of a package, and can be managed like any other npm +configuration param. See <code><a href="../misc/npm-config.html">npm-config(7)</a></code> for more on the topic.</p> + +<h2 id="bundledDependencies">bundledDependencies</h2> + +<p>Array of package names that will be bundled when publishing the package.</p> + +<p>If this is spelled <code>"bundleDependencies"</code>, then that is also honorable.</p> + +<h2 id="optionalDependencies">optionalDependencies</h2> + +<p>If a dependency can be used, but you would like npm to proceed if it +cannot be found or fails to install, then you may put it in the +<code>optionalDependencies</code> hash. This is a map of package name to version +or url, just like the <code>dependencies</code> hash. The difference is that +failure is tolerated.</p> + +<p>It is still your program's responsibility to handle the lack of the +dependency. For example, something like this:</p> + +<pre><code>try { + var foo = require('foo') + var fooVersion = require('foo/package.json').version +} catch (er) { + foo = null +} +if ( notGoodFooVersion(fooVersion) ) { + foo = null +} + +// .. then later in your program .. + +if (foo) { + foo.doFooThings() +}</code></pre> + +<p>Entries in <code>optionalDependencies</code> will override entries of the same name in +<code>dependencies</code>, so it's usually best to only put in one place.</p> + +<h2 id="engines">engines</h2> + +<p>You can specify the version of node that your stuff works on:</p> + +<pre><code>{ "engines" : { "node" : ">=0.1.27 <0.1.30" } }</code></pre> + +<p>And, like with dependencies, if you don't specify the version (or if you +specify "*" as the version), then any version of node will do.</p> + +<p>If you specify an "engines" field, then npm will require that "node" be +somewhere on that list. If "engines" is omitted, then npm will just assume +that it works on node.</p> + +<p>You can also use the "engines" field to specify which versions of npm +are capable of properly installing your program. For example:</p> + +<pre><code>{ "engines" : { "npm" : "~1.0.20" } }</code></pre> + +<p>Note that, unless the user has set the <code>engine-strict</code> config flag, this +field is advisory only.</p> + +<h2 id="engineStrict">engineStrict</h2> + +<p>If you are sure that your module will <em>definitely not</em> run properly on +versions of Node/npm other than those specified in the <code>engines</code> hash, +then you can set <code>"engineStrict": true</code> in your package.json file. +This will override the user's <code>engine-strict</code> config setting.</p> + +<p>Please do not do this unless you are really very very sure. If your +engines hash is something overly restrictive, you can quite easily and +inadvertently lock yourself into obscurity and prevent your users from +updating to new versions of Node. Consider this choice carefully. If +people abuse it, it will be removed in a future version of npm.</p> + +<h2 id="os">os</h2> + +<p>You can specify which operating systems your +module will run on:</p> + +<pre><code>"os" : [ "darwin", "linux" ]</code></pre> + +<p>You can also blacklist instead of whitelist operating systems, +just prepend the blacklisted os with a '!':</p> + +<pre><code>"os" : [ "!win32" ]</code></pre> + +<p>The host operating system is determined by <code>process.platform</code></p> + +<p>It is allowed to both blacklist, and whitelist, although there isn't any +good reason to do this.</p> + +<h2 id="cpu">cpu</h2> + +<p>If your code only runs on certain cpu architectures, +you can specify which ones.</p> + +<pre><code>"cpu" : [ "x64", "ia32" ]</code></pre> + +<p>Like the <code>os</code> option, you can also blacklist architectures:</p> + +<pre><code>"cpu" : [ "!arm", "!mips" ]</code></pre> + +<p>The host architecture is determined by <code>process.arch</code></p> + +<h2 id="preferGlobal">preferGlobal</h2> + +<p>If your package is primarily a command-line application that should be +installed globally, then set this value to <code>true</code> to provide a warning +if it is installed locally.</p> + +<p>It doesn't actually prevent users from installing it locally, but it +does help prevent some confusion if it doesn't work as expected.</p> + +<h2 id="private">private</h2> + +<p>If you set <code>"private": true</code> in your package.json, then npm will refuse +to publish it.</p> + +<p>This is a way to prevent accidental publication of private repositories. +If you would like to ensure that a given package is only ever published +to a specific registry (for example, an internal registry), +then use the <code>publishConfig</code> hash described below +to override the <code>registry</code> config param at publish-time.</p> + +<h2 id="publishConfig">publishConfig</h2> + +<p>This is a set of config values that will be used at publish-time. It's +especially handy if you want to set the tag or registry, so that you can +ensure that a given package is not tagged with "latest" or published to +the global public registry by default.</p> + +<p>Any config values can be overridden, but of course only "tag" and +"registry" probably matter for the purposes of publishing.</p> + +<p>See <code><a href="../misc/npm-config.html">npm-config(7)</a></code> to see the list of config options that can be +overridden.</p> + +<h2 id="SEE-ALSO">SEE ALSO</h2> + +<ul><li><a href="../misc/npm-semver.html">npm-semver(7)</a></li><li><a href="../cli/npm-init.html">npm-init(1)</a></li><li><a href="../cli/npm-version.html">npm-version(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="../cli/npm-help.html">npm-help(1)</a></li><li><a href="../misc/npm-faq.html">npm-faq(7)</a></li><li><a href="../cli/npm-install.html">npm-install(1)</a></li><li><a href="../cli/npm-publish.html">npm-publish(1)</a></li><li><a href="../cli/npm-rm.html">npm-rm(1)</a></li></ul> +</div> +<p id="footer">package.json — npm@1.3.3</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> diff --git a/deps/npm/html/doc/files/npmrc.html b/deps/npm/html/doc/files/npmrc.html new file mode 100644 index 000000000..90cc13410 --- /dev/null +++ b/deps/npm/html/doc/files/npmrc.html @@ -0,0 +1,93 @@ +<!doctype html> +<html> + <title>npmrc</title> + <meta http-equiv="content-type" value="text/html;utf-8"> + <link rel="stylesheet" type="text/css" href="../../static/style.css"> + + <body> + <div id="wrapper"> +<h1><a href="../files/npmrc.html">npmrc</a></h1> <p>The npm config files</p> + +<h2 id="DESCRIPTION">DESCRIPTION</h2> + +<p>npm gets its config settings from the command line, environment +variables, and <code>npmrc</code> files.</p> + +<p>The <code>npm config</code> command can be used to update and edit the contents +of the user and global npmrc files.</p> + +<p>For a list of available configuration options, see <a href="../misc/npm-config.html">npm-config(7)</a>.</p> + +<h2 id="FILES">FILES</h2> + +<p>The three relevant files are:</p> + +<ul><li>per-user config file (~/.npmrc)</li><li>global config file ($PREFIX/npmrc)</li><li>npm builtin config file (/path/to/npm/npmrc)</li></ul> + +<p>All npm config files are an ini-formatted list of <code>key = value</code> +parameters. Environment variables can be replaced using +<code>${VARIABLE_NAME}</code>. For example:</p> + +<pre><code>prefix = ${HOME}/.npm-packages</code></pre> + +<p>Each of these files is loaded, and config options are resolved in +priority order. For example, a setting in the userconfig file would +override the setting in the globalconfig file.</p> + +<h3 id="Per-user-config-file">Per-user config file</h3> + +<p><code>$HOME/.npmrc</code> (or the <code>userconfig</code> param, if set in the environment +or on the command line)</p> + +<h3 id="Global-config-file">Global config file</h3> + +<p><code>$PREFIX/etc/npmrc</code> (or the <code>globalconfig</code> param, if set above): +This file is an ini-file formatted list of <code>key = value</code> parameters. +Environment variables can be replaced as above.</p> + +<h3 id="Built-in-config-file">Built-in config file</h3> + +<p><code>path/to/npm/itself/npmrc</code></p> + +<p>This is an unchangeable "builtin" configuration file that npm keeps +consistent across updates. Set fields in here using the <code>./configure</code> +script that comes with npm. This is primarily for distribution +maintainers to override default configs in a standard and consistent +manner.</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-config.html">npm-config(1)</a></li><li><a href="../misc/npm-config.html">npm-config(7)</a></li><li><a href="../files/package.json.html">package.json(5)</a></li><li><a href="../cli/npm.html">npm(1)</a></li></ul> +</div> +<p id="footer">npmrc — npm@1.3.3</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> diff --git a/deps/npm/html/doc/files/package.json.html b/deps/npm/html/doc/files/package.json.html new file mode 100644 index 000000000..a8e0f6279 --- /dev/null +++ b/deps/npm/html/doc/files/package.json.html @@ -0,0 +1,580 @@ +<!doctype html> +<html> + <title>package.json</title> + <meta http-equiv="content-type" value="text/html;utf-8"> + <link rel="stylesheet" type="text/css" href="../../static/style.css"> + + <body> + <div id="wrapper"> +<h1><a href="../files/package.json.html">package.json</a></h1> <p>Specifics of npm's package.json handling</p> + +<h2 id="DESCRIPTION">DESCRIPTION</h2> + +<p>This document is all you need to know about what's required in your package.json +file. It must be actual JSON, not just a JavaScript object literal.</p> + +<p>A lot of the behavior described in this document is affected by the config +settings described in <code><a href="../misc/npm-config.html">npm-config(7)</a></code>.</p> + +<h2 id="DEFAULT-VALUES">DEFAULT VALUES</h2> + +<p>npm will default some values based on package contents.</p> + +<ul><li><p><code>"scripts": {"start": "node server.js"}</code></p><p>If there is a <code>server.js</code> file in the root of your package, then npm +will default the <code>start</code> command to <code>node server.js</code>.</p></li><li><p><code>"scripts":{"preinstall": "node-waf clean || true; node-waf configure build"}</code></p><p>If there is a <code>wscript</code> file in the root of your package, npm will +default the <code>preinstall</code> command to compile using node-waf.</p></li><li><p><code>"scripts":{"preinstall": "node-gyp rebuild"}</code></p><p>If there is a <code>binding.gyp</code> file in the root of your package, npm will +default the <code>preinstall</code> command to compile using node-gyp.</p></li><li><p><code>"contributors": [...]</code></p><p>If there is an <code>AUTHORS</code> file in the root of your package, npm will +treat each line as a <code>Name <email> (url)</code> format, where email and url +are optional. Lines which start with a <code>#</code> or are blank, will be +ignored.</p></li></ul> + +<h2 id="name">name</h2> + +<p>The <em>most</em> important things in your package.json are the name and version fields. +Those are actually required, and your package won't install without +them. The name and version together form an identifier that is assumed +to be completely unique. Changes to the package should come along with +changes to the version.</p> + +<p>The name is what your thing is called. Some tips:</p> + +<ul><li>Don't put "js" or "node" in the name. It's assumed that it's js, since you're +writing a package.json file, and you can specify the engine using the "engines" +field. (See below.)</li><li>The name ends up being part of a URL, an argument on the command line, and a +folder name. Any name with non-url-safe characters will be rejected. +Also, it can't start with a dot or an underscore.</li><li>The name will probably be passed as an argument to require(), so it should +be something short, but also reasonably descriptive.</li><li>You may want to check the npm registry to see if there's something by that name +already, before you get too attached to it. http://registry.npmjs.org/</li></ul> + +<h2 id="version">version</h2> + +<p>The <em>most</em> important things in your package.json are the name and version fields. +Those are actually required, and your package won't install without +them. The name and version together form an identifier that is assumed +to be completely unique. Changes to the package should come along with +changes to the version.</p> + +<p>Version must be parseable by +<a href="https://github.com/isaacs/node-semver">node-semver</a>, which is bundled +with npm as a dependency. (<code>npm install semver</code> to use it yourself.)</p> + +<p>Here's how npm's semver implementation deviates from what's on semver.org:</p> + +<ul><li>Versions can start with "v"</li><li>A numeric item separated from the main three-number version by a hyphen +will be interpreted as a "build" number, and will <em>increase</em> the version. +But, if the tag is not a number separated by a hyphen, then it's treated +as a pre-release tag, and is <em>less than</em> the version without a tag. +So, <code>0.1.2-7 > 0.1.2-7-beta > 0.1.2-6 > 0.1.2 > 0.1.2beta</code></li></ul> + +<p>This is a little bit confusing to explain, but matches what you see in practice +when people create tags in git like "v1.2.3" and then do "git describe" to generate +a patch version.</p> + +<h2 id="description">description</h2> + +<p>Put a description in it. It's a string. This helps people discover your +package, as it's listed in <code>npm search</code>.</p> + +<h2 id="keywords">keywords</h2> + +<p>Put keywords in it. It's an array of strings. This helps people +discover your package as it's listed in <code>npm search</code>.</p> + +<h2 id="homepage">homepage</h2> + +<p>The url to the project homepage.</p> + +<p><strong>NOTE</strong>: This is <em>not</em> the same as "url". If you put a "url" field, +then the registry will think it's a redirection to your package that has +been published somewhere else, and spit at you.</p> + +<p>Literally. Spit. I'm so not kidding.</p> + +<h2 id="bugs">bugs</h2> + +<p>The url to your project's issue tracker and / or the email address to which +issues should be reported. These are helpful for people who encounter issues +with your package.</p> + +<p>It should look like this:</p> + +<pre><code>{ "url" : "http://github.com/owner/project/issues" +, "email" : "project@hostname.com" +}</code></pre> + +<p>You can specify either one or both values. If you want to provide only a url, +you can specify the value for "bugs" as a simple string instead of an object.</p> + +<p>If a url is provided, it will be used by the <code>npm bugs</code> command.</p> + +<h2 id="license">license</h2> + +<p>You should specify a license for your package so that people know how they are +permitted to use it, and any restrictions you're placing on it.</p> + +<p>The simplest way, assuming you're using a common license such as BSD or MIT, is +to just specify the name of the license you're using, like this:</p> + +<pre><code>{ "license" : "BSD" }</code></pre> + +<p>If you have more complex licensing terms, or you want to provide more detail +in your package.json file, you can use the more verbose plural form, like this:</p> + +<pre><code>"licenses" : [ + { "type" : "MyLicense" + , "url" : "http://github.com/owner/project/path/to/license" + } +]</code></pre> + +<p>It's also a good idea to include a license file at the top level in your package.</p> + +<h2 id="people-fields-author-contributors">people fields: author, contributors</h2> + +<p>The "author" is one person. "contributors" is an array of people. A "person" +is an object with a "name" field and optionally "url" and "email", like this:</p> + +<pre><code>{ "name" : "Barney Rubble" +, "email" : "b@rubble.com" +, "url" : "http://barnyrubble.tumblr.com/" +}</code></pre> + +<p>Or you can shorten that all into a single string, and npm will parse it for you:</p> + +<pre><code>"Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)</code></pre> + +<p>Both email and url are optional either way.</p> + +<p>npm also sets a top-level "maintainers" field with your npm user info.</p> + +<h2 id="files">files</h2> + +<p>The "files" field is an array of files to include in your project. If +you name a folder in the array, then it will also include the files +inside that folder. (Unless they would be ignored by another rule.)</p> + +<p>You can also provide a ".npmignore" file in the root of your package, +which will keep files from being included, even if they would be picked +up by the files array. The ".npmignore" file works just like a +".gitignore".</p> + +<h2 id="main">main</h2> + +<p>The main field is a module ID that is the primary entry point to your program. +That is, if your package is named <code>foo</code>, and a user installs it, and then does +<code>require("foo")</code>, then your main module's exports object will be returned.</p> + +<p>This should be a module ID relative to the root of your package folder.</p> + +<p>For most modules, it makes the most sense to have a main script and often not +much else.</p> + +<h2 id="bin">bin</h2> + +<p>A lot of packages have one or more executable files that they'd like to +install into the PATH. npm makes this pretty easy (in fact, it uses this +feature to install the "npm" executable.)</p> + +<p>To use this, supply a <code>bin</code> field in your package.json which is a map of +command name to local file name. On install, npm will symlink that file into +<code>prefix/bin</code> for global installs, or <code>./node_modules/.bin/</code> for local +installs.</p> + +<p>For example, npm has this:</p> + +<pre><code>{ "bin" : { "npm" : "./cli.js" } }</code></pre> + +<p>So, when you install npm, it'll create a symlink from the <code>cli.js</code> script to +<code>/usr/local/bin/npm</code>.</p> + +<p>If you have a single executable, and its name should be the name +of the package, then you can just supply it as a string. For example:</p> + +<pre><code>{ "name": "my-program" +, "version": "1.2.5" +, "bin": "./path/to/program" }</code></pre> + +<p>would be the same as this:</p> + +<pre><code>{ "name": "my-program" +, "version": "1.2.5" +, "bin" : { "my-program" : "./path/to/program" } }</code></pre> + +<h2 id="man">man</h2> + +<p>Specify either a single file or an array of filenames to put in place for the +<code>man</code> program to find.</p> + +<p>If only a single file is provided, then it's installed such that it is the +result from <code>man <pkgname></code>, regardless of its actual filename. For example:</p> + +<pre><code>{ "name" : "foo" +, "version" : "1.2.3" +, "description" : "A packaged foo fooer for fooing foos" +, "main" : "foo.js" +, "man" : "./man/doc.1" +}</code></pre> + +<p>would link the <code>./man/doc.1</code> file in such that it is the target for <code>man foo</code></p> + +<p>If the filename doesn't start with the package name, then it's prefixed. +So, this:</p> + +<pre><code>{ "name" : "foo" +, "version" : "1.2.3" +, "description" : "A packaged foo fooer for fooing foos" +, "main" : "foo.js" +, "man" : [ "./man/foo.1", "./man/bar.1" ] +}</code></pre> + +<p>will create files to do <code>man foo</code> and <code>man foo-bar</code>.</p> + +<p>Man files must end with a number, and optionally a <code>.gz</code> suffix if they are +compressed. The number dictates which man section the file is installed into.</p> + +<pre><code>{ "name" : "foo" +, "version" : "1.2.3" +, "description" : "A packaged foo fooer for fooing foos" +, "main" : "foo.js" +, "man" : [ "./man/foo.1", "./man/foo.2" ] +}</code></pre> + +<p>will create entries for <code>man foo</code> and <code>man 2 foo</code></p> + +<h2 id="directories">directories</h2> + +<p>The CommonJS <a href="http://wiki.commonjs.org/wiki/Packages/1.0">Packages</a> spec details a +few ways that you can indicate the structure of your package using a <code>directories</code> +hash. If you look at <a href="http://registry.npmjs.org/npm/latest">npm's package.json</a>, +you'll see that it has directories for doc, lib, and man.</p> + +<p>In the future, this information may be used in other creative ways.</p> + +<h3 id="directories-lib">directories.lib</h3> + +<p>Tell people where the bulk of your library is. Nothing special is done +with the lib folder in any way, but it's useful meta info.</p> + +<h3 id="directories-bin">directories.bin</h3> + +<p>If you specify a "bin" directory, then all the files in that folder will +be used as the "bin" hash.</p> + +<p>If you have a "bin" hash already, then this has no effect.</p> + +<h3 id="directories-man">directories.man</h3> + +<p>A folder that is full of man pages. Sugar to generate a "man" array by +walking the folder.</p> + +<h3 id="directories-doc">directories.doc</h3> + +<p>Put markdown files in here. Eventually, these will be displayed nicely, +maybe, someday.</p> + +<h3 id="directories-example">directories.example</h3> + +<p>Put example scripts in here. Someday, it might be exposed in some clever way.</p> + +<h2 id="repository">repository</h2> + +<p>Specify the place where your code lives. This is helpful for people who +want to contribute. If the git repo is on github, then the <code>npm docs</code> +command will be able to find you.</p> + +<p>Do it like this:</p> + +<pre><code>"repository" : + { "type" : "git" + , "url" : "http://github.com/isaacs/npm.git" + } + +"repository" : + { "type" : "svn" + , "url" : "http://v8.googlecode.com/svn/trunk/" + }</code></pre> + +<p>The URL should be a publicly available (perhaps read-only) url that can be handed +directly to a VCS program without any modification. It should not be a url to an +html project page that you put in your browser. It's for computers.</p> + +<h2 id="scripts">scripts</h2> + +<p>The "scripts" member is an object hash of script commands that are run +at various times in the lifecycle of your package. The key is the lifecycle +event, and the value is the command to run at that point.</p> + +<p>See <code><a href="../misc/npm-scripts.html">npm-scripts(7)</a></code> to find out more about writing package scripts.</p> + +<h2 id="config">config</h2> + +<p>A "config" hash can be used to set configuration +parameters used in package scripts that persist across upgrades. For +instance, if a package had the following:</p> + +<pre><code>{ "name" : "foo" +, "config" : { "port" : "8080" } }</code></pre> + +<p>and then had a "start" command that then referenced the +<code>npm_package_config_port</code> environment variable, then the user could +override that by doing <code>npm config set foo:port 8001</code>.</p> + +<p>See <code><a href="../misc/npm-config.html">npm-config(7)</a></code> and <code><a href="../misc/npm-scripts.html">npm-scripts(7)</a></code> for more on package +configs.</p> + +<h2 id="dependencies">dependencies</h2> + +<p>Dependencies are specified with a simple hash of package name to version +range. The version range is EITHER a string which has one or more +space-separated descriptors, OR a range like "fromVersion - toVersion"</p> + +<p><strong>Please do not put test harnesses in your <code>dependencies</code> hash.</strong> See +<code>devDependencies</code>, below.</p> + +<p>Version range descriptors may be any of the following styles, where "version" +is a semver compatible version identifier.</p> + +<ul><li><code>version</code> Must match <code>version</code> exactly</li><li><code>=version</code> Same as just <code>version</code></li><li><code>>version</code> Must be greater than <code>version</code></li><li><code>>=version</code> etc</li><li><code><version</code></li><li><code><=version</code></li><li><code>~version</code> See 'Tilde Version Ranges' below</li><li><code>1.2.x</code> See 'X Version Ranges' below</li><li><code>http://...</code> See 'URLs as Dependencies' below</li><li><code>*</code> Matches any version</li><li><code>""</code> (just an empty string) Same as <code>*</code></li><li><code>version1 - version2</code> Same as <code>>=version1 <=version2</code>.</li><li><code>range1 || range2</code> Passes if either range1 or range2 are satisfied.</li><li><code>git...</code> See 'Git URLs as Dependencies' below</li></ul> + +<p>For example, these are all valid:</p> + +<pre><code>{ "dependencies" : + { "foo" : "1.0.0 - 2.9999.9999" + , "bar" : ">=1.0.2 <2.1.2" + , "baz" : ">1.0.2 <=2.3.4" + , "boo" : "2.0.1" + , "qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0" + , "asd" : "http://asdf.com/asdf.tar.gz" + , "til" : "~1.2" + , "elf" : "~1.2.3" + , "two" : "2.x" + , "thr" : "3.3.x" + } +}</code></pre> + +<h3 id="Tilde-Version-Ranges">Tilde Version Ranges</h3> + +<p>A range specifier starting with a tilde <code>~</code> character is matched against +a version in the following fashion.</p> + +<ul><li>The version must be at least as high as the range.</li><li>The version must be less than the next major revision above the range.</li></ul> + +<p>For example, the following are equivalent:</p> + +<ul><li><code>"~1.2.3" = ">=1.2.3 <1.3.0"</code></li><li><code>"~1.2" = ">=1.2.0 <1.3.0"</code></li><li><code>"~1" = ">=1.0.0 <1.1.0"</code></li></ul> + +<h3 id="X-Version-Ranges">X Version Ranges</h3> + +<p>An "x" in a version range specifies that the version number must start +with the supplied digits, but any digit may be used in place of the x.</p> + +<p>The following are equivalent:</p> + +<ul><li><code>"1.2.x" = ">=1.2.0 <1.3.0"</code></li><li><code>"1.x.x" = ">=1.0.0 <2.0.0"</code></li><li><code>"1.2" = "1.2.x"</code></li><li><code>"1.x" = "1.x.x"</code></li><li><code>"1" = "1.x.x"</code></li></ul> + +<p>You may not supply a comparator with a version containing an x. Any +digits after the first "x" are ignored.</p> + +<h3 id="URLs-as-Dependencies">URLs as Dependencies</h3> + +<p>Starting with npm version 0.2.14, you may specify a tarball URL in place +of a version range.</p> + +<p>This tarball will be downloaded and installed locally to your package at +install time.</p> + +<h3 id="Git-URLs-as-Dependencies">Git URLs as Dependencies</h3> + +<p>Git urls can be of the form:</p> + +<pre><code>git://github.com/user/project.git#commit-ish +git+ssh://user@hostname:project.git#commit-ish +git+ssh://user@hostname/project.git#commit-ish +git+http://user@hostname/project/blah.git#commit-ish +git+https://user@hostname/project/blah.git#commit-ish</code></pre> + +<p>The <code>commit-ish</code> can be any tag, sha, or branch which can be supplied as +an argument to <code>git checkout</code>. The default is <code>master</code>.</p> + +<h2 id="devDependencies">devDependencies</h2> + +<p>If someone is planning on downloading and using your module in their +program, then they probably don't want or need to download and build +the external test or documentation framework that you use.</p> + +<p>In this case, it's best to list these additional items in a +<code>devDependencies</code> hash.</p> + +<p>These things will be installed whenever the <code>--dev</code> configuration flag +is set. This flag is set automatically when doing <code>npm link</code> or when doing +<code>npm install</code> from the root of a package, and can be managed like any other npm +configuration param. See <code><a href="../misc/npm-config.html">npm-config(7)</a></code> for more on the topic.</p> + +<h2 id="bundledDependencies">bundledDependencies</h2> + +<p>Array of package names that will be bundled when publishing the package.</p> + +<p>If this is spelled <code>"bundleDependencies"</code>, then that is also honorable.</p> + +<h2 id="optionalDependencies">optionalDependencies</h2> + +<p>If a dependency can be used, but you would like npm to proceed if it +cannot be found or fails to install, then you may put it in the +<code>optionalDependencies</code> hash. This is a map of package name to version +or url, just like the <code>dependencies</code> hash. The difference is that +failure is tolerated.</p> + +<p>It is still your program's responsibility to handle the lack of the +dependency. For example, something like this:</p> + +<pre><code>try { + var foo = require('foo') + var fooVersion = require('foo/package.json').version +} catch (er) { + foo = null +} +if ( notGoodFooVersion(fooVersion) ) { + foo = null +} + +// .. then later in your program .. + +if (foo) { + foo.doFooThings() +}</code></pre> + +<p>Entries in <code>optionalDependencies</code> will override entries of the same name in +<code>dependencies</code>, so it's usually best to only put in one place.</p> + +<h2 id="engines">engines</h2> + +<p>You can specify the version of node that your stuff works on:</p> + +<pre><code>{ "engines" : { "node" : ">=0.1.27 <0.1.30" } }</code></pre> + +<p>And, like with dependencies, if you don't specify the version (or if you +specify "*" as the version), then any version of node will do.</p> + +<p>If you specify an "engines" field, then npm will require that "node" be +somewhere on that list. If "engines" is omitted, then npm will just assume +that it works on node.</p> + +<p>You can also use the "engines" field to specify which versions of npm +are capable of properly installing your program. For example:</p> + +<pre><code>{ "engines" : { "npm" : "~1.0.20" } }</code></pre> + +<p>Note that, unless the user has set the <code>engine-strict</code> config flag, this +field is advisory only.</p> + +<h2 id="engineStrict">engineStrict</h2> + +<p>If you are sure that your module will <em>definitely not</em> run properly on +versions of Node/npm other than those specified in the <code>engines</code> hash, +then you can set <code>"engineStrict": true</code> in your package.json file. +This will override the user's <code>engine-strict</code> config setting.</p> + +<p>Please do not do this unless you are really very very sure. If your +engines hash is something overly restrictive, you can quite easily and +inadvertently lock yourself into obscurity and prevent your users from +updating to new versions of Node. Consider this choice carefully. If +people abuse it, it will be removed in a future version of npm.</p> + +<h2 id="os">os</h2> + +<p>You can specify which operating systems your +module will run on:</p> + +<pre><code>"os" : [ "darwin", "linux" ]</code></pre> + +<p>You can also blacklist instead of whitelist operating systems, +just prepend the blacklisted os with a '!':</p> + +<pre><code>"os" : [ "!win32" ]</code></pre> + +<p>The host operating system is determined by <code>process.platform</code></p> + +<p>It is allowed to both blacklist, and whitelist, although there isn't any +good reason to do this.</p> + +<h2 id="cpu">cpu</h2> + +<p>If your code only runs on certain cpu architectures, +you can specify which ones.</p> + +<pre><code>"cpu" : [ "x64", "ia32" ]</code></pre> + +<p>Like the <code>os</code> option, you can also blacklist architectures:</p> + +<pre><code>"cpu" : [ "!arm", "!mips" ]</code></pre> + +<p>The host architecture is determined by <code>process.arch</code></p> + +<h2 id="preferGlobal">preferGlobal</h2> + +<p>If your package is primarily a command-line application that should be +installed globally, then set this value to <code>true</code> to provide a warning +if it is installed locally.</p> + +<p>It doesn't actually prevent users from installing it locally, but it +does help prevent some confusion if it doesn't work as expected.</p> + +<h2 id="private">private</h2> + +<p>If you set <code>"private": true</code> in your package.json, then npm will refuse +to publish it.</p> + +<p>This is a way to prevent accidental publication of private repositories. +If you would like to ensure that a given package is only ever published +to a specific registry (for example, an internal registry), +then use the <code>publishConfig</code> hash described below +to override the <code>registry</code> config param at publish-time.</p> + +<h2 id="publishConfig">publishConfig</h2> + +<p>This is a set of config values that will be used at publish-time. It's +especially handy if you want to set the tag or registry, so that you can +ensure that a given package is not tagged with "latest" or published to +the global public registry by default.</p> + +<p>Any config values can be overridden, but of course only "tag" and +"registry" probably matter for the purposes of publishing.</p> + +<p>See <code><a href="../misc/npm-config.html">npm-config(7)</a></code> to see the list of config options that can be +overridden.</p> + +<h2 id="SEE-ALSO">SEE ALSO</h2> + +<ul><li><a href="../misc/npm-semver.html">npm-semver(7)</a></li><li><a href="../cli/npm-init.html">npm-init(1)</a></li><li><a href="../cli/npm-version.html">npm-version(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="../cli/npm-help.html">npm-help(1)</a></li><li><a href="../misc/npm-faq.html">npm-faq(7)</a></li><li><a href="../cli/npm-install.html">npm-install(1)</a></li><li><a href="../cli/npm-publish.html">npm-publish(1)</a></li><li><a href="../cli/npm-rm.html">npm-rm(1)</a></li></ul> +</div> +<p id="footer">package.json — npm@1.3.3</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> |