-
Notifications
You must be signed in to change notification settings - Fork 592
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
17 changed files
with
1,732 additions
and
1,175 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,220 @@ | ||
# Ice for JavaScript Build Instructions | ||
|
||
This file describes how to build and install Ice for JavaScript from source | ||
code. If you prefer, you can also download [binary distributions] for the | ||
supported platforms. | ||
|
||
<!-- TOC depthFrom:2 --> | ||
|
||
- [JavaScript Build Requirements](#javascript-build-requirements) | ||
- [Building the JavaScript libraries and NodeJS packages](#building-the-javascript-libraries-and-nodejs-packages) | ||
- [Running the JavaScript Tests](#running-the-javascript-tests) | ||
- [Browser Information](#browser-information) | ||
- [Self-Signed Certificate](#self-signed-certificate) | ||
- [Windows 8](#windows-8) | ||
- [Secure WebSockets on iOS and Android](#secure-websockets-on-ios-and-android) | ||
- [Installing Certificates on iOS](#installing-certificates-on-ios) | ||
- [Installing Certificates on Android](#installing-certificates-on-android) | ||
- [Installing a Source Build](#installing-a-source-build) | ||
|
||
<!-- /TOC --> | ||
|
||
## JavaScript Build Requirements | ||
|
||
To build Ice for JavaScript you must have the following: | ||
|
||
- The `slice2js` compiler from Ice for C++. If you have not built Ice for C++ | ||
in this source distribution, refer to the | ||
[C++ build instructions](../cpp/README.md). | ||
- Node.js 4.6 or later | ||
|
||
## Building the JavaScript libraries and NodeJS packages | ||
|
||
Change to the Ice for JavaScript source subdirectory: | ||
|
||
```shell | ||
cd js | ||
``` | ||
|
||
Run these commands to build the libraries and tests: | ||
|
||
```shell | ||
npm install | ||
npm run build | ||
``` | ||
|
||
On Windows, you need to set the platform and configuration in order to locate | ||
`slice2js`. For example, if you have built C++ with the x64 Release | ||
configuration, you can use the following command to build JavaScript: | ||
|
||
```shell | ||
npm run build -- --cppPlatform x64 --cppConfiguration Release | ||
``` | ||
|
||
Alternatively you can use the `CPP_PLATFORM` and `CPP_CONFIGURATION` environment | ||
variables: | ||
|
||
```shell | ||
set CPP_PLATFORM=x64 | ||
set CPP_CONFIGURATION=Debug | ||
npm run build | ||
``` | ||
|
||
Upon successful completion, the build generates libraries in the `lib` | ||
subdirectory, including compressed and minified versions. | ||
|
||
For older browsers that do not support all of the required ECMAScript 6 | ||
features used by Ice for JavaScript, we provide pre-compiled versions of | ||
the libraries using the [Babel] JavaScript compiler. These libraries | ||
depend on the [core-js] and [regenerator-runtime] packages | ||
and are available in the `lib/es5` subdirectory with the same names as | ||
the main libraries. | ||
|
||
## Running the JavaScript Tests | ||
|
||
Python is required to run the test suite. Additionally, the Glacier2 tests | ||
require the Python module `passlib`, which you can install with the command: | ||
|
||
```shell | ||
pip install passlib | ||
``` | ||
|
||
The scripts also require Ice for Python, you can build Ice for Python from | ||
[python](../python) folder of this source distribution or install the Python | ||
module `zeroc-ice`, using the following command: | ||
|
||
```shell | ||
pip install zeroc-ice | ||
``` | ||
|
||
The test suites require that the Ice for C++ tests be built in the `cpp` | ||
subdirectory of this source distribution. | ||
|
||
You can start the NodeJS tests with: | ||
|
||
```shell | ||
python allTests.py | ||
``` | ||
|
||
If everything worked out, you should see lots of `ok` messages. In case of a | ||
failure, the tests abort with `failed`. | ||
|
||
You can start the browser tests with: | ||
|
||
```shell | ||
python allTests.py --browser Manual | ||
``` | ||
|
||
Then open the test page (http://127.0.0.1:8080/start) using a web browser. | ||
These tests require a web browser with ECMAScript 6 support, such as | ||
a recent version of Chrome, Firefox, Microsoft Edge or Safari. | ||
|
||
If you are using another web browser, such as Internet Explorer, you should | ||
use instead: | ||
|
||
```shell | ||
python allTests.py --browser Manual --es5 | ||
``` | ||
|
||
Then open the test page (http://127.0.0.1:8080/es5/start) | ||
|
||
This runs a version of the test suite transpiled to ECMAScript 5 using [Babel]. | ||
|
||
On macOS the first time you run the tests, you will be prompted for your | ||
password. This is necessary to configure the trust setting for the HTTP | ||
server certificate, which will enable you to connect to the HTTP server | ||
with SSL via your web browser. | ||
|
||
### Browser Information | ||
|
||
#### Self-Signed Certificate | ||
|
||
The browser-based tests allow you to choose whether to run the tests over | ||
non-secure WebSocket (WS) or secure WebSocket (WSS) connections. The WSS | ||
connections in these tests rely on a self-signed certificate, `cacert`, | ||
provided in the certs(../certs) directory. | ||
|
||
To successfully run the tests over WSS, additional action may be necessary | ||
depending on the browser you're using: | ||
|
||
- Chrome | ||
You'll be presented with a warning about the site's security certificate. | ||
Click the "Proceed anyway" button to temporarily accept the certificate. | ||
|
||
- Firefox | ||
You'll see a warning saying "This Connection is Untrusted". Open Firefox's | ||
Preferences or Options dialog, click on the Advanced section, select the | ||
Certificates tab and click on the "View Certificates..." button. In the | ||
Authorities tab, click the "Import..." button, navigate to the `cacert.pem` | ||
file, and add it as a certificate authority (CA) for trusting web sites. | ||
After closing the dialogs, reload the test page to continue. You should | ||
uninstall this certificate after running the tests. | ||
|
||
- Internet Explorer and Microsoft Edge | ||
Run the management console (mmc.exe) and add the Certificates snap-in for | ||
the computer account. Then select Console Root > Certificates (Local | ||
Computer) > Trusted Root Certificate Authorities. In the Action menu, choose | ||
All Tasks and Import. Navigate to the `cacert.der` file and import it into | ||
the Trusted Root Certificate Authorities. Reload the test page to continue. | ||
You should uninstall this certificate after running the tests. | ||
|
||
#### Windows 8 | ||
|
||
On Windows 8, network isolation prevents Internet Explorer from | ||
connecting to 127.0.0.1. To work around this limitation, you'll need to disable | ||
Internet Explorer's "Protected Mode". Open the "Internet Options" dialog and in | ||
the "Security" settings tab, deselect the "Enable Protected Mode" checkbox. | ||
|
||
#### Secure WebSockets on iOS and Android | ||
|
||
To use WSS on iOS and Android it may be required (depending on browser and | ||
platform) that the server certificate's common name matches the computer hosting | ||
the tests, and that the test certificate authority be installed on your device. | ||
|
||
First you'll need to generate new certificates to match the IP address of the | ||
computer hosting the tests: | ||
|
||
```shell | ||
certs/makecerts.py [IP address] | ||
``` | ||
|
||
Next you must install the certificate authority on your device. The simplest way | ||
is to email the CA certificate (`certs/cacert.pem`) to yourself and then follow | ||
the instructions below to install the certificate on your device. | ||
|
||
Once installed, you connect to the server using the same IP address used to | ||
create the certificates. | ||
|
||
##### Installing Certificates on iOS | ||
|
||
Open the certificate (`cacert.pem`) from the device's email client. You | ||
will be prompted to create a configuration profile containing this certificate. | ||
|
||
##### Installing Certificates on Android | ||
|
||
Download the certificate (`cacert.pem`) to the device from an email client. | ||
Next go to _Settings -> Security -> Install from storage_, and choose | ||
`cacert.pem`. Enter a name and press OK. | ||
|
||
## Installing a Source Build | ||
|
||
After a successful build, you can generate a package by running the | ||
following command: | ||
|
||
```shell | ||
npm pack | ||
``` | ||
|
||
This will generate the file `ice-3.7.100.tgz`, which can be installed by running: | ||
|
||
```shell | ||
npm install ice-3.7.100.tgz | ||
``` | ||
|
||
To use Ice for JavaScript with a browser, copy the appropriate JavaScript | ||
library files located in the `lib` directory to your web server. | ||
|
||
[binary distributions]: https://zeroc.com/downloads/ice | ||
[Babel]: https://babeljs.io | ||
[core-js]: https://www.npmjs.com/package/core-js | ||
[regenerator-runtime]: https://www.npmjs.com/package/regenerator-runtime |
Oops, something went wrong.