diff options
author | isaacs <i@izs.me> | 2010-04-26 03:20:30 +0400 |
---|---|---|
committer | isaacs <i@izs.me> | 2010-04-26 03:39:53 +0400 |
commit | 3ef3ff05d0bdc515b9624e4a9c9d1801b6aaf6b6 (patch) | |
tree | 9aa2d8914218fb4d092930969375a5e73cc75cc5 | |
parent | 841f3b518154f839ac987a6046a3a3272ce61290 (diff) |
refactor the scripts section out
-rw-r--r-- | README.md | 85 | ||||
-rw-r--r-- | doc/scripts.md | 81 |
2 files changed, 81 insertions, 85 deletions
@@ -97,91 +97,6 @@ more easily. If you have strong feelings about package managers, I'd love to hear your opinions. - -## What works now: - -These are the commands that actually do things, as of today. If they don't do -what they say they do, then please [post an issue](http://github.com/isaacs/npm/issues) -about it. - -## Package Lifecycle Scripts - -npm supports the "scripts" member of the package.json script, for the -following scripts: - -`preinstall` - Run BEFORE the package is installed - -`install` - Run AFTER the package is installed. - -`preactivate` - Run BEFORE the package is activated. - -`activate` - Run AFTER the package has been activated. - -`deactivate` - Run BEFORE the package is deactivated. - -`postdeactivate` - Run AFTER the package is deactivated. - -`uninstall` - Run BEFORE the package is uninstalled. - -`postuninstall` - Run AFTER the package is uninstalled. - -### Package Lifecycle Env Vars - -Package scripts are run in an environment where the package.json fields have -been tacked onto the `npm_package_` prefix. So, for instance, if you had -`{"name":"foo", "version":"1.2.5"}` in your package.json file, then in your -various lifecycle scripts, this would be true: - - process.env.npm_package_name === "foo" - process.env.npm_package_version === "1.2.5" - -Objects are flattened following this format, so if you had -`{"scripts":{"install":"foo.js"}}` in your package.json, then you'd see this -in the script: - - process.env.npm_package_scripts_install = "foo.js" - -Last but not least, the `npm_lifecycle_event` environment variable is set to -whichever stage of the cycle is being executed. So, you could have a single -script used for different parts of the process which switches based on what's -currently happening. - -If the script exits with a code other than 0, then this will abort the -process. - -Note that these script files don't have to be nodejs or even javascript -programs. They just have to be some kind of executable file. - -For example, if your package.json contains this: - - { "scripts" : - { "install" : "scripts/install.js" - , "postinstall" : "scripts/install.js" - , "activate" : "scripts/install.js" - , "uninstall" : "scripts/uninstall.js" - } - } - -then the `scripts/install.js` will be called for the install, post-install, -and activate stages of the lifecycle, and the `scripts/uninstall.js` would be -called when the package is uninstalled. Since `scripts/install.js` is running -for three different phases, it would be wise in this case to look at the -`npm_lifecycle_event` environment variable. - -If you want to run a make command, you can do so. This works just fine: - - { "scripts" : - { "preinstall" : "./configure" - , "install" : "make" - , "test" : "make test" - } - } - -However, the script line is not simply a command line, so `make && make install` -would try to execute the `make` command with the arguments `&&`, `make`, and -`install`. If you have a lot of stuff to run in a command, put it in a script -file. - ## Deviations from and Extensions to the Packages/1.0 Spec npm aims to implement the commonjs diff --git a/doc/scripts.md b/doc/scripts.md new file mode 100644 index 000000000..ce51950df --- /dev/null +++ b/doc/scripts.md @@ -0,0 +1,81 @@ +npm-scripts(1) -- How npm handles the "scripts" field +===================================================== + +## DESCRIPTION + +npm supports the "scripts" member of the package.json script, for the +following scripts: + +* preinstall: + Run BEFORE the package is installed +* install: + Run AFTER the package is installed. +* preactivate: + Run BEFORE the package is activated. +* activate: + Run AFTER the package has been activated. +* deactivate: + Run BEFORE the package is deactivated. +* postdeactivate: + Run AFTER the package is deactivated. +* uninstall: + Run BEFORE the package is uninstalled. +* postuninstall: + Run AFTER the package is uninstalled. + +## Package Lifecycle Env Vars + +Package scripts are run in an environment where the package.json fields have +been tacked onto the `npm_package_` prefix. So, for instance, if you had +`{"name":"foo", "version":"1.2.5"}` in your package.json file, then in your +various lifecycle scripts, this would be true: + + process.env.npm_package_name === "foo" + process.env.npm_package_version === "1.2.5" + +Objects are flattened following this format, so if you had +`{"scripts":{"install":"foo.js"}}` in your package.json, then you'd see this +in the script: + + process.env.npm_package_scripts_install = "foo.js" + +Last but not least, the `npm_lifecycle_event` environment variable is set to +whichever stage of the cycle is being executed. So, you could have a single +script used for different parts of the process which switches based on what's +currently happening. + +If the script exits with a code other than 0, then this will abort the +process. + +Note that these script files don't have to be nodejs or even javascript +programs. They just have to be some kind of executable file. + +For example, if your package.json contains this: + + { "scripts" : + { "install" : "scripts/install.js" + , "postinstall" : "scripts/install.js" + , "activate" : "scripts/install.js" + , "uninstall" : "scripts/uninstall.js" + } + } + +then the `scripts/install.js` will be called for the install, post-install, +and activate stages of the lifecycle, and the `scripts/uninstall.js` would be +called when the package is uninstalled. Since `scripts/install.js` is running +for three different phases, it would be wise in this case to look at the +`npm_lifecycle_event` environment variable. + +If you want to run a make command, you can do so. This works just fine: + + { "scripts" : + { "preinstall" : "./configure" + , "install" : "make" + , "test" : "make test" + } + } + +However, the script line is not simply a command line, so `make && make install` +would try to execute the `make` command with the arguments `&&`, `make`, and +`install`. If you have a lot of stuff to run in a command, put it in a script +file. |