C Library Template

Tip

Change the badge link to point to your own repository.

This repository is a GitHub template for modern C libraries. It provides a ready-to-use setup for:

• Multi-platform CI with GitHub Actions (Windows, macOS, Linux)
• Unit testing with Google Test (gtest)
• Dependency management with vcpkg
• Modern CMake (C11, out-of-source builds, install rules)

Note

This template does not include an executable target for the library. Instead we recommend developing and testing the library by adding unit tests in the test/ directory.

If you need to create an executable for your library, you can do so by adding a new CMake target in your CMakeLists.txt file.

Features

• Easy project bootstrap: Just use this template to start a new C library project.
• Cross-platform builds: Automated CI for Windows, macOS, and Linux.
• Google Test integration: Write tests in C++ using gtest, run them locally or in CI.
• vcpkg as a submodule: No need to install vcpkg globally; it's included in the repository.
• vcpkg manifest mode: Manage dependencies in vcpkg.json.
• CMake best practices: Out-of-source builds, install rules, and exportable targets.

Project Structure

c-project-template/
├── include/           # Public header files (C interface)
├── src/               # Source files, private headers go here as well
├── test/              # Unit tests (Google Test)
├── build/             # CMake build output
├── install/           # Installation output
├── CMakeLists.txt     # CMake build configuration
├── vcpkg.json         # vcpkg dependencies
└── .github/           # GitHub Actions workflows

Getting Started

1. Use this template

Click "Use this template" on GitHub to create your own repository.

2. Clone your new repository and initialize submodules (shallow)

git clone https://github.com/your-org/your-new-c-library.git
cd your-new-c-library
git submodule update --init --depth 1 vcpkg

3. Configure and build with CMake (dependencies installed automatically)

Tip

If you are using Visual Studio Code, you can use the CMake Tools extension for easier configuration and building.

Select the configure preset from the CMake Tools Extension in the status bar at the bottom. Then click build to build the project.

When you configure the project with CMake, vcpkg will automatically install all dependencies listed in vcpkg.json.

cmake -B build -S .
cmake --build build

4. Run unit tests

Tip

If you are using Visual Studio Code, you can use the CMake Tools extension to run tests easily.

Simply open the command palette (Ctrl+Shift+P) and type "CMake: Run Tests" to execute all tests or click on Run CTest in the status bar at the bottom. This will also configure and build the project.

cd build
ctest
# or run the test binary directly
./gtest

Customization

• Rename the library:
  • Update project() and target names in CMakeLists.txt.
  • Rename files and headers as needed.
• Add dependencies:
  • Add them to vcpkg.json and follow the CMake comments for linking.
• Add source or test files:
  • Place C sources in src/, headers in include/, and tests in test/.

Continuous Integration

This template includes a sample GitHub Actions workflow for multi-platform builds and tests. vcpkg is automatically bootstrapped and used by CI. See .github/workflows/ci.yml for details.

Note

To trigger a new release, update the version-semver value in vcpkg.json. Any pushes to the main branch will update the current version!

License

This template is provided under the MIT License. See LICENSE for details.