CMAKE in OpenFHE
OpenFHE uses CMake to create the Makefiles that build and install the OpenFHE Library. This page describes how CMake is used in OpenFHE, and how contributors should use CMake when adding new files or new components.
Using OpenFHE’s CMake system
The first step in using CMake is deciding where the build should be performed. This is the “build tree”. The “source tree” is where the OpenFHE source is located. These should be different directories! The build tree can be in a subdirectory of the source directory (such as “build”) or in some other place.
The project is described in files named CMakeLists.txt
.
CMake is run in the build tree. The source tree is passed to CMake as an argument on the command line. CMake will create a Makefile in the build tree. Once this is done, make can be run inside of the build tree.
Therefore the basic steps are:
cd build-tree-location
cmake {other CMake arguments} source-tree-location
make
CMake does not usually have to be rerun. A make
will rerun CMake if it detects changes to any of the project’s CMakeLists.txt files.
Required Compilers
OpenFHE supports any GNU C++ compiler version 9 or above and clang C++ compiler version 10 or above.
A warning is issued if an older version of the compiler is found. The build may run but such compilers are unsupported.
Required Packages
OpenFHE requires that certain packages and applications be available on the system. CMake searches for these packages and may either stop if a required package is missing, or disable functionality.
These packages are as follows:
OpenMP
Autoconfig tools (for some third party code)
Git
Optional Packages
Doxygen (if not found, generating Doxygen files is disabled)
Sphinx (if not found, generating Sphinx documentation is disabled)
Command Line Options
There are a large number of CMake command line options. Most important for our purposes here is the -D option, which allows variables to be set, cached, and used in constructing the Makefile and making OpenFHE.
Combining multiple CMake flags
Different flags can be combined together. For example, to configure cmake with NTL, tcmalloc, MATHBACKEND 6, and have it run in the debug mode, the following command can be used:
cmake -DCMAKE_BUILD_TYPE=Debug -DWITH_NTL=ON -DWITH_TCM=ON -DMATHBACKEND=6 ..
Important CMake Flags Used
We point out a number of the standard CMake variables that can be set using -D from the CMake command line, which may be of use to OpenFHE users. To set one of these variables, use -D*VARIABLE_NAME*=*VALUE* on the command line.
VARIABLE_NAME
Definition
Notes
CMAKE_INSTALL_PREFIX
Base directory for installs
Base directory for installation of OpenFHE. Libraries are installed in ${CMAKE_INSTALL_PREFIX}/lib and include files are installed in ${CMAKE_INSTALL_PREFIX}/include/openfhe. OpenFHE is also exported as a CMake package for the benefit of any users wanting to use OpenFHE; the package files are also installed here
CMAKE_BUILD_TYPE
Debug, Release
Default is to build OpenFHE for release, with no debug information; developers may want to specify -DCMAKE_BUILD_TYPE=Debug
Flags for OpenFHE Builds
The OpenFHE build has a number of options to control what is built and what features are included/excluded.
Each of the options is enabled by saying -DOPTION_NAME=ON
and is disabled by saying -DOPTION_NAME=OFF
The table below shows the current list of options, definition for the option, and a default value.
OPTION_NAME
Description
Default
BUILD_UNITTESTS
Set to ON to build unit tests for the library
ON
BUILD_EXAMPLES
Set to ON to build examples for the library
ON
BUILD_BENCHMARKS
Set to ON to build benchmarks for the library
ON
BUILD_EXTRAS
Set to ON to build extra examples for the library
OFF
BUILD_SHARED
Set to ON to include shared versions of the library
ON
BUILD_STATIC
Set to ON to include static versions of the library
OFF
WITH_BE2
Include Backend 2 in build by setting WITH_BE2 to ON
ON
WITH_BE4
Include Backend 4 in build by setting WITH_BE4 to ON
ON
WITH_NTL
Include Backend 6 and NTL in build by setting WITH_NTL to ON
OFF
WITH_TCM
Activate tcmalloc by setting WITH_TCM to ON
OFF
WITH_OPENMP
Use OpenMP to enable <omp.h>
ON
WITH_NATIVEOPT
Use machine-specific optimizations (major speedup for clang)
OFF
NATIVE_SIZE
Set default word size for native integer arithmetic to 64 or 128 bits
64
CKKS_M_FACTOR
Parameter used to strengthen the CKKS adversarial model in scenarios where decryption results are shared among multiple parties (See Security.md for more details)
1
Note
More Options will be added as development progresses
The default math backend for the OpenFHE build is Backend 2 (basic fixed-maximum-length big integers). This default can be changed on the CMake command line by setting the MATHBACKEND variable. For example, to select backend 6 (high performance fixed integers based on the GMP and NTL libraries), use -DMATHBACKEND=6
on the CMake command line.
Detecting Local Environments
OpenFHE detects most of the capabilities of the target machine. It uses the machine’s capabilities and the values of the user options to create header files that are used to control the build. These files are placed in the src subdirectory of the CMake build tree, and are included in the OpenFHE install.
src/core/config_core.h
is used to control the build of the core component, and any library code that depends on it. Future developments will expand this to other components.
Third-Party Components
OpenFHE uses some third-party components from Google for testing and benchmarking, and it uses a third-party serialization library called CEREAL. These libraries are git submodules under OpenFHE and are fully integrated into the build.
Turn on NTL/GMP (Only for Advanced Users)
By default OpenFHE builds without external dependencies. If you wish to use the NTL/GMP
implementation of BigInteger/BigVector
, you can [install GMP and NTL manually](Instructions-for-installing-GMP-and-NTL) and run cmake with -DWITH_NTL=ON
. The complete command is
cmake -DWITH_NTL=ON ..
We have tested OpenFHE with GMP 6.1.2
and 6.2.1
, and NTL 10.5.0
and 11.4.4
.
Note
A regular binary install (using tools like apt-get
) will not work
Special compilation flags need to be passed. See Instructions for installing GMP and NTL
Note
The performance w/o and w NTL is almost the same for all schemes/operations
NTL is used only for multiprecision integer arithmetic. The latter only when
MATHBACKEND
is set to6
.Most crypto operations are executed using native arithmetic (employing RNS procedures) and do not use higher-precision capabilities.
Turn on tcmalloc
If you wish to use tcmalloc, you can add -DWITH_TCM=ON
to the cmake command. The complete command is
cmake -DWITH_TCM=ON ..
tcmalloc can improve performance in the multi-threaded mode (when OMP_NUM_THREADS>1). It provides efficient thread-caching block allocation for all OpenFHE objects.
Note
tcmalloc
only works in Linux and macOS, and is not currently supported in MinGW
.
Tcmalloc should be installed after running cmake and right before running make for OpenFHE. To build tcmalloc, run
make tcm
To remove tcmalloc, run
make tcm_clean
Location of Build Products
The Makefile created by CMake creates all OpenFHE build products inside the build subdirectory.
The actual libraries are placed in the subdirectory lib.
Third party libraries are placed in third-party/lib.
Unit tests are placed in unittest.
Benchmarks are placed in bin/benchmark.
Examples (of basic OpenFHE features) are placed in bin/examples, and additional examples (more complicated and research-oriented examples) are placed in bin/extras. Note demos are built as part of each sub-component of the library (core, pke, trapdoor, etc.)
Documentation (built in the build directory under
<BUILD_LOCATION>/docs/doxygen/
for DOXYGEN builds, and<BUILD_LOCATION>/docs/sphinx
for Sphinx builds)
Installing OpenFHE on your system for use by applications external to the OpenFHE source tree
Running make install will install all libraries and header files in the directories designated by CMAKE_INSTALL_PREFIX
. Demos, unittests, benchmarks, examples and extras are not installed.
Building applications with an installed OpenFHE library
A user can create a CMake environment for their own OpenFHE application development. Simply copy the file CMakeLists.User.txt from the OpenFHE source tree to CMakeLists.txt in your source tree, and add your CMake directives for your own programs to the end of the file.
This file imports the OpenFHE package that was built and installed by the OpenFHE build.
Cross Compiling with CMake [experimental feature]
Cross compiling OpenFHE for other target environments is an experimental feature. Cross-compilation for new targets should require the following steps:
Obtain and configure a cross-compiler for your target environment (or use the appropriate command line arguments to your compiler to initiate cross compilation).
Specify that CMake should use the cross-compiler.
Proceed with the CMake/make process.
Note
third-party libgmp and NTL libraries will probably need to be built manually for cross compilation using their internal build sequence, and that they may not be supported on the target platform at all. Configuring OpenFHE with -DWITH_NTL=ON will circumvent this issue.
Documentation for extending OpenFHE CMake Files
CMake Files for OpenFHE Components
Each component of the library (core, pke, trapdoor, etc.) has its own CMakeLists.txt file. Each of these files is included by the main OpenFHE CMakeLists.txt file. The structure of all of these component CMakeList.txt files is identical:
Determine the files that are built into the component library
Set include directories to build the component library
Set the version number from the OpenFHE version number
Add rules to build the objects in the component library
Add rules to build and install the component library, dynamic as well as static
If unit tests are included in the build, add rules to build unit tests
Add rules to build all the source files in the demo directory into demos
Add targets to build “all” of various pieces of the component
Adding a new file to OpenFHE
A new file can simply be added to the directory tree, and CMake will add it to the build.
Adding a new component to OpenFHE
When adding a new component to OpenFHE
Observe the structure discussed above when making your new CMakeLists.txt for the component
Be sure to include the component in the main CMakeLists.txt file at the root of the source tree
Be sure to update the “all” targets to include targets from the new component
Documentation of make targets created by OpenFHE CMake system
When make
is run without any target specified, it builds:
all modules,
unit tests (if
BUILD_UNITTESTS=ON
),examples (if
BUILD_EXAMPLES=ON
),benchmarks (if
BUILD_BENCHMARKS=ON
),and extras (if
BUILD_EXTRAS=ON
).
Note
OpenFHE also provides more granular control over which components of OpenFHE are built.
We discuss these options below. Each of these commands can be used instead of make
in the main build instructions.
Note
for many users, it may be easier to rely on CMake flags BUILD_UNITTESTS
, BUILD_EXAMPLES
, and the like,
to control what is built using the standard make command without specifying a target.
Build only the library files
make allmodules
Build library files + main examples (available if BUILD_EXAMPLES=ON)
make allexamples
Build additional examples (not built as part of default build)
make allextras
Build library files + unit tests + run all tests (available if BUILD_UNITTESTS=ON)
make testall
Build only benchmarks and their dependencies (available if BUILD_BENCHMARKS=ON)
make allbenchmark
Build a specific module and its dependencies
The options for the make command are OPENFHEcore, OPENFHEpke, OPENFHEabe, OPENFHEsignature, OPENFHEbinfhe (these correspond to core, pke, abe, signature, and binfhe modules). To install pke, enter
make OPENFHEpke
Build a specific module + examples (available if BUILD_EXAMPLES=ON)
Using pke as an example, enter
make allpkeexamples
Build a specific module + additional examples (available if BUILD_EXTRAS=ON)
Using pke as an example, enter
make allpkeextras
Build a specific module + unit tests (available if BUILD_UNITTESTS=ON)
Using pke as an example, enter
make pke_tests
Build a specific module + unit tests (if BUILD_UNITTESTS=ON) + examples (if BUILD_EXAMPLES=ON)
Using pke as an example, enter
make allpke