diff options
author | isaacs <i@izs.me> | 2011-09-04 22:21:30 +0400 |
---|---|---|
committer | isaacs <i@izs.me> | 2011-09-04 22:21:30 +0400 |
commit | 32f2673e00ddf0714c4a43a4a31d9d8cab981ab8 (patch) | |
tree | 70956b6aa420948f060160269d946b61dfb7d6a6 | |
parent | 023bb497fa410d900fdd8a68b9b759806db5aa42 (diff) |
Add README as proper html/manpage doc
-rw-r--r-- | Makefile | 2 | ||||
-rw-r--r-- | README.md | 8 | ||||
-rw-r--r-- | html/doc/README.html | 8 | ||||
-rw-r--r-- | man1/README.1 | 313 |
4 files changed, 329 insertions, 2 deletions
@@ -2,7 +2,7 @@ SHELL = bash docs = $(shell find doc -name '*.md' \ |sed 's|.md|.1|g' \ - |sed 's|doc/|man1/|g' ) + |sed 's|doc/|man1/|g' ) man1/README.1 htmldocs = $(shell find doc -name '*.md' \ |sed 's|.md|.html|g' \ @@ -1,6 +1,8 @@ npm(1) -- node package manager ============================== +## SYNOPSIS + This is just enough info to get you up and running. Much more info available via `npm help` once it's installed. @@ -187,3 +189,9 @@ reported, and we'll lose respect for you. But there is no vetting process for published modules. If this concerns you, inspect the source before using packages. + +## SEE ALSO + +* npm(1) +* npm-faq(1) +* npm-help(1) diff --git a/html/doc/README.html b/html/doc/README.html index d3b9c1580..66244f86f 100644 --- a/html/doc/README.html +++ b/html/doc/README.html @@ -1,6 +1,6 @@ <!doctype html> <html> - <title></title> + <title><a href="README.html">README</a></title> <meta http-equiv="content-type" value="text/html;utf-8"> <style type="text/css"> @@ -339,6 +339,8 @@ input.submit, input#submit, input.button, button, input[type=submit] { <div id="wrapper"> <h1><a href="npm.html">npm</a></h1> <p>node package manager</p> +<h2 id="SYNOPSIS">SYNOPSIS</h2> + <p>This is just enough info to get you up and running.</p> <p>Much more info available via <code>npm help</code> once it's installed.</p> @@ -524,6 +526,10 @@ reported, and we'll lose respect for you. But there is no vetting process for published modules.</p> <p>If this concerns you, inspect the source before using packages.</p> + +<h2 id="SEE-ALSO">SEE ALSO</h2> + +<ul><li><a href="npm.html">npm</a></li><li><a href="faq.html">npm faq</a></li><li><a href="help.html">npm help</a></li></ul> </div> <script> ;(function () { diff --git a/man1/README.1 b/man1/README.1 new file mode 100644 index 000000000..cafbdbcff --- /dev/null +++ b/man1/README.1 @@ -0,0 +1,313 @@ +.\" Generated with Ronnjs/v0.1 +.\" http://github.com/kapouer/ronnjs/ +. +.TH "NPM" "1" "September 2011" "" "" +. +.SH "NAME" +\fBnpm\fR \-\- node package manager +. +.SH "SYNOPSIS" +This is just enough info to get you up and running\. +. +.P +Much more info available via \fBnpm help\fR once it\'s installed\. +. +.SH "IMPORTANT" +\fBYou need node v0\.4 or higher to run this program\.\fR +. +.P +To install an old \fBand unsupported\fR version of npm that works on node 0\.3 +and prior, clone the git repo and dig through the old tags and branches\. +. +.SH "Simple Install" +To install npm with one command, do this: +. +.IP "" 4 +. +.nf +curl http://npmjs\.org/install\.sh | sh +. +.fi +. +.IP "" 0 +. +.P +To skip the npm 0\.x cleanup, do this: +. +.IP "" 4 +. +.nf +curl http://npmjs\.org/install\.sh | clean=no sh +. +.fi +. +.IP "" 0 +. +.P +To say "yes" to the 0\.x cleanup, but skip the prompt: +. +.IP "" 4 +. +.nf +curl http://npmjs\.org/install\.sh | clean=yes sh +. +.fi +. +.IP "" 0 +. +.P +If that fails, try this: +. +.IP "" 4 +. +.nf +git clone https://github\.com/isaacs/npm\.git +cd npm +sudo make install +. +.fi +. +.IP "" 0 +. +.P +If you\'re sitting in the code folder reading this document in your +terminal, then you\'ve already got the code\. Just do: +. +.IP "" 4 +. +.nf +sudo make install +. +.fi +. +.IP "" 0 +. +.P +and npm will install itself\. +. +.P +If you don\'t have make, and don\'t have curl or git, and ALL you have is +this code and node, you can probably do this: +. +.IP "" 4 +. +.nf +sudo node \./cli\.js install \-g +. +.fi +. +.IP "" 0 +. +.P +However, note that github tarballs \fBdo not contain submodules\fR, so +those won\'t work\. You\'ll have to also fetch the appropriate submodules +listed in the \.gitmodules file\. +. +.SH "Permissions" +\fBtl;dr\fR +. +.IP "\(bu" 4 +Use \fBsudo\fR for greater safety\. Or don\'t, if you prefer not to\. +. +.IP "\(bu" 4 +npm will downgrade permissions if it\'s root before running any build +scripts that package authors specified\. +. +.IP "" 0 +. +.SS "More details\.\.\." +As of version 0\.3, it is recommended to run npm as root\. +This allows npm to change the user identifier to the \fBnobody\fR user prior +to running any package build or test commands\. +. +.P +If you are not the root user, or if you are on a platform that does not +support uid switching, then npm will not attempt to change the userid\. +. +.P +If you would like to ensure that npm \fBalways\fR runs scripts as the +"nobody" user, and have it fail if it cannot downgrade permissions, then +set the following configuration param: +. +.IP "" 4 +. +.nf +npm config set unsafe\-perm false +. +.fi +. +.IP "" 0 +. +.P +This will prevent running in unsafe mode, even as non\-root users\. +. +.SH "Uninstalling" +So sad to see you go\. +. +.IP "" 4 +. +.nf +sudo npm uninstall npm \-g +. +.fi +. +.IP "" 0 +. +.P +Or, if that fails, +. +.IP "" 4 +. +.nf +sudo make uninstall +. +.fi +. +.IP "" 0 +. +.SH "More Severe Uninstalling" +Usually, the above instructions are sufficient\. That will remove +npm, but leave behind anything you\'ve installed\. +. +.P +If you would like to remove all the packages that you have installed, +then you can use the \fBnpm ls\fR command to find them, and then \fBnpm rm\fR to +remove them\. +. +.P +To remove cruft left behind by npm 0\.x, you can use the included \fBclean\-old\.sh\fR script file\. You can run it conveniently like this: +. +.IP "" 4 +. +.nf +npm explore npm \-g \-\- sh scripts/clean\-old\.sh +. +.fi +. +.IP "" 0 +. +.P +npm uses two configuration files, one for per\-user configs, and another +for global (every\-user) configs\. You can view them by doing: +. +.IP "" 4 +. +.nf +npm config get userconfig # defaults to ~/\.npmrc +npm config get globalconfig # defaults to /usr/local/etc/npmrc +. +.fi +. +.IP "" 0 +. +.P +Uninstalling npm does not remove configuration files by default\. You +must remove them yourself manually if you want them gone\. Note that +this means that future npm installs will not remember the settings that +you have chosen\. +. +.SH "Using npm Programmatically" +If you would like to use npm programmatically, you can do that\. +It\'s not very well documented, but it \fIis\fR rather simple\. +. +.IP "" 4 +. +.nf +var npm = require("npm") +npm\.load(myConfigObject, function (er) { + if (er) return handlError(er) + npm\.commands\.install(["some", "args"], function (er, data) { + if (er) return commandFailed(er) + // command succeeded, and data might have some info + }) + npm\.on("log", function (message) { \.\.\.\. }) +}) +. +.fi +. +.IP "" 0 +. +.P +The \fBload\fR function takes an object hash of the command\-line configs\. +The various \fBnpm\.commands\.<cmd>\fR functions take an \fBarray\fR of +positional argument \fBstrings\fR\|\. The last argument to any \fBnpm\.commands\.<cmd>\fR function is a callback\. Some commands take other +optional arguments\. Read the source\. +. +.P +You cannot set configs individually for any single npm function at this +time\. Since \fBnpm\fR is a singleton, any call to \fBnpm\.config\.set\fR will +change the value for \fIall\fR npm commands in that process\. +. +.P +See \fB\|\./bin/npm\.js\fR for an example of pulling config values off of the +command line arguments using nopt\. You may also want to check out \fBnpm +help config\fR to learn about all the options you can set there\. +. +.SH "More Docs" +Check out the docs \fIhttp://npmjs\.org/doc/\fR, +especially the faq \fIhttp://npmjs\.org/doc/faq\.html\fR\|\. +. +.P +You can use the \fBnpm help\fR command to read any of them\. +. +.P +If you\'re a developer, and you want to use npm to publish your program, +you should read this \fIhttp://npmjs\.org/doc/developers\.html\fR +. +.SH "Legal Stuff" +"npm" and "the npm registry" are owned by Isaac Z\. Schlueter\. All +rights not explicitly granted in the MIT license are reserved\. See the +included LICENSE file for more details\. +. +.P +"Node\.js" and "node" are trademarks owned by Joyent, Inc\. npm is not +officially part of the Node\.js project, and is neither owned by nor +officially affiliated with Joyent, Inc\. +. +.P +The packages in the npm registry are not part of npm itself, and are the +sole property of their respective maintainers\. While every effort is +made to ensure accountability, there is absolutely no guarantee, +warrantee, or assertion made as to the quality, fitness for a specific +purpose, or lack of malice in any given npm package\. Modules +published on the npm registry are not affiliated with or endorsed by +Joyent, Inc\., Isaac Z\. Schlueter, Ryan Dahl, or the Node\.js project\. +. +.P +If you have a complaint about a package in the npm registry, and cannot +resolve it with the package owner, please express your concerns to +Isaac Z\. Schlueter at \fIi@izs\.me\fR\|\. +. +.SS "In plain english" +This is mine; not my employer\'s, not Node\'s, not Joyent\'s, not Ryan +Dahl\'s\. +. +.P +If you publish something, it\'s yours, and you are solely accountable +for it\. Not me, not Node, not Joyent, not Ryan Dahl\. +. +.P +If other people publish something, it\'s theirs\. Not mine, not Node\'s, +not Joyent\'s, not Ryan Dahl\'s\. +. +.P +Yes, you can publish something evil\. It will be removed promptly if +reported, and we\'ll lose respect for you\. But there is no vetting +process for published modules\. +. +.P +If this concerns you, inspect the source before using packages\. +. +.SH "SEE ALSO" +. +.IP "\(bu" 4 +npm help npm +. +.IP "\(bu" 4 +npm help faq +. +.IP "\(bu" 4 +npm help help +. +.IP "" 0 + |