| 1 | # How to (re)build the Javascript from the C sources
|
| 2 |
|
| 3 | You will *not* need to do this for a fresh checkout, since the project
|
| 4 | policy is to include the generated javascript as a checked-in file.
|
| 5 |
|
| 6 | ## Ingredients
|
| 7 |
|
| 8 | - Python 2.x
|
| 9 | - Docker, or a recent Emscripten SDK
|
| 10 | - Node.js and npm to run the [mocha](http://visionmedia.github.io/mocha/)-based tests
|
| 11 |
|
| 12 | Recently, I have had trouble getting a stable Emscripten setup on my
|
| 13 | machines, so I now primarily use a
|
| 14 | [Dockerized Emscripten](https://hub.docker.com/r/trzeci/emscripten/)
|
| 15 | courtesy of Docker user `trzeci`.
|
| 16 |
|
| 17 | Within the `js-nacl` directory,
|
| 18 |
|
| 19 | - [`nacl_cooked.js`](nacl_cooked.js) is the high-level Javascript
|
| 20 | interface to the low-level code.
|
| 21 |
|
| 22 | - [`nacl_cooked_prefix.js`](nacl_cooked_prefix.js) and
|
| 23 | [`nacl_cooked_suffix.js`](nacl_cooked_suffix.js) are wrapped
|
| 24 | around `nacl_cooked.js` and `libsodium.js` to create
|
| 25 | `lib/nacl_factory.js`.
|
| 26 |
|
| 27 | - [`test/runner.html`](test/runner.html) runs the Mocha tests in the browser.
|
| 28 |
|
| 29 | - [`test/tests.js`](test/tests.js) is the source code for the test cases themselves.
|
| 30 |
|
| 31 | - [`benchmark.html`](benchmark.html) and
|
| 32 | [`benchmark.js`](benchmark.js) are trivial speed measurements for
|
| 33 | running in the browser.
|
| 34 |
|
| 35 | ## Method
|
| 36 |
|
| 37 | The `js-nacl` Makefile assumes the use of Docker Emscripten.
|
| 38 |
|
| 39 | To rebuild everything:
|
| 40 |
|
| 41 | make veryclean all
|
| 42 |
|
| 43 | This will completely remove any compilation products, and recompile
|
| 44 | everything.
|
| 45 |
|
| 46 | Other Makefile targets:
|
| 47 |
|
| 48 | - `make` or `make test`: builds the library if necessary and then
|
| 49 | runs the test suite using node.js.
|
| 50 |
|
| 51 | - `make clean`: removes generated Javascript, but does not remove the
|
| 52 | unpacked and pre-processed `libsodium` tarball contents.
|
| 53 |
|
| 54 | - `make veryclean`: as `make clean`, but also removes the contents of
|
| 55 | the `libsodium` tarball.
|
| 56 |
|
| 57 | - `make all`: performs all the build steps.
|
| 58 |
|
| 59 | ### Using the Emscripten SDK instead of Docker
|
| 60 |
|
| 61 | If you are not using the Docker Emscripten image, follow the
|
| 62 | instructions from the
|
| 63 | [Emscripten tutorial](http://emscripten.org/Tutorial) to get
|
| 64 | Emscripten ready to run.
|
| 65 |
|
| 66 | Once `emcc` is on your `$PATH` somewhere, build the `libsodium.js`
|
| 67 | file by unpacking the libsodium sources, applying patches as necessary
|
| 68 | (see the Makefile), changing to the `dist-build` directory in the
|
| 69 | unpacked sources, and running `./emscripten.sh --sumo`.
|
| 70 |
|
| 71 | If you for some reason need to use a different python than `python`,
|
| 72 | set the `PYTHON` makefile variable; for example,
|
| 73 |
|
| 74 | make PYTHON=python2.7
|
| 75 |
|
| 76 | Similarly, set `EMCC` to the path to your `emcc` binary if it's not on
|
| 77 | your `$PATH`.
|
| 78 |
|
| 79 | ## Serves three
|
| 80 |
|
| 81 | The build products, Javascript for use in the browser and in node.js,
|
| 82 | will be in `lib/*`.
|