Building from source#

To build the fresnel Python package from source:

$ <package-manager> install cmake git python numpy pybind11 qhull embree
$ <package-manager> install pillow pytest

Obtain the source:

$ git clone --recursive https://github.com/glotzerlab/fresnel

Configure:
```
$ cmake -B build/fresnel -S fresnel
```
Build the package:
```
$ cmake --build build/fresnel
```
Install the package (optional):
```
$ cmake --install build/fresnel
```

To build the documentation from source (optional):

Install prerequisites:

$ <package-manager> install sphinx sphinx_rtd_theme nbsphinx ipython

Build the documentation:

$ sphinx-build -b html fresnel/doc build/fresnel-documentation

The sections below provide details on each of these steps.

Install prerequisites#

fresnel requires a number of tools and libraries to build. The options ENABLE_EMBREE and ENABLE_OPTIX each require additional libraries when enabled.

Note

This documentation is generic. Replace <package-manager> with your package or module manager. You may need to adjust package names and/or install additional packages, such as -dev packages that provide headers needed to build fresnel.

Tip

Create a virtual environment, one place where you can install dependencies and fresnel:

$ python3 -m venv fresnel-venv

You will need to activate your environment before configuring fresnel:

$ source fresnel-venv/bin/activate

General requirements:

C++14 capable compiler (tested with GCC 7-12, Clang 6-14, Visual Studio 2019-2022)
CMake >= 3.8
pybind11 >= 2.2
Python >= 3.6
numpy
Qhull >= 2015.2
For CPU execution (required when ENABLE_EMBREE=ON):
- Intel TBB >= 4.3.20150611
- Intel Embree >= 4.0.0
For GPU execution (required when ENABLE_OPTIX=ON):
- OptiX >= 6.0, < 7.0
- CUDA >= 10

Optional runtime dependencies:

pyside2

To run tests:

pillow
pytest

To build the documentation:

sphinx
sphinx_rtd_theme
nbsphinx
ipython

Obtain the source#

Clone using Git:

$ git clone --recursive https://github.com/glotzerlab/fresnel

Release tarballs are also available on the downloads page.

Configure#

Use CMake to configure a fresnel build in the given directory. Pass -D<option-name>=<value> to cmake to set options on the command line. When modifying code, you only need to repeat the build step to update your build - it will automatically reconfigure as needed.

Tip

Use Ninja to perform incremental builds in less time:

$ cmake -B build/fresnel -S fresnel -GNinja

Tip

Place your build directory in /tmp or /scratch for faster builds. CMake performs out-of-source builds, so the build directory can be anywhere on the filesystem.

Tip

Pass the following options to CMake to optimize the build for your processor: -DCMAKE_CXX_FLAGS=-march=native -DCMAKE_C_FLAGS=-march=native

Important

When using a virtual environment, activate the environment and set the cmake prefix path before running CMake: $ export CMAKE_PREFIX_PATH=<path-to-environment>

fresnel’s cmake configuration accepts a number of options.

Options that find libraries and executables only take effect on a clean invocation of CMake. To set these options, first remove CMakeCache.txt from the build directory and then run cmake with these options on the command line.

PYTHON_EXECUTABLE - Specify which python to build against. Example: /usr/bin/python3.
- Default: python3.X detected on $PATH.
<package-name>_DIR - Specify the location of a package.
- Default: Found on the CMake search path.

Other option changes take effect at any time:

ENABLE_EMBREE - When enabled, build the CPU backend using Embree (default: on).
BUILD_OPTIX - When enabled, build the GPU backend using OpTiX (default: off).
CMAKE_BUILD_TYPE - Sets the build type (case sensitive) Options:
- Debug - Compiles debug information into the library and executables. Enables asserts to check for programming mistakes. fresnel will run slow when compiled in Debug mode, but problems are easier to identify.
- RelWithDebInfo - Compiles with optimizations and debug symbols.
- Release - (default) All compiler optimizations are enabled and asserts are removed. Recommended for production builds.
CMAKE_INSTALL_PREFIX - Directory to install fresnel. Defaults to the root path of the found Python executable.
PYTHON_SITE_INSTALL_DIR - Directory to install fresnel to relative to CMAKE_INSTALL_PREFIX. Defaults to the site-packages directory used by the found Python executable.

Build the package#

The command cmake --build build/fresnel will build the fresnel Python package in the given build directory. After the build completes, the build directory will contain a functioning Python package.

Note

Pass --config <CONFIG> to build a specific configuration when using a multi-configuration generator such as Visual Studio:

cmake --build build/fresnel --config Release

Note

When using a multi-configuration generator, the Python package is built in build/fresnel/<CONFIG>.

Install the package#

The command cmake --install build/fresnel installs the given fresnel build to ${CMAKE_INSTALL_PREFIX}/${PYTHON_SITE_INSTALL_DIR}. CMake autodetects these paths, but you can set them manually in CMake.

Note

Pass --config <CONFIG> to install a specific configuration when using a multi-configuration generator such as Visual Studio.

Build the documentation#

Run Sphinx to build the documentation with the command sphinx-build -b html fresnel/sphinx-doc build/fresnel-documentation. Open the file build/fresnel-documentation/index.html in your web browser to view the documentation.

Tip

When iteratively modifying the documentation, the sphinx options -a -n -W -T --keep-going are helpful to produce docs with consistent links in the side panel and to see more useful error messages:

$ sphinx-build -a -n -W -T --keep-going -b html \
    fresnel/sphinx-doc build/fresnel-documentation