Permalink
Browse files

Document how "link" will work

  • Loading branch information...
1 parent e676ee1 commit 78f7d94b1c3e7f1155a73d673e2c5545a392f02f @isaacs isaacs committed Jan 31, 2011
Showing with 96 additions and 0 deletions.
  1. +44 −0 doc/future-ideas/new-module-system.md
  2. +52 −0 man1/future-ideas/new-module-system.1
@@ -230,3 +230,47 @@ If global is set to "false", or unset and the command is in a package
folder with a copy of the package being removed, then it removes it from
the local folder.
+### Linking
+
+When `npm link` is run without any arguments in a package folder, then a
+symbolic link is created from that folder to `root/<name>/LINK`.
+Additionally, its package dependencies are installed to its
+./node_modules folder as necessary.
+
+When `npm link <name>` is run in another package folder, a symbolic
+link is created from `root/<name>/LINK` to `./node_modules/<name>`, and
+its dependencies are also installed if necessary. (Generally, it will
+not be necessary, as the package will already have its own node_modules
+folder containing its dependencies.)
+
+When publishing, linked package dependencies are resolved to their
+current state. It is assumed that the linked folder was linked for a
+reason, and may contain changes required for the proper functioning of
+the host program.
+
+#### npm link use case
+
+ # create a linked "request" package
+ cd ~/projects/request
+ npm link
+
+ # now write a program that uses request
+ mkdir -p ~/projects/my-program
+ cd ~/projects/my-program
+ git init
+ # do your git stuff...
+ npm init
+ # enter some package.json values
+ # now we're ready to rock.
+ # use redis, but don't need bleeding edge.
+ npm install redis
+ # use the linked copy of request
+ npm link request
+
+ # now any changes to ~/projects/request will
+ # be immediately effective in my-program when
+ # I do require("request")
+
+#### link on Windows
+
+Not sure how this will work. Maybe linking simply isn't possible?
@@ -280,3 +280,55 @@ If global is set to "true", or implied, then it removes the global copy\.
If global is set to "false", or unset and the command is in a package
folder with a copy of the package being removed, then it removes it from
the local folder\.
+.
+.SS "Linking"
+When \fBnpm link\fR is run without any arguments in a package folder, then a
+symbolic link is created from that folder to \fBroot/<name>/LINK\fR\|\.
+Additionally, its package dependencies are installed to its
+\|\./node_modules folder as necessary\.
+.
+.P
+When \fBnpm link <name>\fR is run in another package folder, a symbolic
+link is created from \fBroot/<name>/LINK\fR to \fB\|\./node_modules/<name>\fR, and
+its dependencies are also installed if necessary\. (Generally, it will
+not be necessary, as the package will already have its own node_modules
+folder containing its dependencies\.)
+.
+.P
+When publishing, linked package dependencies are resolved to their
+current state\. It is assumed that the linked folder was linked for a
+reason, and may contain changes required for the proper functioning of
+the host program\.
+.
+.TP
+npm link use case
+.
+.IP "" 4
+.
+.nf
+# create a linked "request" package
+cd ~/projects/request
+npm link
+# now write a program that uses request
+mkdir \-p ~/projects/my\-program
+cd ~/projects/my\-program
+git init
+# do your git stuff\.\.\.
+npm init
+# enter some package\.json values
+# now we\'re ready to rock\.
+# use redis, but don\'t need bleeding edge\.
+npm install redis
+# use the linked copy of request
+npm link request
+# now any changes to ~/projects/request will
+# be immediately effective in my\-program when
+# I do require("request")
+.
+.fi
+.
+.IP "" 0
+.
+.TP
+link on Windows
+.Not sure how this will work\. Maybe linking simply isn\'t possible?

0 comments on commit 78f7d94

Please sign in to comment.