README.md

   1 io.js
   2 ===
   3 [![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/iojs/io.js?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
   4
   5 This repository began as a GitHub fork of
   6 [joyent/node](https://github.com/joyent/node).
   7 io.js contributions, releases, and contributorship are under an
   8 [open governance model](./CONTRIBUTING.md#governance).
   9 We intend to land, with increasing regularity, releases which are
  10 compatible with the npm ecosystem that has been built to date for node.js.
  11
  12 ### Is it io.js or IO.js or iojs or IOjs or iOjS?
  13
  14 The official name is **io.js**, which should never be capitalized,
  15 especially not at the start of a sentence, unless it is being
  16 displayed in a location that is customarily all-caps (such as
  17 the title of man pages.)
  18
  19 ### To build:
  20
  21 Prerequisites (Unix only):
  22
  23 * `gcc` and `g++` 4.8 or newer, or
  24 * `clang` and `clang++` 3.3 or newer
  25 * Python 2.6 or 2.7
  26 * GNU Make 3.81 or newer
  27 * libexecinfo (FreeBSD and OpenBSD only)
  28
  29 Unix/Macintosh:
  30
  31 ```sh
  32 ./configure
  33 make
  34 make install
  35 ```
  36
  37 If your python binary is in a non-standard location or has a
  38 non-standard name, run the following instead:
  39
  40 ```sh
  41 export PYTHON=/path/to/python
  42 $PYTHON ./configure
  43 make
  44 make install
  45 ```
  46
  47 Prerequisites (Windows only):
  48
  49 * Python 2.6 or 2.7
  50 * Visual Studio 2013 for Windows Desktop, or
  51 * Visual Studio Express 2013 for Windows Desktop
  52
  53 Windows:
  54
  55 ```sh
  56 vcbuild nosign
  57 ```
  58
  59 You can download pre-built binaries for various operating systems from
  60 [http://nodejs.org/download/](http://nodejs.org/download/).  The Windows
  61 and OS X installers will prompt you for the location in which to install.
  62 The tarballs are self-contained; you can extract them to a local directory
  63 with:
  64
  65 ```sh
  66 tar xzf /path/to/node-<version>-<platform>-<arch>.tar.gz
  67 ```
  68
  69 Or system-wide with:
  70
  71 ```sh
  72 cd /usr/local && tar --strip-components 1 -xzf \
  73                     /path/to/node-<version>-<platform>-<arch>.tar.gz
  74 ```
  75
  76 ### To run the tests:
  77
  78 Unix/Macintosh:
  79
  80 ```sh
  81 make test
  82 ```
  83
  84 Windows:
  85
  86 ```sh
  87 vcbuild test
  88 ```
  89
  90 ### To build the documentation:
  91
  92 ```sh
  93 make doc
  94 ```
  95
  96 ### To read the documentation:
  97
  98 ```sh
  99 man doc/node.1
 100 ```
 101
 102 ### `Intl` (ECMA-402) support:
 103
 104 [Intl](https://github.com/joyent/node/wiki/Intl) support is not
 105 enabled by default.
 106
 107 #### "small" (English only) support
 108
 109 This option will build with "small" (English only) support, but
 110 the full `Intl` (ECMA-402) APIs.  With `--download=all` it will
 111 download the ICU library as needed.
 112
 113 Unix/Macintosh:
 114
 115 ```sh
 116 ./configure --with-intl=small-icu --download=all
 117 ```
 118
 119 Windows:
 120
 121 ```sh
 122 vcbuild small-icu download-all
 123 ```
 124
 125 The `small-icu` mode builds
 126 with English-only data. You can add full data at runtime.
 127
 128 *Note:* more docs are on
 129 [the wiki](https://github.com/joyent/node/wiki/Intl).
 130
 131 #### Build with full ICU support (all locales supported by ICU):
 132
 133 With the `--download=all`, this may download ICU if you don't
 134 have an ICU in `deps/icu`.
 135
 136 Unix/Macintosh:
 137
 138 ```sh
 139 ./configure --with-intl=full-icu --download=all
 140 ```
 141
 142 Windows:
 143
 144 ```sh
 145 vcbuild full-icu download-all
 146 ```
 147
 148 #### Build with no Intl support `:-(`
 149
 150 The `Intl` object will not be available.
 151 This is the default at present, so this option is not normally needed.
 152
 153 Unix/Macintosh:
 154
 155 ```sh
 156 ./configure --with-intl=none
 157 ```
 158
 159 Windows:
 160
 161 ```sh
 162 vcbuild intl-none
 163 ```
 164
 165 #### Use existing installed ICU (Unix/Macintosh only):
 166
 167 ```sh
 168 pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu
 169 ```
 170
 171 #### Build with a specific ICU:
 172
 173 You can find other ICU releases at
 174 [the ICU homepage](http://icu-project.org/download).
 175 Download the file named something like `icu4c-**##.#**-src.tgz` (or
 176 `.zip`).
 177
 178 Unix/Macintosh: from an already-unpacked ICU
 179
 180 ```sh
 181 ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu
 182 ```
 183
 184 Unix/Macintosh: from a local ICU tarball
 185
 186 ```sh
 187 ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu.tgz
 188 ```
 189
 190 Unix/Macintosh: from a tarball URL
 191
 192 ```sh
 193 ./configure --with-intl=full-icu --with-icu-source=http://url/to/icu.tgz
 194 ```
 195
 196 Windows: first unpack latest ICU to `deps/icu`
 197   [icu4c-**##.#**-src.tgz](http://icu-project.org/download) (or `.zip`)
 198   as `deps/icu` (You'll have: `deps/icu/source/...`)
 199
 200 ```sh
 201 vcbuild full-icu
 202 ```
 203
 204 Resources for Newcomers
 205 ---
 206   - [The Wiki](https://github.com/joyent/node/wiki)
 207   - [nodejs.org](http://nodejs.org/)
 208   - [how to install node.js and npm (node package manager)](http://www.joyent.com/blog/installing-node-and-npm/)
 209   - [list of modules](https://github.com/joyent/node/wiki/modules)
 210   - [searching the npm registry](http://npmjs.org/)
 211   - [list of companies and projects using node](https://github.com/joyent/node/wiki/Projects,-Applications,-and-Companies-Using-Node)
 212   - [node.js mailing list](http://groups.google.com/group/nodejs)
 213   - irc chatroom, [#io.js on freenode.net](http://webchat.freenode.net?channels=io.js&uio=d4)
 214   - [community](https://github.com/joyent/node/wiki/Community)
 215   - [contributing](https://github.com/joyent/node/wiki/Contributing)
 216   - [big list of all the helpful wiki pages](https://github.com/joyent/node/wiki/_pages)