README.md

   1
   2 io.js
   3 =====
   4
   5 [![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/nodejs/io.js?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
   6
   7 This repository began as a GitHub fork of
   8 [joyent/node](https://github.com/joyent/node).
   9
  10 io.js contributions, releases, and contributorship are under an
  11 [open governance model](./GOVERNANCE.md).
  12 We intend to land, with increasing regularity, releases which are
  13 compatible with the npm ecosystem that has been built to date for
  14 Node.js.
  15
  16 ## Is it io.js or IO.js or iojs or IOjs or iOjS?
  17
  18 The official name is **io.js**, which should never be capitalized,
  19 especially not at the start of a sentence, unless it is being
  20 displayed in a location that is customarily all-caps (such as
  21 the title of man pages).
  22
  23 ## Download
  24
  25 Binaries, installers, and source tarballs are available at
  26 <https://iojs.org>.
  27
  28 **Releases** are available at <https://iojs.org/dist/>, listed under
  29 their version string. The <https://iojs.org/dist/latest/> symlink
  30 will point to the latest release directory.
  31
  32 **Nightly** builds are available at
  33 <https://iojs.org/download/nightly/>, listed under their version
  34 string which includes their date (in UTC time) and the commit SHA at
  35 the HEAD of the release.
  36
  37 **API documentation** is available in each release and nightly
  38 directory under _docs_. <https://iojs.org/api/> points to the 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.4 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 ### Android / Android based devices, aka. Firefox OS
 144
 145 Be sure you have downloaded and extracted [Android NDK]
 146 (https://developer.android.com/tools/sdk/ndk/index.html)
 147 before in a folder. Then run:
 148
 149 ```
 150 $ ./android-configure /path/to/your/android-ndk
 151 $ make
 152 ```
 153
 154 ### `Intl` (ECMA-402) support:
 155
 156 [Intl](https://github.com/joyent/node/wiki/Intl) support is not
 157 enabled by default.
 158
 159 #### "small" (English only) support
 160
 161 This option will build with "small" (English only) support, but
 162 the full `Intl` (ECMA-402) APIs.  With `--download=all` it will
 163 download the ICU library as needed.
 164
 165 Unix / Macintosh:
 166
 167 ```text
 168 $ ./configure --with-intl=small-icu --download=all
 169 ```
 170
 171 Windows:
 172
 173 ```text
 174 > vcbuild small-icu download-all
 175 ```
 176
 177 The `small-icu` mode builds with English-only data. You can add full
 178 data at runtime.
 179
 180 *Note:* more docs are on
 181 [the joyent/node wiki](https://github.com/joyent/node/wiki/Intl).
 182
 183 #### Build with full ICU support (all locales supported by ICU):
 184
 185 With the `--download=all`, this may download ICU if you don't have an
 186 ICU in `deps/icu`.
 187
 188 Unix / Macintosh:
 189
 190 ```text
 191 $ ./configure --with-intl=full-icu --download=all
 192 ```
 193
 194 Windows:
 195
 196 ```text
 197 > vcbuild full-icu download-all
 198 ```
 199
 200 #### Build with no Intl support `:-(`
 201
 202 The `Intl` object will not be available. This is the default at
 203 present, so this option is not normally needed.
 204
 205 Unix / Macintosh:
 206
 207 ```text
 208 $ ./configure --with-intl=none
 209 ```
 210
 211 Windows:
 212
 213 ```text
 214 > vcbuild intl-none
 215 ```
 216
 217 #### Use existing installed ICU (Unix / Macintosh only):
 218
 219 ```text
 220 $ pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu
 221 ```
 222
 223 #### Build with a specific ICU:
 224
 225 You can find other ICU releases at
 226 [the ICU homepage](http://icu-project.org/download).
 227 Download the file named something like `icu4c-**##.#**-src.tgz` (or
 228 `.zip`).
 229
 230 Unix / Macintosh
 231
 232 ```text
 233 # from an already-unpacked ICU:
 234 $ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu
 235
 236 # from a local ICU tarball
 237 $ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu.tgz
 238
 239 # from a tarball URL
 240 $ ./configure --with-intl=full-icu --with-icu-source=http://url/to/icu.tgz
 241 ```
 242
 243 Windows
 244
 245 First unpack latest ICU to `deps/icu`
 246 [icu4c-**##.#**-src.tgz](http://icu-project.org/download) (or `.zip`)
 247 as `deps/icu` (You'll have: `deps/icu/source/...`)
 248
 249 ```text
 250 > vcbuild full-icu
 251 ```
 252
 253 # Building io.js with FIPS-compliant OpenSSL
 254
 255 NOTE: Windows is not yet supported
 256
 257 It is possible to build io.js with
 258 [OpenSSL FIPS module](https://www.openssl.org/docs/fips/fipsnotes.html).
 259
 260 Instructions:
 261
 262 1. Download and verify `openssl-fips-x.x.x.tar.gz` from
 263    https://www.openssl.org/source/
 264 2. Extract source to `openssl-fips` folder
 265 3. ``cd openssl-fips && ./config fipscanisterbuild --prefix=`pwd`/out``
 266    (NOTE: On OS X, you may want to run
 267     ``./Configure darwin64-x86_64-cc --prefix=`pwd`/out`` if you are going to
 268     build x64-mode io.js)
 269 4. `make -j && make install`
 270 5. Get into io.js checkout folder
 271 6. `./configure --openssl-fips=/path/to/openssl-fips/out`
 272 7. Build io.js with `make -j`
 273 8. Verify with `node -p "process.versions.openssl"` (`1.0.2a-fips`)
 274
 275 ## Resources for Newcomers
 276
 277 * [CONTRIBUTING.md](./CONTRIBUTING.md)
 278 * [GOVERNANCE.md](./GOVERNANCE.md)
 279 * IRC:
 280   [#io.js on Freenode.net](http://webchat.freenode.net?channels=io.js&uio=d4)
 281 * [iojs/io.js on Gitter](https://gitter.im/nodejs/io.js)
 282
 283 ## Security
 284
 285 All security bugs in io.js are taken seriously and should be reported by
 286 emailing security@iojs.org. This will be delivered to a subset of the project
 287 team who handle security issues. Please don't disclose security bugs
 288 public until they have been handled by the security team.
 289
 290 Your email will be acknowledged within 24 hours, and you’ll receive a more
 291 detailed response to your email within 48 hours indicating the next steps in
 292 handling your report.
 293
 294 ## Current Project Team Members
 295
 296 The io.js project team comprises a group of core collaborators and a sub-group
 297 that forms the _Technical Committee_ (TC) which governs the project. For more
 298 information about the governance of the io.js project, see
 299 [GOVERNANCE.md](./GOVERNANCE.md).
 300
 301 * **Isaac Z. Schlueter** &lt;i@izs.me&gt; ([@isaacs](https://github.com/isaacs)) (Technical Committee)
 302 * **Ben Noordhuis** &lt;info@bnoordhuis.nl&gt; ([@bnoordhuis](https://github.com/bnoordhuis)) (Technical Committee)
 303 * **Bert Belder** &lt;bertbelder@gmail.com&gt; ([@piscisaureus](https://github.com/piscisaureus)) (Technical Committee)
 304 * **Fedor Indutny** &lt;fedor.indutny@gmail.com&gt; ([@indutny](https://github.com/indutny)) (Technical Committee)
 305 * **Trevor Norris** &lt;trev.norris@gmail.com&gt; ([@trevnorris](https://github.com/trevnorris)) (Technical Committee)
 306 * **Chris Dickinson** &lt;christopher.s.dickinson@gmail.com&gt; ([@chrisdickinson](https://github.com/chrisdickinson)) (Technical Committee)
 307   - Release GPG key: 9554F04D7259F04124DE6B476D5A82AC7E37093B
 308 * **Colin Ihrig** &lt;cjihrig@gmail.com&gt; ([@cjihrig](https://github.com/cjihrig))
 309 * **Mikeal Rogers** &lt;mikeal.rogers@gmail.com&gt; ([@mikeal](https://github.com/mikeal))
 310 * **Rod Vagg** &lt;rod@vagg.org&gt; ([@rvagg](https://github.com/rvagg)) (Technical Committee)
 311   - Release GPG key: DD8F2338BAE7501E3DD5AC78C273792F7D83545D
 312 * **Thorsten Lorenz** &lt;thlorenz@gmx.de&gt; ([@thlorenz](https://github.com/thlorenz))
 313 * **Stephen Belanger** &lt;admin@stephenbelanger.com&gt; ([@qard](https://github.com/qard))
 314 * **Jeremiah Senkpiel** &lt;fishrock123@rocketmail.com&gt; ([@fishrock123](https://github.com/fishrock123)) (Technical Committee)
 315   - Release GPG key: FD3A5288F042B6850C66B31F09FE44734EB7990E
 316 * **Evan Lucas** &lt;evanlucas@me.com&gt; ([@evanlucas](https://github.com/evanlucas))
 317 * **Brendan Ashworth** &lt;brendan.ashworth@me.com&gt; ([@brendanashworth](https://github.com/brendanashworth))
 318 * **Vladimir Kurchatkin** &lt;vladimir.kurchatkin@gmail.com&gt; ([@vkurchatkin](https://github.com/vkurchatkin))
 319 * **Nikolai Vavilov** &lt;vvnicholas@gmail.com&gt; ([@seishun](https://github.com/seishun))
 320 * **Nicu Micleușanu** &lt;micnic90@gmail.com&gt; ([@micnic](https://github.com/micnic))
 321 * **Aleksey Smolenchuk** &lt;lxe@lxe.co&gt; ([@lxe](https://github.com/lxe))
 322 * **Shigeki Ohtsu** &lt;ohtsu@iij.ad.jp&gt; ([@shigeki](https://github.com/shigeki))
 323 * **Sam Roberts** &lt;vieuxtech@gmail.com&gt; ([@sam-github](https://github.com/sam-github))
 324 * **Wyatt Preul** &lt;wpreul@gmail.com&gt; ([@geek](https://github.com/geek))
 325 * **Brian White** &lt;mscdex@mscdex.net&gt; ([@mscdex](https://github.com/mscdex))
 326 * **Christian Tellnes** &lt;christian@tellnes.no&gt; ([@tellnes](https://github.com/tellnes))
 327 * **Robert Kowalski** &lt;rok@kowalski.gd&gt; ([@robertkowalski](https://github.com/robertkowalski))
 328 * **Julian Duque** &lt;julianduquej@gmail.com&gt; ([@julianduque](https://github.com/julianduque))
 329 * **Johan Bergström** &lt;bugs@bergstroem.nu&gt; ([@jbergstroem](https://github.com/jbergstroem))
 330 * **Roman Reiss** &lt;me@silverwind.io&gt; ([@silverwind](https://github.com/silverwind))
 331 * **Petka Antonov** &lt;petka_antonov@hotmail.com&gt; ([@petkaantonov](https://github.com/petkaantonov))
 332 * **Yosuke Furukawa** &lt;yosuke.furukawa@gmail.com&gt; ([@yosuke-furukawa](https://github.com/yosuke-furukawa))
 333 * **Alex Kocharin** &lt;alex@kocharin.ru&gt; ([@rlidwka](https://github.com/rlidwka))
 334 * **Christopher Monsanto** &lt;chris@monsan.to&gt; ([@monsanto](https://github.com/monsanto))
 335 * **Ali Ijaz Sheikh** &lt;ofrobots@google.com&gt; ([@ofrobots](https://github.com/ofrobots))
 336 * **Oleg Elifantiev** &lt;oleg@elifantiev.ru&gt; ([@Olegas](https://github.com/Olegas))
 337 * **Domenic Denicola** &lt;d@domenic.me&gt; ([@domenic](https://github.com/domenic))
 338 * **Rich Trott** &lt;rtrott@gmail.com&gt; ([@Trott](https://github.com/Trott))
 339 * **Сковорода Никита Андреевич** &lt;chalkerx@gmail.com&gt; ([@ChALkeR](https://github.com/ChALkeR))
 340
 341 Collaborators follow the [COLLABORATOR_GUIDE.md](./COLLABORATOR_GUIDE.md) in
 342 maintaining the io.js project.