-
Notifications
You must be signed in to change notification settings - Fork 70
CMake HOWTO
Wiki ▸ CMake Build Logic ▸ CMake HOWTO
- Add a source file
- Add an executable or library
- Add a header test
- Add a runtest case
- Other activities
Edit Herc61_SlibSource.cmake. Add the new file name to the <target>_sources CMake variable, where <target> is the name of the executable, shared library, or loadable module that should include the new file.
Header files should be added to the same target as the c program that uses them and to headers_sources. Global header files just be should be added to headers_sources.
At the end of Herc61_SlibSource.cmake, the source file variables are altered as required for a Windows build. If the file being added is for Windows only, it should be added here. If the file being added is not used for Windows, it should be removed here.
Herc61_SlibSource.cmake includes comments and current coding that illustrates all of the above.
CMake refers to executables, shared libraries, and loadable modules as targets, and adding any of these means creating a new target. Functions exist in Herc00_Includes.cmake to standardize target creation within the Hercules build.
First, edit Herc61_SlibSource.cmake as described above to add the source files and headers required to compile the target. It does not matter if the new target is an executable, shared library, or loadable module.
Second, edit Herc60_CreateTargets.cmake to add the new target. Add the new executable, shared library, or loadable module near where other targets of the same type are added. Use the existing herc_Define_Shared_Lib or Herc_Define_Executable statements as examples.
Third, if adding a loadable module, add a target_link_libraries() statement for the added module on the shared library herc to allow for a successful build on Windows or macOS; look for hdt1025c for an example.
Before you begin, review the CMake scripts that contain test for headers and the like to determine which script should be modified, and review the functions available to test for headers etc.
Start by adding the appropriate test(s) to the appropriate script.
Then, and only if source code needs to be aware of the test result, modify cmakeconfig.h.in to include a #cmakedefine statement to expose the test result to the c compiler.
Tests for headers, functions, or structures exist in several places, depending on the nature of the test. Use the following as a guide to the file to be used for a particular test:
| File | Appropriate Tests |
|---|---|
| Herc20_TargetEnv.cmake | Hardware and operating system characteristics. |
| Herc22_Userland.cmake | Userland characteristics of UNIX-like systems. This script is not run when Hercules is configured on a Windows system. |
| Herc22_UserlandWin.cmake | Userland characteristics of Windows systems. This script is not run when Hercules is configured on a UNIX-like or macOS system. |
| Herc25_Compilergcclike.cmake | Characteristics of the installed gcc compiler. This script is also used for gcc-like compilers such as clang. |
| Herc25_CompilerMSVC.cmake | Characteristics of the compiler included with Microsoft Visual Studio. |
Functions exist in Herc00_Includes.cmake to standardize testing for headers, functions, and structures within the Hercules build. These functions also standardize the variables that hold the result of the test.
- herc_Check_Include_Files - Test for a header and set the HAVE_ variable
- herc_Check_Function - Test for a function and set the HAVE_ variable
- herc_Check_Struct_Member - Test a structure for a member and set HAVE_STRUCT
- herc_Check_Symbol_Exists - Test whether a string exists as a macro or identifier
File tests/CMakeLists.txt creates the test cases run by CTEST, or by referencing the test or check targets in the build tool (e.g., make, Ninja). Tests are grouped by category.
First, add the new test script to the tests directory.
Second, add the test file name to the appropriate group in tests/CMakeLists.txt.
If you plan to work in other areas of the CMake scripts, you should review all of the CMake-related documentation on this Wiki, and you should spend time reviewing the scripts themselves. The following is provided to give you a head start on that review.
The script Herc41_ExtPackageBuild.cmake builds external packages by calling function herc_ExtPackageBuild() in script Herc02_ExtPackageBuild.cmake.
You will also need to change Herc10_OptDef.cmake and Herc12_OptEdit.cmake to add and edit options that control building the new package or using one installed on the system. Herc60_CreateTargets.cmake will also need changes to use the imported target for the new external package when linking Hercules components.
Review the code in each of the scripts named above for the BZip2 external package to understand what is required for a new package.
Edit CMakeLists.txt to recognize a new configuration type. Change all of the following scripts to ensure the correct compiler, linker, and for Windows, resource compiler flags are set as needed to create the configuration:
- Herc31_COptsAppleGNU.cmake
- Herc31_COptsClang.cmake
- Herc31_COptsGNU.cmake
- Herc31_COptsMSVC.cmake
- Herc31_COptsUnknown.cmake
You do not need to change Herc10_OptDef.cmake nor Herc12_OptEdit.cmake because the configuration type is specified by a CMake option, not by a Hercules CMake option.
CMake needs to recognize and support the new compiler. See
https://cmake.org/cmake/help/v3.4/variable/CMAKE_LANG_COMPILER_ID.html
for a list of valid CMake compiler identifiers as of CMake 3.4, the baseline version of CMake required to build Hercules. Newer versions of CMake may support additional compilers.
First, code a Herc31_COpts<compiler>.cmake script to set compiler flags and options for Release and Debug build configurations, and for any build configurations that may have been added. Use the existing Herc31 modules as a starting point if that is helpful. If the new compiler is based on gcc or is sufficiently like gcc, you might start with Herc31_COptsGNU.cmake. It is not likely that you will be able to re-use an existing module.
Second, code a Herc25_Compiler<compiler>.cmake script to probe the new compiler's capabilities and set variables as needed. As with the Herc31_COpts script, you might be able to use an existing script. If the new compiler is sufficiently gcc-like, you make be able to use Herc25_Compilergcclike.cmake either as a starting point or as the compiler test script, just as Herc25_Compilergcclike.cmake is used to test both gcc and clang.
Third, change CMakeLists.txt to add the CMake identification of the new compiler to the list variable herc_Compilers.
Fourth, change CMakeLists.txt to test the CMake variable CMAKE_C_COMPILER_ID for the CMake identification of the new compiler when selecting the Herc25 probe script and the Herc31 options-setting script (two edits).
This Wiki page Copyright © 2018 by Stephen R. Orso. This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.