C and C++
Headers, sources and libraries as packages, and using them from CMake or pkg-config
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.tomlsays 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.tomlsays 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:
| Field | What it says |
|---|---|
public_headers | header files a consumer may include (patterns) |
sources | source files a consumer compiles (patterns) |
include_roots | directories to add to the include path |
public_defines | definitions a consumer must compile with, such as NAME=1 |
standard | the language standard: c89 to c23, c++98 to c++26 |
extensions | whether compiler language extensions are needed (default false) |
components | other components of the same package this one needs |
public_dependencies | other packages a consumer of this component also needs |
dependency_components | which component of such a package, when it has several |
system_libraries | system libraries to link, such as m |
frameworks | Apple 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 language | Kept by each language |
|---|---|
| the package name and scope | how source is compiled |
| the exact version and its digest | the language's own lock file |
gritpack.lock and the dependency graph | build scripts and code generation |
| checks, receipts and evidence | test 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 contextall 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
- Installing applications is about programs people run, rather than libraries they build against.
- Optional deep dive: Coming from Cargo, npm or Go puts the four ecosystem chapters side by side.