setup-cpp

Install all the tools required for building and testing C++/C projects.

Setting up a cross-platform environment for building and testing C++/C projects is a bit tricky. Each platform has its own compilers, and each of them requires a different installation procedure. This package aims to fix this issue.

setup-cpp can be used locally from terminal, from CI services like GitHub Actions and GitLab Pipelines, and inside containers like Docker.

setup-cpp is supported on many platforms. It is continuously tested on several configurations including Windows (11, 10, 2022, 2019) x64/ARM/x86, Linux (Ubuntu 24.0, 22.04, 20.04, 18.04, Fedora, ArchLinux) x64/ARM64, and macOS (15, 14, 13, 12, 11, 10.15) x64/ARM. setup-cpp is backed by unit tests for each tool and integration tests for compiling cpp projects.

      # GitHub Actions example:
      - name: Setup Cpp
        uses: aminya/setup-cpp@v1
        with:
          compiler: llvm
          vcvarsall: true
          cmake: true
          ninja: true
          vcpkg: true

Features

setup-cpp is modular and you can choose to install any of these tools:

category	tools
compiler	llvm, gcc, msvc, apple-clang, vcvarsall
build system	cmake, ninja, meson, make, task, bazel
package manager	vcpkg, conan, choco, brew, apt-fast, nala, git, setup-cpp
analyzer/linter	clang-tidy, clang-format, cppcheck, cpplint, flawfinder, lizard, infer, cmakelang, cmake-format, cmake-lint
cache	ccache, sccache
documentation	doxygen, graphviz
coverage	gcovr, opencppcoverage, kcov
other	python, powershell, sevenzip, tar

setup-cpp automatically handles the dependencies of the selected tool (e.g., python is required for conan).

Usage

From Terminal

With npm and Nodejs

Run setup-cpp with the available options.

# Windows example (open PowerShell as admin)
npx setup-cpp --compiler llvm --cmake true --ninja true --ccache true --vcpkg true
# restart the shell to activate the environment

# Linux/Macos example
sudo npx setup-cpp --compiler llvm --cmake true --ninja true --ccache true --vcpkg true
source ~/.cpprc # activate cpp environment variables

NOTE: In the compiler entry, you can specify the version after - like llvm-18. For the tools, you can pass a specific version instead of true that chooses the default version

NOTE: On Unix systems, when setup-cpp is used locally or in other CI services like GitLab, the environment variables are added to ~/.cpprc. You should run source ~/.cpprc to immediately activate the environment variables. This file is automatically sourced in the next shell restart from ~/.bashrc or ~/.profile if SOURCE_CPPRC is not set to 0. To deactivate .cpprc in the next shell restart, rename/remove ~/.cpprc.

NOTE: On Unix systems, if you are already a root user (e.g., in a GitLab runner or Docker), you will not need to use sudo.

NOTE: setup-cpp requires Nodejs 12 or higher. If Nodejs shipped with your distribution is older than 12, install the latest Node (e.g. for Ubuntu 20.04), or alternatively you can use the executables that are self-contained (see the next section).

With executable

Download the executable for your platform from here, and run it with the available options. You can also automate downloading using curl, or other similar tools.

# windows x64
curl -o ./setup-cpp.exe -LJ "https://github.com/aminya/setup-cpp/releases/download/v1.8.1/setup-cpp-x64-windows.exe"
# linux x64
curl -o ./setup-cpp -LJ "https://github.com/aminya/setup-cpp/releases/download/v1.8.1/setup-cpp-x64-linux"
# linux arm64
curl -o ./setup-cpp -LJ "https://github.com/aminya/setup-cpp/releases/download/v1.8.1/setup-cpp-arm64-linux"
# macos arm64
curl -o ./setup-cpp -LJ "https://github.com/aminya/setup-cpp/releases/download/v1.8.1/setup-cpp-arm64-macos"
# macos x64
curl -o ./setup-cpp -LJ "https://github.com/aminya/setup-cpp/releases/download/v1.8.1/setup-cpp-x64-macos"

An example that installs llvm, cmake, ninja, ccache, and vcpkg:

# windows example (open PowerShell as admin)
./setup-cpp --compiler llvm --cmake true --ninja true --ccache true --vcpkg true
# restart the shell to activate the environment

# linux/macos example
chmod +x ./setup-cpp
sudo ./setup-cpp --compiler llvm --cmake true --ninja true --ccache true --vcpkg true
source ~/.cpprc # activate cpp environment variables

NOTE: On Unix systems, if you are already a root user (e.g., in a GitLab runner or Docker), you will not need to use sudo.

Inside GitHub Actions

A simple example for building with LLVM, cmake, ninja, vcpkg:

      - name: Setup Cpp
        uses: aminya/setup-cpp@v1
        with:
          compiler: llvm
          vcvarsall: true
          cmake: true
          ninja: true
          vcpkg: true

A simple example for installing clang-format for code formatting:

      - name: Setup Cpp
        uses: aminya/setup-cpp@v1
        with:
          clang-format: true

A complete cross-platform example that tests llvm, gcc, and msvc. It also uses cmake, ninja, vcpkg, and cppcheck.

.github/workflows/ci.yml:

name: ci
on:
  pull_request:
  push:
    branches:
      - main
      - master

jobs:
  Test:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os:
          - windows-2022
          - ubuntu-24.04
          - macos-14 # arm64
          - macos-13
        compiler:
          - llvm
          - gcc
          # you can specify the version after `-` like `llvm-18`.
        include:
          - os: "windows-2022"
            compiler: "msvc"
    steps:
      - uses: actions/checkout@v3
      - name: Cache
        uses: actions/cache@v3
        with:
          path: |
            ./build/
            ~/vcpkg
            ~/.cache/vcpkg/archives
            ${{ env.LOCALAPPDATA }}/vcpkg/archives
            ${{ env.APPDATA }}/vcpkg/archives
            ${{ env.XDG_CACHE_HOME }}/vcpkg/archives
            ~/.cache/ccache
            ~/.ccache
            ~/.config/ccache
            ~/Library/Caches/ccache
            ${{ env.LOCALAPPDATA }}/ccache
            ${{ env.XDG_CACHE_HOME }}/ccache
          key: ${{ runner.os }}-${{ matrix.compiler }}-${{ env.BUILD_TYPE }}-${{ hashFiles('**/CMakeLists.txt', './vcpkg.json') }}
          restore-keys: |
            ${{ runner.os }}-${{ env.BUILD_TYPE }}-

      - name: Setup Cpp
        uses: aminya/setup-cpp@v1
        with:
          compiler: ${{ matrix.compiler }}
          vcvarsall: true
          cmake: true
          ninja: true
          vcpkg: true
          cppcheck: true # instead of `true`, which chooses the default version, you can pass a specific version.

When using the setup-cpp action in GitHub Actions, by default it will also install the setup-cpp CLI, which you can use in the subsequent commands. You can modify the default behaviour if needed.

  - name: Setup Cpp
    uses: aminya/setup-cpp@v1
    with:
      setup-cpp: true
      node-package-manager: "npm"

  - name: Use Setup Cpp CLI
    run: setup-cpp --compiler llvm --cmake true --ninja true --ccache true --vcpkg true

Prebuilt Docker Images

To provide fast development environments, setup-cpp provides several prebuilt docker images that have the tools you need. You can use these images as a base image for your project.

The tags are in the following template:

• Base image: aminya/setup-cpp-ubuntu:24.04
• Compiler image: aminya/setup-cpp-ubuntu-llvm:24.04
• Base image with pinned setup-cpp version: aminya/setup-cpp-ubuntu:24.04-v1.8.1
• Compiler image with pinned setup-cpp version: aminya/setup-cpp-ubuntu-llvm:24.04-v1.8.1

The supported platforms are ubuntu, alpine, fedora, and arch. The supported compilers are llvm, gcc, and mingw.

Ubuntu Images (amd64 and arm64)

Setup-cpp provides prebuilt images for various Ubuntu versions (20.04, 22.04, 24.04) with support for base tools, and compilers llvm, gcc, and mingw available for amd64 and arm64 architectures.

Base image with cmake, ninja, task, vcpkg, python, make, cppcheck, gcovr, doxygen, ccache, conan, meson, cmakelang for Ubuntu 24.04:

FROM aminya/setup-cpp-ubuntu:24.04 AS builder

Image with llvm and the base tools:

FROM aminya/setup-cpp-ubuntu-llvm:24.04 AS builder

Image with gcc and the base tools:

FROM aminya/setup-cpp-ubuntu-gcc:24.04 AS builder

Image with mingw and the base tools:

FROM aminya/setup-cpp-ubuntu-mingw:24.04 AS builder

There are also the variants for Ubuntu 22.04

FROM aminya/setup-cpp-ubuntu:22.04 AS builder
FROM aminya/setup-cpp-ubuntu-llvm:22.04 AS builder
FROM aminya/setup-cpp-ubuntu-gcc:22.04 AS builder
FROM aminya/setup-cpp-ubuntu-mingw:22.04 AS builder

And for Ubuntu 20.04:

FROM aminya/setup-cpp-ubuntu:20.04 AS builder
FROM aminya/setup-cpp-ubuntu-llvm:20.04 AS builder
FROM aminya/setup-cpp-ubuntu-gcc:20.04 AS builder
FROM aminya/setup-cpp-ubuntu-mingw:20.04 AS builder

Alpine Images (amd64 and arm64)

Setup-cpp provides prebuilt images for Alpine with support for base tools, and compilers llvm, gcc, and mingw available for amd64 and arm64 architectures.

Base image with cmake, ninja, task, vcpkg, python, make, cppcheck, gcovr, doxygen, ccache, conan, meson, cmakelang for Alpine 3.18:

FROM aminya/setup-cpp-alpine:3.21 AS builder

Image with llvm and the base tools:

FROM aminya/setup-cpp-alpine-llvm:3.21 AS builder

Image with gcc and the base tools:

FROM aminya/setup-cpp-alpine-gcc:3.21 AS builder

Image with mingw and the base tools:

FROM aminya/setup-cpp-alpine-mingw:3.21 AS builder

Fedora Images (amd64)

Base image with cmake, ninja, task, vcpkg, python, make, cppcheck, gcovr, doxygen, ccache, conan, meson, cmakelang

FROM aminya/setup-cpp-fedora:40 AS builder

Image with llvm and the base tools:

FROM aminya/setup-cpp-fedora-llvm:40 AS builder

Image with gcc and the base tools:

FROM aminya/setup-cpp-fedora-gcc:40 AS builder

Image with mingw and the base tools:

FROM aminya/setup-cpp-fedora-mingw:40 AS builder

ArchLinux Images (amd64)

Base image with cmake, ninja, task, vcpkg, python, make, cppcheck, gcovr, doxygen, ccache, conan, meson, cmakelang

FROM aminya/setup-cpp-arch:base AS builder

Image with llvm and the base tools:

FROM