Setup C++

Set up a C++ compiler and add it to the PATH.

This is usually the first step in your workflow after consuming a matrix generated by C++ Matrix.

The compiler parameter can be used to provide a compiler name or a compiler name with its version, separated by whitespace or a -. Examples valid names are gcc, g++, clang, gcc-10, g++ 10, clang 9.2.

Note that strings like 10 and 9.2 are semver requirements and not semver versions. For instance, 10 represents the requirement equivalent to >=10.0.0 <11.0.0 while 9.2 represents the requirement equivalent to >=9.2.0 <9.3.0.

If the compiler parameter does not include a version requirement, the version parameter can be used to provide a version semver string in the npm format with the compiler requirements.

Compiler behavior

GCC and Clang

If the compiler is GCC or Clang, this action routes to the appropriate Setup GCC or Setup Clang actions.

MSVC

If the compiler is MSVC, this action will set up the developer command prompt for Microsoft Visual C++.

Visual Studio exposes four overlapping version concepts:

  • Release year – marketing name such as 2022 or 2026.

  • Product version – IDE channel numbers like 17.11.

  • MSVC toolset version – compiler/toolchain identifier such as 14.42.

  • MSVC compiler version – the cl.exe front-end version reported by cl /Bv (for example 19.44.35219).

When you pass compiler: msvc, the version input and any inline requirements (for example msvc-14.42) refer to the MSVC toolset version. Use this number when you depend on a specific cl.exe toolchain. The action still reports the release year and product version in its outputs for reference, but they are not used for resolution.

Use the arch input when you need to force a specific MSVC architecture (for example x86 or arm64). When omitted, the action falls back to the runner architecture.

MinGW and other compilers

If the compiler is MinGW, this action will look for g++ and gcc in the directories listed in the PATH environment variable.

Any other compilers are passed through.

If the compiler is GCC or Clang, the outputs include the paths to the compilers as well as the compiler version ultimately setup by the action.

Next steps

After setting up the proper C++ compiler for a matrix entry, the next step in your workflow should usually be Install Packages.

Example

steps:
- name: Setup C++
  uses: alandefreitas/cpp-actions/setup-cpp@v1.9
  id: setup-cpp
  with:
    compiler: ${{ matrix.compiler }}
    version: ${{ matrix.version }}
    arch: ${{ matrix.arch }}

Input Parameters

Parameter

Description

Default

trace-commands

Trace commands executed by the workflow.

false

compiler

Compiler name. If the compiler contains a version, it overrides 'version'.

*

version

Version range or exact version of GCC to use, using SemVer’s version range syntax.

By default, it uses any version available in the environment.

*

path

The compiler executable. We attempt to find the compiler at this path first.

check-latest

By default, when the compiler is not available, this action will install the minimum version in the version spec. This ensures the code respects its contract in terms of what minimum GCC version is supported.

Set this option if you want the action to check for the latest available version that satisfies the version spec instead.

false

update-environment

Set this option if you want the action to update environment variables.

true

arch

Target architecture name forwarded to MSVC (for example x86, x64, arm64). When empty, the runner architecture is used. Non-MSVC compilers ignore this input.

Outputs

Output

Description

cc

The absolute path to the C compiler executable.

cxx

The absolute path to the C++ compiler executable.

bindir

The absolute path to the directory containing the executable.

dir

The absolute path to the directory containing the installation.

version

The installed compiler version. For MSVC this is the MSVC toolset version; for other compilers it is their native version string.

version-major

The installed compiler version major. Useful when given a version range as input.

version-minor

The installed compiler version minor. Useful when given a version range as input.

version-patch

The installed compiler version patch. Useful when given a version range as input.

msvc-toolset-version

When using MSVC, the toolset version resolved for cl.exe (for example 14.44.35207).

msvc-product-version

When using MSVC, the Visual Studio product version (for example 17.11).

msvc-release-year

When using MSVC, the mapped Visual Studio release year (for example 2022).

msvc-compiler-version

When using MSVC, the cl.exe front-end version reported by cl /Bv (for example 19.44.35219).