diff options
Diffstat (limited to 'man1/folders.1')
-rw-r--r-- | man1/folders.1 | 190 |
1 files changed, 132 insertions, 58 deletions
diff --git a/man1/folders.1 b/man1/folders.1 index 39f06ac63..d07337381 100644 --- a/man1/folders.1 +++ b/man1/folders.1 @@ -7,113 +7,187 @@ \fBnpm-folders\fR \-\- Folder Structures Used by npm . .SH "DESCRIPTION" -Node modules and metadata live -in the \fBroot\fR setting\. Check \fBnpm help config\fR for more -on configuration options\. +npm puts various things on your computer\. That\'s its job\. . .P -\fBroot/foo\fR Symlink to the active version\'s module folder\. +This document will tell you what it puts where\. . -.P -\fBroot/foo@1\.0\.0/\fR Node modules for the foo package\. +.SS "prefix Configuration" +The \fBprefix\fR config defaults to node\'s \fBprocess\.installPrefix\fR\|\. On most +systems, this is \fB/usr/local\fR\|\. . .P -\fBroot/foo@1\.0\.0/{module\-name}\.js\fR Generated shim corresponding to a module -defined in the modules option\. The module shim requires \fBroot/\.npm/foo/1\.0\.0/package/{module\-path}\.js\fR +When the \fBglobal\fR 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 -The \fBmain\fR script is implemented by creating an \fBindex\.js\fR file in this folder\. +.SS "Node Modules" +Packages are droped 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\. . .P -\fBroot/\.npm/foo\fR is where the stuff for package \fBfoo\fR would go\. +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\. . -.P -\fBroot/\.npm/foo/1\.0\.0/package\fR the contents of the tarball containing foo -version 1\.0\.0 +.SS "Executables" +When in global mode, executables are linked into \fBprefix/bin\fR\|\. . .P -\fBroot/\.npm/foo/1\.0\.0/main\.js\fR Generated file that exports the \fBmain\fR module in -foo\. This is a shim, not a symbolic link, so that relative paths will work -appropriately\. +When in local mode, executables are linked into \fBprefix/node_modules/\.bin\fR\|\. . -.P -\fBroot/\.npm/foo/active\fR symlink to the active version\. +.SS "Man Pages" +When in global mode, man pages are linked into \fBprefix/share/man\fR\|\. . .P -\fBroot/\.npm/foo/1\.0\.0/node_modules\fR links to the modules that foo depends upon\. -This is loaded into the require path first in the foo shims\. +When in local node, man pages are not installed\. . -.P -\fBroot/\.npm/foo/1\.0\.0/dependson\fR links to the package folders that foo depends -on\. This is here so that npm can access those packages programmatically\. +.SS "Cache" +See \fBnpm help cache\fR\|\. Cache files are stored in \fB~/\.npm\fR on Posix, or \fB~/npm\-cache\fR on Windows\. . .P -\fBroot/\.npm/foo/1\.0\.0/dependents\fR links to the packages that depend upon foo\. +This is controlled by the \fBcache\fR configuration param\. . -.P -\fBroot/\.npm/\.cache\fR the cache folder\. +.SS "Temp Files" +Temporary files are stored by default in the folder specified by the \fBtmp\fR config, which defaults to either the TMPDIR environment +variable, or \fB/tmp\fR\|\. . .P -\fBroot/\.npm/\.cache/foo/1\.0\.0/package\.json\fR the parsed package\.json for foo@1\.0\.0 +Temp files are given a unique folder under this root for each run of the +program, and are deleted upon successful exit\. . -.P -\fBroot/\.npm/\.cache/foo/1\.0\.0/package\.tgz\fR the tarball of foo@1\.0\.0 +.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\|\. . .P -\fBroot/\.npm/\.cache/foo/1\.0\.0/package\fR the untouched pristine copy of foo@1\.0\.0 +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\. . .P -Executables are installed to the folder specified by the \fBbinroot\fR config\. +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\. . .P -\fBbinroot/foo\fR Symlink to the active version of the "foo" executable\. +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\. . -.P -\fBbinroot/foo@1\.0\.0\fR An executable for foo at version 1\.0\.0\. Either a -symbolic link or a shim to a file in the foo package\. +.SS "Global Installation" +If the \fBglobal\fR configuration is set to true, or if it is not explicitly +set false and no suitable node_modules folder was found, then npm will +install packages "globally"\. . .P -Man pages are installed to the folder specified by the \fBmanroot\fR config\. -Man pages named something other than the package name are prefixed with -the package name\. +This means that the module contents are symlinked (or, on windows, +copied) from \fBroot/<name>/<version>/package\fR to \fBroot/node_modules/<name>\fR\|\. +. +.SS "Cycles, Conflicts, and Folder Parsimony" +Cycles are handled using the property of node\'s module system that it +walks up the directories looking for node\fImodules folders\. So, at every +stage, if a package is already installed in an ancestor node\fRmodules +folder, then it is not installed at the current location\. . .P -\fBmanroot/man1/foo\.1\fR Symlink to the section 1 manpage for the active -version of foo\. +Consider the case above, where \fBfoo \-> bar \-> baz\fR\|\. Imagine if, in +addition to that, baz depended on bar, so you\'d have: \fBfoo \-> bar \-> baz \-> bar \-> baz \.\.\.\fR\|\. However, since the folder +structure is: foo/node\fImodules/bar/node\fRmodules/baz, there\'s no need to +put another copy of bar into \.\.\./baz/node\fImodules, since when it calls +require("bar"), it will get the copy that is installed in +foo/node\fRmodules/bar\. . .P -\fBmanroot/man1/foo@1\.0\.0\.1\fR Section 1 man page for foo version 1\.0\.0 +This shortcut is only used if the exact same +version would be installed in multiple nested node_modules folders\. It +is still possible to have \fBa/node_modules/b/node_modules/a\fR 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 -\fBmanroot/man8/foo\-bar\.8\fR Symlink to a section 8 manpage for the active -version of foo\. +Another optimization can be made by installing dependencies at the +highest level possible, below the localized "target" folder\. . .P -\fBmanroot/man8/foo\-bar@1\.0\.0\.8\fR A section 8 manpage for foo version -1\.0\.0\. +For example, consider this dependency graph: . -.SH "CONFIGURATION" +.IP "" 4 . -.SS "root" -Default: \fB$INSTALL_PREFIX/lib/node\fR +.nf +foo ++\-\- bar@1\.2\.3 +| +\-\- baz@2\.x +| | `\-\- quux@3\.x +| | `\-\- bar@1\.2\.3 (cycle) +| `\-\- asdf@* +`\-\- baz@1\.2\.3 + `\-\- quux@3\.x + `\-\- bar +. +.fi +. +.IP "" 0 . .P -The root folder where packages are installed and npm keeps its data\. +In this case, we might expect a folder structure like this: +. +.IP "" 4 +. +.nf +foo ++\-\- node_modules + +\-\- bar (1\.2\.3) + | +\-\- node_modules + | | `\-\- baz (2\.0\.2) + | | `\-\- node_modules + | | `\-\- quux (3\.2\.0) + | `\-\- asdf (2\.3\.4) + `\-\- baz (1\.2\.3) + `\-\- node_modules + `\-\- quux (3\.2\.0) + `\-\- node_modules + `\-\- bar (1\.2\.3) + `\-\- node_modules + `\-\- asdf (2\.3\.4) +. +.fi . -.SS "binroot" -Default: \fB$INSTALL_PREFIX/bin\fR +.IP "" 0 . .P -The folder where executable programs are installed\. +Since foo depends directly on bar@1\.2\.3 and baz@1\.2\.3, those are +installed in foo\'s node_modules folder\. . .P -Set to "false" to not install executables +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\. . -.SS "manroot" -Default: $INSTALL_PREFIX/share/man +.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 +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\. . .P -The folder where man pages are installed\. +For a graphical breakdown of what is installed where, use \fBnpm ls\fR\|\. +. +.SS "Publishing" +Upon publishing, npm will look in the node_modules folder\. If any of +the items there are on the "dependencies" or "devDependencies" list, +and are not in the \fBbundledDependencies\fR array, then they will not be +included in the package tarball\. . .P -Set to "false" to not install man pages\. +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\. |