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

The wheel will be placed at dist/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. Ensure that you don’t have any virtual environment activated, e.g. running which python3.12 should show /usr/bin/python3.12.

  5. Run PYTHON_VERSION=3.12 ./packaging/fpm.sh -t rpm . to create a .rpm package. It is possible to create other types of packages using fpm, e.g. -t deb .. Note that this is untested and may not work correctly!

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.

  • /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.