diff options
Diffstat (limited to 'man1/future-ideas/new-module-system.1')
| -rw-r--r-- | man1/future-ideas/new-module-system.1 | 334 |
1 files changed, 0 insertions, 334 deletions
diff --git a/man1/future-ideas/new-module-system.1 b/man1/future-ideas/new-module-system.1 deleted file mode 100644 index 296f1573b..000000000 --- a/man1/future-ideas/new-module-system.1 +++ /dev/null @@ -1,334 +0,0 @@ -.\" Generated with Ronnjs/v0.1 -.\" http://github.com/kapouer/ronnjs/ -. -.TH "NPM\-FOLDERS" "1" "March 2011" "" "" -. -.SH "NAME" -\fBnpm-folders\fR \-\- Folder Structures Used by npm -. -.SH "FUTURE" -This functionality is not yet implemented\. It is a plan, not reality\. -It is not the map, nor the territory, but a blueprint with blank areas\. -. -.P -In particular, this is the scheme that will be used starting in npm@0\.3, -which will require node@0\.5\.0 or above\. -. -.SH "GOALS" -. -.IP "\(bu" 4 -Don\'t splat stuff across the filesystem so much\. Just specify a single -root location, and be done with it\. -. -.IP "\(bu" 4 -Work on windows\. -. -.IP "\(bu" 4 -Minimize shim/symlink usage\. -. -.IP "\(bu" 4 -Do not rely on any global system path for node modules\. -. -.IP "\(bu" 4 -Remove the "activation" concept\. -. -.IP "" 0 -. -.SH "DESCRIPTION" -npm metadata lives in the \fBroot\fR setting\. There is the cache folder, -and the contents of all installed packages\. -. -.P -The default npm root folder is \fB/usr/local/lib/npm\fR\|\. -. -.P -TODO: What should the root folder be on windows? -. -.SS "Cache folder" -The cache folder is a mirror of the data in the registry, as well as a -working space for unpacking and creating tarballs\. -. -.P -Files and folders created in the cache are owned by the executing user, -often "root"\. -. -.P -Files are created with 0666 and folders with 0777, so that they can be -modified by any user\. -. -.IP "\(bu" 4 -\fBroot/cache\fR Cache folder -. -.IP "\(bu" 4 -\fBroot/cache/foo/cache\.json\fR Expirable cache of registry/foo json data -. -.IP "\(bu" 4 -\fBroot/cache/foo/1\.2\.3/package\fR Pristine copy of foo package contents -. -.IP "\(bu" 4 -\fBroot/cache/foo/1\.2\.3/package\.tgz\fR tarball of foo@1\.2\.3 -. -.IP "" 0 -. -.SS "Package folders" -In the npm root folder, package contents are unpacked, built, and then -moved into the desired location\. -. -.IP "\(bu" 4 -\fBroot/packages/foo/1\.2\.3\fR Metadata and contents of foo@1\.2\.3 -. -.IP "\(bu" 4 -\fBroot/packages/foo/1\.2\.3/package\fR Build location of foo@1\.2\.3 -. -.IP "\(bu" 4 -\fBroot/packages/foo/1\.2\.3/node_modules\fR Links to (or, on windows, copies of) -dependencies of foo@1\.2\.3 -. -.IP "\(bu" 4 -\fBroot/packages/foo/1\.2\.3/metadata\.json\fR Metadata about the foo package\. -. -.IP "" 0 -. -.SS "Installation in `node_modules` Folders" -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 -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 -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 -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\. -. -.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 -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 "Installing executables" -When installing globally, executables are linked (or, on windows, -shimmed with a \.bat file) to \fBroot/bin\fR\|\. -. -.P -When doing a -localized installation, executables are linked (or, on windows, shimmed) -to \fB\|\./node_modules/\.bin\fR\|\. This also applies to the case when a globally -installed package\'s dependents are being installed into it\. Basically, -whenever writing \fB\|\.\.\./node_modules/foo\fR, and the "foo" -package has an executable named "bar", it\'ll write it to \fB\|\.\.\./node_modules/\.bin/bar\fR\|\. -. -.P -It is up to the user to update their PATH environment variable -appropriately for globally installed executables\. When running package -lifecycle scripts (for example, to build, start, test, etc\.), npm will -put \fB\|\./node_modules/\.bin\fR as the first item in the PATH environ\. -. -.SS "Installing manpages" -npm will install man pages to \fBroot/share/man\fR\|\. It is up to the user to -make sure that their man program searches this location\. -. -.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 -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 -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 -Another optimization can be made by installing dependencies at the -highest level possible, below the localized "target" folder\. -. -.P -For example, consider this dependency graph: -. -.IP "" 4 -. -.nf -foo -+\-\- bar@1\.2\.3 -| +\-\- baz@2\.x -| | `\-\- quux@3\.x -| `\-\- asdf@* -`\-\- baz@1\.2\.3 - `\-\- quux@3\.x -. -.fi -. -.IP "" 0 -. -.P -In this case, we\'d expect a folder structure like this: -. -.IP "" 4 -. -.nf -foo -+\-\- node_modules - +\-\- bar (1\.2\.3) - | `\-\- node_modules - | `\-\- baz (2\.0\.2) - +\-\- quux (3\.2\.0) - +\-\- asdf (0\.2\.5) - `\-\- baz (1\.2\.3) -. -.fi -. -.IP "" 0 -. -.P -Since foo depends directly on bar@1\.2\.3 and baz@1\.2\.3, those are -installed in foo\'s node_modules folder\. -. -.P -Since baz@1\.2\.3 depends on quux@3\.x, a satisfying version is placed in -foo\'s node_modules folder, because there are no conflicts\. -. -.P -Since bar@1\.2\.3 depends on asdf@*, a satisfying version is placed in -foo\'s node\fImodules folder\. It also depends on baz@2\.x, but this -conflicts with the version already installed in foo\'s node\fRmodules -folder, so it is installed into the node_modules folder under bar@1\.2\.3\. -. -.P -baz@2\.0\.2 depends on quux@3\.x, but this dependency is already satisfied -by the quux version installed in foo\'s node_modules folder, so nothing -further needs to be done\. -. -.SS "Snapshotting" -Whenever the \fBnpm snapshot\fR command is run, the package\.json file is -updated to include the versions of all of the packages in the \fB\|\./node_modules\fR folder as dependencies\. -. -.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 unmodified copies of the corresponding packages in \fBroot/node_modules/<name>/<version>/package\fR, then they will not be -included in the package tarball\. -. -.P -If the package has been modified, then it is left as\-is, and included in -the package\. -. -.P -This allows a package maintainer to install all of their dependencies -(and dev dependencies) locally, but only publish those items that cannot -be found elsewhere\. -. -.SS "Updating" -npm keeps track of every installation of foo@1\.2\.3 in \fBroot/packages/foo/1\.2\.3/metadata\.json\fR\|\. -. -.P -When updating in a package folder (see algorithm for determining this in -"Installation in \fBnode_modules\fR Folders"), npm updates the packages in -the local folder to the latest versions that are compatible with the -requirements in the package\.json file\. -. -.P -If global is set to \fB"super"\fR, then npm will attempt to update -all copies of packages installed anywhere and everywhere that it is -aware of\. -. -.P -If \fBglobal\fR is set to `true, or implied by not being in a package folder -at the time, then npm will update the globally installed packages\. -. -.P -If you do \fBnpm update foo\fR, and you\'re in a local package folder, but \fBfoo\fR is not installed there, and it \fIis\fR installed globally, then that -will be equivalent to doing \fBnpm update foo \-\-global\fR\|\. -. -.SS "Uninstalling" -Uninstalling works like updating\. -. -.P -If global is set to "super", then it removes all traces from everywhere\. -. -.P -If global is set to "true", or implied, then it removes the global copy\. -. -.P -If global is set to "false", or unset and the command is in a package -folder with a copy of the package being removed, then it removes it from -the local folder\. -. -.SS "Linking" -When \fBnpm link\fR is run without any arguments in a package folder, then a -symbolic link is created from that folder to \fBroot/<name>/LINK\fR\|\. -Additionally, its package dependencies are installed to its -\|\./node_modules folder as necessary\. -. -.P -When \fBnpm link <name>\fR is run in another package folder, a symbolic -link is created from \fBroot/<name>/LINK\fR to \fB\|\./node_modules/<name>\fR, and -its dependencies are also installed if necessary\. (Generally, it will -not be necessary, as the package will already have its own node_modules -folder containing its dependencies\.) -. -.P -When publishing, linked package dependencies are resolved to their -current state\. It is assumed that the linked folder was linked for a -reason, and may contain changes required for the proper functioning of -the host program\. -. -.TP -npm link use case -. -.IP "" 4 -. -.nf -# create a linked "request" package -cd ~/projects/request -npm link -# now write a program that uses request -mkdir \-p ~/projects/my\-program -cd ~/projects/my\-program -git init -# do your git stuff\.\.\. -npm init -# enter some package\.json values -# now we\'re ready to rock\. -# use redis, but don\'t need bleeding edge\. -npm install redis -# use the linked copy of request -npm link request -# now any changes to ~/projects/request will -# be immediately effective in my\-program when -# I do require("request") -. -.fi -. -.IP "" 0 -. -.TP -link on Windows -.Not sure how this will work\. Maybe linking simply isn\'t possible? |