To build the fresnel Python package from source:
-
$ <package-manager> install cmake git python numpy pybind11 qhull embree $ <package-manager> install pillow pytest
-
$ git clone --recursive https://github.com/glotzerlab/fresnel
-
$ cmake -B build/fresnel -S fresnel
-
$ cmake --build build/fresnel
Install the package (optional):
$ cmake --install build/fresnel
To build the documentation from source (optional):
-
$ <package-manager> install sphinx sphinx_rtd_theme nbsphinx ipython
-
$ sphinx-build -b html fresnel/doc build/fresnel-documentation
The sections below provide details on each of these steps.
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
Clone using Git:
$ git clone --recursive https://github.com/glotzerlab/fresnel
Release tarballs are also available on the downloads page.
.. seealso:: See the `git book`_ to learn how to work with Git repositories.
Warning
fresnel uses Git submodules. Clone with the --recursive
to clone the submodules.
Execute git submodule update --init
to fetch the submodules each time you switch branches
and the submodules show as modified.
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 whichpython
to build against. Example:/usr/bin/python3
.- Default:
python3.X
detected on$PATH
.
- Default:
<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 inDebug
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 installfresnel
to relative toCMAKE_INSTALL_PREFIX
. Defaults to thesite-packages
directory used by the found Python executable.
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>
.
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.
Run Sphinx to build the documentation with the command
sphinx-build -b html fresnel/sphinx-doc build/fresnel-documentation
. Open the file
: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