Packaging#

All packaging for OrangeQS Juice is done in Gitlab CI/CD. After pushing a commit you can download the artifacts of the CI job with the packaged system/Python package. However, if you need to build a package of your local changes for development purposes, you can follow this guide to package OrangeQS Juice locally.

Warning

Do not distribute packages built locally anywhere, packages built locally should only be used for local development! This guide is provided as a convenient service and is not meant as a way to build official packages for OrangeQS Juice.

Python package#

You can build a wheel for the OrangeQS Juice Python package using the build module from python:

pip3 install build
python3 -m build --outdir wheelhouse

The wheel will be placed at wheelhouse/orangeqs_juice_core-<version>-py3-none-any.whl.

System package#

OrangeQS Juice uses fpm to create system packages from the Python package. As the system package uses the python version provided by the system package manager, system packages should be built on the target distribution. These instructions are only test on AlmaLinux 10 for now. The instructions assumes you are packaging for Python 3.12, but any Python version available from the system package manager should work.

Hint

If you are using the dev container for development you can skip the first two steps as ruby and fpm are preinstalled. See Using a development container.

  1. Install a modern version of ruby (e.g. 3.4). You can either:

    • Install ruby using your system package manager, e.g. dnf install ruby.

    • Install ruby using rvm (Ruby Version Manager). Also install and activate some modern ruby version (e.g. 3.4).

  2. Install fpm 1.16.0 (Effing Package Management). Due to a bug with the virtualenv prefix in fpm 1.17.0 please install 1.16.0 specifically using gem install fpm -v 1.16.0. Also ensure you install any optional system dependencies.

  3. Install the Python version you want to use on the host system using the system package manager, for example dnf install python3.12 python3.12-pip.

  4. Run PYTHON_VERSION=3.12 PYTHON_BIN=/usr/bin/python3.12 ./packaging/fpm.sh -t rpm . to create a .rpm package. It is important to pass the correct PYTHON_VERSION and PYTHON_BIN to ensure that the package is built with the correct system Python version. This script will:

    • Install build dependencies from packaging/requirements.txt using pip in the user site package.

    • Build a wheel for the orangeqs-juice-core Python package.

    • Prepare a directory with the correct structure and files for fpm.

    • Run fpm to build the .rpm package.

The package will be placed at orangeqs-juice-core-<version>.noarch.rpm.

Limitations#

The current system packaging has multiple limitations:

  • It depends on Python from the system package manager.

  • It assumes the system Python package is called python<version>, e.g. python3.12.

  • The build environment should use the same python version and architecture as the target system.

Package contents#

The OrangeQS Juice system package consists of the following files and directories:

  • /opt/orangeqs/juice: an isolated virtual environment with the orangeqs-juice-core Python package installed. This virtual environment is using the system Python as its interpreter, but it does not rely on any Python packages from the system Python installation.

  • /opt/orangeqs/juice/bin/python: a symbolic link to the correct system Python binary, e.g. /usr/bin/python3.12.

  • /usr/bin/juice: a symbolic link to the juice CLI script of the orangeqs-juice-core Python package in the virtual environment.

  • /opt/orangeqs/juice/dist/orangeqs_juice_core-<version>-py3-none-any.whl: the wheel file for the orangeqs-juice-core Python package. This will be used as the installation source for the orangeqs-juice-core package inside containerized environments. This way we do not rely on an external Python package index. See Containerized environments for more information.