diff --git a/README.md b/README.md index 6be10c96c8e..d03f7f86372 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ or retrying failed connection attempts (to name just a few of dozens of such low Remote procedure calls ([RPCs][rpcs]) are at the heart of the Ice framework. You create RPCs with an easy 2-step process: + 1. Define the contract between your client and your server with the [Slice][slice] language—Ice's [IDL][idl]. 2. Run the Slice compiler on these Slice definitions to generate stubs in the programming language(s) of your choice. @@ -85,7 +86,7 @@ languages. ## Building Ice from source -[C++](cpp/BUILDING.md) | [C#](csharp/BUILDING.md) | [Java](java/BUILDING.md) | [Java Compat](java-compat/BUILDING.md) | [JavaScript/TypeScript](js) | [MATLAB](matlab) | [Objective-C](objective-c) | [PHP](php) | [Python](python) | [Ruby](ruby) | [Swift](swift) +[C++](cpp/BUILDING.md) | [C#](csharp/BUILDING.md) | [Java](java/BUILDING.md) | [Java Compat](java-compat/BUILDING.md) | [JavaScript/TypeScript](js/BUILDING.md) | [MATLAB](matlab/BUILDING.md) | [Objective-C](objective-c/BUILDING.md) | [PHP](php/BUILDING.md) | [Python](python/BUILDING.md) | [Ruby](ruby/BUILDING.md) | [Swift](swift/BUILDING.md) ## Copyright and license diff --git a/cpp/README.md b/cpp/README.md index 048641540de..75ce7dd7609 100644 --- a/cpp/README.md +++ b/cpp/README.md @@ -2,7 +2,8 @@ [Getting started C++11] | [Examples C++11] | [Getting started C++98] | [Examples C++98] | [NuGet packages] | [Documentation] | [Building from source] -The [Ice framework] provides everything you need to build networked applications, including RPC, pub/sub, server deployment, and more. +The [Ice framework] provides everything you need to build networked applications, +including RPC, pub/sub, server deployment, and more. Ice for C++ is the C++ implementation of Ice. diff --git a/csharp/README.md b/csharp/README.md index 30996bab6eb..a648cc51faa 100644 --- a/csharp/README.md +++ b/csharp/README.md @@ -4,7 +4,7 @@ The [Ice framework] provides everything you need to build networked applications, including RPC, pub/sub, server deployment, and more. -Ice for .NET is the C# / .NET implementation of Ice. +Ice for .NET is the C# / .NET implementation of the Ice framework. ## Sample Code diff --git a/js/BUILDING.md b/js/BUILDING.md new file mode 100644 index 00000000000..474c7f0322d --- /dev/null +++ b/js/BUILDING.md @@ -0,0 +1,220 @@ +# Ice for JavaScript Build Instructions + +This file describes how to build and install Ice for JavaScript from source +code. If you prefer, you can also download [binary distributions] for the +supported platforms. + + + +- [JavaScript Build Requirements](#javascript-build-requirements) +- [Building the JavaScript libraries and NodeJS packages](#building-the-javascript-libraries-and-nodejs-packages) +- [Running the JavaScript Tests](#running-the-javascript-tests) + - [Browser Information](#browser-information) + - [Self-Signed Certificate](#self-signed-certificate) + - [Windows 8](#windows-8) + - [Secure WebSockets on iOS and Android](#secure-websockets-on-ios-and-android) + - [Installing Certificates on iOS](#installing-certificates-on-ios) + - [Installing Certificates on Android](#installing-certificates-on-android) +- [Installing a Source Build](#installing-a-source-build) + + + +## JavaScript Build Requirements + +To build Ice for JavaScript you must have the following: + +- The `slice2js` compiler from Ice for C++. If you have not built Ice for C++ + in this source distribution, refer to the + [C++ build instructions](../cpp/README.md). +- Node.js 4.6 or later + +## Building the JavaScript libraries and NodeJS packages + +Change to the Ice for JavaScript source subdirectory: + +```shell +cd js +``` + +Run these commands to build the libraries and tests: + +```shell +npm install +npm run build +``` + +On Windows, you need to set the platform and configuration in order to locate +`slice2js`. For example, if you have built C++ with the x64 Release +configuration, you can use the following command to build JavaScript: + +```shell +npm run build -- --cppPlatform x64 --cppConfiguration Release +``` + +Alternatively you can use the `CPP_PLATFORM` and `CPP_CONFIGURATION` environment +variables: + +```shell +set CPP_PLATFORM=x64 +set CPP_CONFIGURATION=Debug +npm run build +``` + +Upon successful completion, the build generates libraries in the `lib` +subdirectory, including compressed and minified versions. + +For older browsers that do not support all of the required ECMAScript 6 +features used by Ice for JavaScript, we provide pre-compiled versions of +the libraries using the [Babel] JavaScript compiler. These libraries +depend on the [core-js] and [regenerator-runtime] packages +and are available in the `lib/es5` subdirectory with the same names as +the main libraries. + +## Running the JavaScript Tests + +Python is required to run the test suite. Additionally, the Glacier2 tests +require the Python module `passlib`, which you can install with the command: + +```shell +pip install passlib +``` + +The scripts also require Ice for Python, you can build Ice for Python from +[python](../python) folder of this source distribution or install the Python +module `zeroc-ice`, using the following command: + +```shell +pip install zeroc-ice +``` + +The test suites require that the Ice for C++ tests be built in the `cpp` +subdirectory of this source distribution. + +You can start the NodeJS tests with: + +```shell +python allTests.py +``` + +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. + +You can start the browser tests with: + +```shell +python allTests.py --browser Manual +``` + +Then open the test page (http://127.0.0.1:8080/start) using a web browser. +These tests require a web browser with ECMAScript 6 support, such as +a recent version of Chrome, Firefox, Microsoft Edge or Safari. + +If you are using another web browser, such as Internet Explorer, you should +use instead: + +```shell +python allTests.py --browser Manual --es5 +``` + +Then open the test page (http://127.0.0.1:8080/es5/start) + +This runs a version of the test suite transpiled to ECMAScript 5 using [Babel]. + +On macOS the first time you run the tests, you will be prompted for your +password. This is necessary to configure the trust setting for the HTTP +server certificate, which will enable you to connect to the HTTP server +with SSL via your web browser. + +### Browser Information + +#### Self-Signed Certificate + +The browser-based tests allow you to choose whether to run the tests over +non-secure WebSocket (WS) or secure WebSocket (WSS) connections. The WSS +connections in these tests rely on a self-signed certificate, `cacert`, +provided in the certs(../certs) directory. + +To successfully run the tests over WSS, additional action may be necessary +depending on the browser you're using: + +- Chrome + You'll be presented with a warning about the site's security certificate. + Click the "Proceed anyway" button to temporarily accept the certificate. + +- Firefox + You'll see a warning saying "This Connection is Untrusted". Open Firefox's + Preferences or Options dialog, click on the Advanced section, select the + Certificates tab and click on the "View Certificates..." button. In the + Authorities tab, click the "Import..." button, navigate to the `cacert.pem` + file, and add it as a certificate authority (CA) for trusting web sites. + After closing the dialogs, reload the test page to continue. You should + uninstall this certificate after running the tests. + +- Internet Explorer and Microsoft Edge + Run the management console (mmc.exe) and add the Certificates snap-in for + the computer account. Then select Console Root > Certificates (Local + Computer) > Trusted Root Certificate Authorities. In the Action menu, choose + All Tasks and Import. Navigate to the `cacert.der` file and import it into + the Trusted Root Certificate Authorities. Reload the test page to continue. + You should uninstall this certificate after running the tests. + +#### Windows 8 + +On Windows 8, network isolation prevents Internet Explorer from +connecting to 127.0.0.1. To work around this limitation, you'll need to disable +Internet Explorer's "Protected Mode". Open the "Internet Options" dialog and in +the "Security" settings tab, deselect the "Enable Protected Mode" checkbox. + +#### Secure WebSockets on iOS and Android + +To use WSS on iOS and Android it may be required (depending on browser and +platform) that the server certificate's common name matches the computer hosting +the tests, and that the test certificate authority be installed on your device. + +First you'll need to generate new certificates to match the IP address of the +computer hosting the tests: + +```shell +certs/makecerts.py [IP address] +``` + +Next you must install the certificate authority on your device. The simplest way +is to email the CA certificate (`certs/cacert.pem`) to yourself and then follow +the instructions below to install the certificate on your device. + +Once installed, you connect to the server using the same IP address used to +create the certificates. + +##### Installing Certificates on iOS + +Open the certificate (`cacert.pem`) from the device's email client. You +will be prompted to create a configuration profile containing this certificate. + +##### Installing Certificates on Android + +Download the certificate (`cacert.pem`) to the device from an email client. +Next go to _Settings -> Security -> Install from storage_, and choose +`cacert.pem`. Enter a name and press OK. + +## Installing a Source Build + +After a successful build, you can generate a package by running the +following command: + +```shell +npm pack +``` + +This will generate the file `ice-3.7.100.tgz`, which can be installed by running: + +```shell +npm install ice-3.7.100.tgz +``` + +To use Ice for JavaScript with a browser, copy the appropriate JavaScript +library files located in the `lib` directory to your web server. + +[binary distributions]: https://zeroc.com/downloads/ice +[Babel]: https://babeljs.io +[core-js]: https://www.npmjs.com/package/core-js +[regenerator-runtime]: https://www.npmjs.com/package/regenerator-runtime diff --git a/js/README.md b/js/README.md index f7617a2d7cc..07b488d7dc9 100644 --- a/js/README.md +++ b/js/README.md @@ -1,208 +1,52 @@ -# Building Ice for JavaScript - -This file 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](#javascript-build-requirements) -- [Building the JavaScript libraries and NodeJS packages](#building-the-javascript-libraries-and-nodejs-packages) -- [Running the JavaScript Tests](#running-the-javascript-tests) - - [Browser Information](#browser-information) - - [Self-Signed Certificate](#self-signed-certificate) - - [Windows 8](#windows-8) - - [Secure WebSockets on iOS and Android](#secure-websockets-on-ios-and-android) - - [Installing Certificates on iOS](#installing-certificates-on-ios) - - [Installing Certificates on Android](#installing-certificates-on-android) -- [Installing a Source Build](#installing-a-source-build) - - - -## JavaScript Build Requirements - -To build Ice for JavaScript you must have the following: - -- The `slice2js` compiler from Ice for C++. If you have not built Ice for C++ - in this source distribution, refer to the - [C++ build instructions](../cpp/README.md). -- Node.js 4.6 or later - -## Building the JavaScript libraries and NodeJS packages - -Change to the Ice for JavaScript source subdirectory: -``` -cd js -``` - -Run these commands to build the libraries and tests: -``` -npm install -npm run build -``` - -On Windows, you need to set the platform and configuration in order to locate -`slice2js`. For example, if you have built C++ with the x64 Release -configuration, you can use the following command to build JavaScript: -``` -npm run build -- --cppPlatform x64 --cppConfiguration Release -``` - -Alternatively you can use the `CPP_PLATFORM` and `CPP_CONFIGURATION` environment -variables: -``` -set CPP_PLATFORM=x64 -set CPP_CONFIGURATION=Debug -npm run build -``` - -Upon successful completion, the build generates libraries in the `lib` -subdirectory, including compressed and minified versions. - -For older browsers that do not support all of the required ECMAScript 6 -features used by Ice for JavaScript, we provide pre-compiled versions of -the libraries using the [Babel][2] JavaScript compiler. These libraries -depend on the `core-js`[3] and `regenerator-runtime`[4] packages -and are available in the `lib/es5` subdirectory with the same names as -the main libraries. - -## Running the JavaScript Tests - -Python is required to run the test suite. Additionally, the Glacier2 tests -require the Python module `passlib`, which you can install with the command: -``` -pip install passlib -``` - -The scripts also require Ice for Python, you can build Ice for Python from -[python](../python) folder of this source distribution or install the Python -module `zeroc-ice`, using the following command: -``` -pip install zeroc-ice -``` - -The test suites require that the Ice for C++ tests be built in the `cpp` -subdirectory of this source distribution. - -You can start the NodeJS tests with: -``` -python allTests.py -``` - -If everything worked out, you should see lots of `ok` messages. In case of a -failure, the tests abort with `failed`. - -You can start the browser tests with: -``` -python allTests.py --browser Manual -``` - -Then open the test page (http://127.0.0.1:8080/start) using a web browser. -These tests require a web browser with ECMAScript 6 support, such as -a recent version of Chrome, Firefox, Microsoft Edge or Safari. - -If you are using another web browser, such as Internet Explorer, you should -use instead: -``` -python allTests.py --browser Manual --es5 -``` - -Then open the test page (http://127.0.0.1:8080/es5/start) - -This runs a version of the test suite transpiled to ECMAScript 5 using [Babel][2]. - -On macOS the first time you run the tests, you will be prompted for your -password. This is necessary to configure the trust setting for the HTTP -server certificate, which will enable you to connect to the HTTP server -with SSL via your web browser. - -### Browser Information - -#### Self-Signed Certificate - -The browser-based tests allow you to choose whether to run the tests over -non-secure WebSocket (WS) or secure WebSocket (WSS) connections. The WSS -connections in these tests rely on a self-signed certificate, `cacert`, -provided in the certs(../certs) directory. - -To successfully run the tests over WSS, additional action may be necessary -depending on the browser you're using: - -- Chrome - You'll be presented with a warning about the site's security certificate. - Click the "Proceed anyway" button to temporarily accept the certificate. - -- Firefox - You'll see a warning saying "This Connection is Untrusted". Open Firefox's - Preferences or Options dialog, click on the Advanced section, select the - Certificates tab and click on the "View Certificates..." button. In the - Authorities tab, click the "Import..." button, navigate to the `cacert.pem` - file, and add it as a certificate authority (CA) for trusting web sites. - After closing the dialogs, reload the test page to continue. You should - uninstall this certificate after running the tests. - -- Internet Explorer and Microsoft Edge - Run the management console (mmc.exe) and add the Certificates snap-in for - the computer account. Then select Console Root > Certificates (Local - Computer) > Trusted Root Certificate Authorities. In the Action menu, choose - All Tasks and Import. Navigate to the `cacert.der` file and import it into - the Trusted Root Certificate Authorities. Reload the test page to continue. - You should uninstall this certificate after running the tests. - -#### Windows 8 - -On Windows 8, network isolation prevents Internet Explorer from -connecting to 127.0.0.1. To work around this limitation, you'll need to disable -Internet Explorer's "Protected Mode". Open the "Internet Options" dialog and in -the "Security" settings tab, deselect the "Enable Protected Mode" checkbox. - -#### Secure WebSockets on iOS and Android - -To use WSS on iOS and Android it may be required (depending on browser and -platform) that the server certificate's common name matches the computer hosting -the tests, and that the test certificate authority be installed on your device. - -First you'll need to generate new certificates to match the IP address of the -computer hosting the tests: -``` -certs/makecerts.py [IP address] -``` - -Next you must install the certificate authority on your device. The simplest way -is to email the CA certificate (`certs/cacert.pem`) to yourself and then follow -the instructions below to install the certificate on your device. - -Once installed, you connect to the server using the same IP address used to -create the certificates. - -##### Installing Certificates on iOS - -Open the certificate (`cacert.pem`) from the device's email client. You -will be prompted to create a configuration profile containing this certificate. - -##### Installing Certificates on Android - -Download the certificate (`cacert.pem`) to the device from an email client. -Next go to _Settings -> Security -> Install from storage_, and choose -`cacert.pem`. Enter a name and press OK. - -## Installing a Source Build - -After a successful build, you can generate a package by running the -following command: -``` -npm pack -``` - -This will generate the file `ice-3.7.10.tgz`, which can be installed by running: -``` -npm install ice-3.7.10.tgz -``` - -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/downloads/ice -[2]: https://babeljs.io -[3]: https://www.npmjs.com/package/core-js -[4]: https://www.npmjs.com/package/regenerator-runtime +# Ice For JavaScript + +[Getting started] | [Examples] | [NPM packages] | [Documentation] | [Building from source] + +The [Ice framework] provides everything you need to build networked applications, +including RPC, pub/sub, server deployment, and more. + +Ice for JavaScript is the JavaScript implementation of the Ice framework. + +## Sample Code + +```slice +// Slice definitions (Hello.ice) + +module Demo +{ + interface Hello + { + void sayHello(); + } +} +``` + +```javascript +// Client application (client.js) +let communicator; +try +{ + communicator = Ice.initialize(process.argv); + const hello = await Demo.HelloPrx.checkedCast( + communicator.stringToProxy("hello:tcp -h localhost -p 10000")); + await hello.sayHello(); +} +catch(ex) +{ + console.log(ex.toString()); +} +finally +{ + if(communicator) + { + await communicator.destroy(); + } +} +``` + +[Getting started]: https://doc.zeroc.com/ice/3.7/hello-world-application/writing-an-ice-application-with-javascript +[Examples]: https://github.com/zeroc-ice/ice-demos/tree/3.7/js +[NPM Packages]: https://www.npmjs.com/~zeroc +[Documentation]: https://doc.zeroc.com/ice/3.7 +[Building from source]: https://github.com/zeroc-ice/ice/blob/3.7/js/BUILDING.md +[Ice framework]: https://github.com/zeroc-ice/ice \ No newline at end of file diff --git a/matlab/BUILDING.md b/matlab/BUILDING.md new file mode 100644 index 00000000000..eb7647d4766 --- /dev/null +++ b/matlab/BUILDING.md @@ -0,0 +1,169 @@ +# Ice for MATLAB Build Instructions + +This document describes how to build and install Ice for MATLAB from source. + +ZeroC provides Ice for MATLAB [toolboxes][1] for MATLAB on Windows and Linux, so building Ice for MATLAB from source is +usually unnecessary. + +* [Building Ice for MATLAB on Windows](#building-ice-for-matlab-on-windows) + * [Prerequisites](#prerequisites) + * [Build Instructions](#build-instructions) + * [Packaging the Ice Toolbox](#packaging-the-ice-toolbox) +* [Building Ice for MATLAB on Linux](#building-ice-for-matlab-on-linux) + * [Prerequisites](#prerequisites-1) + * [Build Instructions](#build-instructions-1) +* [Using Ice for MATLAB](#using-ice-for-matlab) + * [Search Path](#search-path) + * [Slice Files](#slice-files) + * [Loading the Library](#loading-the-library) + * [Running the Tests](#running-the-tests) + +## Building Ice for MATLAB on Windows + +### Prerequisites + +The build system requires MATLAB 2016a or later for Windows, Visual Studio 2015 +and a Perl installation. + +### Build Instructions + +Open a Visual Studio x64 command prompt, `VS2015 x64 Native Tools Command Prompt`. In this Command Prompt, change to the +`matlab` subdirectory: + +```shell +cd matlab +``` + +Now you're ready to build Ice for MATLAB: + +```shell +msbuild msbuild\ice.proj +``` + +To build in debug mode instead: + +```shell +msbuild msbuild\ice.proj /p:Configuration=Debug +``` + +Upon completion, a build in release mode generates the following components: + +* Ice for C++11 libraries, located in `cpp\bin\x64\Release` +* slice2matlab executable, located in `cpp\bin\x64\Release` +* ice.mexw64 MEX file, located in `matlab\lib\x64\Release` +* Prototype and thunk files, located in `matlab\lib\x64\Release` +* MATLAB code for core Slice files, located in `matlab\lib\generated` +* MATLAB code for test Slice files, located in `matlab\test\**\generated` + +The MATLAB extension depends on Ice for C++ components from the `cpp` +subdirectory, and those are built if required. It is also possible to build the +MATLAB extension using Ice C++ NuGet packages by setting the `ICE_BIN_DIST` +MSBuild property to `cpp`: + +```shell +msbuild msbuild\ice.proj /p:ICE_BIN_DIST=cpp +``` + +### Packaging the Ice Toolbox + +Use the following command to build the Ice toolbox package: + +```shell +msbuild msbuild\ice.proj /t:Package +``` + +This creates the toolbox package `toolbox\ice---win.mltbx`. + +You can install the toolbox from within MATLAB by double-clicking on the file. + +## Building Ice for MATLAB on Linux + +### Prerequisites + +The build system requires MATLAB 2017b or MATLAB 2019b for Linux, with a supported C++ compiler and a Perl installation. + +* Use GCC 4.9 for 2017b, see [MATLAB 2017b supported compilers][2]. +* Use GCC 6.3 for 2019b, see [MATLAB 2019b supported compilers][3]. + +We recommend using the following build environments: + +* Ubuntu 16.04 (Xenial) with g++-4.9 compiler, for MATLAB 2017b. +* Debian 9 (Stretch) with the default g++ compiler, for MATLAB 2019b. + +### Build Instructions + +The MATLAB extension depends on Ice for C++ components from the cpp subdirectory, and those need to be built, using the +`cpp11-shared` configuration, if you have not built the C++ distribution first review [cpp/README.md](../cpp/README.md). + +In a command window, change to the matlab subdirectory: + +```shell +cd matlab +``` + +Review the [matlab/config/Make.rules](config/Make.rules) in your build tree and update the configuration if needed. The +comments in the file provide more information. + +Run `make` to build the Ice for MATLAB toolbox and the MATLAB tests. Set `V=1` to get a more detailed build output. + +```shell +make +``` + +This creates the toolbox package `toolbox/ice---linux.mltbx`. You can install the toolbox from +within MATLAB by double-clicking on the file. + +To build the Ice for MATLAB toolbox using the C++ binary distribution, set `ICE_BIN_DIST=cpp`, note this is only possible +with the MATLAB 2019b builds, because MATLAB 2017b needs to use the g++-4.9 that is not compatible with the Xenial +binary distribution. + +When building for MATALB 2017b you must set `CC` and `CXX` variables to use the `gcc-4.9` and `g++-4.9` compilers +respectively. + +```shell +CC=gcc-4.9 +CXX=g++-4.9 +``` + +## Using Ice for MATLAB + +### Search Path + +To use a source build, add the following directories to your MATLAB path: + +* `matlab\lib` +* `matlab\lib\generated` +* `matlab\lib\x64\Release` (only on Windows platforms) +* `matlab\lib\x86_64-linux-gnu` (only on Linux platforms) + +### Slice Files + +Use `slice2matlab` to compile your Slice files. Run `slice2matlab -h` for a description of its command-line options. You +can place the generated `*.m` files anywhere you like, but the enclosing directory must be in your MATLAB path. + +### Loading the Library + +The Ice for MATLAB library can be loaded with this command: + +```shell +loadlibrary('ice', @iceproto) +``` + +### Running the Tests + +The Ice for MATLAB tests are located in `matlab\test`. + +Since Ice for MATLAB only supports client functionality, you need test servers from a different language mapping. + +Assuming you've installed Ice for Python, run `allTests.py`: + +```shell +python allTests.py +``` + +This script automatically starts a Python server for each MATLAB client. MATLAB clients are executed using a minimized +MATLAB interpreter and the test output is copied to the Command Prompt window. + +[1]: https://zeroc.com/downloads/ice +[2]: https://www.mathworks.com/content/dam/mathworks/mathworks-dot-com/support/sysreq/files/SystemRequirements-Release2017b_SupportedCompilers.pdf +[3]: https://www.mathworks.com/content/dam/mathworks/mathworks-dot-com/support/sysreq/files/system-requirements-release-2019b-supported-compilers.pdf diff --git a/matlab/README.md b/matlab/README.md index 3dd7f3b457c..1805868d40a 100644 --- a/matlab/README.md +++ b/matlab/README.md @@ -1,164 +1,55 @@ -# Building Ice for MATLAB +# Ice for MATLAB -This document describes how to build and install Ice for MATLAB from source. +[Getting started] | [Examples] | [Documentation] | [Building from source] -ZeroC provides Ice for MATLAB [toolboxes][1] for MATLAB on Windows and Linux, so building Ice for MATLAB from source is -usually unnecessary. +The [Ice framework] provides everything you need to build networked applications, +including RPC, pub/sub, server deployment, and more. -* [Building Ice for MATLAB on Windows](#building-ice-for-matlab-on-windows) - * [Prerequisites](#prerequisites) - * [Build Instructions](#build-instructions) - * [Packaging the Ice Toolbox](#packaging-the-ice-toolbox) -* [Building Ice for MATLAB on Linux](#building-ice-for-matlab-on-linux) - * [Prerequisites](#prerequisites-1) - * [Build Instructions](#build-instructions-1) -* [Using Ice for MATLAB](#using-ice-for-matlab) - * [Search Path](#search-path) - * [Slice Files](#slice-files) - * [Loading the Library](#loading-the-library) - * [Running the Tests](#running-the-tests) +Ice for MATLAB is the MATLAB implementation of the Ice framework. -## Building Ice for MATLAB on Windows +## Sample Code -### Prerequisites +```slice +// Slice definitions (Hello.ice) -The build system requires MATLAB 2016a or later for Windows, Visual Studio 2015 -and a Perl installation. - -### Build Instructions - -Open a Visual Studio x64 command prompt, `VS2015 x64 Native Tools Command Prompt`. In this Command Prompt, change to the -`matlab` subdirectory: - -``` -cd matlab +module Demo +{ + interface Hello + { + void sayHello(); + } +} ``` -Now you're ready to build Ice for MATLAB: -``` -msbuild msbuild\ice.proj -``` +```matlab +// Client application (client.m) +function client(args) + addpath('generated'); + if ~libisloaded('ice') + loadlibrary('ice', @iceproto); + end -To build in debug mode instead: -``` -msbuild msbuild\ice.proj /p:Configuration=Debug -``` + import Demo.* -Upon completion, a build in release mode generates the following components: + if nargin == 0 + args = {}; + end - - Ice for C++11 libraries, located in `cpp\bin\x64\Release` - - slice2matlab executable, located in `cpp\bin\x64\Release` - - ice.mexw64 MEX file, located in `matlab\lib\x64\Release` - - Prototype and thunk files, located in `matlab\lib\x64\Release` - - MATLAB code for core Slice files, located in `matlab\lib\generated` - - MATLAB code for test Slice files, located in `matlab\test\**\generated` - -The MATLAB extension depends on Ice for C++ components from the `cpp` -subdirectory, and those are built if required. It is also possible to build the -MATLAB extension using Ice C++ NuGet packages by setting the `ICE_BIN_DIST` -msbuild property to `cpp`: - -``` -msbuild msbuild\ice.proj /p:ICE_BIN_DIST=cpp -``` - -### Packaging the Ice Toolbox - -Use the following command to build the Ice toolbox package: -``` -msbuild msbuild\ice.proj /t:Package -``` - -This creates the toolbox package `toolbox\ice---win.mltbx`. - -You can install the toolbox from within MATLAB by double-clicking on the file. - -## Building Ice for MATLAB on Linux - -### Prerequisites - -The build system requires MATLAB 2017b or MATLAB 2019b for Linux, with a supported C++ compiler and a Perl installation. - -* Use GCC 4.9 for 2017b, see [MATLAB 2017b supported compilers][2]. -* Use GCC 6.3 for 2019b, see [MATLAB 2019b supported compilers][3]. - -We recommend using the following build environments: - -* Ubuntu 16.04 (Xenial) with g++-4.9 compiler, for MATLAB 2017b. -* Debian 9 (Stretch) with the default g++ compiler, for MATLAB 2019b. - -### Build Instructions - -The MATLAB extension depends on Ice for C++ components from the cpp subdirectory, and those need to be built, using the -`cpp11-shared` configuration, if you have not built the C++ distribution first review [cpp/README.md](../cpp/README.md). - -In a command window, change to the matlab subdirectory: - -``` -cd matlab + try + communicator = Ice.initialize(args); + cleanup = onCleanup(@() communicator.destroy()); + hello = Demo.HelloPrx.checkedCast( + communicator.stringToProxy('hello:default -h localhost -p 10000')); + hello.sayHello(); + catch ex + fprintf('%s\n', getReport(ex)); + end + rmpath('generated'); +end ``` -Review the [matlab/config/Make.rules](config/Make.rules) in your build tree and update the configuration if needed. The -comments in the file provide more information. - -Run `make` to build the Ice for MATLAB toolbox and the MATLAB tests. Set `V=1` to get a more detailed build output. - -``` -make -``` - -This creates the toolbox package `toolbox/ice---linux.mltbx`. You can install the toolbox from -within MATLAB by double-clicking on the file. - -To build the Ice for MATLAB toolbox using the C++ binary distribution, set `ICE_BIN_DIST=cpp`, note this is only possible -with the MATLAB 2019b builds, because MATLAB 2017b needs to use the g++-4.9 that is not compatible with the Xenial -binary distribution. - -When building for MATALB 2017b you must set `CC` and `CXX` variables to use the `gcc-4.9` and `g++-4.9` compilers -respectively. - -``` -CC=gcc-4.9 -CXX=g++-4.9 -``` - -## Using Ice for MATLAB - -### Search Path - -To use a source build, add the following directories to your MATLAB path: - - `matlab\lib` - - `matlab\lib\generated` - - `matlab\lib\x64\Release` (only on Windows platforms) - - `matlab\lib\x86_64-linux-gnu` (only on Linux platforms) - -### Slice Files - -Use `slice2matlab` to compile your Slice files. Run `slice2matlab -h` for a description of its command-line options. You -can place the generated `*.m` files anywhere you like, but the enclosing directory must be in your MATLAB path. - -### Loading the Library - -The Ice for MATLAB library can be loaded with this command: -``` -loadlibrary('ice', @iceproto) -``` - -### Running the Tests - -The Ice for MATLAB tests are located in `matlab\test`. - -Since Ice for MATLAB only supports client functionality, you need test servers from a different language mapping. - -Assuming you've installed Ice for Python, run `allTests.py`: - -``` -python allTests.py -``` - -This script automatically starts a Python server for each MATLAB client. MATLAB clients are executed using a minimized -MATLAB interpreter and the test output is copied to the Command Prompt window. - -[1]: https://zeroc.com/downloads/ice -[2]: https://www.mathworks.com/content/dam/mathworks/mathworks-dot-com/support/sysreq/files/SystemRequirements-Release2017b_SupportedCompilers.pdf -[3]: https://www.mathworks.com/content/dam/mathworks/mathworks-dot-com/support/sysreq/files/system-requirements-release-2019b-supported-compilers.pdf +[Getting started]: https://doc.zeroc.com/ice/3.7/hello-world-application/writing-an-ice-application-with-matlab +[Examples]: https://github.com/zeroc-ice/ice-demos/tree/3.7/matlab +[Documentation]: https://doc.zeroc.com/ice/3.7 +[Building from source]: https://github.com/zeroc-ice/ice/blob/3.7/matlab/BUILDING.md +[Ice framework]: https://github.com/zeroc-ice/ice diff --git a/objective-c/BUILDING.md b/objective-c/BUILDING.md new file mode 100644 index 00000000000..2207ae69a2d --- /dev/null +++ b/objective-c/BUILDING.md @@ -0,0 +1,159 @@ +# Ice for Objective-C Build Instructions + +This page describes how to build and install Ice for Objective-C from source +code on macOS. If you prefer, you can install a [Homebrew] package instead. + +* [Objective\-C Build Requirements](#objective-c-build-requirements) + * [Operating Systems and Compilers](#operating-systems-and-compilers) +* [Building Ice for Objective\-C](#building-ice-for-objective-c) + * [Build configurations and platforms](#build-configurations-and-platforms) + * [Ice Xcode SDK](#ice-xcode-sdk) +* [Installing an Objective\-C Source Build](#installing-an-objective-c-source-build) +* [Building the Test Suite](#building-the-test-suite) +* [Running the Test Suite](#running-the-test-suite) + * [macOS](#macos) + * [iOS Simulator](#ios-simulator) + * [iOS](#ios) + +## Objective-C Build Requirements + +### Operating Systems and Compilers + +Ice for Objective-C is currently only supported on macOS and iOS, and was +extensively tested using the operating system and compiler versions listed for +our [supported platforms]. + +## Building Ice for Objective-C + +The build of Ice for Objective-C requires that you first build Ice for C++ in +the `cpp` subdirectory for the same configuration(s) and platform(s). + +Review the top-level [config/Make.rules](../config/Make.rules) in your build +tree and update the configuration if needed. The comments in the file provide +more information. + +Change to the Ice for Objective-C source subdirectory: + +```shell +cd objective-c +``` + +Run `make` to build the Ice Objective-C libraries and test suite. Set `V=1` to +get a more detailed build output. You can build only the libraries with the +`srcs` target, or only the tests with the `tests` target. For example: + +```shell +make V=1 -j8 srcs +``` + +### Build configurations and platforms + +The Objective-C source tree supports multiple build configurations and +platforms. To see the supported configurations and platforms: + +```shell +make print V=supported-configs +make print V=supported-platforms +``` + +To build all the supported configurations and platforms: + +```shell +make CONFIGS=all PLATFORMS=all -j8 +``` + +The `arc-` configurations (for [Automatic Reference Counting]) apply only to +the test suite; the Ice libraries don't use these configurations, and the same +Ice for Objective-C library can be used with and without ARC. + +### Ice Xcode SDK + +The build system supports building Xcode SDKs for Ice. These SDKs allow you to +easily develop Ice applications with Xcode. To build Xcode SDKs, use the +`xcodesdk` configurations: + +```shell +make CONFIGS=xcodesdk -j8 srcs # Build the Objective-C mapping Xcode SDK + # for the default platform +``` + +The Xcode SDKs are built into `ice/sdk`. + +## Installing an Objective-C Source Build + +Simply run `make install`. This will install Ice in the directory specified by +the `prefix` variable in `../config/Make.rules`. + +When compiling Ice programs, you must pass the location of the +`/include` directory to the compiler with the `-I` option, and the +location of the library directory with the `-L` option. + +## Building the Test Suite + +`make all` or `make tests` builds the test suite for the platform(s) and +configuration(s) you selected. + +However, in order to run the test suite on `iphoneos`, you need to build the +Objective-C Controller app from Xcode: + +* Open the Objective-C Test Controller project located in the + `objective-c/test/ios/controller` directory. +* Build the `Objective-C Controller` or `Objective-C ARC Controller` app. + +## Cleaning the source build + +Running `make clean` will remove the binaries created for the default +configuration and platform. + +To clean the binaries produced for a specific configuration or platform, you +need to specify the `CONFIGS` or `PLATFORMS` variable. For example, +`make CONFIGS=xcodesdk clean` will clean the Xcode SDK build. + +To clean the build for all the supported configurations and platforms, run +`make CONFIGS=all PLATFORMS=all clean`. + +Running `make distclean` will also clean the build for all the configurations +and platforms. In addition, it will also remove the generated files created by +the Slice compilers. + +## Running the Test Suite + +Python is required to run the test suite. After a successful source build, you +can run the tests as shown below. If everything worked out, you should see lots +of `ok` messages. In case of a failure, the tests abort with `failed`. + +### macOS + +```shell +python3 allTests.py # default config and default platform +python3 allTests --config=... --platform=... # use the specified config and platform +``` + +### iOS Simulator + +```shell +python3 allTests.py --config=xcodesdk --platform=iphonesimulator --controller-app +``` + +### iOS + +* Start the `Objective-C Controller` or `Objective-C ARC Controller` app on + your iOS device, from Xcode. +* On your Mac: + + ```shell +python3 allTests.py --config=xcodesdk --platform=iphoneos + ``` + +or + +```shell +python3 allTests.py --config=arc-xcodesdk --platform=iphoneos +``` + +All the test clients and servers run on the iOS device, not on your Mac +computer. + +[Homebrew]: https://doc.zeroc.com/ice/3.7/release-notes/using-the-macos-binary-distribution +[supported platforms]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10 +[Automatic Reference Counting]: https://en.wikipedia.org/wiki/Automatic_Reference_Counting diff --git a/objective-c/README.md b/objective-c/README.md index 0cbfa83dd28..b2bf7348a1d 100644 --- a/objective-c/README.md +++ b/objective-c/README.md @@ -1,140 +1,120 @@ -# Building Ice for Objective-C on macOS +# Ice for Objective-C -This page describes how to build and install Ice for Objective-C from source -code on macOS. If you prefer, you can install a [Homebrew][1] package instead. +[Getting started] | [Examples] | [Documentation] | [Building from source] -* [Objective\-C Build Requirements](#objective-c-build-requirements) - * [Operating Systems and Compilers](#operating-systems-and-compilers) -* [Building Ice for Objective\-C](#building-ice-for-objective-c) - * [Build configurations and platforms](#build-configurations-and-platforms) - * [Ice Xcode SDK](#ice-xcode-sdk) -* [Installing an Objective\-C Source Build](#installing-an-objective-c-source-build) -* [Building the Test Suite](#building-the-test-suite) -* [Running the Test Suite](#running-the-test-suite) - * [macOS](#macos) - * [iOS Simulator](#ios-simulator) - * [iOS](#ios) +The [Ice framework] provides everything you need to build networked applications, including RPC, pub/sub, server deployment, and more. -## Objective-C Build Requirements +Ice for Objective-C is the Objective-C implementation of the Ice framework. -### Operating Systems and Compilers +## Sample Code -Ice for Objective-C is currently only supported on macOS and iOS, and was -extensively tested using the operating system and compiler versions listed for -our [supported platforms][2]. +```slice +// Slice definitions (Hello.ice) -## Building Ice for Objective-C - -The build of Ice for Objective-C requires that you first build Ice for C++ in -the `cpp` subdirectory for the same configuration(s) and platform(s). - -Review the top-level [config/Make.rules](../config/Make.rules) in your build -tree and update the configuration if needed. The comments in the file provide -more information. - -Change to the Ice for Objective-C source subdirectory: -``` - cd objective-c +module Demo +{ + interface Hello + { + void sayHello(); + } +} ``` -Run `make` to build the Ice Objective-C libraries and test suite. Set `V=1` to -get a more detailed build output. You can build only the libraries with the -`srcs` target, or only the tests with the `tests` target. For example: -``` - make V=1 -j8 srcs -``` - -### Build configurations and platforms -The Objective-C source tree supports multiple build configurations and -platforms. To see the supported configurations and platforms: +```objective-c +// Client application (Client.m) +#import +#import + +int +main(int argc, char* argv[]) +{ + int status = 0; + @autoreleasepool + { + id communicator = nil; + @try + { + communicator = [ICEUtil createCommunicator:&argc argv:argv]; + if(argc > 1) + { + NSLog(@"%s: too many arguments", argv[0]); + return 1; + } + id hello = [DemoHelloPrx uncheckedCast: + [communicator stringToProxy:@"hello:default -p 10000"]]; + [hello sayHello]; + } + @catch(ICELocalException* ex) + { + NSLog(@"%@", ex); + status = 1; + } + + [communicator destroy]; + } + return status; +} ``` - make print V=supported-configs - make print V=supported-platforms -``` -To build all the supported configurations and platforms: -``` - make CONFIGS=all PLATFORMS=all -j8 -``` -The `arc-` configurations (for [Automatic Reference Counting][3]) apply only to -the test suite; the Ice libraries don't use these configurations, and the same -Ice for Objective-C library can be used with and without ARC. -### Ice Xcode SDK - -The build system supports building Xcode SDKs for Ice. These SDKs allow you to -easily develop Ice applications with Xcode. To build Xcode SDKs, use the -`xcodesdk` configurations: -``` - make CONFIGS=xcodesdk -j8 srcs # Build the Objective-C mapping Xcode SDK - # for the default platform +```objective-c +// Server application (Server.m) +#import +#import + +int +main(int argc, char* argv[]) +{ + int status = 0; + @autoreleasepool + { + id communicator = nil; + @try + { + communicator = [ICEUtil createCommunicator:&argc argv:argv]; + + id adapter = [communicator + createObjectAdapterWithEndpoints: @"Hello" + endpoints:@"default -p 10000"]; + [adapter add:[HelloI hello] identity:[ICEUtil stringToIdentity:@"hello"]]; + [adapter activate]; + [communicator waitForShutdown]; + } + @catch(ICELocalException* ex) + { + NSLog(@"%@", ex); + status = 1; + } + [communicator destroy]; + } + return status; +} ``` -The Xcode SDKs are built into `ice/sdk`. - -## Installing an Objective-C Source Build -Simply run `make install`. This will install Ice in the directory specified by -the `prefix` variable in `../config/Make.rules`. +```objective-c +// Printer declaration (Printer.h) +#import -When compiling Ice programs, you must pass the location of the -`/include` directory to the compiler with the `-I` option, and the -location of the library directory with the `-L` option. - -## Building the Test Suite - -`make all` or `make tests` builds the test suite for the platform(s) and -configuration(s) you selected. - -However, in order to run the test suite on `iphoneos`, you need to build the -Objective-C Controller app from Xcode: - - Open the Objective-C Test Controller project located in the - `objective-c/test/ios/controller` directory. - - Build the `Objective-C Controller` or `Objective-C ARC Controller` app. - -## Cleaning the source build - -Running `make clean` will remove the binaries created for the default -configuration and platform. - -To clean the binaries produced for a specific configuration or platform, you -need to specify the `CONFIGS` or `PLATFORMS` variable. For example, -`make CONFIGS=xcodesdk clean` will clean the Xcode SDK build. - -To clean the build for all the supported configurations and platforms, run -`make CONFIGS=all PLATFORMS=all clean`. - -Running `make distclean` will also clean the build for all the configurations -and platforms. In addition, it will also remove the generated files created by -the Slice compilers. +@interface Printer : DemoHello +@end +``` -## Running the Test Suite +```objective-c +// Printer implementation (Printer.m) +#import -Python is required to run the test suite. After a successful source build, you -can run the tests as shown below. If everything worked out, you should see lots -of `ok` messages. In case of a failure, the tests abort with `failed`. +#include -### macOS -``` - python3 allTests.py # default config and default platform - python3 allTests --config=... --platform=... # use the specified config and platform +@implementation Printer +-(void) sayHello:(ICECurrent*)current +{ + printf("Hello World!\n"); + fflush(stdout); +} +@end ``` -### iOS Simulator -``` - python3 allTests.py --config=xcodesdk --platform=iphonesimulator --controller-app -``` -### iOS - - Start the `Objective-C Controller` or `Objective-C ARC Controller` app on - your iOS device, from Xcode. - - On your Mac: - ``` - python3 allTests.py --config=xcodesdk --platform=iphoneos - ``` - or - ``` - python3 allTests.py --config=arc-xcodesdk --platform=iphoneos - ``` - All the test clients and servers run on the iOS device, not on your Mac - computer. - -[1]: https://doc.zeroc.com/ice/3.7/release-notes/using-the-macos-binary-distribution -[2]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10 -[3]: https://en.wikipedia.org/wiki/Automatic_Reference_Counting + +[Getting started]: https://doc.zeroc.com/ice/3.7/hello-world-application/writing-an-ice-application-with-objective-c +[Examples]: https://github.com/zeroc-ice/ice-demos/tree/3.7/objective-c +[Documentation]: https://doc.zeroc.com/ice/3.7 +[Building from source]: https://github.com/zeroc-ice/ice/blob/3.7/objective-c/BUILDING.md +[Ice framework]: https://github.com/zeroc-ice/ice diff --git a/php/BUILDING.md b/php/BUILDING.md new file mode 100644 index 00000000000..bf9281b2974 --- /dev/null +++ b/php/BUILDING.md @@ -0,0 +1,362 @@ +# Ice for PHP Build Instructions + +This page describes how to build and install Ice for PHP from source. + +ZeroC provides [binary distributions] for many platforms, including +Linux and Windows, so building Ice for PHP from source is usually +unnecessary. + +* [PHP Build Requirements](#php-build-requirements) +* [Building the PHP Extension](#building-the-php-extension) + * [Linux or macOS](#linux-or-macos) + * [Windows](#windows) +* [Installing the PHP Extension](#installing-the-php-extension) + * [Linux or macOS](#linux-or-macos-1) + * [Windows](#windows-1) +* [PHP Dependencies](#php-dependencies) +* [PHP Source Files](#php-source-files) +* [Running the PHP Tests](#running-the-php-tests) +* [Web Server Permissions](#web-server-permissions) +* [SELinux Notes for PHP](#selinux-notes-for-php) + +## PHP Build Requirements + +Ice was extensively tested using the operating systems and compiler versions +listed on [supported platforms]. + +On Windows, the build requires a recent version of Visual Studio and the +[Ice Builder for Visual Studio]. + +## Building the PHP Extension + +### Linux or macOS + +The build of Ice for PHP requires that you first build Ice for C++ in the `cpp` +subdirectory. + +From the top-level source directory, edit `config/Make.rules` to establish +your build configuration. The comments in the file provide more information. + +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. + +Change to the `php` source subdirectory: + +```shell +cd php +``` + +Ensure that `php` and `php-config` for the version of PHP you wish to +build against are first in your PATH. + +Run `make` to build the extension. + +### Windows + +Open a Visual Studio command prompt. For example, with Visual Studio 2015, you +can open one of: + +* VS2015 x86 Native Tools Command Prompt +* VS2015 x64 Native Tools Command Prompt + +Using the first Command Prompt produces `Win32` binaries by default, while +the second Command Prompt produces `x64` binaries by default. + +In the Command Prompt, change to the `php` subdirectory: + +```shell +cd php +``` + +Now you're ready to build Ice for PHP: + +```shell +msbuild msbuild\ice.proj +``` + +This builds the extension with `Release` binaries for the default platform. The +extension will be placed in `lib\x64\Release\php_ice.dll` for the `x64` platform +and `lib\Win32\Release\php_ice.dll` for the `Win32` platform. + +The default configuration builds the extension against the thread-safe PHP run +time. You can build with the non-thread-safe run time using the `NTS-Release` or +`NTS-Debug` configuration: + +```shell +msbuild msbuild\ice.proj /p:Configuration=NTS-Release +``` + +The extension will be placed in `lib\x64\Release\php_ice_nts.dll` directory for +the `x64` platform and `lib\Win32\Release\php_ice_nts.dll` for the `Win32` +platform. + +The extension is built by default with namespaces enabled. You can build the PHP +extension with namespaces disabled by setting the MSBuild property +`PhpUseNamespaces` to `no`: + +```shell +msbuild msbuild\ice.proj /p:PhpUseNamespaces=no +``` + +The PHP extension is build by default using PHP 7.1, the extension can be build +with PHP 7.1, 7.2 or 7.3 by setting MSBuildProperty `BuildWithPhpVersion` to the +desired version for example you can use the following command to build the +extension with PHP 7.2: + +```shell +msbuild msbuild\ice.proj /p:BuildWithPhpVersion=7.2 +``` + +The PHP extension depends on Ice for C++ components from the `cpp` subdirectory, +and those are built if required. It is also possible to build the PHP extension +using the Ice for C++ NuGet packages by setting the`ICE_BIN_DIST` msbuild +property to `cpp`: + +```shell +msbuild msbuild\ice.proj /p:ICE_BIN_DIST=cpp +``` + +## Installing the PHP Extension + +### Linux or macOS + +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: + +```shell +php -i +``` + +Review the output for a line like this: + +```shell +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: + +```shell +extension = ice.so +``` + +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: + +```shell +Configuration File (php.ini) Path => /etc/php.ini +``` + +Open the configuration file and append the following line: + +```shell +extension = ice.so +``` + +You can verify that PHP is loading the Ice extension by running the command +shown below: + +```shell +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 macOS) 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. + +### Windows + +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: + +```shell +php -i +``` + +Review the output for a line like this: +``` +extension_dir => C:\Program Files\iis express\PHP\v7.1\ext\ => C:\Program Files\iis express\PHP\v7.1\ext\ +``` + +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: + +```shell +Loaded Configuration File => C:\Program Files\iis express\PHP\v7.1\php.ini +``` + +Open `php.ini` and append the following directive: + +```shell +extension=php_ice_nts.dll +``` + +Read the PHP Dependencies and PHP Source Files sections below for more +information about installing the Ice extension. + +## PHP Dependencies + +PHP needs to locate the libraries for the Ice run-time libraries and its +third-party dependencies. + +* Linux and macOS + +```shell +libIce +libIceDiscovery +libIceLocatorDiscovery +libIceSSL +libbz2 +``` + +* Windows + +```shell +bzip2.dll +ice37.dll +icediscovery37.dll +icelocatordiscovery37.dll +icessl37.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 Linux you can add the directory containing the Ice run-time +libraries to `/etc/ld.so.conf` and run `ldconfig`. + +For IIS configured to run PHP as FastCGI, the simplest solution is to copy the +libraries next to the `php-cgi.exe` in `C:\Program Files\iis express\PHP\v7.1`. + +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 + +``` + +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. + +## 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`) 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. For +example, you could append to `php.ini`: + +```ini +include_path=${include_path}";C\ice\php\lib" +``` + +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', +ini_get('include_path') . PATH_SEPARATOR . '/opt/Ice/php'); +require 'Ice.php'; // Load the core Ice run time definitions. +``` + +## 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 suites also 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: + +```shell +python allTests.py +``` + +If you have built the extension using the Ice for C++ NuGet packages, you must +also set the `ICE_BIN_DIST` environment variable to `cpp` for testing: + +```shell +set ICE_BIN_DIST=cpp +python allTests.py +``` + +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. + +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. + +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: + +```shell +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: + +```shell +setsebool httpd_can_network_connect=1 +``` + +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: + +```shell +chcon -R -t httpd_sys_content_t /opt/MyApp/slice +``` + +[binary distributions]: https://zeroc.com/downloads/ice +[supported platforms]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10 +[Ice Builder for Visual Studio]: https://github.com/zeroc-ice/ice-builder-visualstudio diff --git a/php/README.md b/php/README.md index 0c2c4261e0a..c7b07ec51c2 100644 --- a/php/README.md +++ b/php/README.md @@ -1,339 +1,39 @@ -# Building Ice for PHP +# Ice for PHP -This page describes how to build and install Ice for PHP from source. +[Getting started] | [Examples] | [Documentation] | [Building from source] -ZeroC provides [binary distributions][1] for many platforms, including -Linux and Windows, so building Ice for PHP from source is usually -unnecessary. +The [Ice framework] provides everything you need to build networked applications, +including RPC, pub/sub, server deployment, and more. -* [PHP Build Requirements](#php-build-requirements) -* [Building the PHP Extension](#building-the-php-extension) - * [Linux or macOS](#linux-or-macos) - * [Windows](#windows) -* [Installing the PHP Extension](#installing-the-php-extension) - * [Linux or macOS](#linux-or-macos-1) - * [Windows](#windows-1) -* [PHP Dependencies](#php-dependencies) -* [PHP Source Files](#php-source-files) -* [Running the PHP Tests](#running-the-php-tests) -* [Web Server Permissions](#web-server-permissions) -* [SELinux Notes for PHP](#selinux-notes-for-php) +Ice for PHP is the PHP implementation of the Ice framework. -## PHP Build Requirements +## Sample Code -Ice was extensively tested using the operating systems and compiler versions -listed on [supported platforms][2]. +```slice +// Slice definitions (Hello.ice) -On Windows, the build requires a recent version of Visual Studio and the -[Ice Builder for Visual Studio][3]. - -## Building the PHP Extension - -### Linux or macOS - -The build of Ice for PHP requires that you first build Ice for C++ in the `cpp` -subdirectory. - -From the top-level source directory, edit `config/Make.rules` to establish -your build configuration. The comments in the file provide more information. - -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. - -Change to the `php` source subdirectory: -``` -cd php -``` - -Ensure that `php` and `php-config` for the version of PHP you wish to -build against are first in your PATH. - -Run `make` to build the extension. - -### Windows - -Open a Visual Studio command prompt. For example, with Visual Studio 2015, you -can open one of: - -- VS2015 x86 Native Tools Command Prompt -- VS2015 x64 Native Tools Command Prompt - -Using the first Command Prompt produces `Win32` binaries by default, while -the second Command Promt produces `x64` binaries by default. - -In the Command Prompt, change to the `php` subdirectory: -``` -cd php -``` - -Now you're ready to build Ice for PHP: -``` -msbuild msbuild\ice.proj -``` - -This builds the extension with `Release` binaries for the default platform. The -extension will be placed in `lib\x64\Release\php_ice.dll` for the `x64` platform -and `lib\Win32\Release\php_ice.dll` for the `Win32` platform. - -The default configuration builds the extension against the thread-safe PHP run -time. You can build with the non-thread-safe run time using the `NTS-Release` or -`NTS-Debug` configuration: -``` -msbuild msbuild\ice.proj /p:Configuration=NTS-Release -``` - -The extension will be placed in `lib\x64\Release\php_ice_nts.dll` directory for -the `x64` platform and `lib\Win32\Release\php_ice_nts.dll` for the `Win32` -platform. - -The extension is built by default with namespaces enabled. You can build the PHP -extension with namespaces disabled by setting the MSBuild property -`PhpUseNamespaces` to `no`: -``` -msbuild msbuild\ice.proj /p:PhpUseNamespaces=no -``` - -The PHP extension is build by default using PHP 7.1, the extension can be build -with PHP 7.1, 7.2 or 7.3 by setting MSBuildProperty `BuildWithPhpVersion` to the -desired version for example you can use the following command to build the -extension with PHP 7.2: - -``` -msbuild msbuild\ice.proj /p:BuildWithPhpVersion=7.2 -``` - -The PHP extension depends on Ice for C++ components from the `cpp` subdirectory, -and those are built if required. It is also possible to build the PHP extension -using the Ice for C++ NuGet packages by setting the`ICE_BIN_DIST` msbuild -property to `cpp`: -``` -msbuild msbuild\ice.proj /p:ICE_BIN_DIST=cpp -``` - -## Installing the PHP Extension - -### Linux or macOS - -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 -``` - -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: -``` -extension = ice.so -``` - -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 -``` - -Open the configuration file and append the following line: -``` -extension = ice.so -``` - -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 macOS) 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. - -### Windows - -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 -``` - -Review the output for a line like this: -``` -extension_dir => C:\Program Files\iis express\PHP\v7.1\ext\ => C:\Program Files\iis express\PHP\v7.1\ext\ -``` - -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\iis express\PHP\v7.1\php.ini -``` - -Open `php.ini` and append the following directive: -``` -extension=php_ice_nts.dll -``` - -Read the PHP Dependencies and PHP Source Files sections below for more -information about installing the Ice extension. - -## PHP Dependencies - -PHP needs to locate the libraries for the Ice run-time libraries and its -third-party dependencies. - -* Linux and macOS -``` -libIce -libIceDiscovery -libIceLocatorDiscovery -libIceSSL -libbz2 -``` - -* Windows -``` -bzip2.dll -ice37.dll -icediscovery37.dll -icelocatordiscovery37.dll -icessl37.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 Linux you can add the directory containing the Ice run-time -libraries to `/etc/ld.so.conf` and run `ldconfig`. - -For IIS configured to run PHP as FastCGI, the simplest solution is to copy the -libraries next to the `php-cgi.exe` in `C:\Program Files\iis express\PHP\v7.1`. - -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: -``` - -``` - -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. - -## 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`) 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. For -example, you could append to `php.ini`: -``` -include_path=${include_path}";C\ice\php\lib" -``` - -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', -ini_get('include_path') . PATH_SEPARATOR . '/opt/Ice/php'); -require 'Ice.php'; // Load the core Ice run time definitions. -``` - -## 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 suites also 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 you have built the extension using the Ice for C++ NuGet packages, you must -also set the `ICE_BIN_DIST` environment variable to `cpp` for testing: -``` -set ICE_BIN_DIST=cpp -python allTests.py +module Demo +{ + interface Hello + { + void sayHello(); + } +} ``` -If everything worked out, you should see lots of `ok` messages. In case of a -failure, the tests abort with `failed`. +```php +// Client application (Client.php) +require_once 'Ice.php'; +require_once 'Hello.php'; -## 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. - -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. - -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: -``` -# setsebool httpd_can_network_connect=1 -``` - -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: -``` -# chcon -R -t httpd_sys_content_t /opt/MyApp/slice +$communicator = Ice\initialize(); +$hello = Demo\HelloPrxHelper::uncheckedCast( + $communicator->stringToProxy("hello:default -h localhost -p 10000")); +$hello->sayHello(); ``` -[1]: https://zeroc.com/downloads/ice -[2]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10 -[3]: https://github.com/zeroc-ice/ice-builder-visualstudio +[Getting started]: https://doc.zeroc.com/ice/3.7/hello-world-application/writing-an-ice-application-with-php +[Examples]: https://github.com/zeroc-ice/ice-demos/tree/3.7/php +[Documentation]: https://doc.zeroc.com/ice/3.7 +[Building from source]: https://github.com/zeroc-ice/ice/blob/3.7/php/BUILDING.md +[Ice framework]: https://github.com/zeroc-ice/ice diff --git a/python/BUILDING.md b/python/BUILDING.md new file mode 100644 index 00000000000..7005362ef40 --- /dev/null +++ b/python/BUILDING.md @@ -0,0 +1,165 @@ +# Ice for Python Build Instructions + +This document describes how to build and install Ice for Python from source. +You can also download and install a [binary distribution]. + +* [Building with Pip](#building-with-pip) +* [Building with Visual Studio 2015 and MSBuild (Python 3\.11 for Windows)](#building-with-visual-studio-2015-and-msbuild-python-311-for-windows) +* [Building on Linux or macOS](#building-on-linux-or-macos) +* [Configuring your Environment for Python](#configuring-your-environment-for-python) +* [Running the Python Tests](#running-the-python-tests) + +## Building with Pip + +You can build the Ice for Python extension from source using `pip`: + +```shell +pip install +``` + +## Building with Visual Studio 2015 and MSBuild (Python 3.11 for Windows) + +You can build an Ice for Python extension that links with the Ice C++ DLLs using Visual Studio and MSBuild. + +First, open a Visual Studio 2015 command prompt: + +* VS2015 x86 Native Tools Command Prompt + +or + +* VS2015 x64 Native Tools Command Prompt + +Using the first Command Prompt produces `Win32` binaries by default, while +the second Command Prompt produces `x64` binaries by default. + +In the Command Prompt, change to the `python` subdirectory: + +```shell +cd python +``` + +You must build Ice for C++ from the `cpp` subdirectory. If you have not done so, +refer to the [C++ build instructions](../cpp/BUILDING.md). + +Then build the extension: + +```shell +msbuild msbuild\ice.proj +``` + +This builds the extension with `Release` binaries for the default platform. The +extension will be placed in `python\x64\Release\IcePy.pyd` for the `x64` +platform and `python\Win32\Release\IcePy.pyd` for the `Win32` platform. + +If you want to build a debug version of the extension, set the MSBuild +`Configuration` property to `Debug`: + +```shell +msbuild msbuild\ice.proj /p:Configuration=Debug +``` + +The debug version of the extension will be placed in +`python\x64\Debug\IcePy_d.pyd` for the `x64` platform and +`python\Win32\Debug\IcePy_d.pyd` for the `Win32` platform. + +For Debug builds, a debug version of the Python interpreter must be installed +as well. + +If you want to build the extension for a different platform than the Command +Prompt's default platform, you need to set the MSBuild property `Platform`. The +supported values for this property are `Win32` and `x64`. + +The following command builds the `x64` platform binaries with the `Release` +configuration: + +```shell +msbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=x64 +``` + +This command builds the `Win32` platform binaries with the `Release` +configuration: + +```shell +msbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=Win32 +``` + +When using the MSBuild Platform property, the build platform doesn't depend +on the command prompt's default platform. + +The build will use the default location for Python defined in +`python\msbuild\ice.props`. You can override it by setting the `PythonHome` +MSBuild property. For example, the following command will use the Python +installation from `C:\Python310-AMD64` instead of the default location: + +```shell +msbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=x64 /p:PythonHome=C:\Python310-AMD64 +``` + +## Building on Linux or macOS + +Ice for Python supports Python versions 2.7 and 3.11. Note however that +your Python installation must have been built with a C++ compiler that is +compatible with the compiler used to build Ice for C++. + +The build of Ice for Python requires to first build Ice for C++ in the `cpp` +subdirectory. + +From the top-level source directory, edit `config/Make.rules` to establish your +build configuration. The comments in the file provide more information. + +Change to the Ice for Python source subdirectory: + +```shell +cd python +``` + +Execute `python -V` to verify that the correct Python interpreter is in your +executable search path. + +Run `make` to build the extension. + +Upon successful completion, run `make install`. You may need additional user +permissions to install in the directory specified by `config/Make.rules`. + +## Configuring your Environment for Python + +Modify your environment to allow Python to find the Ice extension for Python. +The python interpreter must be able to locate the IcePy extension 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 on Windows, with Ice for Python installed in `C:\Ice`: + +```shell +set PYTHONPATH=C:\Ice\python;C:\Ice\python\Win32\Release +``` + +For example on Linux or macOS, with Ice for Python installed in `/opt/Ice`: + +```shell +export PYTHONPATH=/opt/Ice/python +``` + +## Running the Python Tests + +After a successful build, you can run the tests as follows: + +Windows: + +```shell +python allTests.py --config=Release --platform=Win32 +``` + +(adjust `--config` and `--platform` to match your build) + +Linux/macOS: + +```shell +python allTests.py +``` + +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. + +[binary distribution]: https://zeroc.com/downloads/ice diff --git a/python/README.md b/python/README.md index 6643b8a2b3a..397d087eb78 100644 --- a/python/README.md +++ b/python/README.md @@ -1,145 +1,72 @@ -# Building Ice for Python +# Ice for Python -This document describes how to build and install Ice for Python from source. -You can also download and install a [binary distribution][1]. +[Getting started] | [Examples] | [Documentation] | [Building from source] -* [Building with Pip](#building-with-pip) -* [Building with Visual Studio 2015 and MSBuild (Python 3\.10 for Windows)](#building-with-visual-studio-2015-and-msbuild-python-310-for-windows) -* [Building on Linux or macOS](#building-on-linux-or-macos) -* [Configuring your Environment for Python](#configuring-your-environment-for-python) -* [Running the Python Tests](#running-the-python-tests) +The [Ice framework] provides everything you need to build networked applications, +including RPC, pub/sub, server deployment, and more. -## Building with Pip +Ice for Python is the Python implementation of the Ice framework. -You can build the Ice for Python extension from source using `pip`: -``` -pip install -``` - -## Building with Visual Studio 2015 and MSBuild (Python 3.11 for Windows) - -You can build an Ice for Python extension that links with the Ice C++ DLLs using Visual Studio and MSBuild. - -First, open a Visual Studio 2015 command prompt: - -- VS2015 x86 Native Tools Command Prompt -or -- VS2015 x64 Native Tools Command Prompt - -Using the first Command Prompt produces `Win32` binaries by default, while -the second Command Prompt produces `x64` binaries by default. - -In the Command Prompt, change to the `python` subdirectory: -``` -cd python -``` -You must build Ice for C++ from the `cpp` subdirectory. If you have not done so, -refer to the [C++ build instructions](../cpp/BuildInstructionsWindows.md). +## Sample Code -Then build the extension: -``` -msbuild msbuild\ice.proj -``` -This builds the extension with `Release` binaries for the default platform. The -extension will be placed in `python\x64\Release\IcePy.pyd` for the `x64` -platform and `python\Win32\Release\IcePy.pyd` for the `Win32` platform. +```slice +// Slice definitions (Hello.ice) -If you want to build a debug version of the extension, set the MSBuild -`Configuration` property to `Debug`: -``` -msbuild msbuild\ice.proj /p:Configuration=Debug +module Demo +{ + interface Hello + { + void sayHello(); + } +} ``` -The debug version of the extension will be placed in -`python\x64\Debug\IcePy_d.pyd` for the `x64` platform and -`python\Win32\Debug\IcePy_d.pyd` for the `Win32` platform. -For Debug builds, a debug version of the Python interpreter must be installed -as well. +```python +// Client application (client.py) +import sys +import Ice -If you want to build the extension for a different platform than the Command -Prompt's default platform, you need to set the MSBuild property `Platform`. The -supported values for this property are `Win32` and `x64`. +Ice.loadSlice('Hello.ice') +import Demo -The following command builds the `x64` platform binaries with the `Release` -configuration: -``` -msbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=x64 -``` -This command builds the `Win32` platform binaries with the `Release` -configuration: +# Ice.initialize returns an initialized Ice communicator, the communicator is destroyed +# once it goes out of scope. +with Ice.initialize(sys.argv) as communicator: + hello = Demo.HelloPrx.checkedCast( + communicator.stringToProxy("hello:default -h localhost -p 10000")) + hello.sayHello() ``` -msbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=Win32 -``` -When using the MSBuild Platform property, the build platform doesn't depend -on the command prompt's default platform. -The build will use the default location for Python defined in -`python\msbuild\ice.props`. You can override it by setting the `PythonHome` -MSBuild property. For example, the following command will use the Python -installation from `C:\Python310-AMD64` instead of the default location: -``` -msbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=x64 /p:PythonHome=C:\Python310-AMD64 -``` +```python +// Server application (server.py) -## Building on Linux or macOS +import signal +import sys +import Ice -Ice for Python supports Python versions 2.7 and 3.11. Note however that -your Python installation must have been built with a C++ compiler that is -compatible with the compiler used to build Ice for C++. +Ice.loadSlice('Hello.ice') +import Demo -The build of Ice for Python requires to first build Ice for C++ in the `cpp` -subdirectory. +class Printer(Demo.Hello): + def sayHello(self, current): + print("Hello World!") -From the top-level source directory, edit `config/Make.rules` to establish your -build configuration. The comments in the file provide more information. +# Ice.initialize returns an initialized Ice communicator, the communicator is destroyed +# once it goes out of scope. +with Ice.initialize(sys.argv) as communicator: -Change to the Ice for Python source subdirectory: + # Install a signal handler to shutdown the communicator on Ctrl-C + signal.signal(signal.SIGINT, lambda signum, frame: communicator.shutdown()) + if hasattr(signal, 'SIGBREAK'): + signal.signal(signal.SIGBREAK, lambda signum, frame: communicator.shutdown()) + adapter = communicator.createObjectAdapterWithEndpoints("Hello", "default -h localhost -p 10000") + adapter.add(Printer(), Ice.stringToIdentity("hello")) + adapter.activate() + communicator.waitForShutdown() ``` -cd python -``` - -Execute `python -V` to verify that the correct Python interpreter is in your -executable search path. - -Run `make` to build the extension. - -Upon successful completion, run `make install`. You may need additional user -permissions to install in the directory specified by `config/Make.rules`. - -## Configuring your Environment for Python - -Modify your environment to allow Python to find the Ice extension for Python. -The python interpreter must be able to locate the IcePy extension 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 on Windows, with Ice for Python installed in `C:\Ice`: -``` -set PYTHONPATH=C:\Ice\python;C:\Ice\python\Win32\Release -``` - -For example on Linux or macOS, with Ice for Python installed in `/opt/Ice`: -``` -export PYTHONPATH=/opt/Ice/python -``` - -## Running the Python Tests - -After a successful build, you can run the tests as follows: - -Windows: -``` -python allTests.py --config=Release --platform=Win32 -``` -(adjust `--config` and `--platform` to match your build) - -Linux/macOS: -``` -python allTests.py -``` - -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/downloads/ice +[Getting started]: https://doc.zeroc.com/ice/3.7/hello-world-application/writing-an-ice-application-with-python +[Examples]: https://github.com/zeroc-ice/ice-demos/tree/3.7/python +[Documentation]: https://doc.zeroc.com/ice/3.7 +[Building from source]: https://github.com/zeroc-ice/ice/blob/3.7/python/BUILDING.md +[Ice framework]: https://github.com/zeroc-ice/ice diff --git a/ruby/BUILDING.md b/ruby/BUILDING.md new file mode 100644 index 00000000000..df49c3210a5 --- /dev/null +++ b/ruby/BUILDING.md @@ -0,0 +1,172 @@ +# Ice for Ruby Build Instructions + +This file describes how to build and install Ice for Ruby from source code on +Linux and macOS. If you prefer, you can also download [binary distributions][1] +for the supported platforms. + +* [Ruby Build Requirements](#ruby-build-requirements) + * [Operating Systems and Compilers](#operating-systems-and-compilers) + * [Ruby Versions](#ruby-versions) +* [Building the Ruby Extension](#building-the-ruby-extension) +* [Installing Ice for Ruby](#installing-ice-for-ruby) +* [Configuring your Environment for Ruby](#configuring-your-environment-for-ruby) +* [Running the Ruby Tests](#running-the-ruby-tests) +* [SELinux Notes for Ruby](#selinux-notes-for-ruby) + +## Ruby Build Requirements + +### Operating Systems and Compilers + +Ice for Ruby is expected to build and run properly on macOS and 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 2.0 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 +* ruby-libs (RHEL) + +## Building the Ruby Extension + +The instructions for compiling the Ice extension assume that you have already +installed Ruby. + +The build of Ice for Ruby requires that you first build Ice for C++ in the +`cpp` subdirectory. + +From the top-level source directory, edit `config/Make.rules` to establish your +build configuration. The comments in the file provide more information. + +Change to the Ice for Ruby source subdirectory: + +```shell +cd ruby +``` + +Run `make` to build the extension. + +## Installing Ice for Ruby + +You can perform an automated installation with the following command: + +```shell +make install +``` + +This process uses the `prefix` variable in `../config/Make.rules` as the +installation's root directory. The subdirectory `/ruby` is created as a +copy of the local `ruby` directory and contains the Ice for Ruby extension +library as well as Ruby source code. Using this installation method requires +that you modify your environment as described in *Configuring your Environment +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: + +```shell +cd /ruby/ruby +sudo tar cf - * | (cd /usr/lib/ruby/site_ruby/1.8/i386-linux; tar xvf -) +``` + +On x86_64 systems, change the last command to: + +```shell +sudo tar cf - * | (cd /usr/lib64/ruby/site_ruby/1.8/x86_64-linux; tar xvf -) +``` + +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: + +```shell +export RUBYLIB=/opt/Ice/ruby:$RUBYLIB +``` + +This example assumes that your Ice for Ruby installation is located in the +`/opt/Ice` directory. + +You must also modify `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH` to include the +directory `/opt/Ice/lib`: + +```shell +export LD_LIBRARY_PATH=/opt/Ice/lib:$LD_LIBRARY_PATH (Linux) +export DYLD_LIBRARY_PATH=/opt/Ice/lib:$DYLD_LIBRARY_PATH (macOS) +``` + +To verify that Ruby can load the Ice extension successfully, open a command +window and start the interpreter using `irb`. + +At the prompt, enter: + +```shell +require "Ice" +``` + +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 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: + +```shell +python allTests.py +``` + +You can also run tests individually by changing to the test directory and +running this command: + +```shell +python run.py +``` + +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: + +```shell +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: + +```shell +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: + +```shell +SELINUX=disabled +``` + +[1]: https://zeroc.com/downloads/ice +[2]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10 diff --git a/ruby/README.md b/ruby/README.md index bd6d8f678b2..cc7a7162cbe 100644 --- a/ruby/README.md +++ b/ruby/README.md @@ -1,162 +1,41 @@ -# Building Ice for Ruby on Linux and macOS +# Ice for Ruby -This file describes how to build and install Ice for Ruby from source code on -Linux and macOS. If you prefer, you can also download [binary distributions][1] -for the supported platforms. +[Getting started] | [Examples] | [Documentation] | [Building from source] -* [Ruby Build Requirements](#ruby-build-requirements) - * [Operating Systems and Compilers](#operating-systems-and-compilers) - * [Ruby Versions](#ruby-versions) -* [Building the Ruby Extension](#building-the-ruby-extension) -* [Installing Ice for Ruby](#installing-ice-for-ruby) -* [Configuring your Environment for Ruby](#configuring-your-environment-for-ruby) -* [Running the Ruby Tests](#running-the-ruby-tests) -* [SELinux Notes for Ruby](#selinux-notes-for-ruby) +The [Ice framework] provides everything you need to build networked applications, +including RPC, pub/sub, server deployment, and more. -## Ruby Build Requirements +Ice for Ruby is the Ruby implementation of the Ice framework. -### Operating Systems and Compilers +## Sample Code -Ice for Ruby is expected to build and run properly on macOS and 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]. +```slice +// Slice definitions (Hello.ice) -### Ruby Versions - -Ice for Ruby supports Ruby versions 2.0 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 -ruby-libs (RHEL) -``` - -## Building the Ruby Extension - -The instructions for compiling the Ice extension assume that you have already -installed Ruby. - -The build of Ice for Ruby requires that you first build Ice for C++ in the -`cpp` subdirectory. - -From the top-level source directory, edit `config/Make.rules` to establish your -build configuration. The comments in the file provide more information. - -Change to the Ice for Ruby source subdirectory: -``` -cd ruby -``` - -Run `make` to build the extension. - -## Installing Ice for Ruby - -You can perform an automated installation with the following command: +module Demo +{ + interface Hello + { + void sayHello(); + } +} ``` -make install -``` - -This process uses the `prefix` variable in `../config/Make.rules` as the -installation's root directory. The subdirectory `/ruby` is created as a -copy of the local `ruby` directory and contains the Ice for Ruby extension -library as well as Ruby source code. Using this installation method requires -that you modify your environment as described in *Configuring your Environment -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: -``` -cd /ruby/ruby -sudo tar cf - * | (cd /usr/lib/ruby/site_ruby/1.8/i386-linux; tar xvf -) -``` - -On x86_64 systems, change the last command to: -``` -sudo tar cf - * | (cd /usr/lib64/ruby/site_ruby/1.8/x86_64-linux; tar xvf -) -``` - -There is no need to modify your environment if you use this approach. -## Configuring your Environment for Ruby +```ruby +// Client application (client.rb) +require 'Ice' -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 -``` +Ice::loadSlice('Hello.ice') -This example assumes that your Ice for Ruby installation is located in the -`/opt/Ice` directory. - -You must also modify `LD_LIBRARY_PATH` or `DYLD_LIBRARY_PATH` to include the -directory `/opt/Ice/lib`: -``` -export LD_LIBRARY_PATH=/opt/Ice/lib:$LD_LIBRARY_PATH (Linux) -export DYLD_LIBRARY_PATH=/opt/Ice/lib:$DYLD_LIBRARY_PATH (macOS) -``` - -To verify that Ruby can load the Ice extension successfully, open a command -window and start the interpreter using `irb`. - -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. - -## 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 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: -``` -python allTests.py -``` - -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`. - -## 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: -``` -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: - -``` -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: - -``` -SELINUX=disabled +Ice::initialize(ARGV) do |communicator| + hello = Demo::HelloPrx::checkedCast( + communicator.stringToProxy("hello:default -h localhost -p 10000")) + hello.sayHello() +end ``` -[1]: https://zeroc.com/downloads/ice -[2]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10 +[Getting started]: https://doc.zeroc.com/ice/3.7/hello-world-application/writing-an-ice-application-with-ruby +[Examples]: https://github.com/zeroc-ice/ice-demos/tree/3.7/ruby +[Documentation]: https://doc.zeroc.com/ice/3.7 +[Building from source]: https://github.com/zeroc-ice/ice/blob/3.7/ruby/BUILDING.md +[Ice framework]: https://github.com/zeroc-ice/ice diff --git a/swift/BUILDING.md b/swift/BUILDING.md new file mode 100644 index 00000000000..75f3beea222 --- /dev/null +++ b/swift/BUILDING.md @@ -0,0 +1,105 @@ +# Ice for Swift Build Instructions + +This file describes how to build Ice for Swift from source and how to test the +resulting build. + +- [Swift Build Requirements](#swift-build-requirements) + - [Operating Systems](#operating-systems) + - [Slice to Swift Compiler](#slice-to-swift-compiler) + - [Swift Version](#swift-version) + - [Carthage](#carthage) +- [Building Ice for Swift](#building-ice-for-swift) +- [Running the Swift Test Suite](#running-the-swift-test-suite) + - [macOS](#macos) + - [iOS](#ios) + +## Swift Build Requirements + +### Operating Systems + +Ice for Swift builds and runs on macOS and is supported on the platforms listed +on the [supported platforms] page. + +### Slice to Swift Compiler + +You need the Slice to Swift compiler to build Ice for Swift and also to use Ice +for Swift. The Slice to Swift compiler (`slice2swift`) is a command-line tool +written in C++. You can build the Slice to Swift compiler from source, or +alternatively you can install an Ice [binary distribution] that includes this +compiler. + +### Swift Version + +Ice for Swift requires Swift 5 or later. + +### Carthage + +Carthage must be installed to build Ice for Swift. You can install Carthage +using Homebrew: + +```shell +brew install carthage +``` + +## Building Ice for Swift + +First download and build the PromiseKit framework by running: + +```shell +carthage bootstrap --use-xcframeworks +``` + +from the root directory of your ice repository. + +Then open `ice.xcodeproj` with Xcode and build the `Ice macOS` or `Ice iOS` +targets. + +The test programs for macOS and iOS can be built using `TestDriver macOS` and +`TestDriver iOS` respectively. + +Building the `TestDriver iOS` application to deploy to an iOS device requires +signing the application with a developer certificate. You need to update the Xcode projects +to use your Apple development certificates by setting `DEVELOPMENT_TEAM` environment +variable to the Id of your development team and regenerate the projects with `rake`. + +```shell +export DEVELOPMENT_TEAM=U4TBVKNQ7F +rake +``` + +## Running the Swift Test Suite + +Python is required to run the test suite. + +### macOS + +After a successful build, you can run the tests as follows: + +```shell +python3 allTests.py --config Debug +``` + +If everything worked out, you should see lots of `ok` messages. In case of a +failure, the tests abort with `failed`. + +### iOS + +Start the `TestDriver iOS` application on your iOS device or simulator, from +Xcode. + +Then on your mac, run: + +```shell +python3 allTests.py --config Debug --platform iphoneos +``` + +or + +```shell +python3 allTests.py --config Debug --platform iphonesimulator +``` + +depending on your target. + +[binary distribution]: https://zeroc.com/downloads/ice +[supported platforms]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10 diff --git a/swift/README.md b/swift/README.md index fdb8b4ce7ab..478647ecd8c 100644 --- a/swift/README.md +++ b/swift/README.md @@ -1,98 +1,80 @@ -# Building Ice for Swift -This file describes how to build Ice for Swift from source and how to test the -resulting build. +# Ice For Swift -- [Building Ice for Swift](#building-ice-for-swift) - - [Swift Build Requirements](#swift-build-requirements) - - [Operating Systems](#operating-systems) - - [Slice to Swift Compiler](#slice-to-swift-compiler) - - [Swift Version](#swift-version) - - [Carthage](#carthage) - - [Building Ice for Swift](#building-ice-for-swift-1) - - [Running the Swift Test Suite](#running-the-swift-test-suite) - - [macOS](#macos) - - [iOS](#ios) +[Getting started] | [Examples] | [NuGet package] | [Documentation] | [Building from source] -## Swift Build Requirements +The [Ice framework] provides everything you need to build networked applications, including RPC, pub/sub, server deployment, and more. -### Operating Systems +Ice for Swift is the swift implementation of the Ice framework. -Ice for Swift builds and runs on macOS and is supported on the platforms listed -on the [supported platforms][2] page. +## Sample Code -### Slice to Swift Compiler +```slice +// Slice definitions (Hello.ice) -You need the Slice to Swift compiler to build Ice for Swift and also to use Ice -for Swift. The Slice to Swift compiler (`slice2swift`) is a command-line tool -written in C++. You can build the Slice to Swift compiler from source, or -alternatively you can install an Ice [binary distribution][1] that includes this -compiler. - -### Swift Version - -Ice for Swift requires Swift 5 or later. - -### Carthage - -Carthage must be installed to build Ice for Swift. You can install Carthage -using Homebrew: -``` -brew install carthage -``` - -## Building Ice for Swift - -First download and build the PromiseKit framework by running: -``` -carthage bootstrap --use-xcframeworks -``` -from the root directory of your ice repository. - -Then open `ice.xcodeproj` with Xcode and build the `Ice macOS` or `Ice iOS` -targets. - -The test programs for macOS and iOS can be built using `TestDriver macOS` and -`TestDriver iOS` respectively. - -Building the `TestDriver iOS` application to deploy to an iOS device requires -signing the application with a developer certificate. You need to update the Xcode projects -to use your Apple development certificates by setting `DEVELOPMENT_TEAM` environment -variable to the Id of your development team and regenerate the projects with `rake`. - -``` -export DEVELOPMENT_TEAM=U4TBVKNQ7F -rake +module Demo +{ + interface Hello + { + void sayHello(); + } +} ``` -## Running the Swift Test Suite - -Python is required to run the test suite. - -### macOS - -After a successful build, you can run the tests as follows: - -``` -python allTests.py --config Debug +```swift +// Client application +import Foundation +import Ice + +do { + let communicator = try Ice.initialize(CommandLine.arguments) + defer { + communicator.destroy() + } + + let hello = try uncheckedCast( + prx: communicator.stringToProxy("hello:default -h localhost -p 10000")!, + type: HelloPrx.self) + try hello.sayHello() +} catch { + print("Error: \(error)\n") + exit(1) +} ``` -If everything worked out, you should see lots of `ok` messages. In case of a -failure, the tests abort with `failed`. - -### iOS - -Start the `TestDriver iOS` application on your iOS device or simulator, from -Xcode. - -Then on your mac, run: -``` -python allTests.py --config Debug --platform iphoneos -``` -or -``` -python allTests.py --config Debug --platform iphonesimulator +```swift +// Server application +import Foundation +import Ice + +// Automatically flush stdout +setbuf(__stdoutp, nil) + +struct Printer: Hello { + func sayHello(current _: Ice.Current) throws { + print("Hello World!") + } +} + +do { + let communicator = try Ice.initialize(CommandLine.arguments) + defer { + communicator.destroy() + } + + let adapter = try communicator.createObjectAdapterWithEndpoints( + name: "Hello", + endpoints: "default -h localhost -p 10000") + try adapter.add(servant: HelloDisp(Printer()), id: Ice.stringToIdentity("hello")) + try adapter.activate() + communicator.waitForShutdown() +} catch { + print("Error: \(error)\n") + exit(1) +} ``` -depending on your target. -[1]: https://zeroc.com/downloads/ice -[2]: https://doc.zeroc.com/ice/3.7/release-notes/supported-platforms-for-ice-3-7-10 +[Getting started]: https://doc.zeroc.com/ice/3.7/hello-world-application/writing-an-ice-application-with-swift +[Examples]: https://github.com/zeroc-ice/ice-demos/tree/3.7/swift +[Documentation]: https://doc.zeroc.com/ice/3.7 +[Building from source]: https://github.com/zeroc-ice/ice/blob/3.7/swift/BUILDING.md +[Ice framework]: https://github.com/zeroc-ice/ice \ No newline at end of file