diff options
Diffstat (limited to 'deps/node/deps/npm/man/man5/npm-global.5')
| -rw-r--r-- | deps/node/deps/npm/man/man5/npm-global.5 | 226 |
1 files changed, 226 insertions, 0 deletions
diff --git a/deps/node/deps/npm/man/man5/npm-global.5 b/deps/node/deps/npm/man/man5/npm-global.5 new file mode 100644 index 00000000..0fa03d97 --- /dev/null +++ b/deps/node/deps/npm/man/man5/npm-global.5 @@ -0,0 +1,226 @@ +.TH "NPM\-FOLDERS" "5" "January 2019" "" "" +.SH "NAME" +\fBnpm-folders\fR \- Folder Structures Used by npm +.SH DESCRIPTION +.P +npm puts various things on your computer\. That's its job\. +.P +This document will tell you what it puts where\. +.SS tl;dr +.RS 0 +.IP \(bu 2 +Local install (default): puts stuff in \fB\|\./node_modules\fP of the current +package root\. +.IP \(bu 2 +Global install (with \fB\-g\fP): puts stuff in /usr/local or wherever node +is installed\. +.IP \(bu 2 +Install it \fBlocally\fR if you're going to \fBrequire()\fP it\. +.IP \(bu 2 +Install it \fBglobally\fR if you're going to run it on the command line\. +.IP \(bu 2 +If you need both, then install it in both places, or use \fBnpm link\fP\|\. + +.RE +.SS prefix Configuration +.P +The \fBprefix\fP config defaults to the location where node is installed\. +On most systems, this is \fB/usr/local\fP\|\. On Windows, it's \fB%AppData%\\npm\fP\|\. +On Unix systems, it's one level up, since node is typically installed at +\fB{prefix}/bin/node\fP rather than \fB{prefix}/node\.exe\fP\|\. +.P +When the \fBglobal\fP 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\. +.SS Node Modules +.P +Packages are dropped into the \fBnode_modules\fP folder under the \fBprefix\fP\|\. +When installing locally, this means that you can +\fBrequire("packagename")\fP to load its main module, or +\fBrequire("packagename/lib/path/to/sub/module")\fP to load other modules\. +.P +Global installs on Unix systems go to \fB{prefix}/lib/node_modules\fP\|\. +Global installs on Windows go to \fB{prefix}/node_modules\fP (that is, no +\fBlib\fP folder\.) +.P +Scoped packages are installed the same way, except they are grouped together +in a sub\-folder of the relevant \fBnode_modules\fP folder with the name of that +scope prefix by the @ symbol, e\.g\. \fBnpm install @myorg/package\fP would place +the package in \fB{prefix}/node_modules/@myorg/package\fP\|\. See npm help 7 \fBscope\fP for +more details\. +.P +If you wish to \fBrequire()\fP a package, then install it locally\. +.SS Executables +.P +When in global mode, executables are linked into \fB{prefix}/bin\fP on Unix, +or directly into \fB{prefix}\fP on Windows\. +.P +When in local mode, executables are linked into +\fB\|\./node_modules/\.bin\fP 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 \fBnpm test\fP\|\.) +.SS Man Pages +.P +When in global mode, man pages are linked into \fB{prefix}/share/man\fP\|\. +.P +When in local mode, man pages are not installed\. +.P +Man pages are not installed on Windows systems\. +.SS Cache +.P +See npm help \fBnpm\-cache\fP\|\. Cache files are stored in \fB~/\.npm\fP on Posix, or +\fB%AppData%/npm\-cache\fP on Windows\. +.P +This is controlled by the \fBcache\fP configuration param\. +.SS Temp Files +.P +Temporary files are stored by default in the folder specified by the +\fBtmp\fP config, which defaults to the TMPDIR, TMP, or TEMP environment +variables, or \fB/tmp\fP on Unix and \fBc:\\windows\\temp\fP on Windows\. +.P +Temp files are given a unique folder under this root for each run of the +program, and are deleted upon successful exit\. +.SH More Information +.P +When installing locally, npm first tries to find an appropriate +\fBprefix\fP folder\. This is so that \fBnpm install foo@1\.2\.3\fP will install +to the sensible root of your package, even if you happen to have \fBcd\fPed +into some other folder\. +.P +Starting at the $PWD, npm will walk up the folder tree checking for a +folder that contains either a \fBpackage\.json\fP file, or a \fBnode_modules\fP +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 +If no package root is found, then the current folder is used\. +.P +When you run \fBnpm install foo@1\.2\.3\fP, then the package is loaded into +the cache, and then unpacked into \fB\|\./node_modules/foo\fP\|\. Then, any of +foo's dependencies are similarly unpacked into +\fB\|\./node_modules/foo/node_modules/\.\.\.\fP\|\. +.P +Any bin files are symlinked to \fB\|\./node_modules/\.bin/\fP, so that they may +be found by npm scripts when necessary\. +.SS Global Installation +.P +If the \fBglobal\fP configuration is set to true, then npm will +install packages "globally"\. +.P +For global installation, packages are installed roughly the same way, +but using the folders described above\. +.SS Cycles, Conflicts, and Folder Parsimony +.P +Cycles are handled using the property of node's module system that it +walks up the directories looking for \fBnode_modules\fP folders\. So, at every +stage, if a package is already installed in an ancestor \fBnode_modules\fP +folder, then it is not installed at the current location\. +.P +Consider the case above, where \fBfoo \-> bar \-> baz\fP\|\. Imagine if, in +addition to that, baz depended on bar, so you'd have: +\fBfoo \-> bar \-> baz \-> bar \-> baz \.\.\.\fP\|\. However, since the folder +structure is: \fBfoo/node_modules/bar/node_modules/baz\fP, there's no need to +put another copy of bar into \fB\|\.\.\./baz/node_modules\fP, since when it calls +require("bar"), it will get the copy that is installed in +\fBfoo/node_modules/bar\fP\|\. +.P +This shortcut is only used if the exact same +version would be installed in multiple nested \fBnode_modules\fP folders\. It +is still possible to have \fBa/node_modules/b/node_modules/a\fP 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 +Another optimization can be made by installing dependencies at the +highest level possible, below the localized "target" folder\. +.SS Example +.P +Consider this dependency graph: +.P +.RS 2 +.nf +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 +.fi +.RE +.P +In this case, we might expect a folder structure like this: +.P +.RS 2 +.nf +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] +.fi +.RE +.P +Since foo depends directly on \fBand\fP\fB, those are +installed in foo's\fPnode_modules` folder\. +.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 `, +it does not install another copy under [B]\. +.P +Bar [B] also has dependencies on baz and asdf, so those are installed in +bar's \fBnode_modules\fP folder\. Because it depends on \fB, it cannot +re\-use the\fP\fBinstalled in the parent\fPnode_modules` folder [D], +and must install its own copy [C]\. +.P +Underneath bar, the \fBbaz \-> quux \-> bar\fP 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 +Underneath \fBfoo \-> baz\fP [D], quux's [E] folder tree is empty, because its +dependency on bar is satisfied by the parent folder copy installed at [B]\. +.P +For a graphical breakdown of what is installed where, use \fBnpm ls\fP\|\. +.SS Publishing +.P +Upon publishing, npm will look in the \fBnode_modules\fP folder\. If any of +the items there are not in the \fBbundledDependencies\fP array, then they will +not be included in the package tarball\. +.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 npm help 5 \fBpackage\.json\fP for more information\. +.SH SEE ALSO +.RS 0 +.IP \(bu 2 +npm help 5 package\.json +.IP \(bu 2 +npm help install +.IP \(bu 2 +npm help pack +.IP \(bu 2 +npm help cache +.IP \(bu 2 +npm help config +.IP \(bu 2 +npm help 5 npmrc +.IP \(bu 2 +npm help 7 config +.IP \(bu 2 +npm help publish + +.RE + |