Customising Your Build

The following CMake build options and their default values are listed here if you'd like to tweak the build process:

BUILD_TESTS       ON   Build tests (does not automatically run them).
BUILD_DEFS        ON   Auto-generate C/C++ headers and documentation.
RUN_ANYWHERE      OFF  Build a framework that can run from any folder without installation.
PARASOL_INSTALL   ON   Create installation targets.  If OFF, the build won't install anything.
INSTALL_EXAMPLES  OFF  Install the example scripts.
INSTALL_INCLUDES  OFF  Install the header files.
INSTALL_TESTS     OFF  Install the test programs.
ENABLE_ANALYSIS   OFF  Enable run-time address analysis if available.  Incompatible with gdb.
PARASOL_VLOG      OFF  Enable verbose log messages in the generated binaries.
DISABLE_SSL       OFF  Disable built-in SSL support even if available on this system.
DISABLE_X11       OFF  Disable X11 even if available on this system (Linux/Unix only).
DISABLE_CPACK     OFF  Disable CPack Windows packaging support.

Static Builds

Parasol is built as a series of APIs such as 'core', 'display', 'network' and 'vector'. Each API is compiled as an individual component. A default system build compiles the APIs as shared libraries, as it prevents scripts and programs from loading unnecessary features.

If you're using Parasol for a specific run-time application that you're developing, you probably want a static build so that the framework is embedded with your application. In addition, you can choose each specific API needed for your program - so if you didn't need networking, that entire category of features can be switched off for faster compilation and a smaller binary.

To enable a static build, use the -DPARASOL_STATIC=ON build option. Your program's cmake file should link to the framework with target_link_libraries (your_program PRIVATE ${INIT_LINK}).

To choose the API's that you need, see the next section.

Disabling APIs

By default, every available API will be compiled in the framework unless they are individually switched off. You can disable a given API with -DDISABLE_<API_NAME>=TRUE, where <API_NAME> is one of the following choices:

AUDIO      Audio API
DISPLAY    Display API
DOCUMENT   Document API   Dependent on Display, Vector, Font
FONT       Font API       Dependent on Display
HTTP       HTTP API       Dependent on Network
MP3        MP3 support    Dependent on Audio
NETWORK    Network API
PICTURE    Picture API    Dependent on Display
JPEG       JPEG support   Dependent on Picture
SCINTILLA  Scintilla API  Dependent on Display, Vector, Font
SVG        SVG support    Dependent on Display, Vector, Font
VECTOR     Vector API     Dependent on Display, Font

If you disable an API that has child dependencies, the dependent APIs will not be included in the build. For instance, disabling Network will also result in HTTP being disabled.

Advanced Build Options

Verbose Logging

Use -DPARASOL_VLOG=ON to enable verbose log messages throughout the framework. This is useful for debugging and understanding internal operations, but will increase binary size and reduce performance. Log messages will only be visible if you run programs with the --log-api or --log-trace command-line options.

SSL Configuration

By default, Parasol will use the system's SSL implementation if available (OpenSSL on Linux, native SSL on Windows). To disable SSL support entirely, use -DDISABLE_SSL=ON. This will prevent the Network and HTTP modules from using encrypted connections.

Note that if SSL is enabled, the build system automatically manages SSL certificate bundles:

  • Certificate bundle location: data/ssl/ca-bundle.crt
  • Automatic updates: If the bundle is older than 30 days, it will be refreshed from https://curl.se/ca/cacert.pem during the CMake configuration phase
  • The certificate bundle is installed with the framework and used for HTTPS connections

X11 Windowing System

On Linux and Unix systems, X11 support is automatically detected and enabled if available. To explicitly disable X11 even when it's available on your system, use -DDISABLE_X11=ON. This is useful for headless server builds or when using alternative display systems.

Address Sanitizer

For development builds, you can enable address and leak sanitizers with -DENABLE_ANALYSIS=ON. This enables:

  • Address sanitizer (-fsanitize=address)
  • Leak sanitizer (-fsanitize=leak)
  • Automatic detection of memory errors, buffer overflows, and memory leaks

Important notes:

  • Requires a static build (-DPARASOL_STATIC=ON)
  • Disables Audio API automatically (incompatible with analysis)
  • May interfere with GDB breakpoints
  • Significantly impacts performance - use only for testing
  • On Windows with MSVC, you may need to add the sanitizer DLL path to your environment

Windows Packaging

If building on Windows, CPack integration is enabled by default to create distribution packages. To disable this, use -DDISABLE_CPACK=ON. CPack supports:

  • ZIP archives for portable distribution
  • NSIS installers (for modular builds)
  • Self-extracting archives (requires 7-Zip)

See the Windows Builds documentation for more details on creating release packages.

Installation Targets and Paths

Installation Directory Structure

The framework's installation layout depends on the RUN_ANYWHERE option:

With RUN_ANYWHERE=TRUE (portable builds):

CMAKE_INSTALL_PREFIX/
├── parasol[.exe]          # Main executable
├── lib/                   # Modules and libraries
├── config/                # Configuration, fonts, styles, SSL certs
│   ├── fonts/
│   ├── styles/
│   └── ssl/
└── scripts/               # Fluid standard library

With RUN_ANYWHERE=FALSE (system-wide installation):

CMAKE_INSTALL_PREFIX/
├── bin/
│   └── parasol            # Main executable
├── lib/parasol/           # Modules and libraries
└── share/parasol/         # Shared data
    ├── config/
    ├── scripts/
    └── examples/ (if INSTALL_EXAMPLES=ON)

Common Installation Scenarios

Local development build:

cmake -S . -B build -DCMAKE_INSTALL_PREFIX=local -DRUN_ANYWHERE=TRUE

System-wide installation (Linux):

cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/usr/local
sudo cmake --install build

Portable Windows build:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DRUN_ANYWHERE=TRUE -DCMAKE_INSTALL_PREFIX=parasol-win64

Installation Verification

After installation, the framework automatically runs a verification step:

parasol --log-warning --gfx-driver=headless --verify

This rebuilds the class database (config/classes.bin) and verifies that all modules load correctly. If this step fails, check that all dependencies are satisfied and modules are in the correct locations.

Base Assets

A default build will not only produce compiled binaries, but additional assets such as fonts, icons, UI scripts and utilities. These are considered standard items and their deletion may have unintended consequences - for instance removing certain fonts could impact UI presentation. We don't provide the ability to disable them for that reason, but if a build needs to be trimmed further then we suggest a post-build script to remove unwanted assets in a targeted manner.