User References

Global CMake Build Options

One can pass several options to the build system to tweak its behavior. This is done by passing some special CMake variables (called CMake options) to the build system.

There are 2 kinds of CMake options

• temporary options, used to create a special build for debugging or testing,
• permanent ones that changes the global build behavior. They usually imply changes in the source code itself.

For the first category, the temporary ones, the usual way to modify these options is to use the CMAKEFLAGS environment variable. By changing its value, the top wrapper Makefile of an Elements-based project passes new option to the CMake underlying process.

The List of Options

Name	Default Value	Type	Desc ription	Remark	Since Version
EL EMENTS_ HIDE_SY MBOLS	OFF	Pe rmanent	enable e xplicit symbol vis ibility on gcc-4. With that flag, all symbols of a library are hidden by d efault. They have to be exp licitly exposed with the `` ELEMENT S_API`` macro defined in the El ementsK ernel/E xport.h file	This switch is exp licitly ON for E lements only	N/A
EL EMENTS_ CPP11	ON / OFF	Pe rmanent	enable C++11 l anguage dialect	It is only active for co mpilers that support it	N/A / 5.12
EL EMENTS_ CPP14	OFF / ON	Pe rmanent	enable C++14 l anguage dialect	It is only active for co mpilers that support it	N/A / 5.12
ELEME NTS_PAR ALLEL	OFF	Pe rmanent	enable C++11 p arallel support with OpenMP. Please look `here < https:/ /gcc.gn u.org/o nlinedo cs/libs tdc++/m anual/p arallel _mode.h tml>`__ for more infor mations	Experi mental. U ntested	N/A
ELEM ENTS_FO RTIFY	ON	Pe rmanent	enable g fortify option. The `` -D_FORT IFY_SOU RCE=2`` option is passed to the compi lation. Please look `here < https:/ /access .redhat .com/bl ogs/766 093/pos ts/1976 213>`__ for more d etailed expla nations	It is only used for the builds with some kind of optim ization (- O...)	N/A
US E_LOCAL _INSTAL LAREA	OFF	Te mporary	Use local Inst allArea for the Dev elopers	The top wrapper M akefile of the project is always passing `` -DUSE_L OCAL_IN STALLAR EA=ON`` to CMake	N/A
BUILD _PREFIX _NAME	`` build``	Te mporary	Prefix name for the build di rectory	The top wrapper M akefile of the project is always passing ` -DBUIL D_PREFI X_NAME: STRING= build` to CMake. It creates the `` build.$ {BINARY _TAG}`` dir ectory. If there is no BIN ARY_TAG in the envir onment, the build di rectory becomes just “b uild”	N/A
OPT_ DEBUG	ON	Te mporary	Enable optim isation for the Debug v ersion. It adds the -Og for the debug build.	Full de bugging c apacity r equires to set this option to OFF	N/A
ELEM ENTS_LI NKOPT	OFF	Pe rmanent	Enable Link Time Optim isation	Experi mental. It will only be active for op timized builds	N/A
USE _PYTHON _NOSE	OFF	Pe rmanent	Prefer the Nose test runner instead of the default PyTest one	By d efault, Nose will only be used as a f allback if PyTest is not found.	N/A
` ELEMEN TS_USE_ RPATH`	ON	Pe rmanent	Use full RPATH for both build and insta llation	By d efault, CMake only uses RPATH for the local build and strips the RPATH during instal lation. With this flag e nabled, The RPATH is also used at install time. It is r elative for the links of the same project and a bsolute for the e xternal ones.	4.1
H IDE_SYS INC_WAR NINGS	OFF	Pe rmanent	Hide System i ncludes w arnings by using -is ystem instead of -I for 3rd party s oftware	Useful for li braries like Eigen3	4.1
C XX_SUGG EST_OVE RRIDE	OFF	Pe rmanent	Enable the ` -Wsugg est-ove rride` gcc warning	Warn about ove rriding virtual fu nctions that are not marked with the o verride k eyword. This is a good but i nvasive option that has to be decided by the project ma nagers.	4.1
USE_S PHINX	ON	Pe rmanent	Use sphinx docume ntation gen eration	It will only work if the sphin x-build binary can be found by CMake	4.1
` USE_DO XYGEN`	ON	Pe rmanent	Use doxygen docume ntation gen eration	It will only work if the doxygen binary can be found by CMake	4.1
USE_S PHINX_A PIDOC	ON	Pe rmanent	Use sphinx API docume ntation gen eration	This setting is po intless if the ` USE_SP HINX fl ag is o n OFF`	4.1
` USE_SP HINX_BR EATHE`	OFF	Pe rmanent	Use sphinx C API Breathe plugin to bind to doxygen	idem	4.1
S PHINX_B UILD_OP TIONS	(empty)	Te mporary	pass some extra options to the sphin x-build exe cutable		4.1
SP HINX_AP IDOC_OP TIONS	(empty)	Te mporary	pass some extra options to the sphinx -apidoc exe cutable		4.1
CMAK E_USE_C CACHE	OFF	Te mporary	Use ccache to speed up comp ilation	Only works if the ccache exe cutable is found by CMake	N/A
CMAK E_USE_D ISTCC	OFF	Te mporary	Use distcc to speed up comp ilation	Only works if the distcc exe cutable is found by CMake. This enables the distr ibution of the build over several ma chines. Please read the distcc docume ntation first	N/A
ELEM ENTS_US E_STRIC T_BINAR Y_DEP	OFF	Te mporary	Use the same build variant (opt, dbg, o2g, etc) for the lookup of the de pendent p roject. St rictly. The co nfigure step will break if it is not found.	If the option is ` OFF`, the same build variant is tried first and then it falls back to try the other ones (o2g, opt, dbg, pro, cov, min in that order)	N/A
E LEMENTS _BUILD_ TESTS	ON	Te mporary	Set to ON to disable the build of the tests (li braries and execut ables).		N/A
USE_D EFAULT_ RPMBUIL D_DIR	OFF	Te mporary	Use default RPM build di rectory (the value of the % _topdir r pmbuild var iable). You can get the l ocation by calling	It the option is set to ` OFF`, the default l ocation is set to <p roject> /build. ${BINAR Y_TAG}/ Package s/RPM	N/A
`` RPMBUIL D_EXTRA _ARGS``	(empty)	Te mporary	Pass extra a rgument to the r pmbuild command line		4.1
SQUE EZED_IN STALL	ON	Te mporary	This option enables the special insta llation in a pure C MAKE_IN STALL_P REFIX lo cation. Without the project di rectory and the project version	The default value is ON for a pure CMake build ( without the top Mak efile). If the top wrapper M akefile is used the default value is OFF	5.0
CPACK _REMOVE _SYSTEM _DEPS	OFF	Te mporary	This option removes the depen dencies onto the system pa ckages.	Useful with a non-s tandard RPM d atabase lo cation.	5.2.1
CPAC K_USE_C CACHE	OFF	Te mporary	Use ccache to speed up comp ilation for the p ackages c reation	Only works if the ccache exe cutable is found by CMake	5.2.1
CPAC K_USE_D ISTCC	OFF	Te mporary	Use distcc to speed up comp ilation for the p ackages c reation	Only works if the distcc exe cutable is found by CMake. This enables the distr ibution of the build over several ma chines. Please read the distcc docume ntation first	5.2.1
SANI TIZE_OP TIONS	OFF	Te mporary	A ctivate the s anitize feature of gcc	It has to be su pported by the version of GCC. Please also read the desc ription and remark of the option below	5.2.1
SA NITIZE_ STYLE	unde fined	Te mporary	Sets the s anitize style in use. By default it is the unde fined san itizer. But other are po ssible: `` leak``, add ress, th read. Please have a look at the GCC documen tation.	The corres ponding s anitize library has to be ins talled. For e xample, lib ubsan is the Un defined B ehavior Sa nitizer library	5.2.1
RPM_ FORWARD _PREFIX _PATH	ON	Te mporary	Forward the CMA KE_PREF IX_PATH to the RPM c reation		5.2.1
DATA _MODULE _PATH	${XD G_DATA_ HOME}:$ {XDG_DA TA_DIRS }:/usr/ share	Pe rmanent	Lookup path entries for the [[N ewUserM anual#D ata-Mod ules-si nce-ver sion-54	data mo dules]]	If the X DG_DATA envi ronment va riables don’t exist, the default is /usr/ share	5.4
ELE MENTS_D ATA_SUF FIXES	` DBASE; PARAM;E XTRAPAC KAGES`	Pe rmanent	Lookup path s uffixes for the [[N ewUserM anual#D ata-Mod ules-si nce-ver sion-54	data mo dules]]		5.4
PYTH ON_EXPL ICIT_VE RSION	(empty)	Pe rmanent	use the ` python ${PYTHO N_EXPLI CIT_VER SION}` exec utable. Useful to switch from python to python3	A lthough it is meant to be per manent, it is passed through the CMAKE FLAGS envi ronment v ariable with the top level M akefile	N/A
CO NCEPT_C HECKS	OFF	Te mporary	This add the ` -D_GLI BCXX_CO NCEPT_C HECKS` compile macro. This a ctivate some i nternal check from the std c l ibrary. See https:/ /gcc.gn u.org/o nlinedo cs/libs tdc/man ual/usi ng_macr os.html		5.4
U SE_ENV_ FLAGS	OFF	Pe rmanent	It allows the envi ronment va riables CXX FLAGS and C FLAGS to be used by the builder		5.8
`` USE_RPM _CMAKE_ MACRO``	OFF	Pe rmanent	It forces the RPM spec file to use the %__ cmake RPM macro for the build instead of the plain `` cmake`` command	The U SE_ENV_ FLAGS is set to ON when this one is enabled	5.8
` ELEMEN TS_DEFA ULT_LOG LEVEL`	` INFO`	Pe rmanent	set the default log level for E lements proper m essages at compile time	the default is `` DEBUG`` for a build in s queezed (non- euclid) mode	5.8
TES T_XML_R EPORT	OFF	Te mporary	g enerate XML reports for the boost tests ( instead of HRF)		5.12
U SER_SPH INX_NUM PYDOC	ON	Pe rmanent	Use numpy doc format for sphinx		5.12
`` DEBUG_F ORMAT``	(empty)	Te mporary	set the debug format at compile time tuning the -g gcc option	It has to be used with ` DEBUG_ LEVEL` to form -g${D EBUG_FO RMAT}${ DEBUG_L EVEL}	5.14.0
` DEBUG_ LEVEL`	(empty)	Te mporary	set the debug level at compile time tuning the -g gcc option	It has to be used with `` DEBUG_F ORMAT`` to form -g${D EBUG_FO RMAT}${ DEBUG_L EVEL}	5.14.0
` GCOVR_ EXCLUDE _UNREAC HABLE`	ON	Pe rmanent	add the --ex clude-u nreacha ble-bra nches gcovr option		5.14.0
`` GCOVR_E XCLUDE_ THROW``	ON	Pe rmanent	add the --exc lude-th row-bra nches gcovr option		5.14.0
`` GCOVR_E XTRA_OP TIONS``	(empty)	Pe rmanent	allows extra options to be passed to the gcovr command		5.14.0

The Top Wrapper Makefile

The top wrapper Makefile is located at the root of each Elements-based project. It is designed to simply the command for the developer of the project and it wraps most of the CMake/CTest commands into pain Makefile target. Please note:

• the Makefile of each project should be updated each time that there is a new version of Elements. It contains the last available features.

• A non-permanent options is passed internally by default to the CMake command by the top wrapper Makefile: the -DUSE_LOCAL_INSTALLAREA=ON to create a local install area within the project tree.

• Some extra user temporary options can be passed to the underlying CMake process by using the CMAKEFLAGS envrionment variable. For example:

  export CMAKEFLAGS="-DCMAKE_USE_CCACHE=YES"
  

Please note that plain CMake commands can also be used directly.

Adding Permanent Options to Your Project

In order to change the global behavior of the project build, the main CMakeLists.txt file has to be edited in the following way.

set(ELEMENTS_HIDE_SYMBOLS ON
    CACHE STRING "enable explicit symbol visibility on gcc-4"
    FORCE)

This enables for the current project (and the current project only), the symbols hiding in the generated libraries.

These lines have to be placed after the call to find_package(ElementsProject) and before the call to elements_project.

Adding Temporary Options to Your Project

In order to change temporarily the behavior of the project build, 2 settings are possible:

• add an option to the CMAKEFLAGS environment variables if your are using the top wrapper Makefile
• pass directly the option to CMake if your are using it directly