Skip to content
Browse files

Add built documentation to project, so that the install doesn't requi…

…re ronn
  • Loading branch information...
1 parent a3dec1a commit b70b2a09fa76f1cc3e3f9da7dd4f48ac073d6d0a @isaacs isaacs committed
Showing with 1,348 additions and 1 deletion.
  1. +0 −1 .gitignore
  2. +20 −0 man/activate.1
  3. +37 −0 man/adduser.1
  4. +43 −0 man/build.1
  5. +107 −0 man/config.1
  6. +21 −0 man/deactivate.1
  7. +40 −0 man/folders.1
  8. +24 −0 man/help.1
  9. +148 −0 man/install.1
  10. +240 −0 man/json.1
  11. +20 −0 man/link.1
  12. +26 −0 man/list.1
  13. +20 −0 man/ln.1
  14. +26 −0 man/ls.1
  15. +305 −0 man/npm.1
  16. +21 −0 man/publish.1
  17. +55 −0 man/registry.1
  18. +20 −0 man/rm.1
  19. +131 −0 man/scripts.1
  20. +24 −0 man/tag.1
  21. +20 −0 man/uninstall.1
View
1 .gitignore
@@ -1 +0,0 @@
-man
View
20 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
View
37 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
View
43 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
View
107 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.
View
21 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
View
40 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
View
24 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.
View
148 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
View
240 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)
View
20 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.
View
26 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.
View
20 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.
View
26 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.
View
305 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
View
21 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.
View
55 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.
View
20 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.
View
131 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.
View
24 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.
View
20 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.

0 comments on commit b70b2a0

Please sign in to comment.
Something went wrong with that request. Please try again.