Build System
For CABLE offline applications, the underlying build system is CMake based. CMake is widely used in the C, C++ and Fortran communities and there are many great resources out there on the web, in particular:
- Mastering CMake
- Effective Modern CMake
- Creating a CMake project (with Fortran)
- An Introduction to Modern CMake
Adding source files
Source files can be added easily by adding to the list of source files in CMakeLists.txt. We recommend keeping the list sorted in alphabetical order when adding new source files.
Setting compiler flags
The recommended compiler flags for debug and release builds for each compiler are set in the CMakeLists.txt file via the CABLE_<COMPILER_ID>_Fortran_FLAGS* variables. These can be modified if required.
Warning
Compiler flags should be guarded by a check on the compiler ID as they are generally compiler specific. See CMAKE_<LANG>_COMPILER_ID for a list of supported compiler IDs.
Alternatively, compiler flags can be specified when invoking cmake by specifying -DCMAKE_Fortran_FLAGS=<flags> when generating the project, however the per configuration default flags may take precedence (see CMAKE_<LANG>_FLAGS for more details).
Adding external dependencies (libraries)
When linking against external third-party libraries, we strongly recommend not to hard code library paths, include paths, link flags or compiler flags in the CMakeLists.txt file. This ensures that the build system is portable and insulated from changes to library versions and dependencies.
Instead, CMake should query the required flags for a given library from the library itself. To do this, we recommend using either CMake's find_package mechanism or a tool such as pkg-config (see the FindPkgConfig module for using pkg-config with CMake.). The dependencies should provide exported targets which can be used via target_link_libraries.
For an example, see how the netcdf-fortran dependency was added in CMakeLists.txt.
If these approaches are not supported by the external library, please report this as a bug to its maintainers. If the library is an open-source project, consider sending a patch.
Warning
For most cases, CMake's find_package should be used in Config mode. find_package in Module mode should only be used if the library is part of the CMake module distribution.