diff --git a/deps/npm/doc/cli/json.md b/deps/npm/doc/cli/json.md index 46df441895..c6cedaaaf3 100644 --- a/deps/npm/doc/cli/json.md +++ b/deps/npm/doc/cli/json.md @@ -366,8 +366,8 @@ a version in the following fashion. For example, the following are equivalent: * `"~1.2.3" = ">=1.2.3 <1.3.0"` -* `"~1.2" = ">=1.2.0 <2.0.0"` -* `"~1" = ">=1.0.0 <2.0.0"` +* `"~1.2" = ">=1.2.0 <1.3.0"` +* `"~1" = ">=1.0.0 <1.1.0"` ### X Version Ranges diff --git a/deps/npm/doc/cli/scripts.md b/deps/npm/doc/cli/scripts.md index 3d33a83919..0eba5f7b12 100644 --- a/deps/npm/doc/cli/scripts.md +++ b/deps/npm/doc/cli/scripts.md @@ -6,6 +6,11 @@ npm-scripts(1) -- How npm handles the "scripts" field npm supports the "scripts" member of the package.json script, for the following scripts: +* prepublish: + Run BEFORE the package is published. (Also run on local `npm + install` without any arguments.) +* publish, postpublish: + Run AFTER the package is published. * preinstall: Run BEFORE the package is installed * install, postinstall: @@ -18,10 +23,6 @@ following scripts: Run BEFORE the package is updated with the update command. * update, postupdate: Run AFTER the package is updated with the update command. -* prepublish: - Run BEFORE the package is published. -* publish, postpublish: - Run AFTER the package is published. * pretest, test, posttest: Run by the `npm test` command. * prestop, stop, poststop: @@ -35,6 +36,50 @@ following scripts: Additionally, arbitrary scrips can be run by doing `npm run-script `. +## NOTE: INSTALL SCRIPTS ARE AN ANTIPATTERN + +**tl;dr** Don't use `install`. Use a `.gyp` file for compilation, and +`prepublish` for anything else. + +You should almost never have to explicitly set a `preinstall` or +`install` script. If you are doing this, please consider if there is +another option. + +The only valid use of `install` or `preinstall` scripts is for +compilation which must be done on the target architecture. In early +versions of node, this was often done using the `node-waf` scripts, or +a standalone `Makefile`, and early versions of npm required that it be +explicitly set in package.json. This was not portable, and harder to +do properly. + +In the current version of node, the standard way to do this is using a +`.gyp` file. If you have a file with a `.gyp` extension in the root +of your package, then npm will run the appropriate `node-gyp` commands +automatically at install time. This is the only officially supported +method for compiling binary addons, and does not require that you add +anything to your package.json file. + +If you have to do other things before your package is used, in a way +that is not dependent on the operating system or architecture of the +target system, then use a `prepublish` script instead. This includes +tasks such as: + +* Compile CoffeeScript source code into JavaScript. +* Create minified versions of JavaScript source code. +* Fetching remote resources that your package will use. + +The advantage of doing these things at `prepublish` time instead of +`preinstall` or `install` time is that they can be done once, in a +single place, and thus greatly reduce complexity and variability. +Additionally, this means that: + +* You can depend on `coffee-script` as a `devDependency`, and thus + your users don't need to have it installed. +* You don't need to include the minifiers in your package, reducing + the size for your users. +* You don't need to rely on your users having `curl` or `wget` or + other system tools on the target machines. + ## DEFAULT VALUES npm will default some script values based on package contents. diff --git a/deps/npm/doc/cli/semver.md b/deps/npm/doc/cli/semver.md index 7eb2240639..493dd7a1ef 100644 --- a/deps/npm/doc/cli/semver.md +++ b/deps/npm/doc/cli/semver.md @@ -11,8 +11,8 @@ As a node module: $ npm install semver - semver.valid('1.2.3') // true - semver.valid('a.b.c') // false + semver.valid('1.2.3') // '1.2.3' + semver.valid('a.b.c') // null semver.clean(' =v1.2.3 ') // '1.2.3' semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true semver.gt('1.2.3', '9.8.7') // false @@ -83,7 +83,7 @@ The following range styles are supported: * `<1.2.3` Less than * `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4` * `~1.2.3` := `>=1.2.3 <1.3.0` -* `~1.2` := `>=1.2.0 <2.0.0` +* `~1.2` := `>=1.2.0 <1.3.0` * `~1` := `>=1.0.0 <2.0.0` * `1.2.x` := `>=1.2.0 <1.3.0` * `1.x` := `>=1.0.0 <2.0.0` diff --git a/deps/npm/html/api/bin.html b/deps/npm/html/api/bin.html index 05b588cfe0..73eb5c169b 100644 --- a/deps/npm/html/api/bin.html +++ b/deps/npm/html/api/bin.html @@ -19,7 +19,7 @@

This function should not be used programmatically. Instead, just refer to the npm.bin member.

- +