nodeenv 0.9.0

Node.js virtual environment builder

Node.js virtual environment
===========================

``nodeenv`` (node.js virtual environment) is a tool to create
isolated node.js environments.

It creates an environment that has its own installation directories,
that doesn't share libraries with other node.js virtual environments.

Also new environment can be integrated with environment which was built
by virtualenv_ (python).

Install
-------

Global installation
^^^^^^^^^^^^^^^^^^^

You can install nodeenv globally with `easy_install`_::

$ sudo easy_install nodeenv

or `pip`_::

$ sudo pip install nodeenv

Local installation
^^^^^^^^^^^^^^^^^^

If you're using virtualenv_ then you can install nodeenv via
pip_/easy_install_ inside any virtual environment built with virtualenv::

$ virtualenv env
$ . env/bin/activate
(env) $ pip install nodeenv
(env) $ nodeenv --version
0.6.5

If you want to work with the latest version of the nodeenv you can
install it from the github `repository`_::

$ git clone https://github.com/ekalinin/nodeenv.git
$ ./nodeenv/nodeenv.py --help

.. _repository: https://github.com/ekalinin/nodeenv
.. _pip: http://pypi.python.org/pypi/pip
.. _easy_install: http://pypi.python.org/pypi/setuptools


Dependency
----------

For nodeenv
^^^^^^^^^^^

* make
* curl
* egrep
* sort
* tail
* tar

For node.js
^^^^^^^^^^^

* libssl-dev

Usage
-----

Basic
^^^^^

Create new environment::

$ nodeenv env

Activate new environment::

$ . env/bin/activate

Chek versions of main packages::

(env) $ node -v
v0.10.26

(env) $ npm -v
1.4.3

Deactivate environment::

(env) $ deactivate_node

Advanced
^^^^^^^^

Get available node.js versions::

$ nodeenv --list
0.0.1 0.0.2 0.0.3 0.0.4 0.0.5 0.0.6 0.1.0
0.1.2 0.1.3 0.1.4 0.1.5 0.1.6 0.1.7 0.1.8
0.1.10 0.1.11 0.1.12 0.1.13 0.1.14 0.1.15 0.1.16
0.1.18 0.1.19 0.1.20 0.1.21 0.1.22 0.1.23 0.1.24
0.1.26 0.1.27 0.1.28 0.1.29 0.1.30 0.1.31 0.1.32
0.1.90 0.1.91 0.1.92 0.1.93 0.1.94 0.1.95 0.1.96
0.1.98 0.1.99 0.1.100 0.1.101 0.1.102 0.1.103 0.1.104
0.2.1 0.2.2 0.2.3 0.2.4 0.2.5 0.2.6 0.3.0
0.3.2 0.3.3 0.3.4 0.3.5 0.3.6 0.3.7 0.3.8
0.4.1 0.4.2 0.4.3 0.4.4 0.4.5 0.4.6

Install node.js "0.4.3" without ssl support with 4 parallel commands
for compilation and npm.js "0.3.17"::

$ nodeenv --without-ssl --node=0.4.3 --npm=0.3.17 --jobs=4 env-4.3

Install node.js from prebuilt package::

$ nodeenv --node=0.10.25 --prebuilt env-0.10.25-prebuilt

It mach faster then install & compile node.js from source::

$ time nodeenv --node=0.10.25 --prebuilt env-0.10.25-prebuilt
+ Install node.js (0.10.25) ... done.

real 0m6.928s
user 0m0.408s
sys 0m1.144s

$ time nodeenv --node=0.10.25 env-0.10.25-src
+ Install node.js (0.10.25) ... done.

real 4m12.602s
user 6m34.112s
sys 0m30.524s

Create a new environment with the system-wide node.js::

$ nodeenv --node=system

Saving into the file versions of all installed packages::

$ . env-4.3/bin/activate
(env-4.3)$ npm install -g express
(env-4.3)$ npm install -g jade
(env-4.3)$ freeze ../prod-requirements.txt

Create environment copy from requirement file::

$ nodeenv --requirement=../prod-requirements.txt --jobs=4 env-copy

Requirements files are plain text files that contain a list of packages
to be installed. These text files allow you to create repeatable installations.
Requirements file example::

$ cat ../prod-requirements.txt
connect@1.3.0
express@2.2.2
jade@0.10.4
mime@1.2.1
npm@0.3.17
qs@0.0.7

If you're already have python virtualenv tool, and want to use nodeenv and
virtualenv in conjunction, then you should create (or activate) python virtual
environment::

# in case of using virtualenv_wrapper
$ mkvirtualenv my_env

# in case of using virtualenv
$ . my_env/bin/activate

and add node virtual environment to this existing new_venv::

$ nodeenv -p

If you need to set the path to make used to build node::

$ nodeenv -m /usr/local/bin/gmake ENV

That's all. Now, all your node.js modules will be installed into your virtual
environment::

$ workon my_env
$ npm install -g coffee-script
$ which coffee
/home/monty/virtualenvs/my_env/bin/coffee

If environment's directory already exists then you can use ``--force`` option::

$ nodeenv --requirement=./requirements.txt --jobs=4 --force env

If you alredy have an environment and want to update packages from requirements
file you can use ``--update`` option::

$ . env-4.3/bin/activate
(env-4.3)$ nodeenv --update=./requirements.txt

If you whant to call node from environment without activation then you shoould
use `shim` script:

$ ./env-4.3/bin/shim --version
v0.4.3

Alternatives
------------

There are several alternatives that create isolated environments:

* `nave <https://github.com/isaacs/nave>`_ - Virtual Environments for Node.
Nave stores all environments in one directory ``~/.nave``. Can create
per node version environments using `nave use envname versionname`.
Can not pass additional arguments into configure (for example --without-ssl)
Can't run on windows because it relies on bash.

* `nvm <https://github.com/creationix/nvm/blob/master/nvm.sh>`_ - Node Version
Manager. It is necessarily to do `nvm sync` for caching available node.js
version.
Can not pass additional arguments into configure (for example --without-ssl)

* virtualenv_ — Virtual Python Environment builder. For python only.

.. _`virtualenv`: https://github.com/pypa/virtualenv


Nodeenv changelog
=================

Version 0.9.0
-------------
- Added `shim` script. See `# 59`_

.. _# 59: https://github.com/ekalinin/nodeenv/issues/59

Version 0.8.2
-------------
- Fixed prebuilt installation:
- cp more choosy. See `# 64`_
- exclude top-level files in prebuilt tar. See `# 63`_

.. _#63: https://github.com/ekalinin/nodeenv/issues/63
.. _#64: https://github.com/ekalinin/nodeenv/issues/64

Version 0.8.1
-------------
- Fixed system's node usage. See `# 62`_

.. _# 62: https://github.com/ekalinin/nodeenv/pull/62

Version 0.8.0
-------------
- Added support for prebuilt packages. See `# 56`_
- Added support for python3. See `# 42`_

.. _# 56: https://github.com/ekalinin/nodeenv/issues/56
.. _# 42: https://github.com/ekalinin/nodeenv/issues/42

Version 0.7.3
-------------
- Fixed npm.js redirect. See `# 52`_
- Added ``--update`` option. See `# 25`_

.. _# 52: https://github.com/ekalinin/nodeenv/pull/52
.. _# 25: https://github.com/ekalinin/nodeenv/issues/25

Version 0.7.2
-------------
- Bug fixing in ``freeze``. See `# 47`_

.. _# 47: https://github.com/ekalinin/nodeenv/issues/47

Version 0.7.1
-------------
- Added ``--make`` option

Version 0.7.0
-------------
- added ``--force``. See `# 37`_
- python3 support (first steps). See `# 38`_, `# 39`_
- escaping all directories used by subprocesses. See `# 40`_
- added an option to use system-wide node. See `# 41`_

.. _# 37: https://github.com/ekalinin/nodeenv/pull/37
.. _# 38: https://github.com/ekalinin/nodeenv/issues/38
.. _# 39: https://github.com/ekalinin/nodeenv/issues/39
.. _# 40: https://github.com/ekalinin/nodeenv/pull/40
.. _# 41: https://github.com/ekalinin/nodeenv/pull/41


Version 0.6.6
-------------
- Fixed incomplete package names using freeze. See `# 35`_
- Fixed packages installation type in README. See `# 33`_

.. _# 33: https://github.com/ekalinin/nodeenv/issues/33
.. _# 35: https://github.com/ekalinin/nodeenv/pull/35


Version 0.6.5
-------------
- Node's source not loaded if it already exists in FS.


Version 0.6.4
-------------
- Added python3 compatibility. See `# 32`_

.. _# 32: https://github.com/ekalinin/nodeenv/pull/32


Version 0.6.3
-------------
- Fixed ``nodeenv -p``. See `issue # 31`_

.. _issue # 31: https://github.com/ekalinin/nodeenv/issues/31


Version 0.6.2
-------------
- Skipped stand-alone npm installation by default. See `pull # 30`_
- ``--without-npm`` has been changed to ``--with-npm``. See `pull # 30`_
- Fixed options for running Make instances in parallel. See `pull # 30`_

.. _pull # 30: https://github.com/ekalinin/nodeenv/pull/30


Version 0.6.1
-------------
- Used pkg_resources.parse_version to compare versions. See `pull # 29`_
- Fixed doubling prompt inside a virtualenv. See `issues # 26`_

.. _pull # 29: https://github.com/ekalinin/nodeenv/pull/29
.. _issues # 26: https://github.com/ekalinin/nodeenv/issues/26


Version 0.6.0
-------------
- Fixed typo in deactive command. See `pull # 20`_
- Not used "--insecure" to download npm. See `pull # 21`_
- Removed "src" directory after installation. See `pull # 22`_
- Added option "--clean-src"
- Added integration with python's virtualenv. See `pull # 23`_

.. _pull # 20: https://github.com/ekalinin/nodeenv/pull/20
.. _pull # 21: https://github.com/ekalinin/nodeenv/pull/21
.. _pull # 22: https://github.com/ekalinin/nodeenv/pull/22
.. _pull # 23: https://github.com/ekalinin/nodeenv/pull/23

Version 0.5.3
-------------
- Bug fix. Used https, /dist/latest/. See `pull # 16`_

.. _pull # 16: https://github.com/ekalinin/nodeenv/pull/16

Version 0.5.2
-------------
- Improved installation logic for release candidate versions. See `pull # 10`_

.. _pull # 10: https://github.com/ekalinin/nodeenv/pull/10

Version 0.5.1
-------------
- Improved logic for the option '--without-npm'. See `issue # 14`_, `pull # 15`_

.. _issue # 14: https://github.com/ekalinin/nodeenv/issues/14
.. _pull # 15: https://github.com/ekalinin/nodeenv/pull/15

Version 0.5.0
-------------
- The virtual environment's path is no longer hardcoded into the
activation script. See `pull # 13`_

.. _pull # 13: https://github.com/ekalinin/nodeenv/pull/13

Version 0.4.3
-------------
- Fixed metavar for ``--npm``
- ``npm install -g`` used for npm >=1.0, not noly for `latest`

Version 0.4.2
-------------
- Added README.ru.rst

Version 0.4.1
-------------
- Fixed bug in print_node_versions. See `pull # 11`_
- Added deps in README

.. _pull # 11: https://github.com/ekalinin/nodeenv/pull/11

Version 0.4.0
-------------
- Compatibility with virtualenv (renamed deactivate to deactivate_node).
See `pull # 9`_, `issue # 6`_

.. _pull # 9: https://github.com/ekalinin/nodeenv/pull/9
.. _issue # 6: https://github.com/ekalinin/nodeenv/issues/6

Version 0.3.10
--------------
- Fixed bug in url detection for node.js download

Version 0.3.9
-------------
- Deleted notify method calls. See `pull # 7`_
- Updated tar url for node.js > 0.5.0. See `pull # 8`_

.. _pull # 7: https://github.com/ekalinin/nodeenv/pull/7
.. _pull # 8: https://github.com/ekalinin/nodeenv/pull/8

Version 0.3.8
-------------
- Added `NODE_PATH` variable export (for correct module
search after installation via npm)

Version 0.3.7
-------------
- Shows command output when error occurs
- Excluded 'npm' from `freeze` list
- Fixed bug with 'not only letter' names in `freeze` list
- Added global installation for npm >= 1.0 (when install
soft from requirement file)

Version 0.3.6
-------------
- Fixed ``freeze`` output command. See `request # 5`_
- Diagnostic message fixed. See `pull # 4`_

.. _request # 5 : https://github.com/ekalinin/nodeenv/issues/5
.. _pull # 4 : https://github.com/ekalinin/nodeenv/pull/4

Version 0.3.5
-------------
- Added option ``--npm`` to install certain npm.js version. Request_ .
- Fixed ``freeze`` command for npm >= 1.0.x.

.. _Request: https://github.com/ekalinin/nodeenv/issues/3

Version 0.3.4
-------------

- Fixed `problem #2`_ with new npm installation script. Added
``--no-npm-clean`` option. The default to the npm 0.x cleanup.

.. _problem #2: https://github.com/ekalinin/nodeenv/issues/2

Version 0.3.3
-------------

- Fixed `problem #1`_ with installation from PyPI via easy_install.
Added ``MANIFEST.in`` file.

.. _problem #1: https://github.com/ekalinin/nodeenv/issues/1

Version 0.3.2
-------------

- Internal improvements
- Logging refactoring

Version 0.3.1
-------------

- Default environment promt is folder name

Version 0.3.0
--------------

- Renamed nve to nodeenv