From 0b249b688ccea8ab18aeeb382104a5a3102e9d62 Mon Sep 17 00:00:00 2001 From: isaacs Date: Mon, 21 Mar 2011 13:55:53 -0700 Subject: make doc for 1.0 --- doc/future-ideas/deploy.md | 27 ---- doc/future-ideas/new-module-system.md | 276 ---------------------------------- doc/future-ideas/remote.md | 23 --- doc/future-ideas/site.md | 58 ------- 4 files changed, 384 deletions(-) delete mode 100644 doc/future-ideas/deploy.md delete mode 100644 doc/future-ideas/new-module-system.md delete mode 100644 doc/future-ideas/remote.md delete mode 100644 doc/future-ideas/site.md (limited to 'doc') diff --git a/doc/future-ideas/deploy.md b/doc/future-ideas/deploy.md deleted file mode 100644 index 9d2e17aa6..000000000 --- a/doc/future-ideas/deploy.md +++ /dev/null @@ -1,27 +0,0 @@ -npm-deploy(1) -- Deploy a package to a remote host -================================================== - -## FUTURE - -This functionality does not yet exist. - -## SUMMARY - - npm deploy [--host ] - -## DESCRIPTION - -This is a porcelain command. It is equivalent to doing: - - npm publish --registry $(npm config get host) - npm remote install @ - -That is, it first publishes the package to the server specified -by the `host` config, and then remotely installs that package -on the host. - -## SEE ALSO - -* npm-remote(1) -* npm-site(1) -* npm-publish(1) diff --git a/doc/future-ideas/new-module-system.md b/doc/future-ideas/new-module-system.md deleted file mode 100644 index acac578a3..000000000 --- a/doc/future-ideas/new-module-system.md +++ /dev/null @@ -1,276 +0,0 @@ -npm-folders(1) -- Folder Structures Used by npm -=============================================== - -## FUTURE - -This functionality is not yet implemented. It is a plan, not reality. -It is not the map, nor the territory, but a blueprint with blank areas. - -In particular, this is the scheme that will be used starting in npm@0.3, -which will require node@0.5.0 or above. - -## GOALS - -* Don't splat stuff across the filesystem so much. Just specify a single -root location, and be done with it. - -* Work on windows. - -* Minimize shim/symlink usage. - -* Do not rely on any global system path for node modules. - -* Remove the "activation" concept. - -## DESCRIPTION - -npm metadata lives in the `root` setting. There is the cache folder, -and the contents of all installed packages. - -The default npm root folder is `/usr/local/lib/npm`. - -TODO: What should the root folder be on windows? - -### Cache folder - -The cache folder is a mirror of the data in the registry, as well as a -working space for unpacking and creating tarballs. - -Files and folders created in the cache are owned by the executing user, -often "root". - -Files are created with 0666 and folders with 0777, so that they can be -modified by any user. - -* `root/cache` Cache folder -* `root/cache/foo/cache.json` Expirable cache of registry/foo json data -* `root/cache/foo/1.2.3/package` Pristine copy of foo package contents -* `root/cache/foo/1.2.3/package.tgz` tarball of foo@1.2.3 - -### Package folders - -In the npm root folder, package contents are unpacked, built, and then -moved into the desired location. - -* `root/packages/foo/1.2.3` Metadata and contents of foo@1.2.3 -* `root/packages/foo/1.2.3/package` Build location of foo@1.2.3 -* `root/packages/foo/1.2.3/node_modules` Links to (or, on windows, copies of) - dependencies of foo@1.2.3 -* `root/packages/foo/1.2.3/metadata.json` Metadata about the foo package. - -### Installation in `node_modules` Folders - -When you run `npm install foo@1.2.3` it downloads and builds the -package, and then, if there is a package.json file in the current -working directory, it copies it to `$PWD/node_modules/foo`, so that your -current package will get it when you do `require("foo")`. - -When this is done, it also installs all of foo's dependencies to -`./node_modules/foo/node_modules/`, so that it will get its dependencies -appropriately when it calls `require()`. If foo depends on bar, and bar -depends on baz, then there will also be a -`./node_modules/foo/node_modules/bar/node_modules/baz`, and so on. - -If there is not a package.json in the current working directory, then -npm walks up the working dir parent paths looking for a package.json, -indicating the root of a package, or a node_modules folder, -indicating an npm package deployment location, and then take the party to that -location. This behavior may be suppressed by setting the `seek-root` -config value to false. - -If no package root is found, then a global installation is performed. -The global installation may be supressed by setting the `global` -configuration to false, in which case, the install will fail. - -### Global Installation - -If the `global` configuration is set to true, or if it is not explicitly -set false and no suitable node_modules folder was found, then npm will -install packages "globally". - -This means that the module contents are symlinked (or, on windows, -copied) from `root///package` to -`root/node_modules/`. - -### Installing executables - -When installing globally, executables are linked (or, on windows, -shimmed with a .bat file) to `root/bin`. - -When doing a -localized installation, executables are linked (or, on windows, shimmed) -to `./node_modules/.bin`. This also applies to the case when a globally -installed package's dependents are being installed into it. Basically, -whenever writing `.../node_modules/foo`, and the "foo" -package has an executable named "bar", it'll write it to -`.../node_modules/.bin/bar`. - -It is up to the user to update their PATH environment variable -appropriately for globally installed executables. When running package -lifecycle scripts (for example, to build, start, test, etc.), npm will -put `./node_modules/.bin` as the first item in the PATH environ. - -### Installing manpages - -npm will install man pages to `root/share/man`. It is up to the user to -make sure that their man program searches this location. - -### Cycles, Conflicts, and Folder Parsimony - -Cycles are handled using the property of node's module system that it -walks up the directories looking for node_modules folders. So, at every -stage, if a package is already installed in an ancestor node_modules -folder, then it is not installed at the current location. - -Consider the case above, where `foo -> bar -> baz`. Imagine if, in -addition to that, baz depended on bar, so you'd have: -`foo -> bar -> baz -> bar -> baz ...`. However, since the folder -structure is: foo/node_modules/bar/node_modules/baz, there's no need to -put another copy of bar into .../baz/node_modules, since when it calls -require("bar"), it will get the copy that is installed in -foo/node_modules/bar. - -This shortcut is only used if the exact same -version would be installed in multiple nested node_modules folders. It -is still possible to have `a/node_modules/b/node_modules/a` if the two -"a" packages are different versions. However, without repeating the -exact same package multiple times, an infinite regress will always be -prevented. - -Another optimization can be made by installing dependencies at the -highest level possible, below the localized "target" folder. - -For example, consider this dependency graph: - - foo - +-- bar@1.2.3 - | +-- baz@2.x - | | `-- quux@3.x - | `-- asdf@* - `-- baz@1.2.3 - `-- quux@3.x - -In this case, we'd expect a folder structure like this: - - foo - +-- node_modules - +-- bar (1.2.3) - | `-- node_modules - | `-- baz (2.0.2) - +-- quux (3.2.0) - +-- asdf (0.2.5) - `-- baz (1.2.3) - -Since foo depends directly on bar@1.2.3 and baz@1.2.3, those are -installed in foo's node_modules folder. - -Since baz@1.2.3 depends on quux@3.x, a satisfying version is placed in -foo's node_modules folder, because there are no conflicts. - -Since bar@1.2.3 depends on asdf@*, a satisfying version is placed in -foo's node_modules folder. It also depends on baz@2.x, but this -conflicts with the version already installed in foo's node_modules -folder, so it is installed into the node_modules folder under bar@1.2.3. - -baz@2.0.2 depends on quux@3.x, but this dependency is already satisfied -by the quux version installed in foo's node_modules folder, so nothing -further needs to be done. - -### Snapshotting - -Whenever the `npm snapshot` command is run, the package.json file is -updated to include the versions of all of the packages in the -`./node_modules` folder as dependencies. - -### Publishing - -Upon publishing, npm will look in the node_modules folder. If any of -the items there are on the "dependencies" or "devDependencies" list, and -are unmodified copies of the corresponding packages in -`root/node_modules///package`, then they will not be -included in the package tarball. - -If the package has been modified, then it is left as-is, and included in -the package. - -This allows a package maintainer to install all of their dependencies -(and dev dependencies) locally, but only publish those items that cannot -be found elsewhere. - -### Updating - -npm keeps track of every installation of foo@1.2.3 in -`root/packages/foo/1.2.3/metadata.json`. - -When updating in a package folder (see algorithm for determining this in -"Installation in `node_modules` Folders"), npm updates the packages in -the local folder to the latest versions that are compatible with the -requirements in the package.json file. - -If global is set to `"super"`, then npm will attempt to update -all copies of packages installed anywhere and everywhere that it is -aware of. - -If `global` is set to `true, or implied by not being in a package folder -at the time, then npm will update the globally installed packages. - -If you do `npm update foo`, and you're in a local package folder, but -`foo` is not installed there, and it *is* installed globally, then that -will be equivalent to doing `npm update foo --global`. - -### Uninstalling - -Uninstalling works like updating. - -If global is set to "super", then it removes all traces from everywhere. - -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. - -### Linking - -When `npm link` is run without any arguments in a package folder, then a -symbolic link is created from that folder to `root//LINK`. -Additionally, its package dependencies are installed to its -./node_modules folder as necessary. - -When `npm link ` is run in another package folder, a symbolic -link is created from `root//LINK` to `./node_modules/`, 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? diff --git a/doc/future-ideas/remote.md b/doc/future-ideas/remote.md deleted file mode 100644 index 7806b9b53..000000000 --- a/doc/future-ideas/remote.md +++ /dev/null @@ -1,23 +0,0 @@ -npm-remote(1) -- Execute commands on a remote machine -===================================================== - -## FUTURE - -This functionality does not yet exist. - -## SYNOPSIS - - npm remote - -## DESCRIPTION - -Run a command on a remote npm site instance. - -In order to do this, the current authenticated user must be in -the "admin" list on the server, and it must be running with https -support. - -It uses the `host` config to know where to do things. - - - diff --git a/doc/future-ideas/site.md b/doc/future-ideas/site.md deleted file mode 100644 index 7936e71f7..000000000 --- a/doc/future-ideas/site.md +++ /dev/null @@ -1,58 +0,0 @@ -npm-site(1) -- Run the npm web site -=================================== - -## FUTURE - -This functionality does not yet exist. - -## SYNOPSIS - - npm site [ start | stop ] - -## DESCRIPTION - -This starts up npm in "site" mode. The following configs are relevant, -and can either be specified in the `.npmrc` file, or as command line -options. - -* userfile: - A file containing the encrypted authorization info for all users. If - specified, then this is used for `npm adduser` requests - to this registry. -* admin: - A comma-delimited list of admin users. All of these must already be - in the local adduser config. If there is no admin, then the site will - not allow remote management. All admin usernames must already be - in the userfile, and a userfile must be specified. -* listen: - Ports to listen on for WS requests. The first number is for http, - the second for https, and the third for secure TCP. Set any to "-", - or omit, to use the default. - Defaults to "80,443,15443" -* registry: - If a package is not found, then its contents will be fetched from the - upstream registry, and cached for future retrieval. - - isaacs: Make sure that this does loop-detection, so that a "ring" of - registries can work as a distributed network. Also, once we have - support for checking multiple registries, you could have a distribution - ring that secondarily depends on some other upstream resource. - -The content for the site is stored in the npm cache directory, which is -inside the folder used for the `root` setting, at `{root}/.npm/.cache`. -It is organized in a simple hierarchical folder structure corresponding -to the web service URLs that npm uses. - -## TCP Server - -The TCP server starts up to support the `npm remote` command, if there is -a valid admin userlist. - -## NOTE - -This also is what happens when you do `npm start npm`. - -## SEE ALSO - -* npm-remote(1) -* npm-config(1) -- cgit v1.2.3