diff options
Diffstat (limited to 'deps/npm/man/man5/npm-folders.5')
-rw-r--r-- | deps/npm/man/man5/npm-folders.5 | 226 |
1 files changed, 0 insertions, 226 deletions
diff --git a/deps/npm/man/man5/npm-folders.5 b/deps/npm/man/man5/npm-folders.5 deleted file mode 100644 index 2da094fcc6..0000000000 --- a/deps/npm/man/man5/npm-folders.5 +++ /dev/null @@ -1,226 +0,0 @@ -.TH "NPM\-FOLDERS" "5" "October 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 \fBbar@1\.2\.3\fP and \fBbaz@1\.2\.3\fP, those are -installed in foo's \fBnode_modules\fP 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 \fBblerg@1\.x\fP, -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 \fBbaz@2\.x\fP, it cannot -re\-use the \fBbaz@1\.2\.3\fP installed in the parent \fBnode_modules\fP 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 - |