Copyright Nicolas Clauvelin, 2017. All rights reserved (LICENSE).
Setting up project in CMake can be a bit cumbersome, especially when dealing with custom toolchains. In addition, the project setup does not vary much between projects. This project is an effort to provide some basic functionalities to facilitate project setup in CMake. By design, the implementation is usable on CLion.
Most of my personal programing projects are usually cross-platform or sometimes designed for a specific hardware (usually embedded). CMake therefore seems like a good choice as it provides:
- low-level project management functionalities,
- cross-platform support for project configuration, build and install steps,
- can be used as the project format in CLion.
The project is a collection of CMake scripts grouped into a module named Hephaistos. In order to use the module, it is sufficient to include the main script Hephaistos.cmake.
The Hephaistos
CMake module provides the following functionalities:
- support for various toolchains using the heph_setup_toolchain command,
- the heph_setup_project_tree command to set up the various project directories used for compiling, building, and installing the project,
- a heph_setup_compiler command to adjust compiler settings for various setups (
Debug
,Release
,RelWithDebInfo
, andMinSizeRel
).
All those commands will report status information when CMake is going through the configuration stage.
The file Hephaistos.cmake should be included in the CMake project file in order to load the definitions of those various commands.
This command is implemented in ToolchainManager.cmake and provides toolchain management functionalities. For most projects the toolchain will be automatically setup during CMake configuration step, but in some cases (e.g., embedded platforms) explicit toolchain configuration will be required. In addition, it is sometimes useful to use a specific toolchain for debugging purpose.
The script ToolchainManager.cmake provides two commands:
heph_setup_toolchain([TOOLCHAIN ToolchainID])
: ifToolchainID
is not specified this will use the default toolchain identified by CMake during the configure step,heph_toolchain_diagnostic()
: this command outputs the details of the toolchain configuration.
The table below lists the supported toolchains:
Platform | Toolchain | Supported | Comment |
---|---|---|---|
Windows | MSVC | YES | supported through generator |
Windows | MinGW-w64 | YES | supported through CMAKE_C/CXX_COMPILER |
Linux | GCC | YES | supported by default (see note below) |
OS X | Clang | YES | supported by default |
OS X | GCC | YES | GCC_OSX_HOMEBREW ID (requires homebrew) |
ARM | GCC | YES | GCC_ARM_BAREMETAL ID |
Most Linux distributions are still providing old GCC versions (for example, GCC-4.X or GCC-5.X). In order to simplify support for modern versions, the toolchain ID GCC_LINUX_RECENT
should be used to enforce GCC-6.X or GCC-7.X usage. It is strongly recommended to use this toolchain for any Linux projects.
This toolchain requires the variable ARM_TC_PATH
to be set to the root of the toolchain installation.
This command is implemented in ProjectTree.cmake and provides an automated way to setup the project tree for CMake builds and CLion as well. The typical way to implement this in a project is to use the following snippet (after the project declaration):
heph_setup_project_tree(PROJ_BUILD_DIR ${BUILD_DIR}
PROJ_INSTALL_DIR ${INSTALL_DIR})
This will use the default location for the project tree (i.e., the CMake build directory), but makes it possible override those when invoking CMake using:
cmake -DBUILD_DIR=/path/to/build/dir -DINSTALL_DIR=/path/to/install/dir
This command will create dedicated folder for each build types in the build and install directories.
This command is implemented in CompilerSetup.cmake and provides an automated way to set compiler flags depending on the platform and the compiler. This command will set the flags for the various build types (Debug
, Release
, MinSizeRel
, RelWithDebInfo
). This command does not take any argument and in case the platform and/or the compiler is not supported it will simply use CMake defaults. It is sufficient to call this command after the project declaration to perform the compiler setup.
The supported configurations are (click on the links to see details):
- Windows + GCC
- Windows + MSVC
- Linux/Unix + GCC
- OSX + Clang
- OSX + GCC
- GCC ARM bare metal: this will set the compiler for bare metal builds
Note that, compiler flags for GCC on Linux and Unix platforms are functional for recent GCC versions. It is recommended to use the GCC_LINUX_RECENT
toolchain ID to enforce this usage.
The compiler will be identified based on the toolchain setup. The platform identification relies on the system description. For ARM bare metal projects it is required to configure the toolchain using heph_setup_toolchain.
C++11 will be used as the C++ standard by default. It can be set to C++14 or C++17:
# For C++14 standard.
heph_setup_compiler(CPP14)
# For C++17 standard.
heph_setup_compiler(CPP17)
The option NO_AVX
can be passed when setting up the compiler to disable AVX and AVX2 instructions. For example:
heph_setup_compiler(TOOLCHAIN GCC_LINUX_RECENT NO_AVX)
This option has no effect when using the GCC ARM toolchain for bare metal projects.
When using the GCC ARM toolchain for bare metal projects, the compiler setup command requires the type of ARM hardware to be explicitly specified. This is used by the script to properly define compiler flags for hardware support (e.g., FPU).
The current implementation supports the following ARM architectures:
- Cortex-M0+
- Cortex-M3
- Cortex-M4
To use a specific architecture the compiler setup should be invoked as follow:
# For Cortex-M0+.
heph_setup_compiler(ARM_ARCH M0+)
# For Cortex-M3.
heph_setup_compiler(ARM_ARCH M3)
# For Cortex-M4.
heph_setup_compiler(ARM_ARCH M4)
The compiler setup is designed for bare metal builds (ARM + GCC).