diff options
author | isaacs <i@izs.me> | 2010-08-24 22:40:22 +0400 |
---|---|---|
committer | isaacs <i@izs.me> | 2010-08-25 16:21:49 +0400 |
commit | 4792d408ec52cfb8c2382ff274dab6349bb625c9 (patch) | |
tree | 4bd0ec65dbb8259eb5f6abf8b6008e76505263e1 | |
parent | 3465d16816e23fffcfc25316cc4e4b452d9dcc99 (diff) |
Put directories.lib info back in the doc, and document the repository set
-rw-r--r-- | doc/json.md | 68 | ||||
-rw-r--r-- | man/json.1 | 90 |
2 files changed, 156 insertions, 2 deletions
diff --git a/doc/json.md b/doc/json.md index cdb5118b8..5035b0a5e 100644 --- a/doc/json.md +++ b/doc/json.md @@ -65,8 +65,74 @@ package named `foo`, and the package.json contains `"modules":{"bar":"./lib/baz" and there was a file called `./lib/baz.js`, then require("foo/bar") would include the module defined in `./lib/baz.js`. +Subfolders are supported, so you can do this: + + { "name" : "foo" + , "modules" : + { "bar/baz" : "./lib/bar/baz" + , "quux" : "./quux" + } + } + +And then, doing `require("foo/bar/baz")` would return the module at `./lib/bar/baz` +in the foo package. + Just like the `main` script, the modules linked in this fashion will have their -dependencies and paths set up properly by npm. +dependencies and paths set up properly by npm. (In fact, "main" is just sugar +around setting a module named "index".) + +## directories + +The CommonJS [Packages](http://wiki.commonjs.org/wiki/Packages/1.0) spec details a +few ways that you can indicate the structure of your package using a `directories` +hash. If you look at [npm's package.json](http://registry.npmjs.org/npm/latest), +you'll see that it has directories for doc, lib, and man. + +In the future, this information may be used in other creative ways. + +### directories.lib + +If you specify a "lib" directory, and do not supply a modules hash, then the lib folder +will be walked and any *.js or *.node files found will be exposed as a default module +hash. This is to provide backwards compatibility for packages that may have relied +on this functionality when the lib folder was symlinked directly. Providing an explicit +modules hash is encouraged over exposing the entire lib folder. + +## repository + +Specify the place where your code lives. This is helpful for people who want to +contribute, as well as perhaps maybe being the underpinning of some magical "track +this package on git" feature someday maybe if somebody wants to write it ever. + +Do it like this: + + "repository" : + { "type" : "git" + , "url" : "http://github.com/isaacs/npm.git" + } + + "repository" : + { "type" : "svn" + , "url" : "http://v8.googlecode.com/svn/trunk/" + } + +The URL should be a publicly available (perhaps read-only) url that can be handed +directly to a VCS program without any modification. It should not be a url to an +html project page that you put in your browser. It's for computers. + +Here are some examples of Doing It Wrong: + + WRONG! + "repository" : + { "type" : "git" + , "url" : "git@github.com:isaacs/npm.git" <-- THIS IS PRIVATE! + } + + ALSO WRONG! + "repository" : + { "type" : "git" + , "url" : "http://github.com/isaacs/npm" <-- THIS IS WEBPAGE! + } ## scripts diff --git a/man/json.1 b/man/json.1 index f0cb2b2a5..98c41546d 100644 --- a/man/json.1 +++ b/man/json.1 @@ -84,8 +84,96 @@ and there was a file called \fB\|\./lib/baz\.js\fR, then require("foo/bar") woul the module defined in \fB\|\./lib/baz\.js\fR\|\. . .P +Subfolders are supported, so you can do this: +. +.IP "" 4 +. +.nf +{ "name" : "foo" +, "modules" : + { "bar/baz" : "\./lib/bar/baz" + , "quux" : "\./quux" + } +} +. +.fi +. +.IP "" 0 +. +.P +And then, doing \fBrequire("foo/bar/baz")\fR would return the module at \fB\|\./lib/bar/baz\fR +in the foo package\. +. +.P Just like the \fBmain\fR script, the modules linked in this fashion will have their -dependencies and paths set up properly by npm\. +dependencies and paths set up properly by npm\. (In fact, "main" is just sugar +around setting a module named "index"\.) +. +.SH "directories" +The CommonJS Packages \fIhttp://wiki\.commonjs\.org/wiki/Packages/1\.0\fR spec details a +few ways that you can indicate the structure of your package using a \fBdirectories\fR +hash\. If you look at npm\'s package\.json \fIhttp://registry\.npmjs\.org/npm/latest\fR, +you\'ll see that it has directories for doc, lib, and man\. +. +.P +In the future, this information may be used in other creative ways\. +. +.SS "directories\.lib" +If you specify a "lib" directory, and do not supply a modules hash, then the lib folder +will be walked and any \fI\|\.js or \fR\|\.node files found will be exposed as a default module +hash\. This is to provide backwards compatibility for packages that may have relied +on this functionality when the lib folder was symlinked directly\. Providing an explicit +modules hash is encouraged over exposing the entire lib folder\. +. +.SH "repository" +Specify the place where your code lives\. This is helpful for people who want to +contribute, as well as perhaps maybe being the underpinning of some magical "track +this package on git" feature someday maybe if somebody wants to write it ever\. +. +.P +Do it like this: +. +.IP "" 4 +. +.nf +"repository" : + { "type" : "git" + , "url" : "http://github\.com/isaacs/npm\.git" + } +"repository" : + { "type" : "svn" + , "url" : "http://v8\.googlecode\.com/svn/trunk/" + } +. +.fi +. +.IP "" 0 +. +.P +The URL should be a publicly available (perhaps read\-only) url that can be handed +directly to a VCS program without any modification\. It should not be a url to an +html project page that you put in your browser\. It\'s for computers\. +. +.P +Here are some examples of Doing It Wrong: +. +.IP "" 4 +. +.nf +WRONG! +"repository" : + { "type" : "git" + , "url" : "git@github\.com:isaacs/npm\.git" <\-\- THIS IS PRIVATE! + } +ALSO WRONG! +"repository" : + { "type" : "git" + , "url" : "http://github\.com/isaacs/npm" <\-\- THIS IS WEBPAGE! + } +. +.fi +. +.IP "" 0 . .SH "scripts" The "scripts" member is an object hash of script commands that are run |