How FreeCAD uses Pixi

This is a guest blog post by Jackson Oursland - a FreeCAD maintainer and esteemed member of the conda-forge and Pixi community! FreeCAD uses Conda packages to build AppImages, DMG and Windows artifacts. Pixi greatly simplifies the developer workflow.

FreeCAD is a popular open source 3D CAD modeling, simulation, and analysis project in development since 2001 and available publicly since 2002. FreeCAD is developed and supported on Windows, Linux, and macOS, with some users on FreeBSD. At the foundation its functionality is provided by many software dependencies including Python, Qt, VTK, and many others (339 dependency packages are installed in my development environment). Each OS platform brings its own dependencies and configurations. Managing the software dependencies and build configurations for such a project in a cross-platform is always a challenge.

Years ago, Lorenz Lechner (@looooo) simplified the release build process in a cross-platform manner by implementing a conda-forge package management system for the FreeCAD project. This package management system is used by the weekly builds and tagged releases for the Linux AppImage, macOS DMG, and Windows .7z artifacts available on the FreeCAD GitHub releases page. A walkthrough of this system was presented at the 2023 FreeCAD Users Conference, held at the University of Pretoria in South Africa. A video of the talk can be found on YouTube.

In 2023, we integrated scripts to automate the installation of the conda-forge dependencies and build configuration in order to create developer environments that were cross-platform and matched the weekly builds. Then these scripts were added as build platforms to the FreeCAD continuous integration (CI) pipeline. While this was greatly beneficial for developers and an improvement over per-platform or per-distribution instructions, it did have two major drawbacks:

• configuration scripts and environment management

• dependency updates breaking build environments

In order to ensure that the build system depends upon only the conda-forge packages and not on any other packages installed on the host, the environment must be configured correctly. A script was added to aid in configuring this environment, but the behavior was inconsistent depending upon the developer's preferred IDE. It was not uncommon for FreeCAD to build but not run due to mismatched dependencies and runtime environment errors.

The second issue arises from updates occurring to dependency packages upstream. At environment installation time, the latest compatible versions of each dependency is installed. While it is often ideal for new versions with bug fixes or enhancements to be included in the build, a lack of explicit version pinning means is that individual developers could have different packages installed, resulting in difference of behavior. Worse yet is that the continuous integration system could fail to build because a newer version of a dependency was uploaded, rendering CI unsuitable for the task it was designed to perform.

It did not take long before the build failures started impacting CI such that developer forward progress was stalled. A tool that could pin these dependencies to known good versions while also making version upgrades easy would be a real boon to the project.

Enter Pixi

Lorenz had been experimenting with a new conda-forge package management tool, Pixi, and it was clear that this was going to be exactly what we needed. As with our existing conda-forge scripts, we merely specify the packages we need in an environment in the pixi.toml file, and Pixi resolves the packages to a pixi.lock file for all supported platforms. Later invocations of Pixi would use these known good versions of dependencies, eliminating the uncertainty that a given developer's environment or CI environment may break due to upstream changes. Updating the version pinnings is as simple as running the command pixi update.

Fixing versioning issues isn't all Pixi provides, it also provides configurations and commands. For those familiar with Node's npm or Rust's cargo, it's a bit like that with conda-forge for the dependency packages. With these new powers we quickly adopted Pixi to manage the package dependencies, but also the build configuration, and running of the build artifacts. We went from a relatively complicated set of instructions to get a functioning build system to running the following three commands on all three operating systems:

• pixi run configure

• pixi run build

• pixi run freecad

We're in the process of expanding our use of Pixi to help manage the different tests and improvements to IDE integration. What's really exciting is our progress on migrating our building of the FreeCAD installers from a custom collection of scripts in a release repository to an integrated component in the main repository, using the same pixi.toml that developers already use.

Pixi has been extremely valuable in helping FreeCAD unify and simplify developer environments, which has been vital in onboarding new contributors. Any project, open source or otherwise, looking to simplify cross-platform developer environment management should consider Pixi. It's quite possible that Pixi is exactly what the project needs.