diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | man/activate.1 | 20 | ||||
| -rw-r--r-- | man/adduser.1 | 37 | ||||
| -rw-r--r-- | man/build.1 | 43 | ||||
| -rw-r--r-- | man/config.1 | 107 | ||||
| -rw-r--r-- | man/deactivate.1 | 21 | ||||
| -rw-r--r-- | man/folders.1 | 40 | ||||
| -rw-r--r-- | man/help.1 | 24 | ||||
| -rw-r--r-- | man/install.1 | 148 | ||||
| -rw-r--r-- | man/json.1 | 240 | ||||
| -rw-r--r-- | man/link.1 | 20 | ||||
| -rw-r--r-- | man/list.1 | 26 | ||||
| -rw-r--r-- | man/ln.1 | 20 | ||||
| -rw-r--r-- | man/ls.1 | 26 | ||||
| -rw-r--r-- | man/npm.1 | 305 | ||||
| -rw-r--r-- | man/publish.1 | 21 | ||||
| -rw-r--r-- | man/registry.1 | 55 | ||||
| -rw-r--r-- | man/rm.1 | 20 | ||||
| -rw-r--r-- | man/scripts.1 | 131 | ||||
| -rw-r--r-- | man/tag.1 | 24 | ||||
| -rw-r--r-- | man/uninstall.1 | 20 |
21 files changed, 1348 insertions, 1 deletions
diff --git a/.gitignore b/.gitignore deleted file mode 100644 index 2a3700c15..000000000 --- a/.gitignore +++ /dev/null @@ -1 +0,0 @@ -man diff --git a/man/activate.1 b/man/activate.1 new file mode 100644 index 000000000..eda6bc7c1 --- /dev/null +++ b/man/activate.1 @@ -0,0 +1,20 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "ACTIVATE" "1" "April 2010" "" "" +. +.SH "NAME" +\fBactivate\fR \-\- Activate an installed version of a package +. +.SH "SYNOPSIS" +. +.nf +npm activate <name> <version> +. +.fi +. +.SH "DESCRIPTION" +This "activates" a specific version of a package, so that you can just do\fBrequire("foo")\fR without having to specify the version. +. +.P +See: deactivate diff --git a/man/adduser.1 b/man/adduser.1 new file mode 100644 index 000000000..eb8f6e4e6 --- /dev/null +++ b/man/adduser.1 @@ -0,0 +1,37 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "ADDUSER" "1" "April 2010" "" "" +. +.SH "NAME" +\fBadduser\fR \-\- Add a registry user account +. +.SH "SYNOPSIS" +. +.nf +npm adduser bob password bob@email.com +. +.fi +. +.SH "DESCRIPTION" +Create a user named "bob" in the npm registry, and save the credentials to the\fB.npmrc\fR file. Note that this leaves the password in your \fB.bash_history\fR, and +it is currently stored in the clear in the config file. So, don't use a +password you care too much about. +. +.P +For now, if you somehow break your \fB.npmrc\fR file, and have forgotten your +password, you're boned. \fIEmail isaacs\fR and he'll delete the +record from the registry so that you can re\-add it. +. +.P +If you break your \fB.npmrc\fR file, but you remember your password, you can put your +user auth back by using the \fBbase64\fR program like so: +. +.IP "" 4 +. +.nf +npm config set auth $( echo user:pass | base64 ) +. +.fi +. +.IP "" 0 diff --git a/man/build.1 b/man/build.1 new file mode 100644 index 000000000..e1bb6cf8a --- /dev/null +++ b/man/build.1 @@ -0,0 +1,43 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM\-BUILD" "1" "May 2010" "" "" +. +.SH "NAME" +\fBnpm\-build\fR \-\- Build a package +. +.SH "SYNOPSIS" +. +.nf +npm build <package\-folder> +. +.fi +. +.TP +\fIpackage\-folder\fR +A folder containing a \fBpackage.json\fR file in its root. +. +.SH "DESCRIPTION" +This command should almost never need to be run directly. It is an abstraction +of the functionality shared by both npm\-install(1) and npm\-link(1). +. +.P +This command creates the various interwoven links that ensure a package's contents +are available in the root appropriately, and that its dependencies are linked +appropriately. +. +.SH "SEE ALSO" +. +.IP "\(bu" 4 +npm\-install(1) +. +.IP "\(bu" 4 +npm\-link(1) +. +.IP "\(bu" 4 +npm\-scripts(1) +. +.IP "\(bu" 4 +npm\-json(1) +. +.IP "" 0 diff --git a/man/config.1 b/man/config.1 new file mode 100644 index 000000000..ec261b635 --- /dev/null +++ b/man/config.1 @@ -0,0 +1,107 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM\-CONFIG" "1" "April 2010" "" "" +. +.SH "NAME" +\fBnpm\-config\fR \-\- Manage the npm configuration file +. +.SH "SYNOPSIS" +. +.nf +npm config set <key> <value> +npm config get <key> +npm config delete <key> +npm config list +. +.fi +. +.SH "DESCRIPTION" +The config command is a way to interact with the \fB.npmrc\fR file. This file is a +JSON encoded list of values that npm is concerned with. The first time you run +npm, it will create a conf file filled with default values. +. +.P +On exit, the current state of the config is always saved, so that any changes +will be recorded. You may safely modify the file (as long as it's still +parseable JSON), but it is safer to use the npm config commands. +. +.SH "Sub\-commands" +Config supports the following sub\-commands: +. +.SS "set" +. +.nf +npm config set key value +. +.fi +. +.P +Sets the config key to the value. +. +.SS "get" +. +.nf +npm config get key +. +.fi +. +.P +Echo the config value to stdout. (NOTE: All the other npm logging is done to +stderr, so pipes should work properly, and you can do \fBnpm get key 2>/dev/null\fR +to print out JUST the config value.) +. +.SS "list" +. +.nf +npm config list +. +.fi +. +.P +Show all the config settings. +. +.P +\fBFIXME\fR: Prints to stderr, but should really be stdout, since the log is what +you're after. +. +.SS "delete" +. +.nf +npm config delete key +. +.fi +. +.P +Deletes the key from the configuration file. +. +.SH "Config File Settings" +. +.SS "auto\-activate" +Default: true +. +.P +Automatically activate a package after installation, if there is not an active +version already. Set to "always" to always activate when installing. +. +.SS "root" +Default: ~/.node_libraries +. +.P +The root folder where packages are installed and npm keeps its data. +. +.SS "registry" +Default: http://registry.npmjs.org/ +. +.P +The base URL of the npm package registry. +. +.SS "auth" +A base\-64 encoded "user:pass" pair. +. +.P +\fBFIXME\fR: This is not encoded in any kind of security sense. It's just base\-64 +encoded strictly so that it can be sent along the wire with HTTP Basic +authentication. An upcoming version of npm will encrypt this and save it back +to the registry as \fBauth\-crypt\fR, which will be quite a bit more secure. Until +then, use a unique password that you don't mind being compromised. diff --git a/man/deactivate.1 b/man/deactivate.1 new file mode 100644 index 000000000..ce0c75771 --- /dev/null +++ b/man/deactivate.1 @@ -0,0 +1,21 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM\-DEACTIVATE" "1" "April 2010" "" "" +. +.SH "NAME" +\fBnpm\-deactivate\fR \-\- Deactivate the active version of a package +. +.SH "SYNOPSIS" +. +.nf +npm deactivate <name> +. +.fi +. +.SH "DESCRIPTION" +If there's an active version of the package, this will unlink it from that +preferential position. +. +.P +See: activate diff --git a/man/folders.1 b/man/folders.1 new file mode 100644 index 000000000..f5f61f93c --- /dev/null +++ b/man/folders.1 @@ -0,0 +1,40 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM\-FOLDERS" "1" "April 2010" "" "" +. +.SH "NAME" +\fBnpm\-folders\fR \-\- Folder Structures Used by npm +. +.SH "DESCRIPTION" +Everything lives in the \fBroot\fR setting. This defaults to \fB$HOME/.node_libraries/\fR. I'd like to be able to override it, but that's not +possible yet. +. +.P +\fBroot/.npm/foo\fR is where the stuff for package \fBfoo\fR would go. +. +.P +\fBroot/.npm/foo/1.0.0/package\fR the contents of the tarball containing foo +version 1.0.0 +. +.P +\fBroot/.npm/foo/1.0.0/main.js\fR Generated file that exports the \fBmain\fR module in +foo. +. +.P +\fBroot/.npm/foo/1.0.0/lib\fR symlink to the \fBlib\fR dir in foo. +. +.P +\fBroot/.npm/foo/active\fR symlink to the active version. +. +.P +\fBroot/foo\-1.0.0.js\fR symlink to \fB.npm/foo/1.0.0/main.js\fR +. +.P +\fBroot/foo.js\fR symlink to \fB.npm/foo/active/main.js\fR +. +.P +\fBroot/foo\fR symlink to \fB.npm/foo/active/lib\fR +. +.P +\fBroot/foo\-1.0.0\fR symlink to \fB.npm/foo/1.0.0/lib\fR diff --git a/man/help.1 b/man/help.1 new file mode 100644 index 000000000..dc7490063 --- /dev/null +++ b/man/help.1 @@ -0,0 +1,24 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM\-HELP" "1" "May 2010" "" "" +. +.SH "NAME" +\fBnpm\-help\fR \-\- Get help about npm commands +. +.SH "SYNOPSIS" +. +.nf +npm help <section> +. +.fi +. +.P +Where \fIsection\fR is one of: +. +.br +\fBnpm\fR, \fBactivate\fR, \fBadduser\fR, \fBconfig\fR, \fBdeactivate\fR, \fBfolders\fR, \fBhelp\fR (this +page), \fBinstall\fR, \fBjson\fR, \fBlink\fR (or \fBln\fR), \fBlist\fR (or \fBls\fR), \fBpublish\fR, \fBregistry\fR, \fBtag\fR, \fBuninstall\fR (or \fBrm\fR), \fBbuild\fR, \fBnpm\fR, \fBscripts\fR, \fBjson\fR +. +.SH "Todo" +It'd be nice if this page was automatically generated. diff --git a/man/install.1 b/man/install.1 new file mode 100644 index 000000000..4455c2734 --- /dev/null +++ b/man/install.1 @@ -0,0 +1,148 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM\-INSTALL" "1" "May 2010" "" "" +. +.SH "NAME" +\fBnpm\-install\fR \-\- install a package +. +.SH "SYNOPSIS" +. +.nf +npm install <tarball file> +npm install <tarball url> +npm install <pkg> +npm install <pkg>@<tag> +npm install <pkg>@<version> +npm install <pkg>@<version range> +. +.fi +. +.SH "DESCRIPTION" +This command installs a package, and any packages that it depends on. It +resolves circular dependencies by talking to the npm registry. +. +.TP +npm install \fItarball file\fR +Install a package that is sitting on the filesystem. Note: if you just want +to link a dev directory into your npm root, you can do this more easily by +using \fBnpm link\fR. +. +.IP +In order to distinguish between this and remote installs, the argument +must start with either "file:", ".", or "/" +. +.P + Example: +. +.IP "" 4 +. +.nf + npm install ./package.tgz +. +.fi +. +.IP "" 0 +. +.TP +npm install \fItarball url\fR +Fetch the tarball url, and then install it. In order to distinguish between +this and other options, the argument must start with "http://" or "https://" +. +.IP +Example: +. +.IP + npm install http://github.com/waveto/node\-crypto/tarball/v0.0.5 +. +.TP +npm install \fIpkg\fR +Do a \fIpkg\fR@\fItag\fR install, where \fItag\fR is the "tag" config from either your +.npmrc file, or the \-\-tag argument on the command line. +. +.IP +Example: +. +.IP + npm install sax +. +.TP +npm install \fIpkg\fR@\fItag\fR +Install the version of the package that is referenced by the specified tag. +If the tag does not exist in the registry data for that package, then this +will fail. +. +.IP +Example: +. +.IP + npm install sax@stable +. +.TP +npm install \fIpkg\fR@\fIversion\fR +Install the specified version of the package. This will fail if the version +has not been published to the registry. +. +.IP +Example: +. +.IP + npm install sax@0.1.1 +. +.TP +npm install \fIpkg\fR@\fIversion range\fR +Install a version of the package matching the specified version range. This +will follow the same rules for resolving dependencies described in \fBnpm help json\fR. +. +.IP +Note that most version ranges must be put in quotes so that your shell will +treat it as a single argument. +. +.P + Example: +. +.IP "" 4 +. +.nf + npm install sax@">=0.1.0 <0.2.0" +. +.fi +. +.IP "" 0 +. +.P +You may combine multiple arguments, and even multiple types of arguments. For example: +. +.IP "" 4 +. +.nf +npm install sax@">=0.1.0 <0.2.0" bench supervisor +. +.fi +. +.IP "" 0 +. +.P +The \fB\-\-tag\fR argument will apply to all of the specified install targets. +. +.SH "SEE ALSO" +. +.IP "\(bu" 4 +npm\-build(1) +. +.IP "\(bu" 4 +npm\-registry(1) +. +.IP "\(bu" 4 +npm\-build(1) +. +.IP "\(bu" 4 +npm\-link(1) +. +.IP "\(bu" 4 +npm\-folders(1) +. +.IP "\(bu" 4 +npm\-tag(1) +. +.IP "" 0 diff --git a/man/json.1 b/man/json.1 new file mode 100644 index 000000000..e65563513 --- /dev/null +++ b/man/json.1 @@ -0,0 +1,240 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM\-JSON" "1" "May 2010" "" "" +. +.SH "NAME" +\fBnpm\-json\fR \-\- Specifics of npm's package.json handling +. +.SH "DESCRIPTION" +npm aims to implement the commonjs\fIPackages\fR spec. However, some +adjustments have been made, which may eventually be unmade, but hopefully will +be incorporated into the spec. +. +.SH "overlay" +npm responds to the \fBnode\fR and \fBnpm\fR env\-specific package.json values, which +you can hang on any of the following keys: \fB"overlay", "env", "context", +"ctx", "vnd", "vendor"\fR. +. +.P +For example: +. +.IP "" 4 +. +.nf +{ "name" : "foo" +, "version" : 7 +, "description" : "generic description" +, "overlay" : + { "node" : + { "name" : "bar" + , "description" : "description for node" + } + , "npm" : + { "version" : "1.0.7" + , "description" : "description for npm" + } + , "narwhal" : + { "description" : "description for narwhal" } + } +} +. +.fi +. +.IP "" 0 +. +.P +In this case, this is what npm will treat it as: +. +.IP "" 4 +. +.nf +{ "name" : "bar" +, "version" : "1.0.7" +, "description" : "description for npm" +} +. +.fi +. +.IP "" 0 +. +.P +This way, even if npm is not exactly the same as some other package management +system, you can still use both, and it can be a happy planet. +. +.SH "version" +Version must be \fIsemver\fR\-compliant. npm assumes that you've +read the semver page, and that you comply with it. Versions packages with +non\-semver versions will not be installed by npm. It's just too tricky if you +have more than one way to do it, and semver works well. +. +.P +(This is actually mentioned in the Packages/1.0 spec, but it's worth +mentioning that npm enforces this requirement quite strictly, since it's +pretty liberal about most other things.) +. +.SH "dependencies" +The Packages/1.0 spec's method for specifying dependencies is Unclean in My +Sight. So, npm is using a very simple semver\-based method. +. +.P +Dependencies are specified with a simple hash of package name to version +range. The version range is EITHER a string with has one or more +space\-separated descriptors. +. +.P +Version range descriptors may be any of the following styles, where "version" +is a semver compatible version identifier. +. +.IP "\(bu" 4 +\fBversion\fR Must match \fBversion\fR exactly +. +.IP "\(bu" 4 +\fB=version\fR Same as just \fBversion\fR +. +.IP "\(bu" 4 +\fB>version\fR Must be greater than \fBversion\fR +. +.IP "\(bu" 4 +\fB>=version\fR etc +. +.IP "\(bu" 4 +\fB<version\fR +. +.IP "\(bu" 4 +\fB<=version\fR +. +.IP "\(bu" 4 +\fB*\fR Matches any version +. +.IP "\(bu" 4 +\fB""\fR (just an empty string) Same as \fB*\fR +. +.IP "\(bu" 4 +\fBversion1 \- version2\fR Same as \fB>=version1 <=version2\fR. +. +.IP "" 0 +. +.P +For example, these are all valid: +. +.IP "" 4 +. +.nf +{ "dependencies" : + { "foo" : "1.0.0 \- 2.9999.9999" + , "bar" : ">=1.0.2 <2.1.2" + , "baz" : ">1.0.2 <=2.3.4" + , "boo" : "2.0.1" + } +} +. +.fi +. +.IP "" 0 +. +.SH "link" +You may specify a \fBlink\fR member in your package.json to have npm link +dependencies in to a particular location inside your package dir. For example: +. +.IP "" 4 +. +.nf +{ "dependencies" : + { "boo" : "2.0.1" + , "baz" : ">1.0.2 <=2.3.4" + , "foo" : "1.0.0 \- 2.9999.9999" + , "bar" : ">=1.0.2 <2.1.2" + } +, "link" : + { "boo" : "./deps/boo" + , "baz" : "./lib/baz" + , "foo" : "./deps/foo" + , "bar" : "./deps/bar" + } +} +. +.fi +. +.IP "" 0 +. +.P +This would link the dependencies into the specified locations, so that the +package code could do \fBrequire("./deps/foo")\fR to import whichever version of \fBfoo\fR was satisfying the requirement. +. +.P +\fBWarning!\fR This is currently the \fIonly\fR way +in which npm modifies the pristine nature of the package directory, and it may +go away eventually. It's just that it satisfies a use case that is pretty +tricky to do otherwise. +. +.SH "engines" +Packages/1.0 says that you can have an "engines" field with an array of engine +names. However, it has no provision for specifying which version of the engine +your stuff runs on. +. +.P +With npm, you can use either of the following styles to specify the version of +node that your stuff works on: +. +.IP "" 4 +. +.nf +{ "engines" : [ "node >=0.1.27 <0.1.30" ] } +. +.fi +. +.IP "" 0 +. +.P +or: +. +.IP "" 4 +. +.nf +{ "engines" : { "node" : ">=0.1.27 <0.1.30" } } +. +.fi +. +.IP "" 0 +. +.P +And, like with dependencies, if you don't specify the version (or if you +specify "*" as the version), then any version of node will do. +. +.P +If you specify an "engines" field, then npm will require that "node" be +somewhere on that list. If "engines" is omitted, then npm will just assume +that it works on node. +. +.SH "bin" +A lot of packages have one or more executable files that they'd like to +install into the PATH. npm makes this pretty easy (in fact, it uses this +feature to install the "npm" executable.) +. +.P +To use this, supply a \fBbin\fR field in your package.json which is a map of +command name to local file name. On install, npm will link that file into +place right next to wherever node is installed. (Presumably, this is in your +PATH, and defaults to \fB/usr/local/bin\fR.) On activation, the versioned file +will get linked to the main filename (just like how the main.js stuff works, +but with an executable in the PATH.) +. +.P +For example, npm has this: +. +.IP "" 4 +. +.nf +{ "bin" : { "npm" : "./cli.js" } } +. +.fi +. +.IP "" 0 +. +.P +So, when you install npm, it'll create a symlink from the \fBcli.js\fR script to \fB/usr/local/bin/npm\-version\fR. Then, when you activate that version, it'll +create a symlink from \fB/usr/local/bin/npm\-version\fR to \fB/usr/local/bin/npm\fR. +. +.P +(props to \fImikeal\fR for the idea) diff --git a/man/link.1 b/man/link.1 new file mode 100644 index 000000000..bfc364850 --- /dev/null +++ b/man/link.1 @@ -0,0 +1,20 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM\-LINK" "1" "April 2010" "" "" +. +.SH "NAME" +\fBnpm\-link\fR \-\- Symlink a package folder +. +.SH "SYNOPSIS" +. +.nf +npm link <folder> +. +.fi +. +.SH "DESCRIPTION" +This will link a source folder into npm's registry using a symlink, and then +build it according to the package.json file in that folder's root. This is +handy for installing your own stuff, so that you can work on it and test it +iteratively without having to continually rebuild. diff --git a/man/list.1 b/man/list.1 new file mode 100644 index 000000000..a003e979e --- /dev/null +++ b/man/list.1 @@ -0,0 +1,26 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM\-LIST" "1" "April 2010" "" "" +. +.SH "NAME" +\fBnpm\-list\fR \-\- List installed packages +. +.SH "SYNOPSIS" +. +.nf +npm list [package] +npm ls [package] +. +.fi +. +.SH "DESCRIPTION" +This will show the installed (and, potentially, activated) versions of all the +packages that npm has installed, or just the \fBpackage\fR if specified. +. +.P +This is also aliased to \fBls\fR. +. +.P +\fBFIXME\fR: Prints to stderr, but should really be stdout, since the log is what +you're after. diff --git a/man/ln.1 b/man/ln.1 new file mode 100644 index 000000000..bfc364850 --- /dev/null +++ b/man/ln.1 @@ -0,0 +1,20 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM\-LINK" "1" "April 2010" "" "" +. +.SH "NAME" +\fBnpm\-link\fR \-\- Symlink a package folder +. +.SH "SYNOPSIS" +. +.nf +npm link <folder> +. +.fi +. +.SH "DESCRIPTION" +This will link a source folder into npm's registry using a symlink, and then +build it according to the package.json file in that folder's root. This is +handy for installing your own stuff, so that you can work on it and test it +iteratively without having to continually rebuild. diff --git a/man/ls.1 b/man/ls.1 new file mode 100644 index 000000000..a003e979e --- /dev/null +++ b/man/ls.1 @@ -0,0 +1,26 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM\-LIST" "1" "April 2010" "" "" +. +.SH "NAME" +\fBnpm\-list\fR \-\- List installed packages +. +.SH "SYNOPSIS" +. +.nf +npm list [package] +npm ls [package] +. +.fi +. +.SH "DESCRIPTION" +This will show the installed (and, potentially, activated) versions of all the +packages that npm has installed, or just the \fBpackage\fR if specified. +. +.P +This is also aliased to \fBls\fR. +. +.P +\fBFIXME\fR: Prints to stderr, but should really be stdout, since the log is what +you're after. diff --git a/man/npm.1 b/man/npm.1 new file mode 100644 index 000000000..cf5fa517b --- /dev/null +++ b/man/npm.1 @@ -0,0 +1,305 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM" "1" "May 2010" "" "" +. +.SH "NAME" +\fBnpm\fR \-\- node package manager +. +.SH "SYNOPSIS" +. +.nf +npm <command> [args] +. +.fi +. +.SH "DESCRIPTION" +npm is a little package manager for the Node javascript library. +. +.P +Run \fBnpm help\fR for more details about specific commands. +. +.SH "STATUS: beta" +The core functionality is there. You can publish, tag, and install. It +handles dependencies relatively smartly. +. +.P +Please use this software. It will cut you occasionally. Let me know when +you find a rough edge, and I'll sand it down for you. +. +.P +I appreciate your sense of adventure. +. +.P +If you are a package maintainer, please investigate the documentation on +the \fBjson\fR, \fBpublish\fR, and \fBtag\fR sections first. You might also want to +take a look at the \fBfolders\fR section to see how you can leverage npm's +functionality for your own purposes. You can get to these by running \fBnpm help <subject>\fR or, if you've installed the documentation, by doing \fBman npm\-<subject>\fR. +. +.P +Here's what I mean by "core functionality": +. +.IP "\(bu" 4 +Install packages by name, and get the stable version. +. +.IP "\(bu" 4 +Install packages by supplying a name and version, and get the version +specified. +. +.IP "\(bu" 4 +Install more than one package at a time by specifying them all on the +command line. +. +.IP "\(bu" 4 +Install pre\-requisites automatically, pulling the stable versions of the +dependencies. +. +.IP "\(bu" 4 +Talk to a centralized repository to do all this package/version lookup +magic. +. +.IP "\(bu" 4 +Install more than one version of a package, and optionally select an +"active" version. +. +.IP "\(bu" 4 +Safely uninstall packages, not removing them unless they have no dependents. +. +.IP "\(bu" 4 +Provide a utility for uploading a package.json to a js\-registry repository. +. +.IP "\(bu" 4 +Handle circular dependencies nicely. +. +.IP "\(bu" 4 +Install and activate automatically. +. +.IP "\(bu" 4 +Be much smarter about cli arguments. +. +.IP "\(bu" 4 +Help topics. +. +.IP "\(bu" 4 +Install a "link" to a dev directory, so that it links it in rather than +doing the moveIntoPlace step. +. +.IP "" 0 +. +.SH "Principles" +Put the files where they need to be so that node can find them using the +methods it already uses. +. +.P +Be lazy, not clever. +. +.P +The file system is the database. +. +.P +Sync with habits that are already in use. +. +.P +Packages should be maintained by their authors, not by the package manager +author. +. +.P +Run it on node. Cuz a node package manager should be written in evented +javascript. +. +.SH "Contributing" +If you're interested in helping, that's awesome! Please fork this project, +implement some of the things on the todo list, or fix an issue, or even +just write or edit some documentation. You have no idea just how thankful +I'll be. +. +.P +You can usually find me in #node.js on freenode.net, or you can reach me via +i@izs.me. +. +.P +If you don't want to contribute patches, that's also cool. It's very helpful +to have people play with npm and send issues or complaints. It's stable in +what it does, so you may find it useful even if you just link in your stuff +by doing \fBnpm link .\fR to put it in the \fBNODE_PATH\fR so you can pull it in +more easily. +. +.P +If you have strong feelings about package managers, I'd love to hear your +opinions. +. +.SH "Todo" +. +.IP "\(bu" 4 +Uninstall dependent packages. +. +.IP "\(bu" 4 +Update dependencies when a new satisfying version is installed. +. +.IP "\(bu" 4 +A few of the commands are still a bit user\-hostile, and crash in +strange or un\-helpful ways when they are not given the data they expect. +Make them not do that. +. +.IP "\(bu" 4 +Some sugar to make it simpler to tie a git repo to a published package, and then +automatically update the registry whenever a specific branch (or semver\-looking +tag) is pushed. +. +.IP "\(bu" 4 +Clean up after botched builds. Rather than removing stuff, move it aside, and +only remove it when the process succeeds. If it fails, then roll it all back +to the way it was beforehand. +. +.IP "\(bu" 4 +Show what can be installed by looking at the registry. +. +.IP "\(bu" 4 +Use path.relative so that the whole root can be picked up and moved easily. +. +.IP "\(bu" 4 +Change the registry so that it keeps the tarball as a couchdb attachment. +(That's more a change to js\-registry, not to npm, but they are related.) +. +.IP "\(bu" 4 +Ability to talk to more than one registry at a time. +. +.IP "\(bu" 4 +Abbrev support on the CLI commands +. +.IP "\(bu" 4 +A bash\-completion script +. +.IP "" 0 +. +.SH "Version History" +. +.SS "0.0.1" +. +.IP "\(bu" 4 +Lots of sketches and false starts. Abandoned a few times. +. +.IP "" 0 +. +.SS "0.0.2" +. +.IP "\(bu" 4 +Install worked mostly. Still promise\-based. +. +.IP "" 0 +. +.SS "0.0.3" +. +.IP "\(bu" 4 +Converted to callbacks. +. +.IP "\(bu" 4 +Mikeal Rogers wrote a registry for it. +. +.IP "" 0 +. +.SS "0.0.4" +. +.IP "\(bu" 4 +version dependencies +. +.IP "\(bu" 4 +link packages +. +.IP "\(bu" 4 +activation +. +.IP "\(bu" 4 +lifecycle scripts +. +.IP "\(bu" 4 +bin linking +. +.IP "\(bu" 4 +uninstallation +. +.IP "" 0 +. +.SS "0.0.5" +. +.IP "\(bu" 4 +fix a few bugs in uninstall wrt dependent packages +. +.IP "\(bu" 4 +fix relative require()for nodejs modules installed with the "bin" field. +(issue #2) +. +.IP "\(bu" 4 +update to work with node 0.1.33 (aka net2) +. +.IP "\(bu" 4 +added publish and tag commands +. +.IP "" 0 +. +.SS "0.0.6" +. +.IP "\(bu" 4 +set up a public registry +. +.IP "\(bu" 4 +send content\-length with registry PUTs +. +.IP "\(bu" 4 +adduser command (Mikeal Rogers) +. +.IP "\(bu" 4 +ini file stuff (Mikeal Rogers) +. +.IP "\(bu" 4 +env\-specific package.json +. +.IP "\(bu" 4 +added more info to npm's the package.json (bugs, contributors, etc.) +. +.IP "" 0 +. +.SS "0.0.7" +. +.IP "\(bu" 4 +fixed a few bugs in semver +. +.IP "\(bu" 4 +refactor documentation +. +.IP "\(bu" 4 +add "help" command +. +.IP "\(bu" 4 +add install from registry +. +.IP "\(bu" 4 +everything else core +. +.IP "\(bu" 4 +push to beta +. +.IP "" 0 +. +.SS "0.1.0" +. +.IP "\(bu" 4 +push to beta, and announce +. +.IP "\(bu" 4 +clean up some bugs around lifecycle scripts +. +.IP "\(bu" 4 +reduce reliance on makefile +. +.IP "\(bu" 4 +documentation updates +. +.IP "" 0 +. +.SS "0.1.1" +. +.IP "\(bu" 4 +Fixed 2 DOA bugs in 0.1.0 +. +.IP "" 0 diff --git a/man/publish.1 b/man/publish.1 new file mode 100644 index 000000000..1924809f1 --- /dev/null +++ b/man/publish.1 @@ -0,0 +1,21 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM\-PUBLISH" "1" "April 2010" "" "" +. +.SH "NAME" +\fBnpm\-publish\fR \-\- Publish a package +. +.SH "SYNOPSIS" +. +.nf +npm publish <tarball\-url> +. +.fi +. +.SH "DESCRIPTION" +Publishes a tarball containing a package to the npm registry. +. +.P +When installation from the registry is supported, this will be much more +relevant. diff --git a/man/registry.1 b/man/registry.1 new file mode 100644 index 000000000..ea74f63a3 --- /dev/null +++ b/man/registry.1 @@ -0,0 +1,55 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM\-REGISTRY" "1" "April 2010" "" "" +. +.SH "NAME" +\fBnpm\-registry\fR \-\- Notes on the JavaScript package registry +. +.SH "MARKED FOR REMOVAL" +This doc file will be removed once its contents have been implemented and its +data moved to the relevant command documentation. +. +.SH "npm registry" +Notes on npm's use of the \fIjs\-registry\fR. +. +.P +As of 2010\-04\-25, the "new commands" have been added, but the changes to the +"changed commands" have not been made yet. +. +.SH "Changed commands" +. +.SS "install" +Assuming that the stable branch of foo is 0.1.3, then all three of these do +the same thing: +. +.IP "" 4 +. +.nf +npm install foo +npm install foo\-0.1.3 +npm install foo 0.1.3 +. +.fi +. +.IP "" 0 +. +.P +Furthermore, dependencies are installed implicitly. +. +.SS "list" +npm list will now also show packages that are in the registry for +installation, along with info about their tags and versions, etc. To limit to +a particular tag, preface it with @, for instance: \fBnpm list foo @stable\fR to +show the stable version of foo. \fBnpm list @stable\fR would so all packages with +a tag of \fBstable\fR. +. +.P +The current behavior will be available via \fBnpm list @installed\fR. +. +.SH "Configuration" +A registry base URL must be specified, either with the \fB\-\-registry <url>\fR in +the command line, or by setting a registry url in the .npmrc file. +. +.P +Also, need something to keep track of the user who's logged in? That's dicey. diff --git a/man/rm.1 b/man/rm.1 new file mode 100644 index 000000000..79170fa0c --- /dev/null +++ b/man/rm.1 @@ -0,0 +1,20 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM\-UNINSTALL" "1" "April 2010" "" "" +. +.SH "NAME" +\fBnpm\-uninstall\fR \-\- Remove a package +. +.SH "SYNOPSIS" +. +.nf +npm uninstall <name> <version> +npm rm <name> <version> +. +.fi +. +.SH "DESCRIPTION" +This uninstalls a package, completely removing everything installed for it. If +it's currently active, then it must be deactivated first. If anything is +depending on it, then those must be uninstalled first. diff --git a/man/scripts.1 b/man/scripts.1 new file mode 100644 index 000000000..1c0626342 --- /dev/null +++ b/man/scripts.1 @@ -0,0 +1,131 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM\-SCRIPTS" "1" "April 2010" "" "" +. +.SH "NAME" +\fBnpm\-scripts\fR \-\- How npm handles the "scripts" field +. +.SH "DESCRIPTION" +npm supports the "scripts" member of the package.json script, for the +following scripts: +. +.TP +preinstall +Run BEFORE the package is installed +. +.TP +install +Run AFTER the package is installed. +. +.TP +preactivate +Run BEFORE the package is activated. +. +.TP +activate +Run AFTER the package has been activated. +. +.TP +deactivate +Run BEFORE the package is deactivated. +. +.TP +postdeactivate +Run AFTER the package is deactivated. +. +.TP +uninstall +Run BEFORE the package is uninstalled. +. +.TP +postuninstall +Run AFTER the package is uninstalled. +. +.SH "Package Lifecycle Env Vars" +Package scripts are run in an environment where the package.json fields have +been tacked onto the \fBnpm_package_\fR prefix. So, for instance, if you had \fB{"name":"foo", "version":"1.2.5"}\fR in your package.json file, then in your +various lifecycle scripts, this would be true: +. +.IP "" 4 +. +.nf +process.env.npm_package_name === "foo" +process.env.npm_package_version === "1.2.5" +. +.fi +. +.IP "" 0 +. +.P +Objects are flattened following this format, so if you had\fB{"scripts":{"install":"foo.js"}}\fR in your package.json, then you'd see this +in the script: +. +.IP "" 4 +. +.nf +process.env.npm_package_scripts_install = "foo.js" +. +.fi +. +.IP "" 0 +. +.P +Last but not least, the \fBnpm_lifecycle_event\fR environment variable is set to +whichever stage of the cycle is being executed. So, you could have a single +script used for different parts of the process which switches based on what's +currently happening. +. +.P +If the script exits with a code other than 0, then this will abort the +process. +. +.P +Note that these script files don't have to be nodejs or even javascript +programs. They just have to be some kind of executable file. +. +.P +For example, if your package.json contains this: +. +.IP "" 4 +. +.nf +{ "scripts" : + { "install" : "scripts/install.js" + , "postinstall" : "scripts/install.js" + , "activate" : "scripts/install.js" + , "uninstall" : "scripts/uninstall.js" + } +} +. +.fi +. +.IP "" 0 +. +.P +then the \fBscripts/install.js\fR will be called for the install, post\-install, +and activate stages of the lifecycle, and the \fBscripts/uninstall.js\fR would be +called when the package is uninstalled. Since \fBscripts/install.js\fR is running +for three different phases, it would be wise in this case to look at the \fBnpm_lifecycle_event\fR environment variable. +. +.P +If you want to run a make command, you can do so. This works just fine: +. +.IP "" 4 +. +.nf +{ "scripts" : + { "preinstall" : "./configure" + , "install" : "make" + , "test" : "make test" + } +} +. +.fi +. +.IP "" 0 +. +.P +However, the script line is not simply a command line, so \fBmake && make install\fR +would try to execute the \fBmake\fR command with the arguments \fB&&\fR, \fBmake\fR, and \fBinstall\fR. If you have a lot of stuff to run in a command, put it in a script +file. diff --git a/man/tag.1 b/man/tag.1 new file mode 100644 index 000000000..6132b05d2 --- /dev/null +++ b/man/tag.1 @@ -0,0 +1,24 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM\-TAG" "1" "April 2010" "" "" +. +.SH "NAME" +\fBnpm\-tag\fR \-\- Tag a published version +. +.SH "SYNOPSIS" +. +.nf +npm tag packagename 1.2.3 tagname +. +.fi +. +.SH "DESCRIPTION" +Tags the specified version of "packagename" with the specified "tagname". +. +.P +The only tag with any special significance is "stable". +. +.P +When installation from the registry is supported, this will be much more +relevant. diff --git a/man/uninstall.1 b/man/uninstall.1 new file mode 100644 index 000000000..79170fa0c --- /dev/null +++ b/man/uninstall.1 @@ -0,0 +1,20 @@ +.\" generated with Ronn/v0.4.1 +.\" http://github.com/rtomayko/ronn/ +. +.TH "NPM\-UNINSTALL" "1" "April 2010" "" "" +. +.SH "NAME" +\fBnpm\-uninstall\fR \-\- Remove a package +. +.SH "SYNOPSIS" +. +.nf +npm uninstall <name> <version> +npm rm <name> <version> +. +.fi +. +.SH "DESCRIPTION" +This uninstalls a package, completely removing everything installed for it. If +it's currently active, then it must be deactivated first. If anything is +depending on it, then those must be uninstalled first. |