README.md

   1 io.js
   2 =====
   3
   4 [![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)
   5
   6 This repository began as a GitHub fork of
   7 [joyent/node](https://github.com/joyent/node).
   8
   9 io.js contributions, releases, and contributorship are under an
  10 [open governance model](./GOVERNANCE.md).
  11 We intend to land, with increasing regularity, releases which are
  12 compatible with the npm ecosystem that has been built to date for
  13 Node.js.
  14
  15 ## Is it io.js or IO.js or iojs or IOjs or iOjS?
  16
  17 The official name is **io.js**, which should never be capitalized,
  18 especially not at the start of a sentence, unless it is being
  19 displayed in a location that is customarily all-caps (such as
  20 the title of man pages).
  21
  22 ## Download
  23
  24 Binaries, installers and source tarballs are available at
  25 <https://iojs.org>.
  26
  27 **Releases** are available at <https://iojs.org/dist/>, listed under
  28 their version string. The <https://iojs.org/dist/latest/> symlink
  29 will point to the latest release directory.
  30
  31 **Nightly** builds are available at
  32 <https://iojs.org/download/nightly/>, listed under their version
  33 string which includes their date (in UTC time) and the commit SHA at
  34 the HEAD of the release.
  35
  36 **API documentation** is available in each release and nightly
  37 directory under _docs_. <http://iojs.org/api/> points to the the
  38 latest version.
  39
  40 ### Verifying Binaries
  41
  42 Release and nightly download directories all contain a *SHASUM256.txt*
  43 file that lists the SHA checksums for each file available for
  44 download. To check that a downloaded file matches the checksum, run
  45 it through `sha256sum` with a command such as:
  46
  47 ```
  48 $ grep iojs-vx.y.z.tar.gz SHASUMS256.txt | sha256sum -c -
  49 ```
  50
  51 _(Where "iojs-vx.y.z.tar.gz" is the name of the file you have
  52 downloaded)_
  53
  54 Additionally, releases (not nightlies) have GPG signed copies of
  55 SHASUM256.txt files available as SHASUM256.txt.asc. You can use `gpg`
  56 to verify that the file has not been tampered with.
  57
  58 To verify a SHASUM256.txt.asc, you will first need to import all of
  59 the GPG keys of individuals authorized to create releases. They are
  60 listed at the bottom of this README. Use a command such as this to
  61 import the keys:
  62
  63 ```
  64 $ gpg --keyserver pool.sks-keyservers.net \
  65   --recv-keys DD8F2338BAE7501E3DD5AC78C273792F7D83545D
  66 ```
  67
  68 _(Include each of the key fingerprints at the end of this command.)_
  69
  70 You can then use `gpg --verify SHASUMS256.txt.asc` to verify that the
  71 file has been signed by an authorized member of the io.js team.
  72
  73 Once verified, use the SHASUMS256.txt.asc file to get the checksum for
  74 the binary verification command above.
  75
  76 ## Build
  77
  78 ### Unix / Macintosh
  79
  80 Prerequisites:
  81
  82 * `gcc` and `g++` 4.8 or newer, or
  83 * `clang` and `clang++` 3.3 or newer
  84 * Python 2.6 or 2.7
  85 * GNU Make 3.81 or newer
  86 * libexecinfo (FreeBSD and OpenBSD only)
  87
  88 ```text
  89 $ ./configure
  90 $ make
  91 $ [sudo] make install
  92 ```
  93
  94 If your Python binary is in a non-standard location or has a
  95 non-standard name, run the following instead:
  96
  97 ```text
  98 $ export PYTHON=/path/to/python
  99 $ $PYTHON ./configure
 100 $ make
 101 $ [sudo] make install
 102 ```
 103
 104 To run the tests:
 105
 106 ```text
 107 $ make test
 108 ```
 109
 110 To build the documentation:
 111
 112 ```text
 113 $ make doc
 114 ```
 115
 116 To read the documentation:
 117
 118 ```text
 119 $ man doc/iojs.1
 120 ```
 121
 122 ### Windows
 123
 124 Prerequisites:
 125
 126 * [Python 2.6 or 2.7](https://www.python.org/downloads/)
 127 * Visual Studio 2013 for Windows Desktop, or
 128 * Visual Studio Express 2013 for Windows Desktop
 129 * Basic Unix tools required for some tests,
 130   [Git for Windows](http://git-scm.com/download/win) includes Git Bash
 131   and tools which can be included in the global `PATH`.
 132
 133 ```text
 134 > vcbuild nosign
 135 ```
 136
 137 To run the tests:
 138
 139 ```text
 140 > vcbuild test
 141 ```
 142
 143 ### `Intl` (ECMA-402) support:
 144
 145 [Intl](https://github.com/joyent/node/wiki/Intl) support is not
 146 enabled by default.
 147
 148 #### "small" (English only) support
 149
 150 This option will build with "small" (English only) support, but
 151 the full `Intl` (ECMA-402) APIs.  With `--download=all` it will
 152 download the ICU library as needed.
 153
 154 Unix / Macintosh:
 155
 156 ```text
 157 $ ./configure --with-intl=small-icu --download=all
 158 ```
 159
 160 Windows:
 161
 162 ```text
 163 > vcbuild small-icu download-all
 164 ```
 165
 166 The `small-icu` mode builds with English-only data. You can add full
 167 data at runtime.
 168
 169 *Note:* more docs are on
 170 [the joyent/node wiki](https://github.com/joyent/node/wiki/Intl).
 171
 172 #### Build with full ICU support (all locales supported by ICU):
 173
 174 With the `--download=all`, this may download ICU if you don't have an
 175 ICU in `deps/icu`.
 176
 177 Unix / Macintosh:
 178
 179 ```text
 180 $ ./configure --with-intl=full-icu --download=all
 181 ```
 182
 183 Windows:
 184
 185 ```text
 186 > vcbuild full-icu download-all
 187 ```
 188
 189 #### Build with no Intl support `:-(`
 190
 191 The `Intl` object will not be available. This is the default at
 192 present, so this option is not normally needed.
 193
 194 Unix / Macintosh:
 195
 196 ```text
 197 $ ./configure --with-intl=none
 198 ```
 199
 200 Windows:
 201
 202 ```text
 203 > vcbuild intl-none
 204 ```
 205
 206 #### Use existing installed ICU (Unix / Macintosh only):
 207
 208 ```text
 209 $ pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu
 210 ```
 211
 212 #### Build with a specific ICU:
 213
 214 You can find other ICU releases at
 215 [the ICU homepage](http://icu-project.org/download).
 216 Download the file named something like `icu4c-**##.#**-src.tgz` (or
 217 `.zip`).
 218
 219 Unix / Macintosh
 220
 221 ```text
 222 # from an already-unpacked ICU:
 223 $ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu
 224
 225 # from a local ICU tarball
 226 $ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu.tgz
 227
 228 # from a tarball URL
 229 $ ./configure --with-intl=full-icu --with-icu-source=http://url/to/icu.tgz
 230 ```
 231
 232 Windows
 233
 234 First unpack latest ICU to `deps/icu`
 235 [icu4c-**##.#**-src.tgz](http://icu-project.org/download) (or `.zip`)
 236 as `deps/icu` (You'll have: `deps/icu/source/...`)
 237
 238 ```text
 239 > vcbuild full-icu
 240 ```
 241
 242 ## Resources for Newcomers
 243
 244 * [CONTRIBUTING.md](./CONTRIBUTING.md)
 245 * [GOVERNANCE.md](./GOVERNANCE.md)
 246 * IRC:
 247   [#io.js on Freenode.net](http://webchat.freenode.net?channels=io.js&uio=d4)
 248 * [iojs/io.js on Gitter](https://gitter.im/iojs/io.js)
 249
 250
 251
 252 ## Current Project Team Members
 253
 254 The io.js project team comprises a group of core collaborators and a sub-group
 255 that forms the _Technical Committee_ (TC) which governs the project. For more
 256 information about the governance of the io.js project, see
 257 [GOVERNANCE.md](./GOVERNANCE.md).
 258
 259 * **Isaac Z. Schlueter** ([@isaacs](https://github.com/isaacs)) &lt;i@izs.me&gt; (Technical Committee)
 260 * **Ben Noordhuis** ([@bnoordhuis](https://github.com/bnoordhuis)) &lt;info@bnoordhuis.nl&gt; (Technical Committee)
 261 * **Bert Belder** ([@piscisaureus](https://github.com/piscisaureus)) &lt;bertbelder@gmail.com&gt; (Technical Committee)
 262 * **Fedor Indutny** ([@indutny](https://github.com/indutny)) &lt;fedor.indutny@gmail.com&gt; (Technical Committee)
 263 * **Trevor Norris** ([@trevnorris](https://github.com/trevnorris)) &lt;trev.norris@gmail.com&gt; (Technical Committee)
 264 * **Chris Dickinson** ([@chrisdickinson](https://github.com/chrisdickinson)) &lt;christopher.s.dickinson@gmail.com&gt; (Technical Committee)
 265 <br>Release GPG key: 9554F04D7259F04124DE6B476D5A82AC7E37093B
 266 * **Colin Ihrig** ([@cjihrig](https://github.com/cjihrig)) &lt;cjihrig@gmail.com&gt; (Technical Committee)
 267 * **Mikeal Rogers** ([@mikeal](https://github.com/mikeal)) &lt;mikeal.rogers@gmail.com&gt;
 268 * **Rod Vagg** ([@rvagg](https://github.com/rvagg)) &lt;rod@vagg.org&gt;
 269 <br>Release GPG key: DD8F2338BAE7501E3DD5AC78C273792F7D83545D
 270 * **Thorsten Lorenz** ([@thlorenz](https://github.com/thlorenz)) &lt;thlorenz@gmx.de&gt;
 271 * **Stephen Belanger** ([@qard](https://github.com/qard)) &lt;admin@stephenbelanger.com&gt;
 272 * **Jeremiah Senkpiel** ([@fishrock123](https://github.com/fishrock123)) &lt;fishrock123@rocketmail.com&gt;
 273 * **Evan Lucas** ([@evanlucas](https://github.com/evanlucas)) &lt;evanlucas@me.com&gt;
 274 * **Brendan Ashworth** ([@brendanashworth](https://github.com/brendanashworth)) &lt;brendan.ashworth@me.com&gt;
 275 * **Vladimir Kurchatkin** ([@vkurchatkin](https://github.com/vkurchatkin)) &lt;vladimir.kurchatkin@gmail.com&gt;
 276 * **Nikolai Vavilov** ([@seishun](https://github.com/seishun)) &lt;vvnicholas@gmail.com&gt;
 277 * **Nicu Micleușanu** ([@micnic](https://github.com/micnic)) &lt;micnic90@gmail.com&gt;
 278 * **Aleksey Smolenchuk** ([@lxe](https://github.com/lxe)) &lt;lxe@lxe.co&gt;
 279 * **Shigeki Ohtsu** ([@shigeki](https://github.com/shigeki)) &lt;ohtsu@iij.ad.jp&gt;
 280
 281 Collaborators follow the [COLLABORATOR_GUIDE.md](./COLLABORATOR_GUIDE.md) in
 282 maintaining the io.js project.