Readme xxx

README.md

@@ -20,6 +20,7 @@ or retrying failed connection attempts (to name just a few of dozens of such low
 Remote procedure calls ([RPCs][rpcs]) are at the heart of the Ice framework.
 
 You create RPCs with an easy 2-step process:
+
 1. Define the contract between your client and your server with the [Slice][slice] language—Ice's [IDL][idl].
 2. Run the Slice compiler on these Slice definitions to generate stubs in the programming language(s) of your choice.
 
@@ -85,7 +86,7 @@ languages.
 
 ## Building Ice from source
 
-[C++](cpp/BUILDING.md) | [C#](csharp/BUILDING.md) | [Java](java/BUILDING.md) | [Java Compat](java-compat/BUILDING.md) | [JavaScript/TypeScript](js) | [MATLAB](matlab) | [Objective-C](objective-c) | [PHP](php) | [Python](python) | [Ruby](ruby) | [Swift](swift)
+[C++](cpp/BUILDING.md) | [C#](csharp/BUILDING.md) | [Java](java/BUILDING.md) | [Java Compat](java-compat/BUILDING.md) | [JavaScript/TypeScript](js/BUILDING.md) | [MATLAB](matlab/BUILDING.md) | [Objective-C](objective-c/BUILDING.md) | [PHP](php/BUILDING.md) | [Python](python/BUILDING.md) | [Ruby](ruby/BUILDING.md) | [Swift](swift/BUILDING.md)
 
 ## Copyright and license
 

cpp/README.md

@@ -2,7 +2,8 @@
 
 [Getting started C++11] | [Examples C++11] | [Getting started C++98] | [Examples C++98] | [NuGet packages] | [Documentation] | [Building from source]
 
-The [Ice framework] provides everything you need to build networked applications, including RPC, pub/sub, server deployment, and more.
+The [Ice framework] provides everything you need to build networked applications,
+including RPC, pub/sub, server deployment, and more.
 
 Ice for C++ is the C++ implementation of Ice.
 

csharp/README.md

@@ -4,7 +4,7 @@
 
 The [Ice framework] provides everything you need to build networked applications, including RPC, pub/sub, server deployment, and more.
 
-Ice for .NET is the C# / .NET implementation of Ice.
+Ice for .NET is the C# / .NET implementation of the Ice framework.
 
 ## Sample Code
 

js/BUILDING.md

@@ -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