Install all the tools required for building and testing C++/C projects.
Go to file Use this template
Amin Yahyaabadi f29afea287
Merge pull request #316 from aminya/renovate/pnpm-9.x [skip ci]
2024-11-14 13:28:21 -08:00
.github ci: use node/pnpm versions from config files [skip ci] 2024-10-25 00:20:06 -07:00
.vscode ci: use node/pnpm versions from config files [skip ci] 2024-10-25 00:20:06 -07:00
dev chore: v0.44.0 [skip test] 2024-10-02 14:14:36 -07:00
dist fix: use info for venv/setuptools failures 2024-11-01 05:35:48 -07:00
packages feat: support all brew install options 2024-11-01 02:25:55 -07:00
patches fix: use EsModule for actions/http-client 2024-09-03 23:42:52 -07:00
src fix: use info for venv/setuptools failures 2024-11-01 05:35:48 -07:00
.dockerignore feat: add separate production and testing docker files 2023-07-15 15:08:44 -07:00
.eslintrc.json test: mark the skipped tests in jest 2023-09-04 19:27:23 -07:00
.gitattributes fix: update dependencies 2024-01-22 01:41:20 -08:00
.gitignore feat: add script for fetching LLVM asset list 2024-09-07 01:59:58 -07:00
.gitmodules chore: add cpp_vcpkg_project as an example 2022-04-26 22:54:24 -07:00
.npmrc chore: hoist the types packages 2024-08-20 15:22:14 -07:00
.nvmrc chore(deps): update dependency node to v22.10.0 2024-10-25 07:08:50 +00:00
.prettierignore fix: use node 12 as the main target 2023-07-15 15:31:34 -07:00
.terserrc.mjs fix: refactor setupMinGW into an independent function 2024-09-22 21:19:57 -07:00
CONTRIBUTING.md test: run the jest tests in parallel 2023-07-24 15:28:48 -07:00
LICENSE.dependencies.txt fix: remove unused dependencies + list bundled ones [skip test] 2023-08-31 23:01:58 -07:00
LICENSE.txt chore: add the template 2021-09-14 01:50:42 -05:00
README.md chore: v0.44.0 [skip test] 2024-10-02 14:14:36 -07:00
action.yml feat: add support for facebook/infer 2024-09-18 22:19:38 -07:00
babel.config.mts build: transform babel via babel plugin 2024-09-04 02:04:31 -07:00
biome.jsonc fix(llvm): set LLVM_CPPFLAGS/LDFLAGS instead of CPPFLAGS/LDFLAGS 2024-09-17 12:06:23 -07:00
cspell.config.yaml feat: support all brew install options 2024-11-01 02:25:55 -07:00
dprint.json fix: minify json assets via @aminya/minijson 2024-09-07 00:42:27 -07:00
jest.config.mjs fix: add module type to packages + fix running the packages tests 2024-08-26 14:46:06 -07:00
lefthook.yml fix: fix nala installation on Ubuntu 20.04 2024-09-03 02:37:03 -07:00
package-version.json chore: v0.44.0 [skip test] 2024-10-02 14:14:36 -07:00
package.json chore(deps): update pnpm to v9.13.1 2024-11-14 19:46:37 +00:00
pnpm-lock.yaml fix(deps): update dependencies 2024-09-21 02:59:06 +00:00
pnpm-workspace.yaml build: add turbo for faster builds 2024-08-15 15:55:02 -07:00
prettier.config.mjs lint: use dprint for formatting 2024-04-03 00:15:43 -07:00
tsconfig.json fix: fix the types of node builtin modules 2024-09-17 17:16:43 -07:00
turbo.json fix: add module type to packages + fix running the packages tests 2024-08-26 14:46:06 -07:00
vite.config.mts fix: downgrade numerous + update @types/node 2024-09-20 16:17:38 -07:00

README.md

setup-cpp

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

Build Status (Github Actions)

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/ARM, and macOS (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.

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, nala
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

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/v0.44.0/setup-cpp-x64-windows.exe"

# linux x64
curl -o ./setup-cpp -LJ "https://github.com/aminya/setup-cpp/releases/download/v0.44.0/setup-cpp-x64-linux"
chmod +x ./setup-cpp

# macos arm64
curl -o ./setup-cpp -LJ "https://github.com/aminya/setup-cpp/releases/download/v0.44.0/setup-cpp-arm64-macos"
chmod +x ./setup-cpp

# macos x64
curl -o ./setup-cpp -LJ "https://github.com/aminya/setup-cpp/releases/download/v0.44.0/setup-cpp-x64-macos"
chmod +x ./setup-cpp

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
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

Here is 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: ${{ contains(matrix.os, 'windows') }}
          cmake: true
          ninja: true
          vcpkg: true
          cppcheck: true
          clang-tidy: true # instead of `true`, which chooses the default version, you can pass a specific version.
          # ...

Prebuilt Docker Images

To provide fast development environments, setup-cpp provides several prebuilt docker images that have the tools you need (e.g. llvm, cmake, ninja, task, vcpkg, python, make, cppcheck, gcovr, doxygen, ccache).

You can use these images as a base image for your project.

FROM aminya/setup-cpp-ubuntu-llvm:22.04-0.44.0 AS builder
FROM aminya/setup-cpp-ubuntu-mingw:22.04-0.44.0 AS builder
FROM aminya/setup-cpp-fedora-llvm:40-0.44.0 AS builder
FROM aminya/setup-cpp-arch-llvm:base-0.44.0 AS builder

The names are in the format aminya/setup-cpp-<platform>-<compiler>:<platform_version>-<setup_cpp_version>.

If you need to install the tools selectively, see the next section.

Inside Docker

Here is an example for using setup-cpp to make a builder image that has the Cpp tools you need.

#### Base Image
FROM ubuntu:22.04 as setup-cpp-ubuntu

RUN apt-get update -qq && \
    # install nodejs
    apt-get install -y --no-install-recommends nodejs npm && \
    # install setup-cpp
    npm install -g setup-cpp@v0.44.0 && \
    # install the compiler and tools
    setup-cpp \
        --nala true \
        --compiler llvm \
        --cmake true \
        --ninja true \
        --task true \
        --vcpkg true \
        --python true \
        --make true \
        --cppcheck true \
        --gcovr true \
        --doxygen true \
        --ccache true && \
    # cleanup
    nala autoremove -y && \
    nala autopurge -y && \
    apt-get clean && \
    nala clean --lists && \
    rm -rf /var/lib/apt/lists/* && \
    rm -rf /tmp/*

ENTRYPOINT ["/bin/bash"]

#### Building (example)
FROM setup-cpp-ubuntu AS builder

COPY ./dev/cpp_vcpkg_project /home/app
WORKDIR /home/app
RUN bash -c 'source ~/.cpprc \
    && task build'

#### Running environment
# use a fresh image as the runner
FROM ubuntu:22.04 as runner

# copy the built binaries and their runtime dependencies
COPY --from=builder /home/app/build/my_exe/Release/ /home/app/
WORKDIR /home/app/
ENTRYPOINT ["./my_exe"]

See this folder, for some dockerfile examples.

If you want to build the ones included, then run:

git clone --recurse-submodules https://github.com/aminya/setup-cpp
cd ./setup-cpp
docker build -f ./dev/docker/setup-cpp/setup-cpp-ubuntu.dockerfile -t setup-cpp-ubuntu-llvm:22.04-17 ./

Where you should use the path to the dockerfile after -f.

After build, run the following to start an interactive shell in your container

docker run -it setup-cpp-ubuntu-llvm:22.04-17

Inside Docker inside GitHub Actions

You can use the docker file discussed in the previous section inside GitHub Actions like the following:

jobs:
  Docker:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os:
          - ubuntu-24.04
    steps:
      - uses: actions/checkout@v3
      - name: Build
        id: docker_build
        run: |
          docker build -f ./dev/docker/ubuntu.dockerfile -t setup-cpp .          

Inside GitLab pipelines

The following gives an example for setting up a C++ environment inside GitLab pipelines.

.gitlab-ci.yaml

image: ubuntu:22.04

stages:
  - test

.setup_linux: &setup_linux |
  DEBIAN_FRONTEND=noninteractive

  # set time-zone
  TZ=Canada/Pacific
  ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

  # for downloading
  apt-get update -qq
  apt-get install -y --no-install-recommends curl gnupg ca-certificates  

.setup-cpp: &setup-cpp |
  # install nodejs
  apt-get install -y --no-install-recommends nodejs npm

  # install setup-cpp
  npm install -g setup-cpp@v0.44.0

  # install the compiler and tools
  ./setup-cpp-x64-linux --compiler $compiler --cmake true --ninja true --ccache true --vcpkg true
  source ~/.cpprc  

.test: &test |
  # Build and Test
  # ...  

test_linux_llvm:
  stage: test
  variables:
    compiler: llvm
  script:
    - *setup_linux
    - *setup-cpp
    - *test

test_linux_gcc:
  stage: test
  variables:
    compiler: gcc
  script:
    - *setup_linux
    - *setup-cpp
    - *test

Articles

Setup-Cpp on Dev.to

Usage Examples

See all of the usage examples on GitHub here.