Przejdź do treści

CMake

CMake generuje pliki dla systemu budowania (np. Makefile) z opisu projektu w pliku CMakeLists.txt. Opis mówi, co zbudować (programy, biblioteki, z jakich plików), a nie jakimi poleceniami. CMake sam dopisuje zależności od nagłówków, clean, równoległe budowanie, a ten sam opis działa z innymi kompilatorami i systemami (np. Visual Studio w Windows).

Pierwsze przykłady budują program nwd (nwd.tar.gz):

nwd/
├── include/   nwd.h, nww.h
└── src/       main.c, nwd.c, nww.c

Pierwszy CMakeLists.txt

cmake_minimum_required(VERSION 3.24)
project(nwd C)

add_executable(nwd src/main.c src/nwd.c src/nww.c)
target_include_directories(nwd PRIVATE include)
  • cmake_minimum_required: najstarsza wersja CMake, dla której plik jest napisany (cmake --version).
  • project(nazwa C): nazwa projektu i język.
  • add_executable(nazwa pliki...): program. Programy i biblioteki w CMake to targety.
  • Polecenia target_... ustawiają opcje jednego targetu, tu katalog z nagłówkami (jak -Iinclude).

Budowanie ma dwa kroki, configure i build:

cmake -B build             # configure: sprawdza system, zapisuje build/Makefile
cmake --build build        # build: uruchamia make w build/
build/nwd 12 18
  • Wszystko, co tworzy CMake, trafia do katalogu build/. Źródła zostają czyste, a rm -rf build zawsze można bezpiecznie wykonać.
  • Nie uruchamiaj cmake . w katalogu ze źródłami: CMake zapisze tam swoje pliki i zastąpi istniejący Makefile wygenerowanym.
  • Po zmianie CMakeLists.txt wystarczy cmake --build build: krok configure uruchomi się sam.
  • cmake --build build --verbose pokazuje wykonywane polecenia.

W build/ jest m.in. wygenerowany Makefile (wc -l build/Makefile), CMakeCache.txt z ustawieniami z kroku configure i katalog CMakeFiles/.

Biblioteki w projekcie

Kod używany przez kilka programów opisujemy jako bibliotekę:

cmake_minimum_required(VERSION 3.24)
project(nwd C)

add_library(nwdlib STATIC src/nwd.c src/nww.c)
target_include_directories(nwdlib PUBLIC include)

add_executable(nwd src/main.c)
target_link_libraries(nwd PRIVATE nwdlib)
  • add_library(nazwa STATIC pliki...): biblioteka statyczna build/libnwdlib.a (SHARED: dzielona .so).
  • target_link_libraries(nwd PRIVATE nwdlib): linkuj nwd z biblioteką. CMake sam zbuduje ją wcześniej.

Słowo PUBLIC w target_include_directories(nwdlib PUBLIC include) mówi, przy kompilacji których plików gcc dostanie -Iinclude:

pliki biblioteki (nwd.c, nww.c) pliki programu, który ją linkuje (main.c)
PRIVATE tak nie
PUBLIC tak tak
INTERFACE nie tak

Przykłady:

  • PRIVATE: nwd.c używa pomocniczego nagłówka src/util.h, którego main.c nie dołącza. Program nie musi o nim wiedzieć: target_include_directories(nwdlib PRIVATE src).
  • PUBLIC: nwd.h dołączają i nwd.c, i main.c, jak w przykładzie wyżej.
  • INTERFACE: biblioteka z samych nagłówków, np. stb (stb_image.h wczytuje obrazki). Nie ma w niej czego kompilować, więc opcje są tylko dla programów, które jej używają: add_library(stb INTERFACE) i target_include_directories(stb INTERFACE stb).

main.c dołącza nwd.h, więc też potrzebuje -Iinclude: dlatego PUBLIC. Program dostaje tę opcję sam, przez target_link_libraries. Z PRIVATE kompilacja main.c skończyłaby się błędem nwd.h: No such file or directory.

Tak samo działają target_compile_options i target_compile_definitions.

Opcje kompilatora

add_compile_options(-Wall -Wextra)              # wszystkie targety zdefiniowane poniżej
target_compile_options(nwd PRIVATE -Werror)     # jeden target
target_compile_definitions(nwd PRIVATE DEBUG)   # -DDEBUG
set(CMAKE_C_STANDARD 17)                        # -std=c17 (przed targetami)

Optymalizacje i -g wybiera build type, podawany w kroku configure:

cmake -B build -DCMAKE_BUILD_TYPE=Debug         # -g
cmake -B build -DCMAKE_BUILD_TYPE=Release       # -O3 -DNDEBUG

Wartości podane przez -D CMake zapamiętuje w build/CMakeCache.txt. Lista ustawień: cmake -L build.

FetchContent

FetchContent pobiera kod biblioteki w kroku configure i buduje go razem z projektem. Nic nie trzeba instalować, a wszyscy mają tę samą wersję.

Przykład: hello z hello-qr.tar.gz wypisuje tekst jako kod QR, używając biblioteki qrcodegen.

cmake_minimum_required(VERSION 3.24)
project(hello C)

include(FetchContent)
FetchContent_Declare(qrcodegen
    URL https://github.com/nayuki/QR-Code-generator/archive/refs/tags/v1.8.0.tar.gz
    URL_HASH SHA256=2ec0a4d33d6f521c942eeaf473d42d5fe139abcfa57d2beffe10c5cf7d34ae60
)
FetchContent_MakeAvailable(qrcodegen)

add_library(qrcodegen STATIC ${qrcodegen_SOURCE_DIR}/c/qrcodegen.c)
target_include_directories(qrcodegen PUBLIC ${qrcodegen_SOURCE_DIR}/c)

add_executable(hello src/hello.c)
target_link_libraries(hello PRIVATE qrcodegen)
cmake -B build && cmake --build build
ls build/_deps                         # qrcodegen-src: pobrany kod
build/hello "Hello!"
  • URL_HASH: CMake sprawdza, że pobrał dokładnie ten plik (skrót liczy sha256sum plik).
  • Kod trafia do build/_deps/qrcodegen-src, a ścieżkę zawiera zmienna qrcodegen_SOURCE_DIR.
  • Jeśli pobrany projekt ma własny CMakeLists.txt, FetchContent_MakeAvailable dołącza jego targety i wystarczy target_link_libraries z nazwą targetu z jego dokumentacji. qrcodegen go nie ma, więc bibliotekę opisujemy sami (add_library).
  • Zamiast URL można podać repozytorium: GIT_REPOSITORY i GIT_TAG.

Przydatne polecenia

Polecenie Działanie
cmake -B build configure
cmake --build build build
cmake --build build -j8 budowanie, 8 zadań naraz
cmake --build build --target nwd tylko jeden target
cmake --build build --clean-first od nowa
cmake --build build --verbose z wypisanymi poleceniami
cmake -L build ustawienia z CMakeCache.txt