Installation & Packaging
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Parashell project utilizes a CMake-based build and packaging system to manage dependencies, compile core components, and organize modules into a distributable software package. The system is designed to handle multi-platform requirements, including specific logic for Windows installers and macOS application bundles.
The packaging process involves collecting binaries, Python scripts, resource files (icons, presets, UI files), and third-party libraries into a structured directory hierarchy. This ensures that the application can be run directly from the build tree during development or installed as a standalone package for end-users. Sources: CMakeLists.txt:1-10, src/Mod/BIM/CMakeLists.txt:180-195
Build System Architecture
The primary build orchestration is handled by the root CMakeLists.txt, which configures global settings, detects system dependencies, and iterates through subdirectories for core libraries and workbenches.
Core Build Stages
- Environment Setup: Configures CMake policies, compiler launchers (like ccache), and version information from a
version.jsonfile. - Dependency Management: Finds and configures required libraries such as Python, Qt, Boost, OpenCasCade, and XercesC.
- Component Compilation: Builds the source tree, including internal 3rd-party libraries like
libE57Format. - Module Aggregation: Gathers workbench-specific files (e.g., BIM, CAM, Assembly) and copies them to the build tree.
- Packaging Target Creation: Generates the final installation targets for various platforms.
Sources: CMakeLists.txt:1-120, CMakeLists.txt:170-190
Dependency Flow
The following diagram illustrates how CMake orchestrates the discovery and linking of dependencies before creating the final build targets.
Workbench Packaging
Workbenches (modules) follow a standardized installation pattern. Using the BIM workbench as an example, the process involves defining source lists and using custom CMake functions to populate the build and installation trees.
File Distribution Categories
| Category | File Types | Target Location |
|---|---|---|
| Scripts | .py | Mod/<WorkbenchName>/ |
| Resources | .svg, .csv, .json | data/Mod/<WorkbenchName>/Resources/ |
| Translations | .ts, .qm | Mod/<WorkbenchName>/translations/ |
| UI Files | .ui, .qrc | Mod/<WorkbenchName>/ (often wrapped as Python) |
Sources: src/Mod/BIM/CMakeLists.txt:15-175, src/Mod/BIM/CMakeLists.txt:240-300
Developer Workflow Features
To facilitate rapid development, the system supports symlinking. By setting INSTALL_PREFER_SYMLINKS=ON, source files are symlinked into the build directory rather than copied, allowing changes to Python or resource files to take effect without a re-build. Sources: src/Mod/BIM/CMakeLists.txt:185-205
Platform-Specific Packaging
macOS Application Bundles
On macOS, Parashell is packaged as a .app bundle. This includes specific plugins like QuickLook extensions for file previews. The packaging script ensures that the extensions are placed in Contents/PlugIns and have the correct Bundle Identifiers.
Documentation Packaging
Documentation is generated using Doxygen and Sphinx. The build system creates specific targets for different documentation types:
- DevDoc: Comprehensive technical documentation including source code analysis.
- WebDoc: A lightweight version optimized for web hosting.
- Sphinx: Manuals and user documentation in HTML or PDF formats.
The generated HTML files are installed to the ${CMAKE_INSTALL_DOCDIR} directory. Sources: src/Doc/CMakeLists.txt:45-100, src/Doc/sphinx/make.bat:45-60
3rd Party Library Integration
Internal 3rd-party libraries like libE57Format are integrated into the main build system but maintain their own CMake configuration. They can be built as either static or shared libraries based on the E57_BUILD_SHARED option.
libE57Format Build Configuration
| Option | Default | Description |
|---|---|---|
E57_BUILD_SHARED | OFF | Compile as a shared library instead of static. |
E57_VALIDATION_LEVEL | 1 | Runtime validation (0=OFF, 1=basic, 2=deep). |
E57_RELEASE_LTO | ON | Enable Link-Time Optimization for release builds. |
Sources: src/3rdParty/libE57Format/CMakeLists.txt:75-105, src/3rdParty/libE57Format/CMakeLists.txt:130-150
Contribution and Release Process
Packaging is tied to the project release cycle. Stable releases are always tagged and released from the main branch. Contributors are required to ensure that their Pull Requests (PRs) compile cleanly and pass self-tests on all target platforms before they are merged into the packaging flow. Sources: CONTRIBUTING.md: Section 5, 7
Release Workflow
Sources: CONTRIBUTING.md: Section 6, 7