CI/CD & Build System
Relevant source files
The following files were used as context for generating this wiki page:
Parashell utilizes a robust build infrastructure centered around CMake (minimum version 3.22.0) to manage cross-platform compilation and dependency resolution. As a fork of FreeCAD, the project inherits complex build configurations that support a wide array of third-party libraries, automated testing via CTest, and comprehensive documentation generation.
The CI/CD pipeline is integrated with GitHub Actions, facilitating automated builds, weekly release notes, and mandatory validation for contributions. Every pull request is required to compile cleanly and pass project self-tests on all target platforms before being considered for merging into the main branch.
Sources: CMakeLists.txt:2, CONTRIBUTING.md:1-5, 96-97, .github/workflows/weekly-build-notes.md
Build Configuration and Presets
The build system is driven by a root-level CMakeLists.txt file and standardized configuration presets defined in CMakePresets.json. These presets allow developers to maintain consistent build environments for debugging and release versions across different compilers.
Versioning and Project Metadata
Project metadata, including versioning info, is extracted from a centralized version.json file. This data is used to propagate version strings across the entire application and build artifacts.
| Parameter | Extraction Method | Purpose |
|---|---|---|
PROJECT_NAME | string(JSON ... "name") | Defines the CMake project name. |
PACKAGE_VERSION | MAJOR.MINOR.PATCH | Used for build identification and library versioning. |
COPYRIGHT_YEAR | string(TIMESTAMP ... "%Y") | Automatically updates the package copyright year. |
Sources: CMakeLists.txt:60-75, CMakePresets.json
Build Optimization and Security
Parashell provides built-in support for ccache to speed up subsequent compilations and offers advanced memory and thread sanitizers for GNU and Clang compilers.
- ccache Integration: Enabled via the
FREECAD_USE_CCACHEoption. It auto-detects the presence ofccacheand sets it as the compiler launcher for both C and C++. - Compiler Sanitizers: Developers can enable AddressSanitizer (ASan), LeakSanitizer (LSan), ThreadSanitizer (TSan), UndefinedBehaviorSanitizer (UBSan), and MemorySanitizer (MSan) through advanced CMake options to detect runtime errors.
Sources: CMakeLists.txt:43-56, 80-99
Build Process Flow
The following diagram illustrates the high-level configuration and dependency resolution flow executed during a CMake run.
The build system ensures that all critical components, such as OpenCasCade and Qt, are correctly configured before proceeding to compile the source code in the src directory.
Sources: CMakeLists.txt:104-169
Documentation Build System
Parashell supports automated documentation generation using Doxygen and Sphinx. These tools extract documentation directly from source files and specialized markdown templates.
Documentation Targets
The build system defines specific targets for documentation:
- DevDoc: A target that copies templates and runs Doxygen to generate comprehensive developer-facing documentation.
- WebDoc: A lightweight version of the documentation optimized for web hosting.
BuildDoc.py Script
For legacy or manual documentation builds, a Python script src/Tools/fcbt/BuildDoc.py is provided. This script automates the Doxygen execution, handles log file creation, and organizes the resulting HTML output into the doc/SourceDocumentation directory.
Sources: src/Doc/CMakeLists.txt:98-111, src/Tools/fcbt/BuildDoc.py:20-43
CI/CD and Contribution Pipeline
The project enforces strict quality control through its GitHub CI integration. The release cycle includes automated "weekly builds" which are summarized in generated notes.
Continuous Integration Requirements
| Requirement | Description |
|---|---|
| Clean Compilation | All commits in a PR must compile without errors on all target platforms. |
| Self-Tests | Contributions must pass project self-tests (integrated via CTest). |
| Target Branch | All changes must target the main branch; topic branches are restricted to personal forks. |
| Stable Releases | Releases are created by tagging the repository on the main branch. |
Sources: CONTRIBUTING.md:92-100, 163-166, CMakeLists.txt:185-189
Build Flow for Contributions
The process for validating a new contribution involves multiple build-system checks.
Sources: CONTRIBUTING.md:96-97, CMakeLists.txt:185-189
Conclusion
The Parashell CI/CD and Build System provides a highly automated environment for managing FreeCAD-based software development. By leveraging CMake's flexibility for dependency management and GitHub Actions for continuous validation, the project ensures that the codebase remains stable across multiple platforms while facilitating rapid documentation and release cycles.
Sources: CMakeLists.txt:193-195