CMake version recommendations and install

CMake ≥ 3.21 is strongly recommended for general users for more robust and easy syntax. For project developers, we recommend CMake ≥ 3.28 for C++20 modules and IDE integration.

Downloading the latest release of CMake is usually easy. Admin / sudo is NOT required.

For platforms where CMake binaries aren’t easily available, use scripts/build_cmake.cmake.

To see the merge requests for a certain release, use a URL like: https://gitlab.kitware.com/cmake/cmake/-/merge_requests?milestone_title=3.28.4&scope=all&state=all

CMake 3.29 adds cmake_language(EXIT code) to exit CMake script mode with a specific return code. This is useful when using CMake as a platform-agnostic scripting language instead of shell script. Environment variable CMAKE_INSTALL_PREFIX is used to set the default install prefix across projects–it can be overridden as typical by cmake -DCMAKE_INSTALL_PREFIX= option. Target property TEST_LAUNCHER allows specifying a test launcher e.g. for MPI program this allows deduplicating or making more programmatic test runner scripts. Linker information variables including CMAKE__COMPILER_LINKER_ID have been added to allow programmatic logic like setting target_link_options() based on the particular linker. ctest --parallel without a number or 0 will use unbounded test run parallelism.

CMake 3.28 changes PATH behavior for Windows find_{library,path,file}() to no longer search PATH. This may break some projects that rely on PATH for finding libraries. The MSYS2-distributed CMake is patched to include PATH like earlier CMake, which can be confusing for CI etc. not using MSYS CMake with that patch. Windows CI/user may need to specify environment variable CMAKE_PREFIX_PATH like

$Env:SYSTEMDRIVE/msys64/mingw64/lib

Support for C++20 modules is considerably improved and most users will want at least CMake 3.28 to make C++ modules usable. Generator expressions $<IF> $<AND> $<OR> now short circuit. Test properties now have a DIRECTORY parameter, useful for setting test parameters from the project’s top level CMakeLists.txt. CMake 3.28.4 fixed a long-standing bug in Ninja Fortran targets that use include statements.

CMake 3.27 emits warning for cmake_minimum_required(VERSION) < 3.5. CTest test properties TIMEOUT_SIGNAL_NAME and TIMEOUT_SIGNAL_GRACE_PERIOD specify a POSIX signal to send to a timed out test process. Interactive CMake debugger added by cmake --debugger is used with an IDE such as Visual Studio. CMake script command cmake_file_api() allows querying CMake File API from within CMake. NOTE: Fortran + Ninja was broken for OBJECT libraries in CMake 3.27.0..3.27.8 and fixed in 3.27.9.


Older CMake changelog

X11 on macOS

X11 can be accessed using XQuartz as available via Homebrew.

brew install libx11 xquartz

To finish the one-time setup of XQuartz, logout/login or reboot. Check that X11 server is available by

echo $DISPLAY

which should show a temporary directory ending like “org.xquartz:0”.

Demo and troubleshooting

See that X11 is working with the classic Xeyes test GUI.

xeyes

A useful image browsing program on Linux, macOS etc. is feh:

brew install feh

Troubleshooting: XQuartz GitHub Issues

Specifically, be sure XQuartz is enabled in Login Items to fix problems like the XQuartz window won’t open.

XQuartz will open automatically when any X11 program is started.


Related: PulseAudio on macOS

Cleanup unused files in Linux

Keep at least 10% of drive space to avoid:

  • SSD wear
  • HDD fragmentation

Determine free space on Linux / macOS / Windows Subsystem for Linux with “ncdu”. ncdu uses Ncurses terminal graphics to quickly show the biggest files in the Linux filesystem tree. ncdu is very handy to find large files or directories that may be unneeded.

df -h

gives a drive-level summary of disk usage.

Package managers cache installed files in case of need to reinstall, but the packages can be redownloaded if needed to save disk space by clearing the cache. Clear the package cache–for APT (common in Debian-based systems):

apt autoclean

or for DNF (Fedora, RHEL, CentOS):

dnf clean dbcache

Remove unwanted packages

TeX Live documentation can consume a lot of disk space. To cleanup the documentation, consider removing packages matching texlive-*doc. This also removes texlive-full but with no detriment to TeX Live working.

Synaptic list of files to remove for texlive-doc to save disk space

Packages removed for texlive-doc to save over 1 GB of disk space.


Related:

CMake FindOpenSSL hints

For all CMake find_*() commands including FindOpenSSL, the package path can be hinted by setting an appropriate environment variable or CMake variable. This examples supposes a Homebrew package manager has installed OpenSSL 1.1, which the user wishes to use in a CMake project. To hint the package path when configuring a CMake project, either specify OpenSSL_ROOT by environment variable:

export OpenSSL_ROOT=$(brew --prefix openssl@1.1)

or directly in the CMake configure command:

cmake -B build -DOpenSSL_ROOT=$(brew --prefix openssl@1.1)

The example CMakeLists.txt:

cmake_minimum_required(VERSION 3.16)

project(f LANGUAGES NONE)

find_package(OpenSSL REQUIRED)

Use the –debug-find CMake option to see the paths CMake is searching.

To disable various search paths, consider the following CMake variables. These are normally only used for debugging or special cases.

set(CMAKE_FIND_USE_CMAKE_PATH false)
set(CMAKE_FIND_USE_CMAKE_SYSTEM_PATH false)
set(CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH false)
set(CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH false)

The OpenSSL world is gradually transitioning from OpenSSL 1.1 to 3, and Homebrew uses subdirectory to isolate the OpenSSL installs. CMake does not recursively search as that would in general not have a stopping condition and at least significantly slow down the search performance.

GitHub Actions Apple Silicon CPU

GitHub Actions macOS runners can use Apple Silicon CPU, which is what most Apple users have. Some build issues including the linker have historically had Apple Silicon-specific issues. Generally it’s good to test on the same CPU architecture as the target platform.

We sometimes find it necessary to select the Xcode version compatible with Homebrew GCC if build errors occur that are not present on a physical Apple Silicon laptop.

jobs:

  mac:
    runs-on: macos-14

    strategy:
      matrix:
        cxx: [g++-13, clang++]

    env:
      HOMEBREW_NO_AUTO_CLEANUP: 1
      CXX: ${{ matrix.cxx }}

    steps:
    - uses: actions/checkout

    - name: Ninja install
      run: brew install ninja

    - run: sudo xcode-select --switch /Applications/Xcode_15.1.app

    - run: cmake --workflow --preset debug

    - run: cmake --workflow --preset release

In this example Ninja enables quick testing of builds in Debug and Release mode, which is important to catch bugs.

Matlab on macOS doesn't source ~/.zshrc

On macOS, Matlab does not source ~/.zshrc. This issue has existed at least since macOS started using ZSH as the default shell.

To workaround this issue, particularly when programs from package managers like Homebrew are needed, add a setup script to the Matlab project containing like:

if ~ismac
  return
end

% Add Homebrew to the PATH
[ret, homebrew_prefix] = system('brew --prefix');
if ret == 0
  p = fullfile(strip(homebrew_prefix), "bin");
  if isfolder(p)
    setenv('PATH', append(p, pathsep, getenv('PATH')))
  end
end

Then programs installed by Homebrew like CMake, GCC, etc. will be on Path environment variable in Matlab.

Note that the Matlab commands below do not help:

!source ~/.zshrc

system("source ~/.zshrc")

CMake macOS Xcode Environment

When macOS, Xcode, or Command Line Tools upgrades, build directories (including for CMake-based projects) often need to be refreshed. If the user has set custom environment variables concerning Xcode, they may need to be updated as well. Here are some important environment variables and CMake variables to check if problems occur after upgrading.

For a simple CMake project on macOS, CMakeCache.txt might include:

CMAKE_OSX_DEPLOYMENT_TARGET:STRING=

CMAKE_OSX_SYSROOT:PATH=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX*.sdk

Having multiple directories under /Library/Developer/CommandLineTools/SDKs and /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs is fine, CMake can select the appropriate one. The user can select the SDK:

xcode-select --switch

Workarounds

If Homebrew GCC breaks after upgrading Xcode or Command Line Tools, try specifying an older SDK. For example, if the latest SDK is MacOSX14.4.sdk, try using MacOSX13.3.sdk in “~/gcc.sh”:

export CC=gcc-13 CXX=g++-13 FC=gfortran-13

export SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX13.3.sdk/

and then source ~/gcc.sh before running cmake with a fresh build directory.

If a CMake build step fails, try copy-pasting the command and removing the -isysroot portion of the command. This is a clear clue the older SDK is (at least temporarily) needed till Homebrew updates its GCC formula.

GCC will tell where included files are coming from by adding the gcc -H flag. This tells what to specify for environment variable SDKROOT.

Install AMD AOCC C C++ Fortran compiler

The no-cost AMD AOCC compiler is tuned for AMD CPUs, akin to how Intel oneAPI is tuned for Intel CPUs. Install the “.rpm” file after downloading on a RHEL-based Linux like:

dnf install ./aocc-compiler*.x86_64.rpm

Create a source script “~/aocc.sh” like:

root=/opt/AMD/aocc-compiler-4.2.0/

[[ ! -d ${root} ]] && echo "ERROR: ${root} not found" && exit 1

source ${root}/setenv_AOCC.sh

export CC=clang CXX=clang++ FC=flang

export MPI_ROOT=

flang --version

To use the AOCC compiler:

source ~/aocc.sh

Free C C++ Fortran compiler families

Several modern, currently-supported compiler families are free-to-use for C, C++ and Fortran.

GCC has broad support of modern standards on a very wide range of computing platforms. GCC’s downside in some cases can be slower runtime performance than compilers having less broad language and platform support.

Compiler C C++ Fortran
GNU gcc: C23 g++ C++23 gfortran: F2018
Intel oneAPI icx: C23 icpx: C++23 ifx: F2023
LLVM clang: C17 clang++: C++23 flang-f18: F2018
AOCC clang: C17 clang++: C++17 flang: F2008
NVidia HPC SDK nvc: C11 nvc++: C++20 nvfortran: F2003
IBM OpenXL xlc: C17 xlc++: C++17 xlf: F2018

Intel oneAPI compilers are free to use for any user. The Intel performance libraries like MKL, IPP, and TBB are available at no cost.


LLVM Clang and Flang have significant industry support, including from Nvidia, and are known for high performance.


AMD AOCC LLVM compiler is tuned for AMD CPUs.


Nvidia HPC SDK is free to use. A key feature of the HPC SDK compilers is intrinsic support for CUDA Fortran.


IBM OpenXL LLVM-based compilers are currently for POWER CPUs only e.g. ppc64le. IBM OpenXL compilers do not work with a typical x86-based computer.

PowerShell tilde expansion

PowerShell tilde expansion was dropped in 7.4.0. Automatic variable $home remains available across operating systems.

ls $home

PowerShell tilde expansion was fraught with difficulties that led PowerShell maintainers to at least temporarily drop tilde expansion in PowerShell 7.4.0.

Note that automatic variables are just inside PowerShell itself–they are not environment variables. Thus, automatic PowerShell variables are generally not visible to other programs or scripts unless additional steps are taken to expose them, perhaps as a command line argument or environment variable.