Installation Guide

This module relies heavily on C++ wrapped using pybind11. You can obtain a working copy through the Python Package Index using pip or by compiling the source after downloading it from the brille Github repository.

pip

With an up-to-date version of pip you can install brille via

pip install brille

This will download a precompiled binary of the latest released version of the module or download its source code and compile the module if a precompiled binary does not exist for your system.

Note:

Windows systems must have the Microsoft Visual C++ Redistributable binaries in order to load the PyPI distributed brille module. If you are faced with the error

>>> import brille

ImportError: DLL load failed while importing _brille: The specified module could not be found

please install the latest x64 Visual C++ redistributable package from Microsoft.

source

If your development environment has git, Python ≥ 3.6, a C++17 compliant compiler, and CMake ≥ 3.13, then you can build the latest version of brille from source via

git clone https://github.com/brille/brille
cd brille
python setup.py install

Note:: The CMake build will look for pybind11 and Catch2 header files on your system. If they are not present or not a supported version, they will be downloaded automatically from their respective Github repositories.

debug

If you encounter the need to debug the _brille module, you can compile and install with debugging symbols via

git clone https://github.com/brille/brille
cd brille
python setup.py debug_install

which is an alias for python setup.py build --debug install

development

If you plan to modify the pure Python submodules, e.g., brille.plotting, you may benefit from constructing from source using the develop option.

git clone https://github.com/brille/brille
cd brille
python setup.py develop

This allows any modifications to the Python source files to be immediately available to the Python interpreter; where otherwise the install command would need to be re-run (which rebuilds the C++ module) each time you would like to test your modifications.

restricted user access

On some systems the default installation location used by pip install and python setup.py install is read-only for standard users. While one could use an administrator or root account to perform the install in such a case, a safer alternative is to specify a user-accessible installation directory via

pip install --user brille

or

python setup.py --user install

legacy linux systems

If the available compiler and pip versions are too old and can not be upgraded you may find that pip reports that the manylinux2010 versions available on PyPI are incompatible with your system and building from source may also fail. This is known to apply to RHEL7 based systems but may affect others as well.

In such a case you can produce a suitable installable package on another system by replicating the manylinux build system. For the specific case of RHEL7, starting on a system with devtoolset-7 installed run

scl enable devtoolset-7 bash
git clone https://github.com/brille/brille.git
python3 -m pip wheel -w wheelhouse brille

which produces a file like brille-0.5.0-cp36-cp36m-linux_x86_64.whl that can be copied to the target system. To install the brille package on the target machine one then runs

pip install --user brille-0.5.0-cp36-cp36m-linux_x86_64.whl

or similar.