org.simantics.maps.server/node/node-v4.8.0-win-x64/node_modules/npm/doc/files/npm-folders.md

   1 npm-folders(5) -- Folder Structures Used by npm
   2 ===============================================
   3
   4 ## DESCRIPTION
   5
   6 npm puts various things on your computer.  That's its job.
   7
   8 This document will tell you what it puts where.
   9
  10 ### tl;dr
  11
  12 * Local install (default): puts stuff in `./node_modules` of the current
  13   package root.
  14 * Global install (with `-g`): puts stuff in /usr/local or wherever node
  15   is installed.
  16 * Install it **locally** if you're going to `require()` it.
  17 * Install it **globally** if you're going to run it on the command line.
  18 * If you need both, then install it in both places, or use `npm link`.
  19
  20 ### prefix Configuration
  21
  22 The `prefix` config defaults to the location where node is installed.
  23 On most systems, this is `/usr/local`. On windows, this is the exact
  24 location of the node.exe binary.  On Unix systems, it's one level up,
  25 since node is typically installed at `{prefix}/bin/node` rather than
  26 `{prefix}/node.exe`.
  27
  28 When the `global` flag is set, npm installs things into this prefix.
  29 When it is not set, it uses the root of the current package, or the
  30 current working directory if not in a package already.
  31
  32 ### Node Modules
  33
  34 Packages are dropped into the `node_modules` folder under the `prefix`.
  35 When installing locally, this means that you can
  36 `require("packagename")` to load its main module, or
  37 `require("packagename/lib/path/to/sub/module")` to load other modules.
  38
  39 Global installs on Unix systems go to `{prefix}/lib/node_modules`.
  40 Global installs on Windows go to `{prefix}/node_modules` (that is, no
  41 `lib` folder.)
  42
  43 Scoped packages are installed the same way, except they are grouped together
  44 in a sub-folder of the relevant `node_modules` folder with the name of that
  45 scope prefix by the @ symbol, e.g. `npm install @myorg/package` would place
  46 the package in `{prefix}/node_modules/@myorg/package`. See `scope(7)` for
  47 more details.
  48
  49 If you wish to `require()` a package, then install it locally.
  50
  51 ### Executables
  52
  53 When in global mode, executables are linked into `{prefix}/bin` on Unix,
  54 or directly into `{prefix}` on Windows.
  55
  56 When in local mode, executables are linked into
  57 `./node_modules/.bin` so that they can be made available to scripts run
  58 through npm.  (For example, so that a test runner will be in the path
  59 when you run `npm test`.)
  60
  61 ### Man Pages
  62
  63 When in global mode, man pages are linked into `{prefix}/share/man`.
  64
  65 When in local mode, man pages are not installed.
  66
  67 Man pages are not installed on Windows systems.
  68
  69 ### Cache
  70
  71 See `npm-cache(1)`.  Cache files are stored in `~/.npm` on Posix, or
  72 `~/npm-cache` on Windows.
  73
  74 This is controlled by the `cache` configuration param.
  75
  76 ### Temp Files
  77
  78 Temporary files are stored by default in the folder specified by the
  79 `tmp` config, which defaults to the TMPDIR, TMP, or TEMP environment
  80 variables, or `/tmp` on Unix and `c:\windows\temp` on Windows.
  81
  82 Temp files are given a unique folder under this root for each run of the
  83 program, and are deleted upon successful exit.
  84
  85 ## More Information
  86
  87 When installing locally, npm first tries to find an appropriate
  88 `prefix` folder.  This is so that `npm install foo@1.2.3` will install
  89 to the sensible root of your package, even if you happen to have `cd`ed
  90 into some other folder.
  91
  92 Starting at the $PWD, npm will walk up the folder tree checking for a
  93 folder that contains either a `package.json` file, or a `node_modules`
  94 folder.  If such a thing is found, then that is treated as the effective
  95 "current directory" for the purpose of running npm commands.  (This
  96 behavior is inspired by and similar to git's .git-folder seeking
  97 logic when running git commands in a working dir.)
  98
  99 If no package root is found, then the current folder is used.
 100
 101 When you run `npm install foo@1.2.3`, then the package is loaded into
 102 the cache, and then unpacked into `./node_modules/foo`.  Then, any of
 103 foo's dependencies are similarly unpacked into
 104 `./node_modules/foo/node_modules/...`.
 105
 106 Any bin files are symlinked to `./node_modules/.bin/`, so that they may
 107 be found by npm scripts when necessary.
 108
 109 ### Global Installation
 110
 111 If the `global` configuration is set to true, then npm will
 112 install packages "globally".
 113
 114 For global installation, packages are installed roughly the same way,
 115 but using the folders described above.
 116
 117 ### Cycles, Conflicts, and Folder Parsimony
 118
 119 Cycles are handled using the property of node's module system that it
 120 walks up the directories looking for `node_modules` folders.  So, at every
 121 stage, if a package is already installed in an ancestor `node_modules`
 122 folder, then it is not installed at the current location.
 123
 124 Consider the case above, where `foo -> bar -> baz`.  Imagine if, in
 125 addition to that, baz depended on bar, so you'd have:
 126 `foo -> bar -> baz -> bar -> baz ...`.  However, since the folder
 127 structure is: `foo/node_modules/bar/node_modules/baz`, there's no need to
 128 put another copy of bar into `.../baz/node_modules`, since when it calls
 129 require("bar"), it will get the copy that is installed in
 130 `foo/node_modules/bar`.
 131
 132 This shortcut is only used if the exact same
 133 version would be installed in multiple nested `node_modules` folders.  It
 134 is still possible to have `a/node_modules/b/node_modules/a` if the two
 135 "a" packages are different versions.  However, without repeating the
 136 exact same package multiple times, an infinite regress will always be
 137 prevented.
 138
 139 Another optimization can be made by installing dependencies at the
 140 highest level possible, below the localized "target" folder.
 141
 142 #### Example
 143
 144 Consider this dependency graph:
 145
 146     foo
 147     +-- blerg@1.2.5
 148     +-- bar@1.2.3
 149     |   +-- blerg@1.x (latest=1.3.7)
 150     |   +-- baz@2.x
 151     |   |   `-- quux@3.x
 152     |   |       `-- bar@1.2.3 (cycle)
 153     |   `-- asdf@*
 154     `-- baz@1.2.3
 155         `-- quux@3.x
 156             `-- bar
 157
 158 In this case, we might expect a folder structure like this:
 159
 160     foo
 161     +-- node_modules
 162         +-- blerg (1.2.5) <---[A]
 163         +-- bar (1.2.3) <---[B]
 164         |   `-- node_modules
 165         |       +-- baz (2.0.2) <---[C]
 166         |       |   `-- node_modules
 167         |       |       `-- quux (3.2.0)
 168         |       `-- asdf (2.3.4)
 169         `-- baz (1.2.3) <---[D]
 170             `-- node_modules
 171                 `-- quux (3.2.0) <---[E]
 172
 173 Since foo depends directly on `bar@1.2.3` and `baz@1.2.3`, those are
 174 installed in foo's `node_modules` folder.
 175
 176 Even though the latest copy of blerg is 1.3.7, foo has a specific
 177 dependency on version 1.2.5.  So, that gets installed at [A].  Since the
 178 parent installation of blerg satisfies bar's dependency on `blerg@1.x`,
 179 it does not install another copy under [B].
 180
 181 Bar [B] also has dependencies on baz and asdf, so those are installed in
 182 bar's `node_modules` folder.  Because it depends on `baz@2.x`, it cannot
 183 re-use the `baz@1.2.3` installed in the parent `node_modules` folder [D],
 184 and must install its own copy [C].
 185
 186 Underneath bar, the `baz -> quux -> bar` dependency creates a cycle.
 187 However, because bar is already in quux's ancestry [B], it does not
 188 unpack another copy of bar into that folder.
 189
 190 Underneath `foo -> baz` [D], quux's [E] folder tree is empty, because its
 191 dependency on bar is satisfied by the parent folder copy installed at [B].
 192
 193 For a graphical breakdown of what is installed where, use `npm ls`.
 194
 195 ### Publishing
 196
 197 Upon publishing, npm will look in the `node_modules` folder.  If any of
 198 the items there are not in the `bundledDependencies` array, then they will
 199 not be included in the package tarball.
 200
 201 This allows a package maintainer to install all of their dependencies
 202 (and dev dependencies) locally, but only re-publish those items that
 203 cannot be found elsewhere.  See `package.json(5)` for more information.
 204
 205 ## SEE ALSO
 206
 207 * npm-faq(7)
 208 * package.json(5)
 209 * npm-install(1)
 210 * npm-pack(1)
 211 * npm-cache(1)
 212 * npm-config(1)
 213 * npmrc(5)
 214 * npm-config(7)
 215 * npm-publish(1)