From 1a7ef7729681105ea5b81e9cad5d572a6b8af923 Mon Sep 17 00:00:00 2001 From: isaacs Date: Wed, 25 Aug 2010 17:59:32 -0700 Subject: Document the bundle command --- doc/bundle.md | 70 ++++++++++++++++++++++++++++++++ doc/help.md | 1 + man/bundle.1 | 125 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ man/help.1 | 1 + 4 files changed, 197 insertions(+) create mode 100644 doc/bundle.md create mode 100644 man/bundle.1 diff --git a/doc/bundle.md b/doc/bundle.md new file mode 100644 index 000000000..b630c1d65 --- /dev/null +++ b/doc/bundle.md @@ -0,0 +1,70 @@ +npm-bundle(1) -- Bundle package dependencies +============================================ + +## EXPERIMENTAL + +This is experimental functionality. If you have thoughts about how it +should work, please post a comment at: +http://github.com/isaacs/npm/issues/issue/74 + +## SYNOPSIS + + npm bundle [] + +* ``: + The place where bundled dependencies go. +* ``: + The package whose dependencies are to be bundled. Defaults to $PWD. + See `npm help install` for more on the ways to identify a package. + +## DESCRIPTION + +Bundles all the dependencies of a package into a specific folder. + +Furthermore, sets up an index.js in the folder that will shift it onto the +require.paths, and export the bundled modules. + +For example, to install of your requirements into a "deps" folder, +you could do this: + + npm bundle deps + +Assuming your code is in the "lib" folder, and it depended on a package +"foo", you could then do this: + + require("../deps") // this sets the require.paths properly. + var foo = require("foo") + +The bundle index will also return the modules that your package +depends on. So, this would work as well: + + require("../deps").foo.createFoo(...) + +The dependencies of those packages installed will also be installed and +linked, just like an `npm install` command. In fact, internally `buffer` +just sets the `root` config and then does a normal `npm install` to put +the modules in place. + +To update to new versions (or if the dependencies change) then run the +bundle command again. + +## CAVEATS + +There is no pretty to "remove" a package from a bundle at the moment. +However, you can do this: + + npm --root ./deps rm foo + +Bins and man pages are not installed by bundle. + +Packages are *built*, which often means they're compiled in that +architecture and against that version of node. To update them, you can +do: + + npm --root ./deps rebuild + +or run `npm bundle deps` on the target machine. + +The `npm update` command will do *horrible* things to a bundle folder. +Don't ever point update at that root, or your bundles may no longer +satisfy your dependencies. diff --git a/doc/help.md b/doc/help.md index 0db8c1c62..69b20d6f2 100644 --- a/doc/help.md +++ b/doc/help.md @@ -11,6 +11,7 @@ npm-help(1) -- Get help about npm commands activate adduser build +bundle cache coding-style config diff --git a/man/bundle.1 b/man/bundle.1 new file mode 100644 index 000000000..23c3e25d3 --- /dev/null +++ b/man/bundle.1 @@ -0,0 +1,125 @@ +.\" Generated with Ronnjs/v0.1 +.\" http://github.com/kapouer/ronnjs/ +. +.TH "NPM\-BUNDLE" "1" "August 2010" "" "" +. +.SH "NAME" +\fBnpm-bundle\fR \-\- Bundle package dependencies +. +.SH "EXPERIMENTAL" +This is experimental functionality\. If you have thoughts about how it +should work, please post a comment at: +http://github\.com/isaacs/npm/issues/issue/74 +. +.SH "SYNOPSIS" +. +.nf +npm bundle [] +. +.fi +. +.IP "\(bu" 4 +\fB\fR: +The place where bundled dependencies go\. +. +.IP "\(bu" 4 +\fB\fR: +The package whose dependencies are to be bundled\. Defaults to $PWD\. +See \fBnpm help install\fR for more on the ways to identify a package\. +. +.IP "" 0 +. +.SH "DESCRIPTION" +Bundles all the dependencies of a package into a specific folder\. +. +.P +Furthermore, sets up an index\.js in the folder that will shift it onto the +require\.paths, and export the bundled modules\. +. +.P +For example, to install of your requirements into a "deps" folder, +you could do this: +. +.IP "" 4 +. +.nf +npm bundle deps +. +.fi +. +.IP "" 0 +. +.P +Assuming your code is in the "lib" folder, and it depended on a package +"foo", you could then do this: +. +.IP "" 4 +. +.nf +require("\.\./deps") // this sets the require\.paths properly\. +var foo = require("foo") +. +.fi +. +.IP "" 0 +. +.P +The bundle index will also return the modules that your package +depends on\. So, this would work as well: +. +.IP "" 4 +. +.nf +require("\.\./deps")\.foo\.createFoo(\.\.\.) +. +.fi +. +.IP "" 0 +. +.P +The dependencies of those packages installed will also be installed and +linked, just like an \fBnpm install\fR command\. In fact, internally \fBbuffer\fR +just sets the \fBroot\fR config and then does a normal \fBnpm install\fR to put +the modules in place\. +. +.P +To update to new versions (or if the dependencies change) then run the +bundle command again\. +. +.SH "CAVEATS" +There is no pretty to "remove" a package from a bundle at the moment\. +However, you can do this: +. +.IP "" 4 +. +.nf +npm \-\-root \./deps rm foo +. +.fi +. +.IP "" 0 +. +.P +Bins and man pages are not installed by bundle\. +. +.P +Packages are \fIbuilt\fR, which often means they\'re compiled in that +architecture and against that version of node\. To update them, you can +do: +. +.IP "" 4 +. +.nf +npm \-\-root \./deps rebuild +. +.fi +. +.IP "" 0 +. +.P +or run \fBnpm bundle deps\fR on the target machine\. +. +.P +The \fBnpm update\fR command will do \fIhorrible\fR things to a bundle folder\. +Don\'t ever point update at that root, or your bundles may no longer +satisfy your dependencies\. diff --git a/man/help.1 b/man/help.1 index f17a638cf..b19817ccb 100644 --- a/man/help.1 +++ b/man/help.1 @@ -18,6 +18,7 @@ npm help
activate adduser build +bundle cache coding\-style config -- cgit v1.2.3