2021-09-14 14:51:57 +08:00
# setup-cpp
2021-09-14 14:57:47 +08:00
Install all the tools required for building and testing C++/C projects.
2021-09-14 14:51:57 +08:00
![Build Status (Github Actions) ](https://github.com/aminya/setup-cpp/workflows/CI/badge.svg )
2021-09-14 17:40:04 +08:00
2021-09-17 19:29:58 +08:00
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.
2021-09-14 17:40:04 +08:00
2022-07-11 10:32:25 +08:00
`setup-cpp` can be used locally from terminal, from CI services like GitHub Actions and GitLab Pipelines, and inside containers like Docker.
2021-09-14 17:40:04 +08:00
2022-07-27 15:55:14 +08:00
`setup-cpp` is supported on many platforms. It is continuously tested on several configurations including Windows (11, 10, 2022, 2019), Linux (Ubuntu 22.04, Ubuntu 20.04, Fedora, ArchLinux), and macOS (12, 11, 10.15). `setup-cpp` is backed by unit tests for each tool and integration tests for compiling cpp projects.
2021-09-14 17:40:04 +08:00
2022-07-28 08:36:18 +08:00
## Features
2021-09-16 20:15:17 +08:00
2022-07-11 10:32:25 +08:00
`setup-cpp` is **modular** and you can choose to install any of these tools:
2021-09-16 18:00:16 +08:00
2022-05-25 06:34:34 +08:00
| category | tools |
| --------------------- | ------------------------------------------------------------ |
| compiler and analyzer | llvm, gcc, msvc, vcvarsall, cppcheck, clangtidy, clangformat |
2022-07-28 10:32:33 +08:00
| build system | cmake, ninja, meson, make, task, bazel |
2022-07-28 08:36:18 +08:00
| package manager | vcpkg, conan, choco, brew, nala |
2022-11-21 14:45:45 +08:00
| cache | cppcache, sccache |
2022-05-25 06:34:34 +08:00
| documentation | doxygen, graphviz |
| coverage | gcovr, opencppcoverage, kcov |
2022-11-21 09:51:40 +08:00
| other | python, powershell, sevenzip |
2022-05-25 06:34:34 +08:00
2023-06-30 06:37:08 +08:00
`setup-cpp` automatically handles the dependencies of the selected tool (e.g., `python` is required for `conan` ).
2021-09-16 18:00:16 +08:00
2022-07-28 08:36:18 +08:00
## Usage
2021-09-17 23:27:08 +08:00
2022-07-28 08:36:18 +08:00
### From Terminal
2021-09-18 02:24:17 +08:00
2023-01-18 14:05:33 +08:00
#### With npm and Nodejs
2021-09-18 02:24:17 +08:00
2023-05-25 02:31:29 +08:00
Run `setup-cpp` with the available options.
2023-01-18 14:05:33 +08:00
```shell
2023-05-25 02:31:29 +08:00
# Windows example (open PowerShell as admin)
npx setup-cpp --compiler llvm --cmake true --ninja true --ccache true --vcpkg true
2023-01-18 14:05:33 +08:00
RefreshEnv.cmd # activate the environment
```
2021-09-18 02:24:17 +08:00
2023-01-18 14:05:33 +08:00
```shell
2023-05-25 02:31:29 +08:00
# Linux/Macos example
sudo npx setup-cpp --compiler llvm --cmake true --ninja true --ccache true --vcpkg true
2023-01-18 14:05:33 +08:00
source ~/.cpprc
```
NOTE: In the `compiler` entry, you can specify the version after `-` like `llvm-11.0.0` . 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` .
#### With executable
2023-07-07 06:57:48 +08:00
Download the executable for your platform from [here ](https://github.com/aminya/setup-cpp/releases/tag/v0.30.1 ), and run it with the available options. You can also automate downloading using `wget` , `curl` , or other similar tools.
2023-01-18 14:05:33 +08:00
2021-11-22 02:11:26 +08:00
An example that installs llvm, cmake, ninja, ccache, and vcpkg:
2021-09-18 04:40:13 +08:00
2023-01-18 14:05:33 +08:00
```shell
2023-01-18 13:50:44 +08:00
# windows example (open PowerShell as admin)
2023-07-07 06:57:48 +08:00
curl -LJO "https://github.com/aminya/setup-cpp/releases/download/v0.30.1/setup-cpp-x64-windows.exe"
2023-01-18 13:50:44 +08:00
./setup-cpp-x64-windows --compiler llvm --cmake true --ninja true --ccache true --vcpkg true
2022-01-18 10:51:14 +08:00
2022-03-12 09:48:28 +08:00
RefreshEnv.cmd # activate cpp environment variables
2021-09-18 02:24:17 +08:00
```
2021-09-18 10:42:56 +08:00
2023-01-18 14:05:33 +08:00
```shell
2021-09-18 10:42:56 +08:00
# linux example
2023-07-07 06:57:48 +08:00
wget "https://github.com/aminya/setup-cpp/releases/download/v0.30.1/setup-cpp-x64-linux"
2023-01-18 13:50:44 +08:00
chmod +x ./setup-cpp-x64-linux
sudo ./setup-cpp-x64-linux --compiler llvm --cmake true --ninja true --ccache true --vcpkg true
2022-01-18 10:51:14 +08:00
2022-03-12 09:48:28 +08:00
source ~/.cpprc # activate cpp environment variables
2021-09-18 10:42:56 +08:00
```
2023-01-18 14:05:33 +08:00
```shell
2023-01-18 13:50:44 +08:00
# macos example
2023-07-07 06:57:48 +08:00
wget "https://github.com/aminya/setup-cpp/releases/download/v0.30.1/setup-cpp-x64-macos"
2023-01-18 13:50:44 +08:00
chmod +x ./setup-cpp-x64-macos
sudo ./setup-cpp-x64-macos --compiler llvm --cmake true --ninja true --ccache true --vcpkg true
2022-01-18 10:51:14 +08:00
2022-03-12 09:48:28 +08:00
source ~/.cpprc # activate cpp environment variables
2021-09-18 02:24:17 +08:00
```
2022-07-28 08:36:18 +08:00
### Inside GitHub Actions
2021-09-17 23:27:08 +08:00
2021-12-07 00:41:50 +08:00
Here is a complete cross-platform example that tests llvm, gcc, and msvc. It also uses cmake, ninja, vcpkg, and cppcheck.
2021-09-17 23:27:08 +08:00
`.github/workflows/ci.yml` :
```yaml
name: ci
on:
pull_request:
push:
branches:
- main
- master
jobs:
Test:
runs-on: ${{ matrix.os }}
strategy:
fail-fast: false
matrix:
os:
2022-02-14 09:50:58 +08:00
- windows-2022
2022-08-22 15:00:57 +08:00
- ubuntu-22.04
- macos-12
2021-09-17 23:27:08 +08:00
compiler:
- llvm
- gcc
2021-11-22 06:40:30 +08:00
# you can specify the version after `-` like `llvm-13.0.0` .
2021-11-23 15:51:10 +08:00
include:
2022-02-14 09:50:58 +08:00
- os: "windows-2022"
2021-11-23 15:51:10 +08:00
compiler: "msvc"
2021-09-17 23:27:08 +08:00
steps:
2022-08-22 15:00:57 +08:00
- uses: actions/checkout@v3
2021-11-23 15:51:10 +08:00
- name: Cache
2022-08-22 15:00:57 +08:00
uses: actions/cache@v3
2021-11-23 15:51:10 +08:00
with:
path: |
~/vcpkg
./build/vcpkg_installed
${{ env.HOME }}/.cache/vcpkg/archives
${{ env.XDG_CACHE_HOME }}/vcpkg/archives
${{ env.LOCALAPPDATA }}\vcpkg\archives
${{ env.APPDATA }}\vcpkg\archives
key: ${{ runner.os }}-${{ matrix.compiler }}-${{ env.BUILD_TYPE }}-${{ hashFiles('**/CMakeLists.txt') }}-${{ hashFiles('./vcpkg.json')}}
restore-keys: |
2022-02-21 07:55:32 +08:00
${{ runner.os }}-${{ env.BUILD_TYPE }}-
2021-11-23 15:51:10 +08:00
2021-09-17 23:27:08 +08:00
- name: Setup Cpp
2021-09-18 04:32:14 +08:00
uses: aminya/setup-cpp@v1
2021-09-17 23:27:08 +08:00
with:
compiler: ${{ matrix.compiler }}
2022-01-30 07:13:52 +08:00
vcvarsall: ${{ contains(matrix.os, 'windows') }}
2021-09-17 23:27:08 +08:00
cmake: true
ninja: true
2021-11-22 07:07:02 +08:00
vcpkg: true
2022-01-30 07:13:52 +08:00
cppcheck: true
clangtidy: true # instead of `true` , which chooses the default version, you can pass a specific version.
# ...
2021-09-17 23:27:08 +08:00
```
2022-07-28 08:36:18 +08:00
### Inside Docker
2021-09-19 00:50:18 +08:00
2023-01-18 13:40:21 +08:00
Here is an example for using setup-cpp to make a builder image that has the Cpp tools you need.
2021-09-19 00:50:18 +08:00
```dockerfile
2022-04-27 14:05:25 +08:00
#### Base Image
2023-07-16 10:21:51 +08:00
FROM ubuntu:22.04 as setup-cpp-ubuntu
2021-09-19 00:50:18 +08:00
2023-07-16 06:05:41 +08:00
RUN apt-get update -qq & & \
2023-07-16 10:21:51 +08:00
# install nodejs
2023-07-16 06:05:41 +08:00
apt-get install -y --no-install-recommends nodejs npm & & \
2023-07-16 10:21:51 +08:00
# install setup-cpp
npm install -g setup-cpp@v0.30.1 & & \
# 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/*
2022-01-18 10:51:14 +08:00
2023-07-16 06:05:41 +08:00
ENTRYPOINT ["/bin/bash"]
2022-04-27 14:05:25 +08:00
2023-07-16 06:05:41 +08:00
#### Building (example)
2023-07-16 10:21:51 +08:00
FROM setup-cpp-ubuntu AS builder
2023-07-16 06:05:41 +08:00
COPY ./dev/cpp_vcpkg_project /home/app
2022-04-27 14:05:25 +08:00
WORKDIR /home/app
2022-04-27 15:02:35 +08:00
RUN bash -c 'source ~/.cpprc \
2023-07-16 06:05:41 +08:00
& & task build'
2023-07-16 10:21:51 +08:00
#### Running environment
# use a fresh image as the runner
FROM ubuntu:22.04 as runner
2022-04-27 14:05:25 +08:00
# 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"]
2021-09-19 00:50:18 +08:00
```
2022-04-27 13:07:54 +08:00
See [this folder ](https://github.com/aminya/setup-cpp/tree/master/dev/docker ), for some dockerfile examples.
2021-09-19 00:50:18 +08:00
2021-09-19 01:05:52 +08:00
If you want to build the ones included, then run:
2021-09-19 00:50:18 +08:00
2023-01-18 14:05:33 +08:00
```shell
2022-04-27 13:33:36 +08:00
git clone --recurse-submodules https://github.com/aminya/setup-cpp
cd ./setup-cpp
2023-07-16 10:21:51 +08:00
docker build -f ./dev/docker/setup-cpp-ubuntu.dockerfile -t setup-cpp .
2021-09-19 00:50:18 +08:00
```
2022-01-30 07:13:52 +08:00
Where you should use the path to the dockerfile after `-f` .
2021-09-30 08:56:28 +08:00
After build, run the following to start an interactive shell in your container
2023-01-18 14:05:33 +08:00
```shell
2023-01-18 13:40:21 +08:00
docker run -it setup-cpp
2021-09-30 08:56:28 +08:00
```
2021-12-07 05:02:01 +08:00
2022-07-28 08:36:18 +08:00
### Inside Docker inside GitHub Actions
2021-12-07 05:02:01 +08:00
You can use the docker file discussed in the previous section inside GitHub Actions like the following:
```yaml
jobs:
Docker:
runs-on: ${{ matrix.os }}
strategy:
matrix:
os:
2022-08-22 15:00:57 +08:00
- ubuntu-22.04
2021-12-07 05:02:01 +08:00
steps:
2022-08-22 15:00:57 +08:00
- uses: actions/checkout@v3
2021-12-07 05:02:01 +08:00
- name: Build
id: docker_build
run: |
2023-07-16 06:05:41 +08:00
docker build -f ./dev/docker/ubuntu.dockerfile -t setup-cpp .
2021-12-07 16:46:07 +08:00
```
2021-12-17 01:51:52 +08:00
2022-07-28 08:36:18 +08:00
### Inside GitLab pipelines
2022-01-20 09:42:18 +08:00
The following gives an example for setting up a C++ environment inside GitLab pipelines.
.gitlab-ci.yaml
```yaml
2022-05-03 13:37:10 +08:00
image: ubuntu:22.04
2022-01-20 09:42:18 +08:00
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
# keys used by apt
apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 3B4FE6ACC0B21F32
apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 40976EAF437D05B5
apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 1E9377A2BA9EF27F
2023-01-18 13:40:21 +08:00
.setup-cpp: & setup-cpp |
2023-07-07 06:57:48 +08:00
curl -LJO "https://github.com/aminya/setup-cpp/releases/download/v0.30.1/setup-cpp-x64-linux"
2023-01-18 13:50:44 +08:00
chmod +x setup-cpp-x64-linux
./setup-cpp-x64-linux --compiler $compiler --cmake true --ninja true --ccache true --vcpkg true
2022-03-01 18:43:50 +08:00
source ~/.cpprc
2022-01-20 09:42:18 +08:00
.test: & test |
# Build and Test
# ...
test_linux_llvm:
stage: test
variables:
compiler: llvm
script:
- *setup_linux
2023-01-18 13:40:21 +08:00
- *setup-cpp
2022-01-20 09:42:18 +08:00
- *test
test_linux_gcc:
stage: test
variables:
compiler: gcc
script:
- *setup_linux
2023-01-18 13:40:21 +08:00
- *setup-cpp
2022-01-20 09:42:18 +08:00
- *test
```
2022-07-28 08:36:18 +08:00
## Articles
2021-12-17 01:51:52 +08:00
[Setup-Cpp on Dev.to ](https://dev.to/aminya/setup-cpp-3ia4 )
2022-07-28 08:36:18 +08:00
## Usage Examples
2021-12-17 01:51:52 +08:00
2022-04-27 15:27:44 +08:00
- [cpp_vcpkg_project project ](https://github.com/aminya/cpp_vcpkg_project )
2022-10-20 15:52:01 +08:00
- [project_options ](https://github.com/aminya/project_options )
2022-01-30 07:13:52 +08:00
- [cpp-best-practices starter project ](https://github.com/cpp-best-practices/cpp_starter_project )
2022-10-09 07:40:01 +08:00
- [ftxui ](https://github.com/ArthurSonzogni/FTXUI )
- [inja ](https://github.com/pantor/inja )
- [teslamotors/fixed-containers ](https://github.com/teslamotors/fixed-containers )
- [zeromq.js ](https://github.com/zeromq/zeromq.js )
2022-04-27 15:27:44 +08:00
- [json2cpp ](https://github.com/lefticus/json2cpp )
- [lefticus/tools ](https://github.com/lefticus/tools )
2022-11-07 16:07:27 +08:00
- [watcher ](https://github.com/e-dant/watcher )
- [pinpoint-c-agent ](https://github.com/pinpoint-apm/pinpoint-c-agent )
2021-12-17 01:51:52 +08:00
- [dpp ](https://github.com/atilaneves/dpp )
2022-10-09 07:40:01 +08:00
- [DSpellCheck ](https://github.com/Predelnik/DSpellCheck )
- [simdjson-rust ](https://github.com/SunDoge/simdjson-rust )
- [CXXIter ](https://github.com/seijikun/CXXIter )
- [git-tui ](https://github.com/ArthurSonzogni/git-tui )
2022-11-07 16:07:27 +08:00
- [supercell ](https://github.com/orex/supercell )
2022-10-09 07:40:01 +08:00
- [libclang ](https://github.com/atilaneves/libclang )
2021-12-17 01:51:52 +08:00
- [d-tree-sitter ](https://github.com/aminya/d-tree-sitter )
2022-10-09 07:40:01 +08:00
- [atom-community/papm ](https://github.com/atom-community/papm )
- [ecs_benchmark ](https://github.com/abeimler/ecs_benchmark )
- [smk ](https://github.com/ArthurSonzogni/smk )
2021-12-17 01:51:52 +08:00
See all of the usage examples on GitHub [here ](https://github.com/search?q=aminya%2Fsetup-cpp+path%3A.github%2Fworkflows%2F+language%3AYAML+fork%3Atrue&type=code ).