Skip to content

Commit

Permalink
More README fixes
Browse files Browse the repository at this point in the history
  • Loading branch information
@pepone
pepone committed Oct 9, 2023
1 parent 3f175b2 commit 230c844
Show file tree
Hide file tree
Showing 5 changed files with 421 additions and 275 deletions.
3 changes: 2 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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

Expand Down
165 changes: 165 additions & 0 deletions python/BUILDING.md
View file
Original file line number Diff line number Diff line change
@@ -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 <URL of Ice source distribution for Python>
```

## 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
177 changes: 53 additions & 124 deletions python/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,145 +1,74 @@
# 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 Ice.

You can build the Ice for Python extension from source using `pip`:
```
pip install <URL of Ice source distribution for Python>
```

## 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:
## Sample Code

- VS2015 x86 Native Tools Command Prompt
or
- VS2015 x64 Native Tools Command Prompt
```slice (Hello.ice)
#pragma once
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
module Demo
{
interface Hello
{
void sayHello();
}
}
```
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).

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.
```python
// Client application (client.py)
import sys
import 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
```
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`.
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.

From the top-level source directory, edit `config/Make.rules` to establish your
build configuration. The comments in the file provide more information.
class Printer(Demo.Hello):
def sayHello(self, current):
print("Hello World!")

Change to the Ice for Python source subdirectory:
```
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
# Ice.initialize returns an initialized Ice communicator, the communicator is destroyed
# once it goes out of scope.
with Ice.initialize(sys.argv) as communicator:

After a successful build, you can run the tests as follows:

Windows:
```
python allTests.py --config=Release --platform=Win32
# 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()
```
(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
Loading

0 comments on commit 230c844

Please sign in to comment.