From 725ffc040b1f7bda9591547a73667deca622407e Mon Sep 17 00:00:00 2001 From: isaacs Date: Sat, 30 Apr 2011 17:54:19 -0700 Subject: make doc --- man1/changelog.1 | 67 ++++++------------------------------------- man1/explore.1 | 4 +-- man1/faq.1 | 78 +++++++++++++++++++++++++++----------------------- man1/folders.1 | 86 ++++++++++++++++++++++++++++++++------------------------ man1/global.1 | 86 ++++++++++++++++++++++++++++++++------------------------ man1/npm.1 | 4 +-- 6 files changed, 155 insertions(+), 170 deletions(-) (limited to 'man1') diff --git a/man1/changelog.1 b/man1/changelog.1 index 4382e115d..751c85ef1 100644 --- a/man1/changelog.1 +++ b/man1/changelog.1 @@ -1,7 +1,7 @@ .\" Generated with Ronnjs/v0.1 .\" http://github.com/kapouer/ronnjs/ . -.TH "NPM\-CHANGELOG" "1" "March 2011" "" "" +.TH "NPM\-CHANGELOG" "1" "April 2011" "" "" . .SH "NAME" \fBnpm-changelog\fR \-\- Changes @@ -17,9 +17,6 @@ Lots of sketches and false starts\. Abandoned a few times\. .br Core functionality established\. . -.br -alpha\. -. .IP "\(bu" 4 0\.1 . @@ -27,30 +24,6 @@ alpha\. push to beta, and announce . .br -documentation, caching, more robust script support -. -.br -ownership tracking in the registry (no more admin party!) -. -.br -more robust config and option parsing -. -.br -stabilize semver semantics -. -.br -tests -. -.br -update command -. -.br -bundle command -. -.br -Rollback for failed installations -. -.br Solaris and Cygwin support . .IP "\(bu" 4 @@ -58,51 +31,30 @@ Solaris and Cygwin support . .br First allegedly "stable" release\. -Various fixes found during the Node Knockout extravaganza -. -.br -Minor updates and bugfixes -. -.br -more complete semver functionality -. -.br -Make npm OK to use programmatically (Charlie Robbins) -recursive package removal . .br -tab completion (Evan Meagher) +Most functionality implemented\. . .br -shasums on all tarballs +Used shim files and \fBname@version\fR symlinks . .br -explore command: see \fBnpm help explore\fR +Feature explosion . .br -docs command: see \fBnpm help docs\fR -. -.br -Frequently asked questions at \fBnpm faq\fR -xmas easter egg -. -.br -work with homebrew nodejs -. -.br -Support for \fB"":""\fR for dependencies\. +Kind of a mess\. . .IP "\(bu" 4 0\.3 . .br -More correct permission/uid handling\. (Sudo now encouraged!) +More correct permission/uid handling when running as root . .br Require node 0\.4\.0 . .br -Separate semver out into a separate utility\. +Reduce featureset . .br Packages without "main" modules don\'t export modules\. @@ -110,14 +62,11 @@ Packages without "main" modules don\'t export modules\. .br Remove support for invalid JSON (since node doesn\'t support it) . -.br -No shims! (Still has symlinks, though) -. .IP "\(bu" 4 1\.0 . .br -Simplify configuration greatly\. +Simplify folder structure greatly\. . .br Install locally (bundle by default) diff --git a/man1/explore.1 b/man1/explore.1 index 30e7fba9f..5e4304c0b 100644 --- a/man1/explore.1 +++ b/man1/explore.1 @@ -1,7 +1,7 @@ .\" Generated with Ronnjs/v0.1 .\" http://github.com/kapouer/ronnjs/ . -.TH "NPM\-EXPLORE" "1" "March 2011" "" "" +.TH "NPM\-EXPLORE" "1" "April 2011" "" "" . .SH "NAME" \fBnpm-explore\fR \-\- Browse an installed package @@ -9,7 +9,7 @@ .SH "SYNOPSIS" . .nf -npm explore [@] [] +npm explore [@] [ \-\- ] . .fi . diff --git a/man1/faq.1 b/man1/faq.1 index 72825cbc3..888874202 100644 --- a/man1/faq.1 +++ b/man1/faq.1 @@ -1,7 +1,7 @@ .\" Generated with Ronnjs/v0.1 .\" http://github.com/kapouer/ronnjs/ . -.TH "NPM\-FAQ" "1" "March 2011" "" "" +.TH "NPM\-FAQ" "1" "April 2011" "" "" . .SH "NAME" \fBnpm-faq\fR \-\- Frequently Asked Questions @@ -36,22 +36,32 @@ and its modules go in \fBnpm root \-g\fR\|\. . .IP "" 0 . +.SH "How do I install something everywhere?" +Install it globally by tacking \fB\-g\fR or \fB\-\-global\fR to the command\. +. .SH "I installed something globally, but I can\'t `require()` it" Install it locally\. . .SH "I don\'t wanna\." -Ok, then do this: +Check out \fBnpm link\fR\|\. You might like it\. +. +.SH "No, I really want 0\.x style "everything\'s global" style\." +Ok, fine\. Do this: . .IP "" 4 . .nf echo \'export NODE_PATH="\'$(npm root \-g)\'"\' >> ~/\.bashrc \|\. ~/\.bashrc +npm config set global true . .fi . .IP "" 0 . +.P +This is not recommended\. +. .SH "How do I list installed packages?" \fBnpm ls\fR . @@ -62,34 +72,34 @@ echo \'export NODE_PATH="\'$(npm root \-g)\'"\' >> ~/\.bashrc Arguments are greps\. \fBnpm ls jsdom\fR shows jsdom packages\. . .SH "How do I update npm?" -\fBNOTE\fR: This is the release candidate documentation\. To update to the -newer 1\.0 release candidate, do this: -. -.IP "" 4 . .nf -npm install npm@rc \-g +npm update npm \-g . .fi . -.IP "" 0 +.P +You can also update all outdated local packages by doing \fBnpm update\fR without +any arguments, or global packages by doing \fBnpm update \-g\fR\|\. +. +.P +Occasionally, the version of npm will progress such that the current +version cannot be properly installed with the version that you have +installed already\. (Consider, if there is ever a bug in the \fBupdate\fR +command\.) . .P -Once 1\.0 is stable, do this: +In those cases, you can do this: . .IP "" 4 . .nf -npm update npm \-g +curl http://npmjs\.org/install\.sh | sh . .fi . .IP "" 0 . -.P -You can also update all outdated local packages by doing \fBnpm update\fR without -any arguments, or global packages by doing \fBnpm update \-g\fR\|\. -. .SH "What is a `package`?" A package is: . @@ -140,6 +150,9 @@ See \fBnpm help developers\fR and \fBnpm help json\fR\|\. You\'ll most likely want to \fBnpm link\fR your development folder\. That\'s awesomely handy\. . +.P +To set up your own private registry, check out \fBnpm help registry\fR\|\. +. .SH "Can I list a url as a dependency?" Yes\. It should be a url to a gzipped tarball containing a single folder that has a package\.json in its root\. (See "what is a package?" above\.) @@ -148,38 +161,33 @@ that has a package\.json in its root\. (See "what is a package?" above\.) No\. . .P -Source repositories change quickly\. That is their purpose\. Whatever -you bundle into your package is your business, but having the registry -refer to a git URL as a "dependency" defeats the whole purpose\. -. -.P -It\'s possible that something a bit more snazzy will be developed at some -point in the future, but not likely\. The current system allows for a -lot of use cases, and is very easy to maintain\. -. -.P -If you really really want to have the latest checkout in your program, -you can clone the git repo, and then \fBnpm link\fR it, and then \fBnpm link -\fR in any packages that use it to install the link locally to that -package\. +However, you can list a url as a dependency\. . -.SH "How do I symlink to a dev folder so that I don\'t have to keep re\-installing?" +.SH "How do I symlink to a dev folder so I don\'t have to keep re\-installing?" See \fBnpm help link\fR . .SH "The package registry website\. What is that exactly?" -See \fBnpm help registry\fR for more info, or just visit \fIhttp://github\.com/isaacs/npmjs\.org\fR\|\. +See \fBnpm help registry\fR\|\. . .SH "What\'s up with the insecure channel warnings?" As of this writing, node has problems uploading files over HTTPS\. That -means that publishes go over HTTP\. +means that publishes go over HTTP by default\. . .P -Until the problem is solved, npm will complain about being insecure\. -The warnings will disappear when node supports uploading tarballs over -https reliably\. +Allegedly this problem is solved in node 0\.4\.7\. You can suppress those +warnings by doing this: +. +.IP "" 4 +. +.nf +npm config set registry https://registry\.npmjs\.org +. +.fi +. +.IP "" 0 . .SH "I forgot my password, and can\'t publish\. How do I reset it?" -Go to \fIhttp://admin\.npmjs\.org/\fR to reset it\. +Go to \fIhttp://admin\.npmjs\.org/\fR\|\. . .SH "I get ECONNREFUSED a lot\. What\'s up?" Either the registry is down, or node\'s DNS isn\'t able to reach out\. 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///package\fR to \fBroot/node_modules/\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\|\. diff --git a/man1/global.1 b/man1/global.1 index e6a660173..4ee926e9f 100644 --- a/man1/global.1 +++ b/man1/global.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///package\fR to \fBroot/node_modules/\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\|\. diff --git a/man1/npm.1 b/man1/npm.1 index 9b6e779e6..dcee3d917 100644 --- a/man1/npm.1 +++ b/man1/npm.1 @@ -1,7 +1,7 @@ .\" Generated with Ronnjs/v0.1 .\" http://github.com/kapouer/ronnjs/ . -.TH "NPM" "1" "March 2011" "" "" +.TH "NPM" "1" "April 2011" "" "" . .SH "NAME" \fBnpm\fR \-\- node package manager @@ -106,7 +106,7 @@ Defaults: . .br npm\'s default configuration options are defined in -lib/utils/default\-config\.js\. These should not be changed\. +lib/utils/config\-defs\.js\. These must not be changed\. . .IP "" 0 . -- cgit v1.2.3