diff options
| -rw-r--r-- | cpp/BuildInstructionsLinux.md | 75 | ||||
| -rw-r--r-- | cpp/BuildInstructionsMinGW.md | 66 | ||||
| -rw-r--r-- | cpp/BuildInstructionsOSX.md | 68 | ||||
| -rw-r--r-- | cpp/BuildInstructionsWinRT.md | 76 | ||||
| -rw-r--r-- | cpp/BuildInstructionsWindows.md | 66 | ||||
| -rw-r--r-- | csharp/BuildInstructions.md | 94 | ||||
| -rw-r--r-- | java/BuildInstructions.md | 157 | ||||
| -rw-r--r-- | js/BuildInstructions.md | 57 | ||||
| -rw-r--r-- | php/BuildInstructionsLinuxOSX.md | 128 | ||||
| -rw-r--r-- | php/BuildInstructionsWindows.md | 140 | ||||
| -rw-r--r-- | python/BuildInstructionsLinuxOSX.md | 39 | ||||
| -rw-r--r-- | python/BuildInstructionsWindows.md | 52 | ||||
| -rw-r--r-- | ruby/BuildInstructionsLinux.md | 93 | ||||
| -rw-r--r-- | ruby/BuildInstructionsWindows.md | 84 |
14 files changed, 862 insertions, 333 deletions
diff --git a/cpp/BuildInstructionsLinux.md b/cpp/BuildInstructionsLinux.md index b9e50803d6f..bb91d67e767 100644 --- a/cpp/BuildInstructionsLinux.md +++ b/cpp/BuildInstructionsLinux.md @@ -1,35 +1,46 @@ # Building Ice for C++ on Linux -This page describes the Ice source distribution, including information about compiler requirements, third-party dependencies, and instructions for building and testing the distribution. If you prefer, you can install [binary packages](https://doc.zeroc.com/display/Ice36/Using+the+Linux+Binary+Distributions) for supported platforms that contain pre-compiled libraries, executables, and everything else necessary to build Ice applications on Linux. +This page describes the Ice source distribution, including information about +compiler requirements, third-party dependencies, and instructions for building +and testing the distribution. If you prefer, you can install [binary packages][1] +for supported platforms that contain pre-compiled libraries, executables, and +everything else necessary to build Ice applications on Linux. -## C++ Build Requirements for Linux +## C++ Build Requirements ### Operating Systems and Compilers -Ice is expected to build and run properly on any recent Linux distribution for x86 and x86_64, and was extensively tested using the operating systems and compiler versions listed for our [supported platforms](https://zeroc.com/platforms_3_6_0.html). +Ice is expected to build and run properly on any recent Linux distribution for +x86 and x86_64, and was extensively tested using the operating systems and compiler +versions listed for our [supported platforms][2]. ### Third-Party Libraries Ice has dependencies on a number of third-party libraries: - - [expat](http://expat.sourceforge.net/) 2.0 - - [OpenSSL](http://openssl.org) 0.9.8 or later - - [bzip](http://bzip.org) 1.0 - - [Berkeley DB](http://www.oracle.com/us/products/database/berkeley-db/overview/index.htm) 5.3 - - [mcpp](https://github.com/zeroc-ice/mcpp) 2.7.2 (with patches) + - [expat][3] 2.0 + - [OpenSSL][4] 0.9.8 or later + - [bzip][5] 1.0 + - [Berkeley DB][6] 5.3 + - [mcpp][7] 2.7.2 (with patches) -Expat, OpenSSL and bzip are included with most Linux distributions. ZeroC supplies binary packages for Berkeley DB and mcpp on supported Linux distributions that do not include them: +Expat, OpenSSL and bzip are included with most Linux distributions. ZeroC supplies +binary packages for Berkeley DB and mcpp on supported Linux distributions that do +not include them: -- Berkeley DB 5.3.28 on RHEL 6, SLES12, SLES 11 and AMZN 2015.03 -- mcpp 2.7.2 with patches (```mcpp-devel```) on RHEL 7, RHEL 6, SLES 12, SLES 11 and AMZN 2015.03 +- Berkeley DB 5.3.28 on RHEL 6, SLES12, SLES 11 and Amzn 2015.03 +- mcpp 2.7.2 with patches (`mcpp-devel`) on RHEL 7, RHEL 6, SLES 12, SLES 11 +and Amzn 2015.03 ## Compiling and Testing Ice for C++ on Linux -In a command window, change to the ```cpp``` subdirectory: +In a command window, change to the `cpp` subdirectory: $ cd cpp -Edit ```config/Make.rules``` to establish your build configuration. The comments in the file provide more information. Pay particular attention to the variables that define the locations of the third-party libraries. +Edit `config/Make.rules` to establish your build configuration. The comments in +the file provide more information. Pay particular attention to the variables +that define the locations of the third-party libraries. Now you're ready to build Ice: @@ -37,7 +48,8 @@ Now you're ready to build Ice: This will build the Ice core libraries, services, and tests. -Python is required to run the test suite. After a successful build, you can run the tests as follows: +Python is required to run the test suite. After a successful build, you can run +the tests as follows: $ make test @@ -45,28 +57,36 @@ This command is equivalent to: $ python allTests.py -If everything worked out, you should see lots of ```ok``` messages. In case of a failure, the tests abort with ```failed```. +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. ### 64-bit Source Builds on Linux x86_64 To build Ice in 64-bit mode, you need to do the following: -- Obtain or build all the third-party dependencies, and put the 64-bit libraries in the lib64 directories. For example, put Berkeley DB 64-bit libraries in ```$DB_HOME/lib64```. +- Obtain or build all the third-party dependencies, and put the 64-bit libraries +in the lib64 directories. For example, put Berkeley DB 64-bit libraries in +`$DB_HOME/lib64`. - Build and test as described above. ### 32-bit Source Builds on Linux x86_64 -By default, builds on x86_64 are 64-bit. To perform a 32-bit build on an x86_64 Linux system, set the environment variable ```LP64``` to no, as shown below: +By default, builds on x86_64 are 64-bit. To perform a 32-bit build on an x86_64 +Linux system, set the environment variable `LP64` to no, as shown below: $ export LP64=no -## Installing a C++ Source Build on Linux +## Installing a C++ Source Build -Simply run ```make install```. This will install Ice in the directory specified by the ```prefix``` variable in ```config/Make.rules```. +Simply run `make install`. This will install Ice in the directory specified by +the `prefix` variable in `config/Make.rules`. -After installation, make sure that the ```prefix/bin``` directory is in your ```PATH```. +After installation, make sure that the `prefix/bin` directory is in your `PATH`. -If you choose to not embed a ```runpath``` into executables at build time (see your build settings in ```config/Make.rules```) or did not create a symbolic link from the ```runpath``` directory to the installation directory, you also need to add the library directory to your ```LD_LIBRARY_PATH```. +If you choose to not embed a `runpath` into executables at build time (see your +build settings in `config/Make.rules`) or did not create a symbolic link from +the `runpath` directory to the installation directory, you also need to add the +library directory to your `LD_LIBRARY_PATH`. On an x86 system, the library directory is: @@ -78,4 +98,15 @@ On an x86_64 system: prefix/lib64 (RHEL, SLES, Amazon) prefix/lib/x86_64-linux-gnu (Ubuntu) -When compiling Ice programs, you must pass the location of the ```prefix/include``` directory to the compiler with the ```-I``` option, and the location of the library directory with the ```-L``` option. If building a C++11 program, you must add the ```/c++11``` suffix to the library directory (such as ```prefix/lib/c++11```). +When compiling Ice programs, you must pass the location of the `prefix/include` +directory to the compiler with the `-I` option, and the location of the library +directory with the `-L` option. If building a C++11 program, you must add the +`/c++11` suffix to the library directory (such as `prefix/lib/c++11`). + +[1]: https://doc.zeroc.com/display/Ice36/Using+the+Linux+Binary+Distributions +[2]: https://zeroc.com/platforms_3_6_0.html +[3]: http://expat.sourceforge.net +[4]: http://openssl.org +[5]: http://bzip.org +[6]: http://www.oracle.com/us/products/database/berkeley-db/overview/index.htm +[7]: https://github.com/zeroc-ice/mcpp diff --git a/cpp/BuildInstructionsMinGW.md b/cpp/BuildInstructionsMinGW.md index 38d371fbc17..e0e3778c17e 100644 --- a/cpp/BuildInstructionsMinGW.md +++ b/cpp/BuildInstructionsMinGW.md @@ -1,53 +1,67 @@ # Building Ice for C++ with MinGW -> *MinGW is only supported for building the Ice extension for Ruby. It is not supported for general application development. If you prefer, you can install a [Ruby gem](https://doc.zeroc.com/display/Ice36/Using+the+Ruby+Distribution) that contains a complete Ice for Ruby run-time.* +> *MinGW is only supported for building the Ice extension for Ruby. It is not +supported for general application development. If you prefer, you can install +a [Ruby gem][1] that contains a complete Ice for Ruby run-time.* -## Build Requirements for MinGW +## Build Requirements ### Compiler Ice for C++ was tested with the following MinGW compilers: -- [mingw 4.7.3 32-bit](http://sourceforge.net/projects/mingwbuilds/files/host-windows/releases/4.7.3/32-bit/threads-win32/sjlj/x32-4.7.3-release-win32-sjlj-rev1.7z/download) -- mingw 4.7.2 64-bit, included in the [Ruby Development Kit](http://rubyinstaller.org/downloads/) version 4.7.2 +- [mingw 4.7.3 32-bit][2] +- mingw 4.7.2 64-bit, included in the [Ruby Development Kit][3] version 4.7.2 -> *mingw 4.7.2 32-bit, included in the 32-bit Ruby Development Kit version 4.7.2, contains a very severe bug that makes it unsuitable to build Ice.* +> *mingw 4.7.2 32-bit, included in the 32-bit Ruby Development Kit version 4.7.2, +contains a very severe bug that makes it unsuitable to build Ice.* ### Third-Party Libraries Ice has dependencies on the following third-party libraries: - - [bzip](http://bzip.org) 1.0 - - [mcpp](https://github.com/zeroc-ice/mcpp) 2.7.2 (with patches) + - [bzip][4] 1.0 + - [mcpp][5] 2.7.2 (with patches) -You do not need to build these packages yourself, as ZeroC supplies a separate [Windows installer](https://zeroc.com/download.html) that contains release and debug libraries for all of the third-party dependencies. +You do not need to build these packages yourself, as ZeroC supplies a separate +[Windows installer][6] that contains release and debug libraries for all of the +third-party dependencies. -## Compiling and Testing Ice with MinGW +## Compiling and Testing Ice -The Ice build system for MinGW builds only a small subset of Ice for C++, namely the core run time libraries (Ice, IceUtil, IceDiscovery, IceSSL), slice2cpp, slice2rb and the corresponding tests. +The Ice build system for MinGW builds only a small subset of Ice for C++, namely +the core run time libraries (Ice, IceUtil, IceDiscovery, IceSSL), slice2cpp, +slice2rb and the corresponding tests. ### Building Ice -In a command window, change to the ```cpp``` subdirectory: +In a command window, change to the `cpp` subdirectory: > cd cpp -Run the ```devkitvars.bat``` batch file from the Ruby development kit to set up your environment. For example, if you installed the development kit in ```C:\RubyDevKit-4.7.2```, run the following: +Run the `devkitvars.bat` batch file from the Ruby development kit to set up your +environment. For example, if you installed the development kit in +`C:\RubyDevKit-4.7.2`, run the following: > C:\RubyDevKit-4.7.2\devkitvars.bat If you are building for Windows 32-bit: -- Add mingw 4.7.3 to your PATH, before the mingw 4.7.2 included in the Ruby development kit. For example, if you installed mingw 4.7.3 in ```C:\mingw-4.7.3```, run the following: +- Add mingw 4.7.3 to your PATH, before the mingw 4.7.2 included in the Ruby +development kit. For example, if you installed mingw 4.7.3 in `C:\mingw-4.7.3`, +run the following: - ```> set PATH=C:\mingw-4.7.3\bin;%PATH%``` + > set PATH=C:\mingw-4.7.3\bin;%PATH% - Then double-check the desired version of g++ is in your PATH: - ```> g++ -dumpversion - 4.7.3``` + > g++ -dumpversion + 4.7.3 -Edit ```config\Make.rules``` to establish your build configuration. The comments in the file provide more information. In particular, if Ice third-party packages are not installed in the default location, set ```THIRDPARTY_HOME``` to the Ice third-party installation directory. +Edit `config\Make.rules` to establish your build configuration. The comments +in the file provide more information. In particular, if Ice third-party +packages are not installed in the default location, set `THIRDPARTY_HOME` to +the Ice third-party installation directory. Now you are ready to build Ice: @@ -55,12 +69,22 @@ Now you are ready to build Ice: ### Running the Test Suite -Python is required to run the test suite. After a successful build, you can run the tests as follows: +Python is required to run the test suite. After a successful build, you can run +the tests as follows: > python allTests.py -If everything worked out, you should see lots of ```ok``` messages. In case of a failure, the tests abort with ```failed```. +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. -## Installing a C++ Source Build for MinGW +## Installing a C++ Source Build -Simply run ```make install``` from a command prompt. This will install Ice in the directory specified by the prefix variable in ```config\Make.rules```. +Simply run `make install` from a command prompt. This will install Ice in the +directory specified by the `prefix` variable in `config\Make.rules`. + +[1]: https://doc.zeroc.com/display/Ice36/Using+the+Ruby+Distribution +[2]: http://sourceforge.net/projects/mingwbuilds/files/host-windows/releases/4.7.3/32-bit/threads-win32/sjlj/x32-4.7.3-release-win32-sjlj-rev1.7z/download +[3]: http://rubyinstaller.org/downloads +[4]: http://bzip.org +[5]: https://github.com/zeroc-ice/mcpp +[6]: https://zeroc.com/download.html diff --git a/cpp/BuildInstructionsOSX.md b/cpp/BuildInstructionsOSX.md index c112e4bb2e9..702c4edabc9 100644 --- a/cpp/BuildInstructionsOSX.md +++ b/cpp/BuildInstructionsOSX.md @@ -1,41 +1,50 @@ # Building Ice for C++ on OS X -This page describes the Ice source distribution, including information about compiler requirements, third-party dependencies, and instructions for building and testing the distribution. If you prefer, you can install a [Homebrew](https://doc.zeroc.com/display/Ice36/Using+the+OS+X+Binary+Distribution) package instead. +This page describes the Ice source distribution, including information about +compiler requirements, third-party dependencies, and instructions for building +and testing the distribution. If you prefer, you can install a [Homebrew][1] +package instead. -## C++ Build Requirements for OS X +## C++ Build Requirements ### Operating Systems and Compilers -Ice was extensively tested using the operating systems and compiler versions listed for our [supported platforms](https://zeroc.com/platforms_3_6_0.html). +Ice was extensively tested using the operating systems and compiler versions +listed for our [supported platforms][2]. ### Third-Party Libraries Ice has dependencies on a number of third-party libraries: - - [expat](http://expat.sourceforge.net/) 2.0 - - [OpenSSL](http://openssl.org) 0.9.8 or later - - [bzip](http://bzip.org) 1.0 - - [Berkeley DB](http://www.oracle.com/us/products/database/berkeley-db/overview/index.htm) 5.3 - - [mcpp](https://github.com/zeroc-ice/mcpp) 2.7.2 (with patches) + - [expat][3] 2.0 + - [OpenSSL][4] 0.9.8 or later + - [bzip][5] 1.0 + - [Berkeley DB][6] 5.3 + - [mcpp][7] 2.7.2 (with patches) -Expat, OpenSSL and bzip are included with your system. For Berkeley DB and mcpp, you have a couple of options: +Expat, OpenSSL and bzip are included with your system. For Berkeley DB and mcpp, +you have a couple of options: -- Using [Homebrew](http://brew.sh), install Berkeley DB and mcpp with these commands: +- Using [Homebrew][8], install Berkeley DB and mcpp with these commands: $ brew tap zeroc-ice/tap $ brew install berkeley-db53 [--without-java] $ brew install mcpp - The ```berkeley-db53``` package is a pre-compiled bottle that includes Java support by default; you can exclude Java support using the ```--without-java``` option. + The `berkeley-db53` package is a pre-compiled bottle that includes Java support + by default; you can exclude Java support using the `--without-java` option. + - Download the Berkeley DB and mcpp source distributions and build them yourself. -## Compiling and Testing Ice for C++ on OS X +## Compiling and Testing Ice -In a command window, change to the ```cpp``` subdirectory: +In a command window, change to the `cpp` subdirectory: $ cd cpp -Edit ```config/Make.rules``` to establish your build configuration. The comments in the file provide more information. Pay particular attention to the variables that define the locations of the third-party libraries. +Edit `config/Make.rules` to establish your build configuration. The comments in +the file provide more information. Pay particular attention to the variables that +define the locations of the third-party libraries. Now you're ready to build Ice: @@ -43,7 +52,8 @@ Now you're ready to build Ice: This will build the Ice core libraries, services, and tests. -Python is required to run the test suite. After a successful build, you can run the tests as follows: +Python is required to run the test suite. After a successful build, you can run the +tests as follows: $ make test @@ -51,14 +61,30 @@ This command is equivalent to: $ python allTests.py -If everything worked out, you should see lots of ```ok``` messages. In case of a failure, the tests abort with ```failed```. +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. + +## Installing a C++ Source Build -## Installing a C++ Source Build on OS X +Simply run `make install`. This will install Ice in the directory specified by +the `prefix` variable in `config/Make.rules`. -Simply run ```make install```. This will install Ice in the directory specified by the ```prefix``` variable in ```config/Make.rules```. +After installation, make sure that the `<prefix>/bin` directory is in your `PATH`. -After installation, make sure that the ```prefix/bin``` directory is in your ```PATH```. +If you choose to not embed a `runpath` into executables at build time (see your +build settings in `config/Make.rules`) or did not create a symbolic link from the +`runpath` directory to the installation directory, you also need to add the +library directory to your `DYLD_LIBRARY_PATH`. -If you choose to not embed a ```runpath``` into executables at build time (see your build settings in ```config/Make.rules```) or did not create a symbolic link from the ```runpath``` directory to the installation directory, you also need to add the library directory to your ```DYLD_LIBRARY_PATH```. +When compiling Ice programs, you must pass the location of the `<prefix>/include` +directory to the compiler with the `-I` option, and the location of the library +directory with the `-L` option. -When compiling Ice programs, you must pass the location of the ```prefix/include``` directory to the compiler with the ```-I``` option, and the location of the library directory with the ```-L``` option. +[1]: https://doc.zeroc.com/display/Ice36/Using+the+OS+X+Binary+Distribution +[2]: https://zeroc.com/platforms_3_6_0.html +[3]: http://expat.sourceforge.net +[4]: http://openssl.org +[5]: http://bzip.org +[6]: http://www.oracle.com/us/products/database/berkeley-db/overview/index.htm +[7]: https://github.com/zeroc-ice/mcpp +[8]: http://brew.sh diff --git a/cpp/BuildInstructionsWinRT.md b/cpp/BuildInstructionsWinRT.md index f847594e715..3ff56795024 100644 --- a/cpp/BuildInstructionsWinRT.md +++ b/cpp/BuildInstructionsWinRT.md @@ -1,31 +1,42 @@ # Building Ice for C++ for WinRT Applications -This page describes the Ice source distribution, including information about compiler requirements, third-party dependencies, and instructions for building and testing the distribution. If you prefer, you can download a [Windows installer](https://doc.zeroc.com/display/Ice36/Using+the+Windows+Binary+Distribution) that contains pre-compiled debug and release libraries, executables, and everything else necessary to build Ice applications on Windows. +This page describes the Ice source distribution, including information about +compiler requirements, third-party dependencies, and instructions for building +and testing the distribution. If you prefer, you can download a [Windows installer][1] +that contains pre-compiled debug and release libraries, executables, and everything +else necessary to build Ice applications for WinRT. ## Build Requirements for WinRT -Ice was extensively tested using the operating systems and compiler versions listed for our [supported platforms](https://zeroc.com/platforms_3_6_0.html). +Ice was extensively tested using the operating systems and compiler versions listed +for our [supported platforms][2]. -## Compiling and Testing Ice for WinRT +## Compiling and Testing Ice ### Building Ice -> *To build Ice for WinRT you first need to build Ice for Windows. The build of Ice for Windows is necessary to create the Slice translators that we need to build Ice for WinRT.* +> *To build Ice for WinRT you first need to build Ice for Windows. The build of Ice +for Windows is necessary to create the Slice translators that we need to build Ice +for WinRT.* -Open a command prompt that is configured for your target architecture. For example, Visual Studio gives you several alternatives: +Open a command prompt that is configured for your target architecture. For example, +Visual Studio gives you several alternatives: - Visual Studio Command Prompt - Visual Studio x64 Win64 Command Prompt - Visual Studio x64 Cross Tools Command Prompt - Visual Studio ARM Cross Tools Command Prompt -Using the first configuration produces 32-bit binaries, while the second and third produce 64-bit binaries and the fourth produces ARM binaries. +Using the first configuration produces 32-bit binaries, while the second and third +produce 64-bit binaries and the fourth produces ARM binaries. -In the command window, change to the ```cpp``` subdirectory: +In the command window, change to the `cpp` subdirectory: $ cd cpp -Edit ```config\Make.rules.mak``` to establish your build configuration. The comments in the file provide more information. In particular, you must set ```WINRT``` to yes in ```Make.rules.mak``` or in your environment: +Edit `config\Make.rules.mak` to establish your build configuration. The comments +in the file provide more information. In particular, you must set `WINRT` to yes +in `Make.rules.mak` or in your environment: > set WINRT=yes @@ -37,11 +48,14 @@ After the build has completed, you must register the Ice SDK in the Windows regi > nmake /f Makefile.mak register-sdk -> *This command must be executed in a command prompt that has administrative privileges because it requires write access to the registry.* +> *This command must be executed in a command prompt that has administrative privileges +because it requires write access to the registry.* ### Running the Test Suite -The WinRT test suite is composed of a set of dynamic libraries (one for each client/server test) and a GUI application that loads and runs the tests in the dynamic libraries. +The WinRT test suite is composed of a set of dynamic libraries (one for each +client/server test) and a GUI application that loads and runs the tests in the +dynamic libraries. You need to build the dynamic libraries first. Change the working directory: @@ -55,26 +69,46 @@ In Visual Studio, open this solution file: cpp/test/WinRT/TestSuite.sln -Now select the configuration that matches the settings in ```config\Make.rules.mak``` that you used to build the dynamic libraries. For example, if you built the test libraries for x86 and debug, you must select Win32 Debug. +Now select the configuration that matches the settings in `config\Make.rules.mak` +that you used to build the dynamic libraries. For example, if you built the test +libraries for x86 and debug, you must select Win32 Debug. -After selecting the appropriate configuration, build the solution by choosing "Build Solution" in the "Build" menu. +After selecting the appropriate configuration, build the solution by choosing +"Build Solution" in the "Build" menu. -After the build completes, you can deploy the application using "Deploy Solution" in the "Build" menu. Once deployed, you can start the application from the WinRT Desktop by clicking the "Ice Test Suite" icon. +After the build completes, you can deploy the application using "Deploy Solution" +in the "Build" menu. Once deployed, you can start the application from the WinRT +Desktop by clicking the "Ice Test Suite" icon. -If you want to run the tests with SSL enabled, you must use servers from another language mapping as WinRT does not support server-side SSL. +If you want to run the tests with SSL enabled, you must use servers from another +language mapping as WinRT does not support server-side SSL. -To run a test with SSL, open a command window and change to the test directory. At the command prompt, execute: +To run a test with SSL, open a command window and change to the test directory. +At the command prompt, execute: > python run.py --winrt --protocol=ssl -Then open the "Ice Test Suite" Windows Store application, check "Enable SSL", and click the "Run" button. +Then open the "Ice Test Suite" Windows Store application, check "Enable SSL", +and click the "Run" button. -To run the tests on a remote device such as the Surface, you will need to install the Remote Debugger Tools. +To run the tests on a remote device such as the Surface, you will need to install +the Remote Debugger Tools. -> *Some tests might fail if you run the tests with the debugger attached. You should choose "Start without Debugging" from the Debug menu to run the tests.* +> *Some tests might fail if you run the tests with the debugger attached. You +should choose "Start without Debugging" from the Debug menu to run the tests.* -## Installing a C++ Source Build for WinRT +## Installing a C++ Source Build -Simply run ```nmake /f Makefile.mak install```. This will install the Ice SDK in the directory specified by the ```prefix``` variable in ```config\Make.rules.mak```. +Simply run `nmake /f Makefile.mak install`. This will install the Ice SDK in the +directory specified by the `prefix` variable in `config\Make.rules.mak`. -> *This command must be executed in a command prompt that has administrative privileges because it requires write access to the registry.* +> *This command must be executed in a command prompt that has administrative +privileges because it requires write access to the registry.* + +[1]: https://doc.zeroc.com/display/Ice36/Using+the+Windows+Binary+Distribution +[2]: https://zeroc.com/platforms_3_6_0.html +[3]: http://expat.sourceforge.net +[4]: http://bzip.org +[5]: http://www.oracle.com/us/products/database/berkeley-db/overview/index.htm +[6]: https://github.com/zeroc-ice/mcpp +[7]: https://zeroc.com/download.html diff --git a/cpp/BuildInstructionsWindows.md b/cpp/BuildInstructionsWindows.md index 137e91178d0..e483648419f 100644 --- a/cpp/BuildInstructionsWindows.md +++ b/cpp/BuildInstructionsWindows.md @@ -1,51 +1,63 @@ # Building Ice for C++ for Windows Applications -This page describes the Ice source distribution, including information about compiler requirements, third-party dependencies, and instructions for building and testing the distribution. If you prefer, you can download a [Windows installer](https://doc.zeroc.com/display/Ice36/Using+the+Windows+Binary+Distribution) that contains pre-compiled debug and release libraries, executables, and everything else necessary to build Ice applications on Windows. +This page describes the Ice source distribution, including information about +compiler requirements, third-party dependencies, and instructions for building +and testing the distribution. If you prefer, you can download a [Windows installer][1] +that contains pre-compiled debug and release libraries, executables, and everything +else necessary to build Ice applications on Windows. -## Build Requirements for Windows +## Build Requirements ### Operating Systems and Compilers -Ice was extensively tested using the operating systems and compiler versions listed for our [supported platforms](https://zeroc.com/platforms_3_6_0.html). +Ice was extensively tested using the operating systems and compiler versions listed +for our [supported platforms][2]. ### Third-Party Libraries Ice has dependencies on a number of third-party libraries: - - [expat](http://expat.sourceforge.net/) 2.0 - - [bzip](http://bzip.org) 1.0 - - [Berkeley DB](http://www.oracle.com/us/products/database/berkeley-db/overview/index.htm) 5.3 - - [mcpp](https://github.com/zeroc-ice/mcpp) 2.7.2 (with patches) + - [expat][3] 2.0 + - [bzip][4] 1.0 + - [Berkeley DB][5] 5.3 + - [mcpp][6] 2.7.2 (with patches) -You do not need to build these packages yourself, as ZeroC supplies a separate [Windows installer](https://zeroc.com/download.html) that contains release and debug libraries for all of the third-party dependencies. +You do not need to build these packages yourself, as ZeroC supplies a separate +[Windows installer][7] that contains release and debug libraries for all of the +third-party dependencies. ### Monotonic Clock -Ice uses the ```QueryPerformanceCounter``` Windows API function to measure time with a monotonic clock. If you are experiencing timing or performance issues, there are two knowledgebase articles that may be relevant for your system: +Ice uses the `QueryPerformanceCounter` Windows API function to measure time with +a monotonic clock. If you are experiencing timing or performance issues, there +are two knowledgebase articles that may be relevant for your system: - [KB 896256](http://support.microsoft.com/?id=896256) - [KB 895980](http://support.microsoft.com/?id=895980) -## Compiling and Testing Ice for C++ on Windows +## Compiling and Testing Ice ### Building Ice -Open a command prompt that is configured for your target architecture. For example, when using Visual Studio 2013, you have several alternatives: +Open a command prompt that is configured for your target architecture. For example, +when using Visual Studio 2013, you have several alternatives: - Developer Command Prompt - VS2013 x86 Native Tools Command Prompt - VS2013 x64 Native Tools Command Prompt - VS2013 x64 Cross Tools Command Prompt -Using the first two configurations produces 32-bit binaries, while the third and fourth configurations produce 64-bit binaries. +Using the first two configurations produces 32-bit binaries, while the third and +fourth configurations produce 64-bit binaries. > *You must be using a Windows x64 platform when compiling a 64-bit version of Ice.* -In the command window, change to the ```cpp``` subdirectory: +In the command window, change to the `cpp` subdirectory: $ cd cpp -Edit ```config\Make.rules.mak``` to establish your build configuration. The comments in the file provide more information. +Edit `config\Make.rules.mak` to establish your build configuration. The comments +in the file provide more information. Now you're ready to build Ice: @@ -55,20 +67,34 @@ This will build the Ice core libraries, services, and tests. ### Running the Test Suite -Python is required to run the test suite. After a successful build, you can run the tests as follows: +Python is required to run the test suite. After a successful build, you can run +the tests as follows: > python allTests.py -If everything worked out, you should see lots of ```ok``` messages. In case of a failure, the tests abort with ```failed```. +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. ### x64 Platform -Building Ice on x64 with the Visual Studio C++ compiler is like building Ice on x86. You just need to perform the build in an "x64 Command Prompt", and not in a regular "Developer Command Prompt". +Building Ice on x64 with the Visual Studio C++ compiler is like building Ice on +x86. You just need to perform the build in an "x64 Command Prompt", and not in +a regular "Developer Command Prompt". > *You must be using a Windows x64 platform when compiling a 64-bit version of Ice.* -## Installing a C++ Source Build on Windows +## Installing a C++ Source Build -Simply run ```nmake /f Makefile.mak install```. This will install Ice in the directory specified by the ```prefix``` variable in ```config\Make.rules.mak```. +Simply run `nmake /f Makefile.mak install`. This will install Ice in the directory +specified by the `prefix` variable in `config\Make.rules.mak`. -If you built a 64-bit version of Ice, the binaries are installed in the ```bin\x64``` directory and the libraries are installed in the ```lib\x64``` directory. +If you built a 64-bit version of Ice, the binaries are installed in the `bin\x64` +directory and the libraries are installed in the `lib\x64` directory. + +[1]: https://doc.zeroc.com/display/Ice36/Using+the+Windows+Binary+Distribution +[2]: https://zeroc.com/platforms_3_6_0.html +[3]: http://expat.sourceforge.net +[4]: http://bzip.org +[5]: http://www.oracle.com/us/products/database/berkeley-db/overview/index.htm +[6]: https://github.com/zeroc-ice/mcpp +[7]: https://zeroc.com/download.html diff --git a/csharp/BuildInstructions.md b/csharp/BuildInstructions.md index 5b24f99142f..4a29e3448ba 100644 --- a/csharp/BuildInstructions.md +++ b/csharp/BuildInstructions.md @@ -1,95 +1,143 @@ # Building Ice for .NET -This page describes how to build and install Ice for .NET from source code using Visual Studio. If you prefer, you can also download [binary distributions](https://zeroc.com/download.html) for the supported platforms. +This page describes how to build and install Ice for .NET from source code using +Visual Studio. If you prefer, you can also download [binary distributions][1] for +the supported platforms. ## Build Requirements ### Operating Systems and Compilers -Ice for .NET was extensively tested using the operating systems and compiler versions listed for our [supported platforms](https://zeroc.com/platforms_3_6_0.html). +Ice for .NET was extensively tested using the operating systems and compiler versions +listed for our [supported platforms][2]. ### Slice to C# Translator -You will need the Slice to C# translator. ZeroC provides translator binaries for our supported platforms, or you can build Ice for C++ (which contains the Slice to C# translator) from source. +You will need the Slice to C# translator. ZeroC provides translator binaries for our +supported platforms, or you can build Ice for C++ (which contains the Slice to C# +translator) from source. ## Compiling Ice for .NET with Visual Studio ### Preparing to Build -The build system requires the Slice translator from Ice for C++. If you have not built Ice for C++ in this source distribution, you must set the ```ICE_HOME``` environment variable with the path name of your Ice installation: +The build system requires the Slice translator from Ice for C++. If you have not +built Ice for C++ in this source distribution, you must set the `ICE_HOME` +environment variable with the path name of your Ice installation: > set ICE_HOME=C:\Program Files (x86)\ZeroC\Ice-3.6.0 ### Building Ice for .NET -Open a Visual Studio command window and change to the ```csharp``` subdirectory: +Open a Visual Studio command window and change to the `csharp` subdirectory: > cd csharp -Review the settings in the file ```config\Make.rules.mak.cs``` and edit as necessary. For example, you may wish to enable optimization. +Review the settings in the file `config\Make.rules.mak.cs` and edit as necessary. +For example, you may wish to enable optimization. To build the Ice assemblies, services and tests, run > nmake /f Makefile.mak -Upon completion, the Ice assemblies are placed in the ```Assemblies``` subdirectory. +Upon completion, the Ice assemblies are placed in the `Assemblies` subdirectory. ## Running the .NET Tests -Some of the Ice for .NET tests employ applications that are part of the Ice for C++ distribution. If you have not built Ice for C++ in this source distribution then you must set the ```ICE_HOME``` environment variable with the path name of your Ice installation: +Some of the Ice for .NET tests employ applications that are part of the Ice for +C++ distribution. If you have not built Ice for C++ in this source distribution +then you must set the `ICE_HOME` environment variable with the path name of your +Ice installation: > set ICE_HOME=C:\Program Files (x86)\ZeroC\Ice-3.6.0 -Python is required to run the test suite. To run the tests, open a command window and change to the top-level directory. At the command prompt, execute: +Python is required to run the test suite. To run the tests, open a command window +and change to the top-level directory. At the command prompt, execute: > python allTests.py -You can also run tests individually by changing to the test directory and running this command: +You can also run tests individually by changing to the test directory and running +this command: > python run.py -If everything worked out, you should see lots of ```ok``` messages. In case of a failure, the tests abort with ```failed```. +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. ## Protocol Compression with .NET -Ice for .NET attempts to dynamically load ```bzip2.dll``` to support protocol compression, therefore this DLL must be present in your PATH. Ice automatically disables protocol compression if the DLL cannot be found. +Ice for .NET attempts to dynamically load `bzip2.dll` to support protocol compression, +therefore this DLL must be present in your PATH. Ice automatically disables protocol +compression if the DLL cannot be found. -On 64-bit Windows, you must ensure that Ice finds the 64-bit version of ```bzip2.dll``` before the 32-bit version. The 64-bit and 32-bit bzip2 libraries are installed in ```<prefix>\bin\x64``` and ```<prefix>\bin```, respectively. For 64-bit Windows, the ```<prefix>\bin\x64``` directory must appear before ```<prefix>\bin``` in your application's PATH. (The Ice run time prints a warning to the console if it detects a ```bzip2.dll``` format mismatch during start-up.) +On 64-bit Windows, you must ensure that Ice finds the 64-bit version of `bzip2.dll` +before the 32-bit version. The 64-bit and 32-bit bzip2 libraries are installed in +`<prefix>\bin\x64` and `<prefix>\bin`, respectively. For 64-bit Windows, the +`<prefix>\bin\x64` directory must appear before `<prefix>\bin` in your application's +PATH. (The Ice run time prints a warning to the console if it detects a `bzip2.dll` +format mismatch during start-up.) ## Installing Ice for .NET -Run ```nmake /f Makefile.mak install``` to install Ice for .NET in the directory specified by the ```prefix``` variable in ```config\Make.rules.mak.cs```. After installation, the ```<prefix>\bin``` directory contains executables (such as ```iceboxnet.exe```), and the ```<prefix>\Assemblies``` directory contains the .NET assemblies. +Run `nmake /f Makefile.mak install` to install Ice for .NET in the directory specified +by the `prefix` variable in `config\Make.rules.mak.cs`. After installation, the +`<prefix>\bin` directory contains executables (such as `iceboxnet.exe`), and the +`<prefix>\Assemblies` directory contains the .NET assemblies. -> *This command must be executed in a command prompt that has administrative privileges because it requires write access to the registry to register the assemblies.* +> *This command must be executed in a command prompt that has administrative +privileges because it requires write access to the registry to register the +assemblies.* ## GAC Installation -You can add the assemblies to the Global Assembly Cache (GAC). To do this, open Windows Explorer and navigate to the directory ```C:\WINDOWS\assembly```. Next, drag and drop (or copy and paste) the assemblies from the ```Assemblies``` subdirectory of your Ice source build into the right-hand pane to install them in the cache. +You can add the assemblies to the Global Assembly Cache (GAC). To do this, open +Windows Explorer and navigate to the directory `C:\WINDOWS\assembly`. Next, drag +and drop (or copy and paste) the assemblies from the `Assemblies` subdirectory +of your Ice source build into the right-hand pane to install them in the cache. -You can also use ```gacutil``` from the command line to achieve the same result: +You can also use `gacutil` from the command line to achieve the same result: > gacutil /i library.dll -The ```gacutil``` tool should already be in your PATH if you open a Visual Studio command prompt. +The `gacutil` tool should already be in your PATH if you open a Visual Studio +command prompt. -Once installed in the cache, the assemblies will always be located correctly without having to set environment variables or copy them into the same directory as an executable. +Once installed in the cache, the assemblies will always be located correctly +without having to set environment variables or copy them into the same directory +as an executable. -If you want line numbers for stack traces, you must also install the PDB (```.pdb```) files in the GAC. Unfortunately, you cannot do this using Explorer, so you have to do it from the command line. Open a command shell window and navigate to ```C:\WINDOWS\assembly\Microsoft.NET\GAC_MSIL\Ice``` (assuming ```C:\WINDOWS``` is your system root). Doing a directory listing there, you will find a directory named ```v4.0_3.5.0.0__<UUID>```, for example: +If you want line numbers for stack traces, you must also install the PDB (`.pdb`) +files in the GAC. Unfortunately, you cannot do this using Explorer, so you have +to do it from the command line. Open a command shell window and navigate to +`C:\WINDOWS\assembly\Microsoft.NET\GAC_MSIL\Ice` (assuming `C:\WINDOWS` is your +system root). Doing a directory listing there, you will find a directory named +`v4.0_3.5.0.0__<UUID>`, for example: v4.0_3.5.0.0__cdd571ade22f2f16 -Change to that directory (making sure that you use the correct version number for this release of Ice). In this directory, you will see the file ```Ice.dll``` that you installed into the GAC in the preceding step. Now copy the ```Ice.pdb``` file into this directory: +Change to that directory (making sure that you use the correct version number +for this release of Ice). In this directory, you will see the file `Ice.dll` +that you installed into the GAC in the preceding step. Now copy the `Ice.pdb` +file into this directory: > copy path_to_ice.pdb . ## Targeting Managed Code -By default, Ice for .NET uses unmanaged code for performing protocol compression and for handling signals in the ```Ice.Application``` class. You can build a managed version of Ice for .NET that lacks the aforementioned features by editing ```config/Make.rules.mak.cs``` and uncommenting the ```MANAGED=yes``` line before you build. Run nmake to start the build: +By default, Ice for .NET uses unmanaged code for performing protocol compression +and for handling signals in the `Ice.Application` class. You can build a managed +version of Ice for .NET that lacks the aforementioned features by editing +`config/Make.rules.mak.cs` and uncommenting the `MANAGED=yes` line before you +build. Run nmake to start the build: > nmake /f Makefile.mak ## Targeting Unity -Ice for .NET can also be compiled to target the Unity API. To build Ice for the Unity API, open ```config\Make.rules.mak.cs``` and set ```UNITY=yes```. Run nmake as before: +Ice for .NET can also be compiled to target the Unity API. To build Ice for the +Unity API, open `config\Make.rules.mak.cs` and set `UNITY=yes`. Run nmake as before: > nmake /f Makefile.mak + +[1]: https://zeroc.com/download.html +[2]: https://zeroc.com/platforms_3_6_0.html diff --git a/java/BuildInstructions.md b/java/BuildInstructions.md index 26dea7b6faa..27dab5a4e59 100644 --- a/java/BuildInstructions.md +++ b/java/BuildInstructions.md @@ -1,64 +1,97 @@ # Building Ice for Java -This page describes how to build and install Ice for Java from source code. If you prefer, you can also download [binary distributions](https://zeroc.com/download.html) for the supported platforms. +This page describes how to build and install Ice for Java from source code. If +you prefer, you can also download [binary distributions][1] for the supported +platforms. ## Build Requirements ### Operating Systems -Ice for Java is expected to build and run properly on Windows, OS X, and any recent Linux distribution for x86 and x86_64, and was extensively tested using the operating systems and compiler versions listed for our [supported platforms](https://zeroc.com/platforms_3_6_0.html). Due to the portability of Java, it is very likely that it will also work on other platforms for which a suitable Java implementation is available. +Ice for Java is expected to build and run properly on Windows, OS X, and any +recent Linux distribution for x86 and x86_64, and was extensively tested using +the operating systems and compiler versions listed for our [supported platforms][2]. +Due to the portability of Java, it is very likely that it will also work on other +platforms for which a suitable Java implementation is available. ### Slice to Java Translator -You will need the Slice to Java translator. ZeroC provides translator binaries for our supported platforms. For other platforms, you will have to either port Ice for C++ (which contains the Slice to Java translator), or you will have to translate your Slice files to Java on a supported platform and then copy the generated Java files to your target platform. +You will need the Slice to Java translator. ZeroC provides translator binaries for +our supported platforms. For other platforms, you will have to either port Ice for +C++ (which contains the Slice to Java translator), or you will have to translate +your Slice files to Java on a supported platform and then copy the generated Java +files to your target platform. ### Java Version Ice for Java requires J2SE 1.7.0 or later. -The Metrics Graph feature of the graphical IceGrid administrative tool requires J2SE 7u6 or later with JavaFX support. This feature will not be available if you build the source with a JVM that lacks support for JavaFX. Alternatively, building the source using J2SE 7u6 or later with JavaFX produces a JAR file that can be used in JVMs with or without JavaFX support, as the Metrics Graph feature is enabled dynamically. +The Metrics Graph feature of the graphical IceGrid administrative tool requires +J2SE 7u6 or later with JavaFX support. This feature will not be available if you +build the source with a JVM that lacks support for JavaFX. Alternatively, building +the source using J2SE 7u6 or later with JavaFX produces a JAR file that can be +used in JVMs with or without JavaFX support, as the Metrics Graph feature is +enabled dynamically. -Make sure that the ```javac``` and ```java``` commands are present in your PATH. +Make sure that the `javac` and `java` commands are present in your PATH. ### Berkeley DB -"Freeze" is an optional Ice component that provides a persistence facility for Ice applications. Freeze uses Berkeley DB as its underlying database and currently requires Berkeley DB version 5.3 (the recommended version is 5.3.28). +"Freeze" is an optional Ice component that provides a persistence facility for +Ice applications. Freeze uses Berkeley DB as its underlying database and currently +requires Berkeley DB version 5.3 (the recommended version is 5.3.28). -ZeroC includes Berkeley DB in the binary distributions for all supported platforms, or you can build it from source yourself. +ZeroC includes Berkeley DB in the binary distributions for all supported platforms, +or you can build it from source yourself. -In order to run an application that uses Freeze, you must add ```db.jar``` to your CLASSPATH and verify that the Berkeley DB shared libraries are in your ```java.library.path```. +In order to run an application that uses Freeze, you must add `db.jar` to your +CLASSPATH and verify that the Berkeley DB shared libraries are in your +`java.library.path`. -Assuming you are using ZeroC's distribution of Berkeley DB, the bash command is shown below for Linux: +Assuming you are using ZeroC's distribution of Berkeley DB, the bash command is +shown below for Linux: $ export LD_LIBRARY_PATH=/usr/lib:$LD_LIBRARY_PATH (RHEL, SLES, Amazon) $ export LD_LIBRARY_PATH=/usr/lib/i386-linux-gnu:$LD_LIBRARY_PATH (Ubuntu) -On an x86_64 system with a 64-bit JVM, the 64-bit Berkeley DB libraries are installed in a different directory: +On an x86_64 system with a 64-bit JVM, the 64-bit Berkeley DB libraries are +installed in a different directory: $ export LD_LIBRARY_PATH=/usr/lib64:$LD_LIBRARY_PATH (RHEL, SLES, Amazon) $ export LD_LIBRARY_PATH=/usr/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH (Ubuntu) ### Gradle -Ice for Java uses the [Gradle](http://gradle.org) build system, and includes the Gradle wrapper version 2.4 in the distribution. You cannot build the Ice for Java source distribution without an Internet connection. Except for Berkeley DB, Gradle will download all required packages automatically. These packages are listed below. Gradle will automatically download any necessary build artifacts from ZeroC's Maven repository located at +Ice for Java uses the [Gradle][3] build system, and includes the Gradle wrapper +version 2.4 in the distribution. You cannot build the Ice for Java source +distribution without an Internet connection. Except for Berkeley DB, Gradle will +download all required packages automatically. These packages are listed below. +Gradle will automatically download any necessary build artifacts from ZeroC's +Maven repository located at http://repo.zeroc.com/nexus/content/repositories/thirdparty ### Bzip2 Compression -Ice for Java supports protocol compression using the bzip2 classes included with Apache Ant or available separately from [kohsuke.org](). +Ice for Java supports protocol compression using the bzip2 classes included +with Apache Ant or available separately from [kohsuke.org](). The Maven package id for the bzip2 JAR file is as follows: groupId=org.apache.tools, version=1.0, artifactId=bzip2 -The demos and tests are automatically setup to enable protocol compression by adding the bzip2 JAR to the manifest class path. For your own applications you must add the bzip2 JAR to the application CLASSPATH to enable protocol compression. +The demos and tests are automatically setup to enable protocol compression by +adding the bzip2 JAR to the manifest class path. For your own applications you +must add the bzip2 JAR to the application CLASSPATH to enable protocol +compression. -> *These classes are a pure Java implementation of the bzip2 algorithm and therefore add significant latency to Ice requests.* +> *These classes are a pure Java implementation of the bzip2 algorithm and +therefore add significant latency to Ice requests.* ### JGoodies -The graphical IceGrid administrative tool uses the JGoodies libraries Common, Forms, and Looks. The following versions were tested: +The graphical IceGrid administrative tool uses the JGoodies libraries Common, +Forms, and Looks. The following versions were tested: JGoodies Common 1.8.0 JGoodies Forms 1.8.0 @@ -72,7 +105,8 @@ The Maven package ids for the JGoodies packages are as follows: ### ProGuard -Gradle uses [ProGuard](http://proguard.sourceforge.net) to create the standalone JAR file for the graphical IceGrid administrative tool. +Gradle uses [ProGuard][4] to create the standalone JAR file for the graphical +IceGrid administrative tool. The Maven package id for the ProGuard package is as follows: @@ -80,7 +114,8 @@ The Maven package id for the ProGuard package is as follows: ### Java Application Bundler -Under OS X Gradle uses the Java Application Bundler to create an application bundle for the graphical IceGrid administrative tool. +Under OS X Gradle uses the Java Application Bundler to create an application +bundle for the graphical IceGrid administrative tool. The Maven package id for the application bundler package is as follows: @@ -90,14 +125,20 @@ The Maven package id for the application bundler package is as follows: ### Preparing to Build -This source distribution cannot be compiled successfully without the Berkeley DB run time for Java (```db.jar```). The build system searches in standard locations for the following two JAR files. +This source distribution cannot be compiled successfully without the Berkeley DB +run time for Java (`db.jar`). The build system searches in standard locations +for the following two JAR files: db-5.3.28.jar db.jar -If neither of these files is present in the standard locations on your system, you must set ```dbHome``` in ```gradle.properties```. +If neither of these files is present in the standard locations on your system, +you must set `dbHome` in `gradle.properties`. -The build system also requires the Slice translators from Ice for C++. If you have not built Ice for C++ in this source distribution, you must set the ```ICE_HOME``` environment variable with the path name of your Ice installation. For example, on Unix: +The build system also requires the Slice translators from Ice for C++. If you +have not built Ice for C++ in this source distribution, you must set the +`ICE_HOME` environment variable with the path name of your Ice installation. +For example, on Unix: $ export ICE_HOME=/opt/Ice-3.6.0 (For local build) $ export ICE_HOME=/usr (For RPM installation) @@ -106,28 +147,31 @@ On Windows: > set ICE_HOME=C:\Program Files (x86)\ZeroC\Ice-3.6.0 -Before building Ice for Java, review the settings in the file ```gradle.properties``` and edit as necessary. +Before building Ice for Java, review the settings in the file `gradle.properties` +and edit as necessary. ### Building Ice for Java To build Ice, all services, and tests, run - > ./gradlew build + > gradlew build -Upon completion, the Ice JAR and POM files are placed in the ```lib``` subdirectory. +Upon completion, the Ice JAR and POM files are placed in the `lib` subdirectory. -If at any time you wish to discard the current build and start a new one, use these commands: +If at any time you wish to discard the current build and start a new one, use +these commands: - $ ./gradlew clean - $ ./gradlew build + > gradlew clean + > gradlew build ## Installing Ice for Java -To install Ice for Java in the directory specified by the ```prefix``` variable in ```gradle.properties``` run the following command +To install Ice for Java in the directory specified by the `prefix` variable in +`gradle.properties` run the following command - > ./gradlew install + > gradlew install -The installation installs the following JAR files to ```<prefix>/lib```. +The installation installs the following JAR files to `<prefix>/lib`. freeze-3.6.0.jar glacier2-3.6.0.jar @@ -140,13 +184,20 @@ The installation installs the following JAR files to ```<prefix>/lib```. icepatch2-3.6.0.jar icestorm-3.6.0.jar -POM files are also installed for ease of deployment to a maven-based distribution system. +POM files are also installed for ease of deployment to a maven-based distribution +system. ## Ice for Android -Ice requires Android 4.2 or later. The JAR files created and installed by the standard Java build as detailed above fully support Android. However, for ease of development and testing of Ice itself, an Android Studio project is bundled in the source distribution which itself builds all required Ice JAR files. This is not necessary for your own projects as it considerably complicates the project configuration. +Ice requires Android 4.2 or later. The JAR files created and installed by the +standard Java build as detailed above fully support Android. However, for ease +of development and testing of Ice itself, an Android Studio project is bundled +in the source distribution which itself builds all required Ice JAR files. +This is not necessary for your own projects as it considerably complicates the +project configuration. -Building any Ice application for Android requires Android Studio and the Android SDK build tools. We tested the following: +Building any Ice application for Android requires Android Studio and the Android +SDK build tools. We tested the following: - Android Studio 1.0.0. - Android SDK Build-tools 21.1.1 @@ -157,7 +208,8 @@ Ice requires at minimum API level 17: The bundled project builds Ice and a test suite application. -If you want to target a later version of the Android API level for the test suite, edit ```android/gradle.properties``` and change the following variables: +If you want to target a later version of the Android API level for the test +suite, edit `android/gradle.properties` and change the following variables: ice_compileSdkVersion ice_minSdkVersion @@ -166,16 +218,20 @@ If you want to target a later version of the Android API level for the test suit To import the Ice for Android project into Android Studio follow these steps 1. Start Android studio -1. Select Open Project -1. Navigate to the android subdirectory -1. You should now have an "Import Project from Gradle" dialog -1. Ensure "Use default gradle wrapper" is selected and press OK +2. Select Open Project +3. Navigate to the android subdirectory +4. You should now have an "Import Project from Gradle" dialog +5. Ensure "Use default gradle wrapper" is selected and press OK -The Android Studio project contains a ```testApp``` application to run the Ice test suite. To run the application, select it in the configuration pull down and run it. +The Android Studio project contains a `testApp` application to run the Ice test +suite. To run the application, select it in the configuration pull down and run it. ## Running the Java Tests -Some of the Ice for Java tests employ applications that are part of the Ice for C++ distribution. If you have not built Ice for C++ in this source distribution then you must set the ```ICE_HOME``` environment variable with the path name of your Ice installation. On Unix: +Some of the Ice for Java tests employ applications that are part of the Ice for +C++ distribution. If you have not built Ice for C++ in this source distribution +then you must set the `ICE_HOME` environment variable with the path name of your +Ice installation. On Unix: $ export ICE_HOME=/opt/Ice-3.6.0 (For local build) $ export ICE_HOME=/usr (For RPM installation) @@ -184,22 +240,33 @@ On Windows: > set ICE_HOME=c:\Program Files (x86)\ZeroC\Ice-3.6.0 -Python is required to run the test suite. To run the tests, open a command window and change to the top-level directory. At the command prompt, execute: +Python is required to run the test suite. To run the tests, open a command window +and change to the top-level directory. At the command prompt, execute: > python allTests.py -You can also run tests individually by changing to the test directory and running this command: +You can also run tests individually by changing to the test directory and running +this command: > python run.py -If everything worked out, you should see lots of ```ok``` messages. In case of a failure, the tests abort with ```failed```. +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. ## IceGrid Admin Tool -Ice for Java includes a graphical administrative tool for IceGrid. It can be found in the file ```lib/icegridgui.jar```. +Ice for Java includes a graphical administrative tool for IceGrid. It can be +found in the file `lib/icegridgui.jar`. -The JAR file is completely self-contained and has no external dependencies. You can start the tool with the following command: +The JAR file is completely self-contained and has no external dependencies. +You can start the tool with the following command: > java -jar icegridgui.jar -In OS X there is also an application bundle named IceGrid Admin. You can start the IceGrid Admin tool by double-clicking the IceGrid Admin icon in Finder. +In OS X there is also an application bundle named IceGrid Admin. You can start +the IceGrid Admin tool by double-clicking the IceGrid Admin icon in Finder. + +[1]: https://zeroc.com/download.html +[2]: https://zeroc.com/platforms_3_6_0.html +[3]: http://gradle.org +[4]: http://proguard.sourceforge.net diff --git a/js/BuildInstructions.md b/js/BuildInstructions.md index b46570d08d3..609e32a5e5c 100644 --- a/js/BuildInstructions.md +++ b/js/BuildInstructions.md @@ -1,6 +1,8 @@ # Building Ice for JavaScript -This page describes how to build and install Ice for JavaScript from source code. If you prefer, you can also download [binary distributions](https://zeroc.com/download.html) for the supported platforms. +This page describes how to build and install Ice for JavaScript from source +code. If you prefer, you can also download [binary distributions][1] for the +supported platforms. ## JavaScript Build Requirements @@ -11,7 +13,8 @@ To build Ice for JavaScript you must have the following: ## Building the JavaScript libraries and NodeJS packages -If you have not built Ice for C++ in the ```cpp``` subdirectory, set ```ICE_HOME``` to the directory of your Ice for C++ installation. For example, on Unix: +If you have not built Ice for C++ in the `cpp` subdirectory, set `ICE_HOME` to +the directory of your Ice for C++ installation. For example, on Unix: $ export ICE_HOME=/opt/Ice @@ -34,15 +37,20 @@ Python is required to run the test suite with Node.js. To start the tests simply > npm run gulp:test:run-with-node -If everything worked out, you should see lots of ```ok``` messages. In case of a failure, the tests abort with ```failed```. +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. To start the browser tests run: > npm run gulp:test:run-with-browser -This script requires Ice for Python to be installed. Follow the instructions from your Ice distribution to set up the environment for Ice for Python. +This script requires Ice for Python to be installed. Follow the instructions +from your Ice distribution to set up the environment for Ice for Python. -The first time you run the script, 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. +The first time you run the script, 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. You can then navigate to http://127.0.0.1:8080/index.html to start the tests. @@ -50,29 +58,52 @@ You can then navigate to http://127.0.0.1:8080/index.html to start the tests. #### 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. This distribution includes a self-signed certificate used for securing WSS connections, located in ```certs/cacert.pem```. If you select WSS, the page will automatically reload if necessary to connect to the HTTPS port 9090. To successfully run the tests over WSS, additional action may be necessary depending on the browser you're using: +The browser-based tests allow you to choose whether to run the tests over +non-secure WebSocket (WS) or secure WebSocket (WSS) connections. This +distribution includes a self-signed certificate used for securing WSS +connections, located in `certs/cacert.pem`. If you select WSS, the page +will automatically reload if necessary to connect to the HTTPS port 9090. +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. + 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'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. - Internet Explorer - Run the management console (mmc.exe) and add the Certificates snap-in for the computer account. In the console window, open the Certificates folder. From the Action menu, choose All Tasks and Import. Navigate to the cacert.pem file and import it into the Trusted Root Certification Authorities store. Reload the test page to continue. + Run the management console (mmc.exe) and add the Certificates snap-in for + the computer account. In the console window, open the Certificates folder. + From the Action menu, choose All Tasks and Import. Navigate to the + cacert.pem file and import it into the Trusted Root Certification Authorities + store. Reload the test page to continue. #### Windows 8 -On Windows 8 and Windows 8.1, 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. +On Windows 8 and Windows 8.1, 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. ## Installing a Source Build -After a successful build, you can generate an npm package by running the following command: +After a successful build, you can generate an npm package by running the +following command: > npm pack -This will generate the file ```ice-3.6.0.tgz```, which can be installed by running: +This will generate the file `ice-3.6.0.tgz`, which can be installed by running: > npm install <path_to_file>/ice-3.6.0.tgz -To use Ice for JavaScript with a browser, copy the appropriate JavaScript library files located in the ```lib``` directory to your web server. +To use Ice for JavaScript with a browser, copy the appropriate JavaScript +library files located in the `lib` directory to your web server. + +[1]: https://zeroc.com/download.html diff --git a/php/BuildInstructionsLinuxOSX.md b/php/BuildInstructionsLinuxOSX.md index 291bbd407cc..c4c8204835d 100644 --- a/php/BuildInstructionsLinuxOSX.md +++ b/php/BuildInstructionsLinuxOSX.md @@ -1,40 +1,53 @@ # Building Ice for PHP on Linux and OS X -This page describes how to build and install Ice for PHP from source code on Linux and OS X. If you prefer, you can also download [binary distributions](https://zeroc.com/download.html) for the supported platforms. +This page describes how to build and install Ice for PHP from source code on +Linux and OS X. If you prefer, you can also download [binary distributions][1] +for the supported platforms. ## PHP Build Requirements ### Operating Systems and Compilers -Ice for PHP was extensively tested using the operating systems and compiler versions listed for our [supported platforms](https://zeroc.com/platforms_3_6_0.html). +Ice for PHP was extensively tested using the operating systems and compiler +versions listed for our [supported platforms][2]. ### Ice Development Kit -You will need the Ice development kit for C++, which you can install as a binary distribution or compile from source yourself. +You will need the Ice development kit for C++, which you can install as a binary +distribution or compile from source yourself. ## Building the PHP Extension -Our source code only supports building Ice for PHP as a dynamic PHP extension; the product of the build is a shared library that you must configure PHP to load. +Our source code only supports building Ice for PHP as a dynamic PHP extension; +the product of the build is a shared library that you must configure PHP to load. -First, change to the ```php``` source subdirectory: +First, change to the `php` source subdirectory: $ cd php -Edit ```config/Make.rules``` and review the build settings. For example, you may want to enable ```OPTIMIZE```. If your PHP installation resides in a non-standard location, modify the ```PHP_HOME``` setting to contain the installation directory. If you are using PHP 5.3 or later and wish to use PHP namespaces, set ```USE_NAMESPACES=yes```. +Edit `config/Make.rules` and review the build settings. For example, you may want +to enable `OPTIMIZE`. If your PHP installation resides in a non-standard location, +modify the `PHP_HOME` setting to contain the installation directory. If you are +using PHP 5.3 or later and wish to use PHP namespaces, set `USE_NAMESPACES=yes`. -If you have not built Ice for C++ from the ```cpp``` subdirectory, then set the ```ICE_HOME``` environment variable to the directory containing your Ice installation. For example, if Ice is installed in ```/opt/Ice```, set ```ICE_HOME``` as follows: +If you have not built Ice for C++ from the `cpp` subdirectory, then set the +`ICE_HOME` environment variable to the directory containing your Ice installation. +For example, if Ice is installed in `/opt/Ice`, set `ICE_HOME` as follows: $ export ICE_HOME=/opt/Ice -If you installed Ice using RPM or DEB packages, set ```ICE_HOME``` as shown below: +If you installed Ice using RPM or DEB packages, set `ICE_HOME` as shown below: $ export ICE_HOME=/usr -Run ```make``` to build the extension. +Run `make` to build the extension. ## Installing the PHP Extension -To install the Ice extension, you must move the extension's shared library into PHP's extension directory. This directory is determined by the PHP configuration directive ```extension_dir```. You can determine the default value for this directive by running the command-line version of PHP with the ```-i``` option: +To install the Ice extension, you must move the extension's shared library into +PHP's extension directory. This directory is determined by the PHP configuration +directive `extension_dir`. You can determine the default value for this directive +by running the command-line version of PHP with the `-i` option: $ php -i @@ -42,7 +55,14 @@ Review the output for a line like this: extension_dir => /usr/lib/php/modules => /usr/lib/php/modules -Once you've copied the extension to PHP's extension directory, you will need to enable the extension in your PHP configuration. Your PHP installation likely supports the ```/etc/php.d``` configuration directory, which you can verify by examining the output of ```php -i``` and looking for the presence of ```--with-config-file-scan-dir``` in the "Configure Command" entry. If present, you can create a file in ```/etc/php.d``` that contains the directive to load the Ice extension. For example, create the file ```/etc/php.d/ice.ini``` containing the following line on Linux: +Once you've copied the extension to PHP's extension directory, you will need to +enable the extension in your PHP configuration. Your PHP installation likely +supports the `/etc/php.d` configuration directory, which you can verify by +examining the output of `php -i` and looking for the presence of +`--with-config-file-scan-dir` in the "Configure Command" entry. If present, +you can create a file in `/etc/php.d` that contains the directive to load the +Ice extension. For example, create the file `/etc/php.d/ice.ini` containing +the following line on Linux: extension = IcePHP.so @@ -50,7 +70,8 @@ Or on OS X: extension = IcePHP.dy -If PHP does not support the ```/etc/php.d``` directory, determine the path name of PHP's configuration file as reported by the ```php -i``` command: +If PHP does not support the `/etc/php.d` directory, determine the path name of +PHP's configuration file as reported by the `php -i` command: Configuration File (php.ini) Path => /etc/php.ini @@ -62,40 +83,64 @@ Or on OS X: extension = IcePHP.dy -You can verify that PHP is loading the Ice extension by running the command shown below: +You can verify that PHP is loading the Ice extension by running the command +shown below: $ php -m -Look for ```ice``` among the installed modules. Note that your library search path (```LD_LIBRARY_PATH``` on Linux or ```DYLD_LIBRARY_PATH``` on OS X) must include the directory containing the Ice shared libraries. +Look for `ice` among the installed modules. Note that your library search path +(`LD_LIBRARY_PATH` on Linux or `DYLD_LIBRARY_PATH` on OS X) must include the +directory containing the Ice shared libraries. -Read the PHP Dependencies and PHP Source Files sections below for more information about installing the Ice extension. +Read the PHP Dependencies and PHP Source Files sections below for more +information about installing the Ice extension. ## PHP Dependencies -PHP will need to be able to locate the libraries for the Ice run-time libraries and its third-party dependencies. These libraries are named as follows: +PHP will need to be able to locate the libraries for the Ice run-time libraries +and its third-party dependencies. These libraries are named as follows: libIce libIceUtil libSlice libbz2 -In general, these libraries must reside in a directory of the user's PATH. For Web servers, the libraries may need to reside in a system directory. For example, on Linux you can add the directory containing the Ice run-time libraries to ```/etc/ld.so.conf``` and run ```ldconfig```. +In general, these libraries must reside in a directory of the user's PATH. For +Web servers, the libraries may need to reside in a system directory. For example, +on Linux you can add the directory containing the Ice run-time libraries to +`/etc/ld.so.conf` and run `ldconfig`. -You can verify that the Ice extension is installed properly by examining the output of the ```php -m``` command, or by calling the ```phpInfo()``` function from a script. For example, you can create a file in the Web server's document directory containing the following PHP script: +You can verify that the Ice extension is installed properly by examining the +output of the `php -m` command, or by calling the `phpInfo()` function from a +script. For example, you can create a file in the Web server's document directory +containing the following PHP script: <?php phpInfo(); ?> -Then start a browser window and open the URL corresponding to this script. If the Ice extension is successfully installed, you will see an ```ice``` section among the configuration information. +Then start a browser window and open the URL corresponding to this script. If +the Ice extension is successfully installed, you will see an `ice` section among +the configuration information. -Note that if you want to use IceSSL from the Ice extension, then PHP will also need access to the shared libraries for IceSSL and OpenSSL. +Note that if you want to use IceSSL from the Ice extension, then PHP will also +need access to the shared libraries for IceSSL and OpenSSL. ## PHP Source Files -In addition to the binary Ice extension module and its library dependencies, you will also need to make the Ice for PHP source files available to your scripts. These files are located in the ```lib``` subdirectory and consist of the Ice run time definitions (```Ice.php``` or ```Ice_ns.php```) along with PHP source files generated from the Slice files included in the Ice distribution. +In addition to the binary Ice extension module and its library dependencies, you +will also need to make the Ice for PHP source files available to your scripts. +These files are located in the `lib` subdirectory and consist of the Ice run time +definitions (`Ice.php` or `Ice_ns.php`) along with PHP source files generated from +the Slice files included in the Ice distribution. -The Ice extension makes no assumptions about the location of these files, so you can install them anywhere you like. For example, you can simply include them in the same directory as your application scripts. Alternatively, if you prefer to install them in a common directory, you may need to modify PHP's ```include_path``` directive so that the PHP interpreter is able to locate these files. Another option is to modify the include path from within your script prior to including any Ice run-time file. Here is an example that assumes Ice is installed in ```/opt```: +The Ice extension makes no assumptions about the location of these files, so you +can install them anywhere you like. For example, you can simply include them in +the same directory as your application scripts. Alternatively, if you prefer to +install them in a common directory, you may need to modify PHP's `include_path` +directive so that the PHP interpreter is able to locate these files. Another +option is to modify the include path from within your script prior to including +any Ice run-time file. Here is an example that assumes Ice is installed in `/opt`: // PHP ini_set('include_path', @@ -104,38 +149,57 @@ The Ice extension makes no assumptions about the location of these files, so you ## Running the PHP Tests -The test subdirectory contains PHP implementations of the core Ice test suite. Python is required to run the test suite. +The test subdirectory contains PHP implementations of the core Ice test suite. +Python is required to run the test suite. -The test suites require that the Ice for C++ tests be built in the ```cpp``` subdirectory of this source distribution. In addition, the scripts require that the CLI version of the PHP interpreter be available in your PATH. +The test suites require that the Ice for C++ tests be built in the `cpp` +subdirectory of this source distribution. In addition, the scripts require +that the CLI version of the PHP interpreter be available in your PATH. After a successful build, you can run the tests as follows: $ python allTests.py -If everything worked out, you should see lots of ```ok``` messages. In case of a failure, the tests abort with ```failed```. +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. ## Web Server Permissions -The Web server normally runs in a special user account that may not necessarily have access to the Ice extension, its dependent libraries and PHP source files, and other resources such as Ice configuration and your application scripts. It is very important that you review the permissions of these files and verify that the Web server has sufficient access. +The Web server normally runs in a special user account that may not necessarily +have access to the Ice extension, its dependent libraries and PHP source files, +and other resources such as Ice configuration and your application scripts. It +is very important that you review the permissions of these files and verify +that the Web server has sufficient access. -On Linux, Apache typically runs in the ```apache``` account, so you will either need to change the owner or group of the libraries and other resources, or modify their permissions to make them sufficiently accessible. +On Linux, Apache typically runs in the `apache` account, so you will either +need to change the owner or group of the libraries and other resources, or +modify their permissions to make them sufficiently accessible. ## SELinux Notes for PHP -SELinux augments the traditional Unix permissions with a number of new features. In particular, SELinux can prevent the httpd daemon from opening network connections and reading files without the proper SELinux types. +SELinux augments the traditional Unix permissions with a number of new features. +In particular, SELinux can prevent the httpd daemon from opening network +connections and reading files without the proper SELinux types. -If you suspect that your Ice for PHP application does not work due to SELinux restrictions, we recommend that you first try it with SELinux disabled. As root, run: +If you suspect that your Ice for PHP application does not work due to SELinux +restrictions, we recommend that you first try it with SELinux disabled. +As root, run: # setenforce 0 to disable SELinux until the next reboot of your computer. -If you want to run httpd with Ice for PHP and SELinux enabled, there are two steps you need to take. First, allow httpd to open network connections: +If you want to run httpd with Ice for PHP and SELinux enabled, there are two +steps you need to take. First, allow httpd to open network connections: # setsebool httpd_can_network_connect=1 -Add the ```-P``` option to make this setting persistent across reboots. +Add the `-P` option to make this setting persistent across reboots. -Second, make sure any ```.ice``` file used by your PHP scripts can be read by httpd. The enclosing directory also needs to be accessible. For example: +Second, make sure any `.ice` file used by your PHP scripts can be read by httpd. +The enclosing directory also needs to be accessible. For example: # chcon -R -t httpd_sys_content_t /opt/MyApp/slice + +[1]: https://zeroc.com/download.html +[2]: https://zeroc.com/platforms_3_6_0.html diff --git a/php/BuildInstructionsWindows.md b/php/BuildInstructionsWindows.md index fd3701a3639..2ce2028f20a 100644 --- a/php/BuildInstructionsWindows.md +++ b/php/BuildInstructionsWindows.md @@ -1,35 +1,52 @@ # Building Ice for PHP on Windows -This page describes how to build and install Ice for PHP from source code on Windows. If you prefer, you can also download [binary distributions](https://zeroc.com/download.html) for the supported platforms. +This page describes how to build and install Ice for PHP from source code on +Windows. If you prefer, you can also download [binary distributions][1] for the +supported platforms. ## PHP Build Requirements ### Operating Systems and Compilers -Ice for PHP was extensively tested using the operating systems and compiler versions listed for our [supported platforms](https://zeroc.com/platforms_3_6_0.html). +Ice for PHP was extensively tested using the operating systems and compiler +versions listed for our [supported platforms][2]. ### Ice Development Kit -You will need the Ice development kit for C++, which you can install as a binary distribution or compile from source yourself. +You will need the Ice development kit for C++, which you can install as a binary +distribution or compile from source yourself. ## Building the PHP Extension -The Ice installer for Windows includes a pre-compiled extension for PHP 5.6 built with Visual Studio 2012 (Visual C++ 11) and compatible with the "Thread-safe VC11" distribution of PHP available on [php.net](). We encourage you to use this extension if possible, together with a compatible Web server. +The Ice installer for Windows includes a pre-compiled extension for PHP 5.6 built +with Visual Studio 2012 (Visual C++ 11) and compatible with the "Thread-safe VC11" +distribution of PHP available on [php.net](). We encourage you to use this +extension if possible, together with a compatible Web server. -> *The Apache binaries provided by the Apache Software Foundation are compiled with Visual C++ 6 and therefore are not compatible with the Ice for PHP extension included in our Windows installer. A VC11 build of Apache is available from alternate sources.* +> *The Apache binaries provided by the Apache Software Foundation are compiled with +Visual C++ 6 and therefore are not compatible with the Ice for PHP extension included +in our Windows installer. A VC11 build of Apache is available from alternate sources.* -The most common motivation for compiling the Ice extension yourself is to create an extension that is compatible with your existing environment, such as when your Web server or PHP interpreter is built with a different compiler. +The most common motivation for compiling the Ice extension yourself is to create an +extension that is compatible with your existing environment, such as when your Web +server or PHP interpreter is built with a different compiler. -To build the Ice extension, first download the PHP5 binary archive or Windows installer and install the distribution. +To build the Ice extension, first download the PHP5 binary archive or Windows installer +and install the distribution. -You will also need to download and extract the PHP5 sources (Ice for PHP requires the PHP header files). Change to the PHP5 source directory and run the following commands: +You will also need to download and extract the PHP5 sources (Ice for PHP requires +the PHP header files). Change to the PHP5 source directory and run the following +commands: > buildconf > configure -You do not need to actually build PHP from source, but these two steps are necessary to generate header files that are required by the Ice extension. +You do not need to actually build PHP from source, but these two steps are +necessary to generate header files that are required by the Ice extension. -If you have not built Ice for C++ from the ```cpp``` subdirectory then you need to set the ```ICE_HOME``` environment variable to the location of your Ice for C++ installation. For example: +If you have not built Ice for C++ from the `cpp` subdirectory then you need to +set the `ICE_HOME` environment variable to the location of your Ice for C++ +installation. For example: > set ICE_HOME=C:\Ice @@ -37,17 +54,27 @@ Change to the Ice for PHP source directory: > cd php -Open ```config\Make.rules.mak.php```, review the comments, and make any necessary changes. In particular, you may need to change the values of ```PHP_HOME``` and ```PHP_BIN_HOME``` to refer to your PHP source and binary installations, respectively. If you compiled PHP from source, you should also review the setting of ```PHP_LIBDIR```. If you are using PHP 5.3 or later and wish to use PHP namespaces, set ```USE_NAMESPACES=yes```. Finally, if you are using a non-thread-safe PHP installation, set ```PHP_ZTS=no```. +Open `config\Make.rules.mak.php`, review the comments, and make any necessary +changes. In particular, you may need to change the values of `PHP_HOME` and +`PHP_BIN_HOME` to refer to your PHP source and binary installations, respectively. +If you compiled PHP from source, you should also review the setting of +`PHP_LIBDIR`. If you are using PHP 5.3 or later and wish to use PHP namespaces, +set `USE_NAMESPACES=yes`. Finally, if you are using a non-thread-safe PHP +installation, set `PHP_ZTS=no`. Run NMAKE to build the extension: > nmake /f Makefile.mak -Upon successful completion, the Ice for PHP extension is created as ```lib\php_ice.dll``` (Release) or ```lib\php_iced.dll``` (Debug). +Upon successful completion, the Ice for PHP extension is created as `lib\php_ice.dll` +(Release) or `lib\php_iced.dll` (Debug). ## Installing the PHP Extension -To install the Ice extension, you must move the extension's shared library into PHP's extension directory. This directory is determined by the PHP configuration directive ```extension_dir```. You can determine the default value for this directive by running the command-line version of PHP with the ```-i``` option: +To install the Ice extension, you must move the extension's shared library into PHP's +extension directory. This directory is determined by the PHP configuration directive +`extension_dir`. You can determine the default value for this directive by running +the command-line version of PHP with the `-i` option: > php -i @@ -59,53 +86,86 @@ The directive may also be set to a relative path, such as: extension_dir => ./ => ./ -In the case of a relative path, the value is relative to the current working directory of the process. As a result, the working directory when running the command-line version of PHP will likely differ from the working directory when PHP is running as a Web server module. Using a typical installation of Apache as an example, the working directory is Apache's installation directory, therefore the extension must be copied to +In the case of a relative path, the value is relative to the current working +directory of the process. As a result, the working directory when running the +command-line version of PHP will likely differ from the working directory when +PHP is running as a Web server module. Using a typical installation of Apache +as an example, the working directory is Apache's installation directory, +therefore the extension must be copied to \Program Files\Apache Software Foundation\Apache2.2 -Once you've copied the extension to the appropriate directory, you will need to enable the extension in your PHP configuration. First you must discover the location of PHP's configuration file (```php.ini```), which is also displayed by the ```-i``` option. Look for the following line: +Once you've copied the extension to the appropriate directory, you will need +to enable the extension in your PHP configuration. First you must discover the +location of PHP's configuration file (`php.ini`), which is also displayed by +the `-i` option. Look for the following line: Loaded Configuration File => C:\Program Files\PHP\php.ini -If you used the Windows installer for PHP, your Web server's configuration may have already been modified to load PHP. You can also review your Web server's settings to discover the location of ```php.ini```. For example, PHP's Windows installer modifies Apache's configuration to add the following directives: +If you used the Windows installer for PHP, your Web server's configuration may +have already been modified to load PHP. You can also review your Web server's +settings to discover the location of `php.ini`. For example, PHP's Windows +installer modifies Apache's configuration to add the following directives: PHPIniDir "C:/Program Files/PHP/" LoadModule php5_module "C:/Program Files/PHP/php5apache2_2.dll" -The ```PHPIniDir``` directive specifies the directory containing the ```php.ini``` file. +The `PHPIniDir` directive specifies the directory containing the `php.ini` file. -Open ```php.ini``` and append this directive: +Open `php.ini` and append this directive: extension = php_ice.dll -Read the PHP Dependencies and PHP Source Files sections below for more information about installing the Ice extension. +Read the PHP Dependencies and PHP Source Files sections below for more +information about installing the Ice extension. ## PHP Dependencies -PHP will need to be able to locate the libraries for the Ice run-time libraries and its third-party dependencies. On Windows, these DLLs are required: +PHP will need to be able to locate the libraries for the Ice run-time libraries +and its third-party dependencies. On Windows, these DLLs are required: ice36.dll iceutil36.dll slice36.dll bzip2.dll -In general, these libraries must reside in a directory of the user's PATH. For Web servers, the libraries may need to reside in a system directory. For example, on Windows you can copy the DLLs to the ```C:\WINDOWS\system32``` directory, or to the Apache installation directory. +In general, these libraries must reside in a directory of the user's PATH. For +Web servers, the libraries may need to reside in a system directory. For example, +on Windows you can copy the DLLs to the `C:\WINDOWS\system32` directory, or to +the Apache installation directory. -You can verify that the Ice extension is installed properly by examining the output of the ```php -m``` command, or by calling the ```phpInfo()``` function from a script. For example, you can create a file in the Web server's document directory containing the following PHP script: +You can verify that the Ice extension is installed properly by examining the +output of the `php -m` command, or by calling the `phpInfo()` function from a +script. For example, you can create a file in the Web server's document +directory containing the following PHP script: <?php phpInfo(); ?> -Then start a browser window and open the URL corresponding to this script. If the Ice extension is successfully installed, you will see an ```ice``` section among the configuration information. +Then start a browser window and open the URL corresponding to this script. If +the Ice extension is successfully installed, you will see an `ice` section +among the configuration information. -Note that if you want to use IceSSL from the Ice extension, then PHP will also need access to the shared libraries for IceSSL and OpenSSL. +Note that if you want to use IceSSL from the Ice extension, then PHP will also +need access to the shared libraries for IceSSL and OpenSSL. ## PHP Source Files -In addition to the binary Ice extension module and its library dependencies, you will also need to make the Ice for PHP source files available to your scripts. These files are located in the ```lib``` subdirectory and consist of the Ice run time definitions (```Ice.php``` or ```Ice_ns.php```) along with PHP source files generated from the Slice files included in the Ice distribution. - -The Ice extension makes no assumptions about the location of these files, so you can install them anywhere you like. For example, you can simply include them in the same directory as your application scripts. Alternatively, if you prefer to install them in a common directory, you may need to modify PHP's ```include_path``` directive so that the PHP interpreter is able to locate these files. Another option is to modify the include path from within your script prior to including any Ice run-time file. Here is an example that assumes Ice is installed in ```C:\IcePHP```: +In addition to the binary Ice extension module and its library dependencies, +you will also need to make the Ice for PHP source files available to your +scripts. These files are located in the `lib` subdirectory and consist of the +Ice run time definitions (`Ice.php` or `Ice_ns.php`) along with PHP source +files generated from the Slice files included in the Ice distribution. + +The Ice extension makes no assumptions about the location of these files, so +you can install them anywhere you like. For example, you can simply include +them in the same directory as your application scripts. Alternatively, if you +prefer to install them in a common directory, you may need to modify PHP's +`include_path` directive so that the PHP interpreter is able to locate these +files. Another option is to modify the include path from within your script +prior to including any Ice run-time file. Here is an example that assumes +Ice is installed in `C:\IcePHP`: // PHP ini_set('include_path', @@ -114,23 +174,39 @@ The Ice extension makes no assumptions about the location of these files, so you ## Running the PHP Tests -The test subdirectory contains PHP implementations of the core Ice test suite. Python is required to run the test suite. +The test subdirectory contains PHP implementations of the core Ice test suite. +Python is required to run the test suite. -The test suites require that the Ice for C++ tests be built in the ```cpp``` subdirectory of this source distribution. In addition, the scripts require that the CLI version of the PHP interpreter be available in your PATH. +The test suites require that the Ice for C++ tests be built in the `cpp` +subdirectory of this source distribution. In addition, the scripts require +that the CLI version of the PHP interpreter be available in your PATH. After a successful build, you can run the tests as follows: $ python allTests.py -If everything worked out, you should see lots of ```ok``` messages. In case of a failure, the tests abort with ```failed```. +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. ## Web Server Permissions -The Web server normally runs in a special user account that may not necessarily have access to the Ice extension, its dependent libraries and PHP source files, and other resources such as Ice configuration and your application scripts. It is very important that you review the permissions of these files and verify that the Web server has sufficient access. +The Web server normally runs in a special user account that may not necessarily +have access to the Ice extension, its dependent libraries and PHP source files, +and other resources such as Ice configuration and your application scripts. It +is very important that you review the permissions of these files and verify +that the Web server has sufficient access. -For example, on Windows the Apache server typically runs as a service in the "Local System" account. You will need to modify the access rights of the aforementioned files to grant access to this account. In a command window, you can use the ```cacls``` utility to establish the appropriate access rights. Assuming that you have copied the Ice extension and dependent DLLs to Apache's installation directory, you can modify the access rights as shown below: +For example, on Windows the Apache server typically runs as a service in the +"Local System" account. You will need to modify the access rights of the +aforementioned files to grant access to this account. In a command window, +you can use the `cacls` utility to establish the appropriate access rights. +Assuming that you have copied the Ice extension and dependent DLLs to Apache's +installation directory, you can modify the access rights as shown below: cd \Program Files\Apache Software Foundation\Apache2.2 cacls php_ice.dll /G SYSTEM:F Administrators:F cacls bzip2.dll /G SYSTEM:F Administrators:F ... + +[1]: https://zeroc.com/download.html +[2]: https://zeroc.com/platforms_3_6_0.html diff --git a/python/BuildInstructionsLinuxOSX.md b/python/BuildInstructionsLinuxOSX.md index a97305800ad..4f0975e45fd 100644 --- a/python/BuildInstructionsLinuxOSX.md +++ b/python/BuildInstructionsLinuxOSX.md @@ -1,20 +1,27 @@ # Building Ice for Python on Linux and OS X -This page describes how to build and install Ice for Python from source code on Linux and OS X. If you prefer, you can also download [binary distributions](https://zeroc.com/download.html) for the supported platforms. +This page describes how to build and install Ice for Python from source code on +Linux and OS X. If you prefer, you can also download [binary distributions][1] +for the supported platforms. ## Python Build Requirements ### Operating Systems and Compilers -Ice for Python is expected to build and run properly on OS X and any recent Linux distribution for x86 and x86_64, and was extensively tested using the operating systems and compiler versions listed for our [supported platforms](https://zeroc.com/platforms_3_6_0.html). +Ice for Python is expected to build and run properly on OS X and any recent Linux +distribution for x86 and x86_64, and was extensively tested using the operating +systems and compiler versions listed for our [supported platforms][2]. ### Python Versions -Ice for Python supports Python versions 2.6, 2.7, 3.3 or 3.4. Note however that your Python installation must have been built with a C++ compiler that is compatible with the one used to build Ice for C++. +Ice for Python supports Python versions 2.6, 2.7, 3.3 or 3.4. Note however that +your Python installation must have been built with a C++ compiler that is +compatible with the one used to build Ice for C++. ### Ice Development Kit -You will need the Ice development kit for C++, which you can install as a binary distribution or compile from source yourself. +You will need the Ice development kit for C++, which you can install as a binary +distribution or compile from source yourself. ## Building the Python Extension @@ -22,21 +29,27 @@ Change to the Ice for Python source subdirectory: $ cd python -If you have not built Ice for C++ in the ```cpp``` subdirectory, set ```ICE_HOME``` to the directory of your Ice for C++ installation. For example: +If you have not built Ice for C++ in the `cpp` subdirectory, set `ICE_HOME` to +the directory of your Ice for C++ installation. For example: $ export ICE_HOME=/opt/Ice -Edit ```config/Make.rules```, modify the installation prefix (if necessary), and review the comments describing the ```PYTHON_VERSION``` variable. +Edit `config/Make.rules`, modify the installation prefix (if necessary), and +review the comments describing the `PYTHON_VERSION` variable. -Execute ```python -V``` to verify that the correct Python interpreter is in your executable search path. +Execute `python -V` to verify that the correct Python interpreter is in your +executable search path. -Run ```make``` to build the extension. +Run `make` to build the extension. -Upon successful completion, run ```make install```. You may need additional user privileges to install in the directory specified by ```config/Make.rules```. +Upon successful completion, run `make install`. You may need additional user +privileges to install in the directory specified by `config/Make.rules`. ## Configuring your Environment for Python -Modify your ```PYTHONPATH``` environment variable to include the Ice extension for Python. For example, assuming you installed the extension in the directory ```/opt/Ice```, you would modify your environment as shown below: +Modify your `PYTHONPATH` environment variable to include the Ice extension +for Python. For example, assuming you installed the extension in the directory +`/opt/Ice`, you would modify your environment as shown below: $ export PYTHONPATH=/opt/Ice/python:$PYTHONPATH @@ -46,4 +59,8 @@ After a successful build, you can run the tests as follows: $ python allTests.py -If everything worked out, you should see lots of ```ok``` messages. In case of a failure, the tests abort with ```failed```. +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. + +[1]: https://zeroc.com/download.html +[2]: https://zeroc.com/platforms_3_6_0.html diff --git a/python/BuildInstructionsWindows.md b/python/BuildInstructionsWindows.md index 98097174fad..3ab291aff50 100644 --- a/python/BuildInstructionsWindows.md +++ b/python/BuildInstructionsWindows.md @@ -1,48 +1,72 @@ # Building Ice for Python on Windows -This page describes how to build and install Ice for Python from source code on Windows. If you prefer, you can also download [binary distributions](https://zeroc.com/download.html) for the supported platforms. +This document describes how to build and install Ice for Python from source code on +Windows. If you prefer, you can also download [binary distributions][1] for the +supported platforms. ## Python Build Requirements ### Operating Systems and Compilers -Ice for Python is expected to build and run properly on Windows and was extensively tested using the operating systems and compiler versions listed for our [supported platforms](https://zeroc.com/platforms_3_6_0.html). +Ice for Python is expected to build and run properly on Windows and was extensively +tested using the operating systems and compiler versions listed for our [supported +platforms][2]. ### Python Versions -Ice for Python supports Python versions 2.6, 2.7, 3.3 or 3.4. Note however that your Python installation must have been built with a C++ compiler that is compatible with the one used to build Ice for C++. +Ice for Python supports Python versions 2.6, 2.7, 3.3 or 3.4. Note however that your +Python installation must have been built with a C++ compiler that is compatible with +the one used to build Ice for C++. ### Ice Development Kit -You will need the Ice development kit for C++, which you can install as a binary distribution or compile from source yourself. +You will need the Ice development kit for C++, which you can install as a binary +distribution or compile from source yourself. ## Building the Python Extension -The Python interpreter is readily available on Windows platforms. You can build it yourself using Microsoft Visual C++, or obtain a binary distribution from the Python web site. The Python 3.4.x binary distribution is compiled with Visual C++ 10, and you should use this binary distribution if you want to compile the Ice extension with Visual C++ 10. +The Python interpreter is readily available on Windows platforms. You can build +it yourself using Microsoft Visual C++, or obtain a binary distribution from the +Python web site. The Python 3.4.x binary distribution is compiled with Visual +C++ 10, and you should use this binary distribution if you want to compile the +Ice extension with Visual C++ 10. -Open a command prompt that supports command-line compilation with Visual C++. For example, you can execute the Visual C++ batch file ```vcvars32.bat``` to configure your environment. Alternatively, you can start a Visual Studio Command Prompt by selecting the appropriate entry from the Visual Studio program group in your Start menu. +Open a command prompt that supports command-line compilation with Visual C++. +For example, you can execute the Visual C++ batch file `vcvars32.bat` to +configure your environment. Alternatively, you can start a Visual Studio Command +Prompt by selecting the appropriate entry from the Visual Studio program group +in your Start menu. Change to the Ice for Python source subdirectory: > cd python -If you have not built Ice for C++ from the ```cpp``` subdirectory, set ```ICE_HOME``` to the directory of your Ice for C++ installation. For example: +If you have not built Ice for C++ from the `cpp` subdirectory, set `ICE_HOME` +to the directory of your Ice for C++ installation. For example: > set ICE_HOME=C:\Ice -Edit ```config\Make.rules.mak``` and review the settings. In particular you must set ```CPP_COMPILER``` to the appropriate compiler. +Edit `config\Make.rules.mak` and review the settings. In particular you must set +`CPP_COMPILER` to the appropriate compiler. Run nmake: > nmake /f Makefile.mak -Upon completion, the Ice extension is created as ```python\IcePy.pyd```. +Upon completion, the Ice extension is created as `python\IcePy.pyd`. -> *Normally you should build with ```OPTIMIZE=yes```. If you wish to build a debug version of the Ice extension, set ```OPTIMIZE=no```. In this case, you will also need to build a debug version of the Python interpreter from sources.* +> *Normally you should build with `OPTIMIZE=yes`. If you wish to build a debug +version of the Ice extension, set `OPTIMIZE=no`. In this case, you will also +need to build a debug version of the Python interpreter from sources.* ## Configuring your Environment for Python -Modify your environment to allow Python to find the Ice extension for Python. The interpreter must be able to locate the extension DLL as well as the Python source files in the ```python``` subdirectory. This is normally accomplished by setting the ```PYTHONPATH``` environment variable to contain the necessary subdirectory. For example, if the Ice for Python extension is installed in ```C:\Ice```, you could configure your environment as follows: +Modify your environment to allow Python to find the Ice extension for Python. +The interpreter must be able to locate the extension DLL as well as the Python +source files in the `python` subdirectory. This is normally accomplished by +setting the `PYTHONPATH` environment variable to contain the necessary +subdirectory. For example, if the Ice for Python extension is installed in +`C:\Ice`, you could configure your environment as follows: > set PYTHONPATH=C:\Ice\python @@ -52,4 +76,8 @@ After a successful build, you can run the tests as follows: $ python allTests.py -If everything worked out, you should see lots of ```ok``` messages. In case of a failure, the tests abort with ```failed```. +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. + +[1]: https://zeroc.com/download.html +[2]: https://zeroc.com/platforms_3_6_0.html diff --git a/ruby/BuildInstructionsLinux.md b/ruby/BuildInstructionsLinux.md index e13d5dda574..4bca4b13ab6 100644 --- a/ruby/BuildInstructionsLinux.md +++ b/ruby/BuildInstructionsLinux.md @@ -1,16 +1,22 @@ # Building Ice for Ruby on Linux -This page describes how to build and install Ice for Ruby from source code. If you prefer, you can also download [binary distributions](https://zeroc.com/download.html) for the supported platforms. +This document describes how to build and install Ice for Ruby from source code. +If you prefer, you can also download [binary distributions][1] for the supported +platforms. ## Ruby Build Requirements ### Operating Systems and Compilers -Ice for Ruby is expected to build and run properly on any recent Linux distribution for x86 and x86_64, and was extensively tested using the operating systems and Ruby versions listed for our [supported platforms](https://zeroc.com/platforms_3_6_0.html). +Ice for Ruby is expected to build and run properly on any recent Linux distribution +for x86 and x86_64, and was extensively tested using the operating systems and Ruby +versions listed for our [supported platforms][2]. ### Ruby Versions -Ice for Ruby supports Ruby versions 1.8.1 or later. You can use a source or binary installation of Ruby. If you use an RPM installation, the following packages are required: +Ice for Ruby supports Ruby versions 1.8.1 or later. You can use a source or binary +installation of Ruby. If you use an RPM installation, the following packages are +required: ruby ruby-devel @@ -18,17 +24,21 @@ Ice for Ruby supports Ruby versions 1.8.1 or later. You can use a source or bina ### Ice Development Kit -You will need the Ice development kit for C++, which you can install as a binary distribution or compile from source yourself. +You will need the Ice development kit for C++, which you can install as a binary +distribution or compile from source yourself. ## Building the Ruby Extension -The instructions for compiling the Ice extension assume that you have already installed Ruby. +The instructions for compiling the Ice extension assume that you have already +installed Ruby. -If you installed Ruby in a non-standard location, set the ```RUBY_HOME``` environment variable to the installation directory. For example: +If you installed Ruby in a non-standard location, set the `RUBY_HOME` environment +variable to the installation directory. For example: $ export RUBY_HOME=/opt/ruby -If you have not built Ice for C++ in the ```cpp``` subdirectory, set ```ICE_HOME``` to the directory of your Ice for C++ installation. For example: +If you have not built Ice for C++ in the `cpp` subdirectory, set `ICE_HOME` +to the directory of your Ice for C++ installation. For example: $ export ICE_HOME=/opt/Ice @@ -36,9 +46,10 @@ Change to the Ice for Ruby source subdirectory: $ cd ruby -Edit ```config/Make.rules```and adjust as necessary. For example, you may wish to enable ```OPTIMIZE```. +Edit `config/Make.rules`and adjust as necessary. For example, you may wish to +enable `OPTIMIZE`. -Run ```make``` to build the extension. +Run `make` to build the extension. ## Installing Ice for Ruby @@ -46,9 +57,16 @@ You can perform an automated installation with the following command: $ make install -This process uses the ```prefix``` variable in ```config/Make.rules``` as the installation's root directory. The subdirectory ```<prefix>/ruby``` is created as a copy of the local ```ruby``` directory and contains the Ice for Ruby extension library (```IceRuby.so```) as well as Ruby source code. Using this installation method requires that you modify your environment as described in *Using Ice for Ruby* below. +This process uses the `prefix` variable in `config/Make.rules` as the +installation's root directory. The subdirectory `<prefix>/ruby` is created +as a copy of the local `ruby` directory and contains the Ice for Ruby +extension library (`IceRuby.so`) as well as Ruby source code. Using this +installation method requires that you modify your environment as described +in *Using Ice for Ruby* below. -Another option is to copy the contents of the local ```ruby``` directory to your Ruby installation's ```site_ruby``` directory. For example, if you installed Ruby via RPM, you can use the steps below: +Another option is to copy the contents of the local `ruby` directory to your +Ruby installation's `site_ruby` directory. For example, if you installed Ruby +via RPM, you can use the steps below: # cd <Ice source directory>/ruby/ruby # sudo tar cf - * | (cd /usr/lib/ruby/site_ruby/1.8/i386-linux; tar xvf -) @@ -61,17 +79,21 @@ There is no need to modify your environment if you use this approach. ## Configuring your Environment for Ruby -The Ruby interpreter must be able to locate the Ice extension. If you used the automated installation described above, you need to define the ```RUBYLIB``` environment variable as follows: +The Ruby interpreter must be able to locate the Ice extension. If you used the +automated installation described above, you need to define the `RUBYLIB` +environment variable as follows: $ export RUBYLIB=/opt/Ice/ruby:$RUBYLIB -This example assumes that your Ice for Ruby installation is located in the ```/opt/Ice``` directory. +This example assumes that your Ice for Ruby installation is located in the +`/opt/Ice` directory. -You must also modify ```LD_LIBRARY_PATH``` to include the directory ```/opt/Ice/lib```: +You must also modify `LD_LIBRARY_PATH` to include the directory `/opt/Ice/lib`: $ export LD_LIBRARY_PATH=/opt/Ice/lib:$LD_LIBRARY_PATH -To verify that Ruby can load the Ice extension successfully, open a command window and start the interpreter using ```irb```: +To verify that Ruby can load the Ice extension successfully, open a command +window and start the interpreter using `irb`: > irb irb(main):001:0> @@ -80,41 +102,50 @@ At the prompt, enter require "Ice" -If the interpreter responds with the value true, the Ice extension was loaded successfully. Enter ```exit``` to quit the interpreter. +If the interpreter responds with the value true, the Ice extension was loaded +successfully. Enter `exit` to quit the interpreter. ## Running the Ruby Tests -The ```test``` subdirectory contains Ruby implementations of the core Ice test suite. Python is required to run the test suite. +The `test` subdirectory contains Ruby implementations of the core Ice test suite. +Python is required to run the test suite. -The test suites require that the Ice for C++ tests be built in the ```cpp``` subdirectory of this source distribution. +The test suites require that the Ice for C++ tests be built in the `cpp` +subdirectory of this source distribution. -Open a command window and change to the top-level directory. At the command prompt, execute: +Open a command window and change to the top-level directory. At the command +prompt, execute: > python allTests.py -You can also run tests individually by changing to the test directory and running this command: +You can also run tests individually by changing to the test directory and +running this command: > python run.py -If everything worked out, you should see lots of ```ok``` messages. In case of a failure, the tests abort with ```failed```. +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. ## SELinux Notes for Ruby -If SELinux is enabled on your RHEL system, you may encounter this error message when Ruby attempts to load the Ice extension: +If SELinux is enabled on your RHEL system, you may encounter this error message +when Ruby attempts to load the Ice extension: cannot restore segment prot after reloc: Permission denied There are two ways to solve this problem: -- Change the default security context for the Ice extension using the following command: +- Change the default security context for the Ice extension using the following +command: - ``` - $ chcon -t texrel_shlib_t /opt/Ice/ruby/IceRuby.so - ``` + $ chcon -t texrel_shlib_t /opt/Ice/ruby/IceRuby.so - Replace ```/opt/Ice``` with your installation directory. -- Disable SELinux completely by adding the following line to your ```/etc/sysconfig/selinux``` file: + Replace `/opt/Ice` with your installation directory. - ``` - SELINUX=disabled - ``` +- Disable SELinux completely by adding the following line to your +`/etc/sysconfig/selinux` file: + + SELINUX=disabled + +[1]: https://zeroc.com/download.html +[2]: https://zeroc.com/platforms_3_6_0.html diff --git a/ruby/BuildInstructionsWindows.md b/ruby/BuildInstructionsWindows.md index ce2a5a82f59..4d985134a84 100644 --- a/ruby/BuildInstructionsWindows.md +++ b/ruby/BuildInstructionsWindows.md @@ -1,12 +1,16 @@ # Building Ice for Ruby on Windows -This page describes how to build and install Ice for Ruby from source code. If you prefer, you can also download [binary distributions](https://zeroc.com/download.html) for the supported platforms. +This page describes how to build and install Ice for Ruby from source code. +If you prefer, you can also download [binary distributions][1] for the +supported platforms. ## Ruby Build Requirements ### Operating Systems -Ice for Ruby is expected to build and run properly on Windows, and was extensively tested using the operating systems and Ruby versions listed for our [supported platforms](https://zeroc.com/platforms_3_6_0.html). +Ice for Ruby is expected to build and run properly on Windows, and was extensively +tested using the operating systems and Ruby versions listed for our [supported +platforms][2]. ### Prerequisites @@ -17,16 +21,21 @@ To build Ice for Ruby you must have the following: - Ruby Development Kit 4.7.2 - mingw 4.7.3 (only for 32-bit builds) -The Ruby distribution for Windows uses the MinGW compiler, therefore MinGW is the only C++ compiler supported by Ice for Ruby. +The Ruby distribution for Windows uses the MinGW compiler, therefore MinGW is the +only C++ compiler supported by Ice for Ruby. -The instructions in this file make the following assumptions about your build environment: +The instructions in this file make the following assumptions about your build +environment: -1. You have installed the Ice 3.6.0 distribution using the ZeroC installer. The default installation directory is ```C:\Program Files (x86)\ZeroC\Ice-3.6.0```. -1. You have installed Ruby 2.2.1 using the Windows installer. The default installation directory is ```C:\Ruby221```. -1. You have installed the Ruby Development Kit 4.7.2 in ```C:\RubyDevKit-4.7.2```. -1. For 32-bit builds, you have installed mingw 4.7.3 in ```C:\mingw-4.7.3```. +1. You have installed the Ice 3.6.0 distribution using the ZeroC installer. The +default installation directory is `C:\Program Files (x86)\ZeroC\Ice-3.6.0`. +2. You have installed Ruby 2.2.1 using the Windows installer. The default installation +directory is `C:\Ruby221`. +3. You have installed the Ruby Development Kit 4.7.2 in `C:\RubyDevKit-4.7.2`. +4. For 32-bit builds, you have installed mingw 4.7.3 in `C:\mingw-4.7.3`. -If you selected different installation directories, you will need to modify the relevant path names in the steps below to match your configuration. +If you selected different installation directories, you will need to modify the +relevant path names in the steps below to match your configuration. ## Building the Ruby Extension @@ -34,34 +43,36 @@ Open a Windows command prompt and add Ruby to your environment: > C:\Ruby221\bin\setrbvars.bat -Run the ```devkitvars.bat``` batch file from the Ruby development kit to setup your environment: +Run the `devkitvars.bat` batch file from the Ruby development kit to setup your +environment: > C:\RubyDevKit-4.7.2\devkitvars.bat If you are building for Windows 32-bit: -1. Add mingw 4.7.3 to your PATH, before the mingw 4.7.2 included in the Ruby development kit: +1. Add mingw 4.7.3 to your PATH, before the mingw 4.7.2 included in the Ruby +development kit: - ``` - > set PATH=C:\mingw-4.7.3\bin;%PATH% - ``` + > set PATH=C:\mingw-4.7.3\bin;%PATH% 1. Then double-check the desired version of g++ is in your PATH: - ``` - > g++ -dumpversion - 4.7.3 - ``` + > g++ -dumpversion + 4.7.3 Change to the Ice for Ruby source directory: > cd ruby -If you have not built Ice for C++ in the ```cpp``` subdirectory, set the ```ICE_HOME``` environment variable to point to your Ice installation. This path must contain forward slashes (/) as directory separators, and cannot contain any space. If your Ice installation's path contains any space, use the DOS 8-character name as a work-around, for example: +If you have not built Ice for C++ in the `cpp` subdirectory, set the `ICE_HOME` +environment variable to point to your Ice installation. This path must contain +forward slashes (/) as directory separators, and cannot contain any space. +If your Ice installation's path contains any space, use the DOS 8-character +name as a work-around, for example: > set ICE_HOME=C:/PROGRA~2/Ice-3.6.0 -You can use ```dir /x``` to get this DOS name, for example: +You can use `dir /x` to get this DOS name, for example: > cd c:\ > dir /x @@ -82,17 +93,24 @@ You can perform an automated installation with the following command: > make install -This process uses the ```prefix``` variable in ```config\Make.rules``` as the installation's root directory. The subdirectory ```<prefix>\ruby``` is created as a copy of the local ruby directory and contains the Ice for Ruby extension library (```IceRuby.so```) as well as Ruby source code. Using this installation method requires that you modify your environment as described below. +This process uses the `prefix` variable in `config\Make.rules` as the installation's +root directory. The subdirectory `<prefix>\ruby` is created as a copy of the local +ruby directory and contains the Ice for Ruby extension library (`IceRuby.so`) as +well as Ruby source code. Using this installation method requires that you modify +your environment as described below. ## Configuring your Environment for Ruby -The Ruby interpreter must be able to locate the Ice extension. One way to configure the interpreter is to define the ```RUBYLIB``` environment variable as follows: +The Ruby interpreter must be able to locate the Ice extension. One way to configure +the interpreter is to define the `RUBYLIB` environment variable as follows: > set RUBYLIB=C:\Ice-3.6.0\ruby -This example assumes your Ice for Ruby installation is located in the ```C:\Ice-3.6.0``` directory. +This example assumes your Ice for Ruby installation is located in the `C:\Ice-3.6.0` +directory. -In addition, you must modify your PATH environment variable to include the following directories: +In addition, you must modify your PATH environment variable to include the following +directories: C:\Program Files (x86)\ZeroC\Ice-3.6.0\bin C:\Ice-3.6.0\bin @@ -103,16 +121,24 @@ At a command prompt, you can set your PATH as shown below: ## Running the Ruby Tests -The ```test``` subdirectory contains Ruby implementations of the core Ice test suite. Python is required to run the test suite. +The `test` subdirectory contains Ruby implementations of the core Ice test suite. +Python is required to run the test suite. -The test suites require that the Ice for C++ tests be built in the ```cpp``` subdirectory of this source distribution. +The test suites require that the Ice for C++ tests be built in the `cpp` +subdirectory of this source distribution. -Open a command window and change to the top-level directory. At the command prompt, execute: +Open a command window and change to the top-level directory. At the command +prompt, execute: > python allTests.py -You can also run tests individually by changing to the test directory and running this command: +You can also run tests individually by changing to the test directory and +running this command: > python run.py -If everything worked out, you should see lots of ```ok``` messages. In case of a failure, the tests abort with ```failed```. +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. + +[1]: https://zeroc.com/download.html +[2]: https://zeroc.com/platforms_3_6_0.html |