INTRODUCTION Overview Download and Install Documentation Publications REPOSITORY Libraries DEVELOPER Dev Guide Dashboard PEOPLE Contributors Users Project Download Mailing lists
|
Tutorial for the GearBox Build System The term build system refers the software and procedures responsible for compiling, installing, and distributing source code. GearBox uses CMake to handle its build system. CMake is a cross-platform tool, designed as a replacement for autotools. Contents: BasicsBuilds are controlled by a set of files called 'CMakeLists.txt'. There is approximately one in each directory, and builds descend recursively through the source tree. An individual developer only needs to be concerned with writing CMakeLists.txt files in the directory containing his or her library code and below. ExampleHere's an example of a CMakeLists.txt file to builid a library. We'll go through it line by line. SET ( lib_name GbxAdvanced ) GBX_ADD_LICENSE( GPL ) SET ( build TRUE ) # Check for human input GBX_REQUIRE_OPTION( build LIB ${lib_name} ON ) # Check arbitrary variables GBX_REQUIRE_VAR( build LIB ${lib_name} GBX_OS_LINUX "only Linux OS is supported" ) # Check local targets (libraries or executables) SET( dep_libs basic ) GBX_REQUIRE_TARGETS( build LIB ${lib_name} ${dep_libs} ) IF ( build ) INCLUDE( ${GBX_CMAKE_DIR}/UseBasicRules.cmake ) FILE( GLOB hdrs *.h ) FILE( GLOB srcs *.cpp ) GBX_ADD_LIBRARY( ${lib_name} DEFAULT ${srcs} ) TARGET_LINK_LIBRARIES( ${lib_name} ${dep_libs} ) GBX_ADD_HEADERS( gbxadvanced ${hdrs} ) ENDIF ( build ) Line-by-LineSET ( lib_name GbxAdvanced ) All variables in CMake contain text. Assignment is done with SET function. (The C++ equivalent of this line:
Notice the GearBox convention for naming CMake variables:
GBX_ADD_LICENSE( GPL ) This macro adds license information about this library to the global list which will be dumped into the SET ( build TRUE ) This and the following few lines determine whether we are going to build this library or not. We start with the assumption that we will and then check a few requirements sequentially. We define a variable called # Check for human input GBX_REQUIRE_OPTION( build LIB ${lib_name} ON ) Any text following "#" is a comment. Use them to explain uncommon usage. This GearBox macro checks for user input into the build process. It is actually a shortcut which does several things:
Notice that to evaluate the variable you have to inclose it in braces and add a dollar sign, i.e. This macro is quite flexible. You can specify custom names for the option variables and provide a custom description.
It is sometimes useful to disable compilation of all targets and then selectively enable a few. To do this set GBX_DISABLE_ALL to ON. In this case, all default compilation settings for all targets are set to OFF. It is still possible to individually enable targets with e.g. ENABLE_LIB_GBXADVANCED=ON. For GBX_DISABLE_ALL to take effect, make sure you clear CMake cache first, by deleting CMakeCache.txt file. GBX_REQUIRE_VAR( build LIB ${lib_name} GBX_OS_LINUX "only Linux OS is supported" ) Next comes another "REQUIRE_" macro. This one checks that an arbitrary variable, in this case - This is the most common macro. Typically, several of these macros check variables one after another. The complete signature: GBX_REQUIRE_VAR ( cumulative_var [EXE | LIB] module_name test_var reason )
SET( dep_libs basic ) GBX_REQUIRE_TARGETS( build LIB ${lib_name} ${dep_libs} ) The last of the "REQUIRE_" macros: very useful if you link to other libraries in GearBox. Important: this one is for working with internal libraries only. You have to make sure that the required libraries are going to be built because they may be disabled for the same reasons as this one, i.e. user configuration, unsupported OS, lack of prerequisites. Notice that - The complete signature of this macro and a related "singular" version: GBX_REQUIRE_TARGETS( cumulative_var [EXE | LIB] module_name TARGET0 [TARGET1 TARGET2 ...] ) GBX_REQUIRE_TARGET( cumulative_var [EXE | LIB] module_name TARGET [reason] ) IF ( build ) Ok, we've checked everything. Now A note on slightly funky CMake syntax: notice that in the IF statement and in other places with a boolean context, CMake accepts both the variable name, i.e. INCLUDE( ${GBX_CMAKE_DIR}/UseBasicRules.cmake ) Commonly used CMake scripts are stored in a one directory FILE( GLOB hdrs *.h ) FILE( GLOB srcs *.cpp ) Search for file in the current directory which fit the specified pattern and assign the list to the variables
GBX_ADD_LIBRARY( ${lib_name} DEFAULT ${srcs} ) TARGET_LINK_LIBRARIES( ${lib_name} ${dep_libs} )
Now you can see why we bothered with defining variables. These commands are generic and can be easily used for other libraries. GBX_ADD_HEADERS( gbxadvanced ${hdrs} ) This custom macro doesn't save much space but prevents easily-made mistakes. It specifies destination for header files to be ENDIF ( build ) Don't forget to close the IF structure. Notice that CMake is quite strict with A comprehensive list of CMake variables defined by GearBoxBuild system configuration: GBX_DEFAULT_LIB_TYPE # Valid options {SHARED, STATIC}. Defaults to SHARED. Project description: GBX_PROJECT_VERSION_MAJOR GBX_PROJECT_VERSION_MINOR GBX_PROJECT_VERSION_PATCH GBX_PROJECT_VERSION (=MAJOR.MINOR.PATCH) GBX_PROJECT_NAME_LOWER (e.g. 'gearbox' ) GBX_PROJECT_NAME_UPPER (e.g. 'GEARBOX' ) GBX_PROJECT_NAME_CAP (e.g. 'Gearbox' ) OS variables: evaluate to TRUE when running on the corresponding OS, otherwise to FALSE. We define our own because the standard CMake ones are inconsistently named and the one for Linux is not defined. GBX_OS_LINUX GBX_OS_MAC GBX_OS_QNX GBX_OS_WIN Under Linux, an additional variable if defined GBX_PROC_64BIT Source and binary directories can be distinguished as so GBX_PROJECT_BINARY_DIR GBX_PROJECT_SOURCE_DIR Install directories can be referenced with absolute paths GBX_BIN_INSTALL_DIR GBX_CMAKE_INSTALL_DIR GBX_CMAKE_PKGCONFIG_INSTALL_DIR GBX_INCLUDE_INSTALL_DIR GBX_LIB_INSTALL_DIR GBX_PKGCONFIG_INSTALL_DIR GBX_SHARE_INSTALL_DIR .. or path relative to the install directory GBX_BIN_INSTALL_SUFFIX GBX_CMAKE_INSTALL_SUFFIX GBX_CMAKEPKGCONFIG_INSTALL_SUFFIX GBX_INCLUDE_INSTALL_SUFFIX GBX_LIB_INSTALL_SUFFIX GBX_PKGCONFIG_INSTALL_SUFFIX GBX_SHARE_INSTALL_SUFFIX |