Build ITK Module Python packages¶
ITK is organized into modules. Modules for ITK can be developed outside the ITK source tree as external modules. The external module can be made available in ITK’s CMake configuration by contributing it as a remote module. Python packages can also be generated for external modules and uploaded to the Python Package Index (PyPI)
This section describes how to create, build, and upload ITK external module Python packages to PyPI.
Building wheels requires:
- C++ Compiler - Platform specific requirements are summarized in scikit-build documentation.
Create the module¶
To create an ITK module with Python wrapping, first run cookiecutter:
python -m pip install cookiecutter python -m cookiecutter gh:InsightSoftwareConsortium/ITKModuleTemplate # Fill in the information requested at the prompts
GitHub automated CI package builds¶
Freely available continous integration (CI) testing services for open source repositories on GitHub can be used to generate Linux, macOS, and Windows Python packages for your module.
After enabling builds for the GitHub repository with a CircleCI, TravisCI, and AppVeyor account, Python wheel packages will be available with the continuous integration builds. These services use the configurations generated by the ITKModuleTemplate.
Automated platform scripts¶
Automated scripts are available in this repository to build Python packages that are binary compatible with the Python distributions provided by Python.org, Anaconda, and package managers like apt or Homebrew. The following sections outline how to use the associated scripts for Linux, macOS, and Windows.
Once the builds are complete, Python packages will be available in the dist directory.
To build portable Python packages on Linux, first install Docker.
For the first local build, clone the ITKPythonPackage repository inside your and download the required ITK binary builds:
cd ~/ITKMyModule git clone https://github.com/InsightSoftwareConsortium/ITKPythonPackage ./ITKPythonPackage/scripts/dockcross-manylinux-download-cache-and-build-module-wheels.sh
For subsequent builds, just call the build script:
First, install the Python.org macOS Python distributions. This step requires sudo:
cd ~/ITKMyModule git clone https://github.com/InsightSoftwareConsortium/ITKPythonPackage ./ITKPythonPackage/scripts/macpython-install-python.sh
Then, build the wheels:
First, install Microsoft Visual Studio 2015, Git, and CMake, which should be added to the system PATH environmental variable.
Open a PowerShell terminal as Administrator, and install Python:
PS C:\> Set-ExecutionPolicy Unrestricted PS C:\> $pythonArch = "64" PS C:\> iex ((new-object net.webclient).DownloadString('https://raw.githubusercontent.com/scikit-build/scikit-ci-addons/master/windows/install-python.ps1'))
In a PowerShell prompt, run the windows-build-wheels.ps1 script:
PS C:\Windows> cd C:\ITKMyModule PS C:\ITKMyModule> git clone https://github.com/InsightSoftwareConsortium/ITKPythonPackage.git IPP PS C:\ITKMyModule> .\ITKPythonPackage\scripts\windows-download-cache-and-build-module-wheels.ps1
Upload the packages to PyPI¶
First, register for an account on PyPI.
Next, create a ~/.pypirc file with your login credentials:
[distutils] index-servers = pypi pypitest [pypi] username=<your-username> password=<your-password> [pypitest] repository=https://test.pypi.org/legacy/ username=<your-username> password=<your-password>
where <your-username> and <your-password> correspond to your PyPI account.
Then, upload wheels to the testing server:
python -m pip install twine python -m twine upload -r pypitest dist/*
Check out the packages on https://test.pypi.org/ the testing server.
Finally, upload the wheel packages to the production PyPI server:
python -m twine upload dist/*
Congratulations! Your packages can be installed with the commands:
python -m pip install --upgrade pip python -m pip install itk-<yourmodulename>