diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 12610b87e7144d737ffe669dd4136bfaa6ed8226..2705500c8a9299ae45a8da3d968015eff9c77ce5 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -70,6 +70,10 @@ check-recipes: - cmake --build 10_production - ./10_production/app + - CXXFLAGS="-march=icelake-server" cmake -S 11_customization -B 11_build + - cmake --build 11_build --verbose + - ./11_build/hello_world + check-links: before_script: - module purge diff --git a/11_customization/CMakeLists.txt b/11_customization/CMakeLists.txt new file mode 100644 index 0000000000000000000000000000000000000000..d8a0d8ce042e33e1896dab9002f684463d03e0b9 --- /dev/null +++ b/11_customization/CMakeLists.txt @@ -0,0 +1,11 @@ +cmake_minimum_required(VERSION 3.20) + +project(11_customization + LANGUAGES CXX) + +########################## +# EXECUTABLE +########################## +add_executable(hello_world) +target_sources(hello_world PRIVATE main.cpp) + diff --git a/11_customization/README.md b/11_customization/README.md new file mode 100644 index 0000000000000000000000000000000000000000..6c5dc4e21f56dc37da9246913eda34a857ca357f --- /dev/null +++ b/11_customization/README.md @@ -0,0 +1,34 @@ +# How can I influence the build process as a user? + +There are situations where you as a user need to influence the build process. +This can be adding custom compiler flags, include directories, linker flags, etc. +**If you are the library author you should consider using CMake for doing these thing. +The following is mainly intended for the end-user.** + +## Automatic flags added by `CMAKE_BUILD_TYPE` + +Targets provide modularization and encapsulation. A target +encapsulates everything needed for a certain build job. It also +is some kind of container that allows efficient use as a building +block. + +| CMAKE_BUILD_TYPE | Compiler Flags | Linker Flags | +|------------------|------------------------------------------|------------------| +| Debug | `-g` | | +| Release | `-O3 -DNDEBUG` | | +| RelWithDebInfo | `-O2 -g -DNDEBUG` | | +| MinSizeRel | `-Os -DNDEBUG` | | + +There is no default build type! If you do not specify a build types no flags will be added. + +## CMake uses common environment variables to modify the compiler and linker commands. +CMake uses environment variables like `CFLAGS`, `CXXFLAGS`, `LDFLAGS`, ... to initialize its internal variables [[Ref]](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html#variable:CMAKE_%3CLANG%3E_FLAGS). You can either use the environment variables or the CMake variables directly. +**CAUTION! the internal variables are set during the first configure call and are cached. Meaning, subsequent changes to the environment variables will not be followed by CMake. To make CMake aware of the changes you can either delete and recreate the build folder or use `--fresh`[[Ref]](https://cmake.org/cmake/help/latest/manual/cmake.1.html#cmdoption-cmake-fresh).** + +## Example +The following example shows how to add architecture specific optimization flags. **Note, without `CMAKE_BUILD_TYPE` no optimization level is set.** +``` +CXXFLAGS="-march=icelake-server" cmake -S . -B build +cmake --build build --verbose +./build/hallo_world +``` \ No newline at end of file diff --git a/11_customization/main.cpp b/11_customization/main.cpp new file mode 100644 index 0000000000000000000000000000000000000000..caf46ef35c003a8895c9d54921dc87ceefe6e3f0 --- /dev/null +++ b/11_customization/main.cpp @@ -0,0 +1,7 @@ +#include <iostream> + +int main(int /*argc*/, char** /*argv*/) +{ + std::cout << "Hello World" << std::endl; + exit(EXIT_SUCCESS); +} diff --git a/README.md b/README.md index 43ee1ce96e7ae1ce96ba647c15be0c378884dc5f..38ee6a5c397b1cb3f1c710784e694df0c6912016 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ we run them in our CI. * [How to manage all the tests in your project?](08_ctest) * [How to install a project with CMake?](09_install) * [How to add compilation configurations to your project?](10_presets) + * [How can I influence the build process as a user (custom flags, etc)?](11_customization) ## Why CMake? * Automatically search for programs, libraries, and header files