netlify / cmake

Netlify's Common CMake Modules

Overview

This is the common set of CMake based modules used by all C++ projects at Netlify. For the most part, these include FindXXX.cmake files, but also support a few specific functions. Some of these will be removed in the future once Netlify migrates to using IXM for its projects, and this will instead work as a Project Blueprint for Netlify's internal projects.

Minimum Supported Platform

These are the only settings where these modules are used.

• Ubuntu 20.04
• Clang 10
• C++2a
• CMake 3.16

Any other compilers, operating systems, or languages are not guaranteed to be supported.

Roadmap

The following features are not yet (fully) implemented, but are currently planned

• Better IXM Integration (This is reliant on IXM being released)
• Custom Toolchain File (To ensure Clang, LLD, libc++, etc.)
• Profile Guidance Code Generation
• Sanitizer Support

Usage

This project is intended to be acquired via FetchContent. Thus, the following code should go at the top of every project's root CMakeLists.txt file.

cmake_minimum_required(VERSION 3.16)
include(FetchContent)
FetchContent_Declare(cmake GIT_REPOSITORY https://github.com/netlify/cmake GIT_TAG main)
FetchContent_MakeAvailable(cmake)

This will pull in the Netlify CMake Library, set several internal values, prepare various properties, etc.

If using additional CMake libraries via FetchContent, simply declare more of them before calling FetchContent_MakeAvailable.

Projects

Most projects will do the following

cmake_minimum_required(VERSION 3.16)
include(FetchContent)
FetchContent_Declare(cmake GIT_REPOSITORY https://github.com/netlify/cmake GIT_TAG main)
FetchContent_MakeAvailable(cmake)
set(CMAKE_PROJECT_INCLUDE ${NETLIFY_PROJECT_PRELUDE})
project(<project-name-here> LANGUAGES CXX)

This will attempt to set and find the most common flags and variables for our given target.

Behavior

Netlify's CMake modules perform the following operations when first included. This is done to ensure that we have a guaranteed behavior across all of our projects. However, this might disrupt others workflows. The changes these modules do are mentioned below:

• CTest is included, but the CDash related targets are disabled.
• CMAKE_EXPORT_COMPILE_COMMANDS is set to YES.
• CMAKE_POLICY_DEFAULT_CMP0077 is set to NEW.
• In-Source builds are disabled with a hard error
• The Catch2 Unit Testing library is declared.
• Color diagnostics are enabled by default.
• -Og and -ggdb are enabled by default for Debug based builds.

cmake's Issues

Warn when CXX/CC environment variables are set and are *not* some form of clang

This is a constant problem brought on by the cmake rust crate where it automatically overrides the CMAKE_CXX_COMPILER and CMAKE_C_COMPILER variables regardless of your toolchain file. This breaks a LOT of things and is confusing.

We should warn (or maybe even error) when a form of clang is not the selected CMAKE_CXX_COMPILER, or maybe just rewrite/replace the CMake rust crate with something of our own design.

FeatureSummary prints conflicting information

The following output was observed when configuring netlify/aegis

-- The following features have been enabled:

 * Documentation, Generate Documentation
 * Format, Run clang format

-- The following build dependencies have been found:

 * Threads, System Threading Library
 * OpenSSL

-- The following development tools have been found:

 * Sphinx, Sphinx Documentation Generator, <https://sphinx-doc.org>
 * ClangFormat, A tool to format C, C++, and Protobuf code., <https://clang.llvm.org/docs/ClangFormat.html>
 * ClangCheck, LibTooling wrapper for basic error checking and AST dumping, <https://clang.llvm.org/docs/ClangCheck.html>
 * ClangTidy, Clang based C++ 'linter' tool, <https://clang.llvm.org/extra/clang-tidy>
 * SCCache, Shared Compilation Cache, <https://github.com/mozilla/sccache>

-- The following sanitizers have been found:

 * UndefinedBehaviorSanitizer, Fast undefined behavior detector, <https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html>
 * AddressSanitizer, Fast memory error detector, <https://clang.llvm.org/docs/AddressSanitizer.html>
 * MemorySanitizer, Detector of uninitalized reads, <https://clang.llvm.org/docs/MemorySanitizer.html>
 * ThreadSanitizer, Data race detector, <https://clang.llvm.org/docs/ThreadSanitizer.html>
 * SafeStack, Instrumentation pass that protects programs, <https://clang.llvm.org/docs/SafeStack.html>

-- The following features have been disabled:

 * Unit Tests, Enable Unit Tests
 * Safe Stack, Enable Safe Stack instrumentation pass
 * UBSan, Enable UndefinedBehaviorSanitizer
 * ASan, Enable AddressSanitizer
 * TSan, Enable ThreadSanitizer
 * MSan, Enable MemorySanitizer
 * Documentation, Generate Documentation
 * Format, Run clang format

Notice that the enabled and disabled features both show the "Documentation, Generate Documentation" and "Format, Run clang format" features.

Because aegis depends on netlify/apex, both are being shown with the same description. What needs to change is

1. A top-level documentation feature
2. Per-target documentation feature (e.g., "Apex Documentation")
3. Making inter-library links work "out of the box" with sphinx (though this requires either manual linking of predetermined URLs or figuring out how to generate the apex documentation as a sub directory)