Building Ice for Python from Source

Table of Contents

• Build roadmap
• Building Ice for Python from source
  • Prerequisites
  • Building Ice for Python
  • Running the tests
  • Generating the API reference
• Building the Python packages
  • Creating Python packages

Build roadmap

This document describes two distinct build workflows:

1. Source Build: Builds Ice for Python directly from the source tree. This build requires a prior build of Ice for C++ and is typically used for development, testing, packaging for Linux distributions, and contributing to Ice for Python.

   flowchart LR
       c++(Ice for C++) --> python(Ice for Python)
       python -- doc --> api(API Reference)
       python --> tests(Tests)
   

2. Python Package Build: Builds standalone Python packages from the source tree. This workflow does not require Ice for C++ and is intended for producing distributable packages (e.g., wheels) for PyPI or internal use.

Building Ice for Python from source

This build compiles Ice for Python directly from the source tree and requires a prior build of Ice for C++.

Prerequisites

1. Python 3.12 or later

2. Ice for C++ source build

3. Python dependency for Glacier2 tests The Glacier2 test suite requires the passlib package.

Building Ice for Python

Before building Ice for Python, you must first build the Ice for C++ source distribution. Refer to the build instructions in the cpp subdirectory for details.

Once Ice for C++ is built, open a command prompt and navigate to the python subdirectory. To build Ice for Python, run the following commands:

On Linux and macOS:

make

On Windows:

MSBuild msbuild\ice.proj

This builds Ice for Python for the default platform and configuration (i.e., x64/Release).

By default, the Windows build uses the Python installation located at:

• C:\Program Files\Python314 for x64 builds
• C:\Program Files (x86)\Python314-32 for Win32 builds

If your Python installation is in a different location, set the PythonHome MSBuild property:

MSBuild msbuild\ice.proj /p:PythonHome=C:\Python314

You can select a different platform and configuration by setting the MSBuild Platform and Configuration properties. For example, to build for Win32 in debug mode:

MSBuild msbuild\ice.proj /p:Platform=Win32 /p:Configuration=Debug

Running the tests

To run the tests, open a command prompt and change to the python subdirectory. Then run:

python allTests.py --all

Generating the API reference

To build the API reference documentation, run the following commands from the python/docs subdirectory:

1. Create and activate a Python virtual environment:

   python -m venv venv
   source venv/bin/activate  # On macOS/Linux
   venv\Scripts\activate     # On Windows
   

2. Install the documentation dependencies:

   pip install -r requirements.txt
   

3. Build the documentation:

   make html
   

Building the Python packages

This build process creates standalone Python packages without requiring a prior Ice for C++ build.

Creating Python packages

1. Create and activate a Python virtual environment:

   python -m venv venv
   source venv/bin/activate  # On macOS/Linux
   venv\Scripts\activate     # On Windows
   

2. Install the build package:

   pip install build
   

3. Build the Python package:

   python -m build
   

The resulting wheel and source distribution files will be placed in the dist/ directory.