diff options
Diffstat (limited to 'man1/folders.1')
| -rw-r--r-- | man1/folders.1 | 86 |
1 files changed, 50 insertions, 36 deletions
diff --git a/man1/folders.1 b/man1/folders.1 index e6a660173..4ee926e9f 100644 --- a/man1/folders.1 +++ b/man1/folders.1 @@ -12,6 +12,22 @@ npm puts various things on your computer\. That\'s its job\. .P This document will tell you what it puts where\. . +.SS "tl;dr" +. +.IP "\(bu" 4 +Local install (default): puts stuff in \./node_modules +. +.IP "\(bu" 4 +Global install (with \fB\-g\fR): puts stuff in /usr/local +. +.IP "\(bu" 4 +Install it \fBlocally\fR if you\'re going to \fBrequire()\fR it\. +. +.IP "\(bu" 4 +Install it \fBglobally\fR if you\'re going to run it on the command line\. +. +.IP "" 0 +. .SS "prefix Configuration" The \fBprefix\fR config defaults to node\'s \fBprocess\.installPrefix\fR\|\. On most systems, this is \fB/usr/local\fR\|\. @@ -23,11 +39,10 @@ current working directory if not in a package already\. . .SS "Node Modules" Packages are dropped into the \fBnode_modules\fR folder under the \fBprefix\fR\|\. -When installing locally, this means that you can \fBrequire("packagename")\fR to load its main module, or \fBrequire("packagename/path/to/sub/module")\fR to load other modules\. +When installing locally, this means that you can \fBrequire("packagename")\fR to load its main module, or \fBrequire("packagename/lib/path/to/sub/module")\fR to load other modules\. . .P -If you wish to install node modules globally which can be loaded via \fBrequire()\fR from anywhere, then add the \fBprefix/node_modules\fR folder to -your NODE_PATH environment variable\. +If you wish to \fBrequire()\fR a package, then install it locally\. . .SS "Executables" When in global mode, executables are linked into \fBprefix/bin\fR\|\. @@ -39,7 +54,7 @@ When in local mode, executables are linked into \fBprefix/node_modules/\.bin\fR\ When in global mode, man pages are linked into \fBprefix/share/man\fR\|\. . .P -When in local node, man pages are not installed\. +When in local mode, man pages are not installed\. . .SS "Cache" See \fBnpm help cache\fR\|\. Cache files are stored in \fB~/\.npm\fR on Posix, or \fB~/npm\-cache\fR on Windows\. @@ -56,28 +71,29 @@ 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" -When you run \fBnpm install foo@1\.2\.3\fR it downloads and builds the -package, and then, if there is a package\.json file in the current -working directory, it copies it to \fB$PWD/node_modules/foo\fR, so that your -current package will get it when you do \fBrequire("foo")\fR\|\. +When doing local installings, npm first tries to find an appropriate \fBprefix\fR folder\. This is so that \fBnpm install foo@1\.2\.3\fR will install +to the sensible root of your package, even if you happen to have \fBcd\fRed +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\fR file, or a \fBnode_modules\fR +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 -When this is done, it also installs all of foo\'s dependencies to \fB\|\./node_modules/foo/node_modules/\fR, so that it will get its dependencies -appropriately when it calls \fBrequire()\fR\|\. If foo depends on bar, and bar -depends on baz, then there will also be a \fB\|\./node_modules/foo/node_modules/bar/node_modules/baz\fR, and so on\. +If no package root is found, then the current folder is used\. . .P -If there is not a package\.json in the current working directory, then -npm walks up the working dir parent paths looking for a package\.json, -indicating the root of a package, or a node_modules folder, -indicating an npm package deployment location, and then take the party to that -location\. This behavior may be suppressed by setting the \fBseek\-root\fR -config value to false\. +When you run \fBnpm install foo@1\.2\.3\fR, then the package is loaded into +the cache, and then unpacked into \fB\|\./node_modules/foo\fR\|\. Then, any of +foo\'s dependencies are similarly unpacked into \fB\|\./node_modules/foo/node_modules/\.\.\.\fR\|\. . .P -If no package root is found, then a global installation is performed\. -The global installation may be supressed by setting the \fBglobal\fR -configuration to false, in which case, the install will fail\. +Any bin files are symlinked to \fB\|\./node_modules/\.bin/\fR, so that they may +be found by npm scripts when necessary\. . .SS "Global Installation" If the \fBglobal\fR configuration is set to true, or if it is not explicitly @@ -85,8 +101,9 @@ set false and no suitable node_modules folder was found, then npm will install packages "globally"\. . .P -This means that the module contents are symlinked (or, on windows, -copied) from \fBroot/<name>/<version>/package\fR to \fBroot/node_modules/<name>\fR\|\. +For global installation, packages are installed roughly the same way, +but the module root is \fB/usr/local/lib/node_modules\fR, and bin files are +linked to \fB/usr/local/bin\fR instead of \fB\|\./node_modules/\.bin\fR\|\. . .SS "Cycles, Conflicts, and Folder Parsimony" Cycles are handled using the property of node\'s module system that it @@ -142,19 +159,15 @@ In this case, we might expect a folder structure like this: .nf foo +\-\- node_modules - +\-\- bar (1\.2\.3) + +\-\- bar (1\.2\.3) <\-\-\-[A] | +\-\- node_modules - | | `\-\- baz (2\.0\.2) + | | `\-\- baz (2\.0\.2) <\-\-\-[B] | | `\-\- node_modules | | `\-\- quux (3\.2\.0) | `\-\- asdf (2\.3\.4) - `\-\- baz (1\.2\.3) + `\-\- baz (1\.2\.3) <\-\-\-[C] `\-\- node_modules - `\-\- quux (3\.2\.0) - `\-\- node_modules - `\-\- bar (1\.2\.3) - `\-\- node_modules - `\-\- asdf (2\.3\.4) + `\-\- quux (3\.2\.0) <\-\-\-[D] . .fi . @@ -165,18 +178,19 @@ Since foo depends directly on bar@1\.2\.3 and baz@1\.2\.3, those are installed in foo\'s node_modules folder\. . .P -Bar has dependencies on baz and asdf, so those are installed in bar\'s -node\fImodules folder\. Baz has a dependency on quux, so that is installed -in its node\fRmodules folder\. +Bar [A] has dependencies on baz and asdf, so those are installed in bar\'s +node\fImodules folder\. Because it depends on \fBbaz@2\.x\fR, it cannot re\-use +the \fBbaz@1\.2\.3\fR installed in the parent node\fRmodules folder [C], and +must install its own copy [B]\. . .P Underneath bar, the \fBbaz\->quux\->bar\fR dependency creates a cycle\. -However, because \fBbar\fR is already in \fBquux\fR\'s ancestry, it does not +However, because \fBbar\fR is already in \fBquux\fR\'s ancestry [A], it does not unpack another copy of bar into that folder\. . .P -Similarly, underneath \fBfoo\->baz\fR, the same cycle is gradually prevented -because \fBbar\fR\'s \fBquux\fR dependency is satisfied by its parent folder\. +Underneath \fBfoo\->baz\fR [C], quux\'s [D] folder tree is empty, because its +dependnecy on bar is satisfied by the parent folder copy installed at [A]\. . .P For a graphical breakdown of what is installed where, use \fBnpm ls\fR\|\. |