C and C++

Headers, sources and libraries as packages, and using them from CMake or pkg-config

Chapter 13 of 34Current for Gritpack 1.2.63Source: docs/guide/13-c-and-cpp.md

For most of the history of C and C++, "the package" has been a folder you copied, a tarball on a wiki page, or a Git submodule. This chapter gives those files a name, a version and an identity you can check, and lets any build system use them: CMake, pkg-config, Make, or a one-line compile. Gritpack never tells you how to build. It delivers the headers and sources, and the facts your build needs about them.

Maturity. Plain C and C++ packages (files with a name, version and dialect) are Available: they are ordinary Gritpack packages. The C/C++ description file, gritpack-c.toml, and the CMake and pkg-config files Gritpack generates from it are Experimental: they work for source and header-only libraries today. Describing prebuilt libraries in that file is Planned; section 6 shows what works now.

What you will be able to do

  • describe a C or C++ library as a package, with its public headers and sources;
  • check the description before you publish;
  • depend on the library and build against it from CMake, pkg-config or any other build system;
  • depend on a C package from a project in another language.

This chapter builds on Projects and dependencies and Publish your first package. If you have not read those, the commands will still make sense, but the reasons will not.

Two small files

A C or C++ package has two files at its root:

  • gritpack.toml says what the package is: name, version, dialect, which files it carries, its README and licence, and its dependencies. It is the same file every Gritpack package has.
  • gritpack-c.toml says what a consumer needs to know to build against it: its components, public headers, sources, include directories, defines, language standard and dependencies. It is optional. Without it the package is still a perfectly good package of files; with it, Gritpack can check the description and generate CMake and pkg-config files.

gritpack-c.toml holds consumer facts only. There are no commands, compiler flags, generators, scripts or build directories in it, and a field Gritpack does not know is an error rather than something quietly ignored.

1. Describe the library

Here is a small library, @ada/textkit, with one header and one source file:

textkit/
├── gritpack.toml
├── gritpack-c.toml
├── include/textkit/shout.h
├── src/shout.c
├── README.md
└── LICENSE
[package]
name = "@ada/textkit"
version = "1.0.0"
dialect = "c/c17"
description = "Small text helpers for C"
readme = "README.md"
license = "MIT"
files = ["include/**", "src/**", "gritpack-c.toml", "README.md", "LICENSE"]

[dependencies]

The dialect is the language and its version: c/c17, c/c23, c++/c++20 and so on. Remember to list gritpack-c.toml in files, so it travels with the package.

schema = "gritpack/c-package@1"

[components.shout]
kind = "source-library"
public_headers = ["include/textkit/*.h"]
sources = ["src/*.c"]
include_roots = ["include"]
public_defines = ["TEXTKIT_ASCII=1"]
standard = "c17"

A component is one thing a consumer can build against. A package can have several. Each one has a kind:

  • source-library: headers and source files the consumer compiles into its own program;
  • header-only: headers only.

And these optional fields:

FieldWhat it says
public_headersheader files a consumer may include (patterns)
sourcessource files a consumer compiles (patterns)
include_rootsdirectories to add to the include path
public_definesdefinitions a consumer must compile with, such as NAME=1
standardthe language standard: c89 to c23, c++98 to c++26
extensionswhether compiler language extensions are needed (default false)
componentsother components of the same package this one needs
public_dependenciesother packages a consumer of this component also needs
dependency_componentswhich component of such a package, when it has several
system_librariessystem libraries to link, such as m
frameworksApple frameworks to link

Every pattern must match at least one packaged file. A package that depends on another C package names it under [dependencies] in gritpack.toml as well, and lists it in public_dependencies if consumers need it too.

2. Check it

Build the package file and look at it:

$ gritpack pack --output ../textkit-1.0.0.gpk
packed @ada/textkit 1.0.0 dialect=c/c17 files=6 payload_sha256=e6985415... -> ../textkit-1.0.0.gpk
$ gritpack c verify ../textkit-1.0.0.gpk
verified C/C++ package @ada/textkit 1.0.0 components=1 operation=verify
$ gritpack c exports ../textkit-1.0.0.gpk
@ada/textkit 1.0.0 dialect=c/c17 target=any
  shout kind=source-library headers=1 sources=1 include_roots=include public_dependencies=

c exports --json prints the whole description with every pattern expanded to the files it matched.

Mistakes are caught while packing, before anything is published. A sources pattern that matches nothing, for example, stops pack and publish:

$ gritpack pack --output ../broken.gpk
invalid manifest: ... invalid C/C++ package: component "shout" sources pattern "src/*.cpp" matched no packaged file

The checks also refuse paths that leave the package, a file given two contradictory roles, components that depend on each other in a circle, and anything in the generated files that would point outside the package.

3. Publish it

A C package is published like any other package; see Publish your first package:

gritpack publish --dry-run
gritpack publish

4. Use it from a project

In the consuming project:

$ gritpack init --dialect c/c17
initialized app 0.1.0 dialect=c/c17 at ./gritpack.toml status=changed
$ gritpack add @ada/textkit
added @ada/textkit and installed 1 packages into ./packages

The package arrives as a self-contained directory, a prefix, with the build files Gritpack generated from gritpack-c.toml:

packages/@ada/textkit/
├── gritpack-c.toml
├── gritpack-package.json
├── gritpack.toml
├── include/textkit/shout.h
├── lib/cmake/ada_textkit/ada_textkitConfig.cmake
├── lib/pkgconfig/ada_textkit-shout.pc
├── LICENSE
├── README.md
└── src/shout.c

The generated names come from the package's name: @ada/textkit becomes ada_textkit, so two packages can never collide. Every path in the generated files is relative to the prefix, so you can move the directory anywhere.

From CMake

Put the prefix on CMAKE_PREFIX_PATH and use the generated package. Its target is <name>::<component>:

cmake_minimum_required(VERSION 3.20)
project(app LANGUAGES C)

find_package(ada_textkit CONFIG REQUIRED)

add_executable(app main.c)
target_link_libraries(app PRIVATE ada_textkit::shout)
$ cmake -S . -B build -DCMAKE_PREFIX_PATH="$PWD/packages/@ada/textkit"
$ cmake --build build
$ ./build/app
HELLO!

The target carries the include directory, the defines, the language standard and, for a source library, the source files, which CMake compiles into your program. Gritpack did not run CMake and did not compile anything.

From pkg-config, Make or a shell

Each component gets a .pc file. For a source library, the files to compile are in the gritpack_sources variable:

$ export PKG_CONFIG_PATH=$PWD/packages/@ada/textkit/lib/pkgconfig
$ pkg-config --cflags ada_textkit-shout
-I.../packages/@ada/textkit/lib/pkgconfig/../../include -DTEXTKIT_ASCII=1
$ cc main.c $(pkg-config --variable=gritpack_sources ada_textkit-shout) $(pkg-config --cflags --libs ada_textkit-shout) -o app
$ ./app
HELLO!

From anything else

For a build system Gritpack makes no files for, ask for the facts directly:

$ gritpack c context @ada/textkit --component shout
@ada/textkit:shout universe=c79813e4... components=1
  @ada/textkit:shout 1.0.0 kind=source-library root=./packages/@ada/textkit
  include=./packages/@ada/textkit/include
  header=./packages/@ada/textkit/include/textkit/shout.h
  source=./packages/@ada/textkit/src/shout.c
  define=TEXTKIT_ASCII=1

With --json it is a gritpack/c-consumer-context@1 record: include roots, public headers, sources, defines, system libraries and frameworks, for the component and everything it depends on, each with the package it came from. It never prints a build command. It hands your build its inputs and stops.

Without a project

To unpack a package file into a prefix without a project, for example on a build machine, use c project. The output directory must not exist yet:

$ gritpack c project ../textkit-1.0.0.gpk --output ../prefix
materialized C/C++ package @ada/textkit 1.0.0 components=1 projections=3 -> ../prefix

5. One dependency, two languages

A package of one language can depend on a package of another. A Rust project's gritpack.toml can depend on this C library, naming its dialect because it differs from the project's own:

$ gritpack init greeter --dialect rust/2024
initialized greeter 0.1.0 dialect=rust/2024 at ./gritpack.toml status=changed
$ gritpack add @ada/textkit --dialect c/c17
added @ada/textkit and installed 1 packages into ./packages
[dependencies."@ada/textkit"]
dialect = "c/c17"
version = "^1.0.0"

[package]
dialect = "rust/2024"
name = "greeter"
version = "0.1.0"

One packages/ directory and one gritpack.lock hold both. The project's own build, such as a Cargo build.rs using the cc crate, compiles the C sources from packages/@ada/textkit or from gritpack c context. Gritpack resolved, locked and checked the files; your build tools still do the building.

Shared by every languageKept by each language
the package name and scopehow source is compiled
the exact version and its digestthe language's own lock file
gritpack.lock and the dependency graphbuild scripts and code generation
checks, receipts and evidencetest runners and the toolchain

6. Ship a prebuilt library

Sometimes consumers should link a library you have already compiled. Today you publish it as an ordinary package, once per platform, with an encoding that marks it as a binary and a target that names the platform:

[package]
name = "@ada/textkit"
version = "1.0.0"
dialect = "c/c17"
encoding = "binary/static-library"
target = "x86_64-unknown-linux-gnu"
files = ["include/**", "lib/**", "README.md", "LICENSE"]

Publish the same name and version again for each platform you support, from the same source, so every variant has the same headers. The encoding keeps the prebuilt variants apart from the source variant of the same version. A consumer names the platform it wants, and Gritpack refuses to guess when several match:

gritpack add @ada/textkit 1.0 --target x86_64-unknown-linux-gnu

Gritpack checks and locks the exact bytes, but it does not generate CMake or pkg-config files for a prebuilt library: ship your own .pc file in lib/pkgconfig/, with paths relative to the file (prefix=${pcfiledir}/../..). Describing prebuilt libraries, their link mode and their ABI in gritpack-c.toml is planned.

What Gritpack will not do

  • run your compiler, CMake, Meson or any other build tool;
  • choose your build system or add flags of its own;
  • work out your public API by reading your headers.

The description is declarative on purpose: the same package has to work in toolchains that agree on very little else.

What just happened

  • Two small files turned a directory of headers and sources into a named, versioned package that Gritpack can check.
  • A consuming project got a self-contained prefix with CMake and pkg-config files generated from the description.
  • CMake, pkg-config with a plain compiler, and gritpack c context all built against the same package.
  • A Rust project depended on the C package through the same lock.

You can stop here

A C or C++ team that wanted dependable packaging without adopting a new build system is done.

Next