BUILDING.md

   1 ## Building Node.js
   2
   3 Depending on what platform or features you require the build process may
   4 differ slightly. After you've successfully built a binary, running the
   5 test suite to validate that the binary works as intended is a good next step.
   6
   7 If you consistently can reproduce a test failure, search for it in the
   8 [Node.js issue tracker](https://github.com/nodejs/node/issues) or
   9 file a new issue.
  10
  11
  12 ### Unix / Macintosh
  13
  14 Prerequisites:
  15
  16 * `gcc` and `g++` 4.8 or newer, or
  17 * `clang` and `clang++` 3.4 or newer
  18 * Python 2.6 or 2.7
  19 * GNU Make 3.81 or newer
  20 * libexecinfo (FreeBSD and OpenBSD only)
  21
  22 ```text
  23 $ ./configure
  24 $ make
  25 $ [sudo] make install
  26 ```
  27
  28 If your Python binary is in a non-standard location or has a
  29 non-standard name, run the following instead:
  30
  31 ```text
  32 $ export PYTHON=/path/to/python
  33 $ $PYTHON ./configure
  34 $ make
  35 $ [sudo] make install
  36 ```
  37
  38 To run the tests:
  39
  40 ```text
  41 $ make test
  42 ```
  43
  44 To build the documentation:
  45
  46 ```text
  47 $ make doc
  48 ```
  49
  50 To read the documentation:
  51
  52 ```text
  53 $ man doc/node.1
  54 ```
  55
  56 To test if Node.js was built correctly:
  57
  58 ```
  59 $ node -e "console.log('Hello from Node.js ' + process.version)"
  60 ```
  61
  62
  63 ### Windows
  64
  65 Prerequisites:
  66
  67 * [Python 2.6 or 2.7](https://www.python.org/downloads/)
  68 * Visual Studio 2013 / 2015, all editions including the Community edition, or
  69 * Visual Studio Express 2013 / 2015 for Desktop
  70 * Basic Unix tools required for some tests,
  71   [Git for Windows](http://git-scm.com/download/win) includes Git Bash
  72   and tools which can be included in the global `PATH`.
  73
  74 ```text
  75 > vcbuild nosign
  76 ```
  77
  78 To run the tests:
  79
  80 ```text
  81 > vcbuild test
  82 ```
  83
  84 To test if Node.js was built correctly:
  85
  86 ```
  87 $ node -e "console.log('Hello from Node.js ' + process.version)"
  88 ```
  89
  90 ### Android / Android based devices, aka. Firefox OS
  91
  92 Be sure you have downloaded and extracted [Android NDK]
  93 (https://developer.android.com/tools/sdk/ndk/index.html)
  94 before in a folder. Then run:
  95
  96 ```
  97 $ ./android-configure /path/to/your/android-ndk
  98 $ make
  99 ```
 100
 101
 102 ### `Intl` (ECMA-402) support:
 103
 104 [Intl](https://github.com/nodejs/node/wiki/Intl) support is not
 105 enabled by default.
 106
 107
 108 #### "small" (English only) support
 109
 110 This option will build with "small" (English only) support, but
 111 the full `Intl` (ECMA-402) APIs.  With `--download=all` it will
 112 download the ICU library as needed.
 113
 114 ##### Unix / Macintosh:
 115
 116 ```text
 117 $ ./configure --with-intl=small-icu --download=all
 118 ```
 119
 120 ##### Windows:
 121
 122 ```text
 123 > vcbuild small-icu download-all
 124 ```
 125
 126 The `small-icu` mode builds with English-only data. You can add full
 127 data at runtime.
 128
 129 *Note:* more docs are on
 130 [the node wiki](https://github.com/nodejs/node/wiki/Intl).
 131
 132 #### Build with full ICU support (all locales supported by ICU):
 133
 134 With the `--download=all`, this may download ICU if you don't have an
 135 ICU in `deps/icu`.
 136
 137 ##### Unix / Macintosh:
 138
 139 ```text
 140 $ ./configure --with-intl=full-icu --download=all
 141 ```
 142
 143 ##### Windows:
 144
 145 ```text
 146 > vcbuild full-icu download-all
 147 ```
 148
 149 #### Building without Intl support
 150
 151 The `Intl` object will not be available. This is the default at
 152 present, so this option is not normally needed.
 153
 154 ##### Unix / Macintosh:
 155
 156 ```text
 157 $ ./configure --with-intl=none
 158 ```
 159
 160 ##### Windows:
 161
 162 ```text
 163 > vcbuild intl-none
 164 ```
 165
 166 #### Use existing installed ICU (Unix / Macintosh only):
 167
 168 ```text
 169 $ pkg-config --modversion icu-i18n && ./configure --with-intl=system-icu
 170 ```
 171
 172 If you are cross compiling, your `pkg-config` must be able to supply a path
 173 that works for both your host and target environments.
 174
 175 #### Build with a specific ICU:
 176
 177 You can find other ICU releases at
 178 [the ICU homepage](http://icu-project.org/download).
 179 Download the file named something like `icu4c-**##.#**-src.tgz` (or
 180 `.zip`).
 181
 182 ##### Unix / Macintosh
 183
 184 ```text
 185 # from an already-unpacked ICU:
 186 $ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu
 187
 188 # from a local ICU tarball
 189 $ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu.tgz
 190
 191 # from a tarball URL
 192 $ ./configure --with-intl=full-icu --with-icu-source=http://url/to/icu.tgz
 193 ```
 194
 195 ##### Windows
 196
 197 First unpack latest ICU to `deps/icu`
 198 [icu4c-**##.#**-src.tgz](http://icu-project.org/download) (or `.zip`)
 199 as `deps/icu` (You'll have: `deps/icu/source/...`)
 200
 201 ```text
 202 > vcbuild full-icu
 203 ```
 204
 205 ## Building Node.js with FIPS-compliant OpenSSL
 206
 207 NOTE: Windows is not yet supported
 208
 209 It is possible to build Node.js with
 210 [OpenSSL FIPS module](https://www.openssl.org/docs/fips/fipsnotes.html).
 211
 212 **Note**: building in this way does **not** allow you to claim that the
 213 runtime is FIPS 140-2 validated. Instead you can indicate that the runtime
 214 uses a validated module. See the [security policy](http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140sp/140sp1747.pdf)
 215 page 60 for more details. In addition, the validation for the underlying module
 216 is only valid if it is deployed in accordance with its [security policy](http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140sp/140sp1747.pdf).
 217 If you need FIPS validated cryptography it is recommended that you read both
 218 the [security policy](http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140sp/140sp1747.pdf)
 219 and [user guide](https://openssl.org/docs/fips/UserGuide-2.0.pdf).
 220
 221 ### Instructions
 222
 223 1. Obtain a copy of openssl-fips-x.x.x.tar.gz.
 224    To comply with the security policy you must ensure the path
 225    through which you get the file complies with the requirements
 226    for a "secure installation" as described in section 6.6 in
 227    the [user guide](https://openssl.org/docs/fips/UserGuide-2.0.pdf).
 228    For evaluation/experimentation you can simply download and verify
 229    `openssl-fips-x.x.x.tar.gz` from https://www.openssl.org/source/
 230 2. Extract source to `openssl-fips` folder and `cd openssl-fips`
 231 3. `./config`
 232 4. `make`
 233 5. `make install`
 234    (NOTE: to comply with the security policy you must use the exact
 235    commands in steps 3-5 without any additional options as per
 236    Appendix A in the [security policy](http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/140sp/140sp1747.pdf).
 237    The only exception is that `./config no-asm` can be
 238    used in place of `./config`, and the FIPSDIR environment variable
 239    may be used to specify a non-standard install folder for the
 240    validated module, as per User Guide sections 4.2.1, 4.2.2, and 4.2.3.
 241 6. Get into Node.js checkout folder
 242 7. `./configure --openssl-fips=/path/to/openssl-fips/installdir`
 243    For example on ubuntu 12 the installation directory was
 244    /usr/local/ssl/fips-2.0
 245 8. Build Node.js with `make -j`
 246 9. Verify with `node -p "process.versions.openssl"` (`1.0.2a-fips`)