# toolchains-cc

**Repository Path**: justbuild/toolchains-cc

## Basic Information

- **Project Name**: toolchains-cc
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-02-04
- **Last Updated**: 2025-07-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# C/C++ Toolchains for Justbuild

This repository provides system and prebuilt toolchain definitions for
Justbuild.

## Available toolchains

Currently available toolchains are:

- `system_toolchain` **(default)**
- `prebuilt_clang19-aarch64-linux-gnu`
- `prebuilt_clang18-x86_64-ubuntu`
- `prebuilt_clang18-aarch64-linux-gnu`
- `prebuilt_clang17-x86_64-ubuntu`
- `prebuilt_clang17-aarch64-linux-gnu`
- `prebuilt_clang16-aarch64-linux-gnu`
- `prebuilt_clang14-x86_64-rhel`
- `prebuilt_clang14-aarch64-linux-gnu`

All toolchains are based on the [C/C++ rule set](https://github.com/just-buildsystem/rules-cc),
so that they can be directly used as rules.

> Please note that the prebuilt toolchains do not support cross-compilation.


## Getting started

You can import the `system_toolchain` definition from this repository as alias
`toolchain`, by adding the following entry to the *imports section* of your
`repos.in.json`:

~~~ jsonc
"imports": [
  {
    "source": "git",
    "branch": "master",
    "url": "https://gitee.com/justbuild/toolchains-cc",
    "repos": [{"repo": "system_toolchain", "alias": "toolchain"}]
  },
  // ...
],
~~~

Afterwards, run `just-lock` to generate the `repos.json` lock file, needed for
building.

## General Configuration

The toolchain is configured using the following configuration variables:

|Variable|Description|Default Value|
|-|-|-:|
| `DEBUG` | Debug build options | `null` |
| `ARCH` | Unqualified architecture | `"x86_64"` |
| `HOST_ARCH` | Build host's architecture | *derived from ARCH* |
| `TARGET_ARCH` | Build target's architecture | *derived from ARCH* |
| `TOOLCHAIN_CONFIG["FAMILY"]` | Compiler family | `"generic"` |
| `TOOLCHAIN_CONFIG["VENDOR"]` | Target triplet vendor | `""` |
| `TOOLCHAIN_CONFIG["SYSTEM"]` | Target triplet system | `"linux-gnu"` |
| `TOOLCHAIN_CONFIG["CFLAGS"]` | Extra C compile flags | `[]` |
| `TOOLCHAIN_CONFIG["CXXFLAGS"]` | Extra C++ compile flags | `[]` |
| `TOOLCHAIN_CONFIG["LDFLAGS"]` | Extra linker flags | `[]` |
| `TOOLCHAIN_CONFIG["PATH"]` | Toolchain system paths | `["/bin", "/usr/bin"]` |
| `TOOLCHAIN_CONFIG["GRPC_PLUGIN"]` | gRPC C++ plugin path | `"/usr/bin/grpc_cpp_plugin"` |
| `TOOLCHAIN_CONFIG["PKG_CONFIG_PATH"]` | Additional pkg-config paths | `[]` |
| `TOOLCHAIN_CONFIG["FORCE_CC"]` | Force C compiler name | `null` |
| `TOOLCHAIN_CONFIG["FORCE_CXX"]` | Force C++ compiler name | `null` |
| `TOOLCHAIN_CONFIG["FORCE_AR"]` | Force archiver name | `null` |
| `TOOLCHAIN_CONFIG["FORCE_DWP"]` | Force DWARF pkg utility | `null` |

> Please note that `DEBUG` is a map and anything logically false (e.g., `null`,
> empty map) disables debug mode. For full list of valid options, please see the
> [C/C++ rule documentation on debug fission](https://github.com/just-buildsystem/rules-cc/blob/master/doc/debug-fission.md).

### System Toolchain

The system toolchain supports the following compiler families:

- `"gnu"`: GCC compiler from system
- `"clang"`: Clang compiler from system
- `"generic"`: Generic compiler interface (`cc`/`c++`)

Please note that the family `"generic"` does not support cross-compilation. For
the other families, the cross-compilation target triplet is computed from the
variables: `<TARGET_ARCH>-[<VENDOR>-]<SYSTEM>`.


**Example:** Building with GCC on Void Linux x86_64 with musl libc:

~~~ json
{
  "ARCH": "x86_64",
  "TOOLCHAIN_CONFIG": {
    "FAMILY": "gnu",
    "SYSTEM": "linux-musl",
    "FORCE_AR": "ar"
  }
}
~~~

**Example:** Cross-compiling for arm64 with Clang on RedHat Linux x86_64:

~~~ json
{
  "ARCH": "x86_64",
  "TARGET_ARCH": "arm64",
  "TOOLCHAIN_CONFIG": {
    "FAMILY": "clang",
    "VENDOR": "redhat",
    "SYSTEM": "linux-gnu"
  }
}
~~~

### Prebuilt Clang Toolchains

The prebuilt Clang toolchains support the following additional configuration
variables:

|Variable|Description|Default Value|
|-|-|-:|
| `TOOLCHAIN_CONFIG["USE_LIBCXX"]` | Use LLVM's libc++ | `false` |
| `TOOLCHAIN_CONFIG["STATIC_RUNLIBS"]` | Link runtime libraries statically | `false` |

**Example:** Compiling using LLVM's libc++ and linking all runtime libraries
statically:

~~~ json
{
  "TOOLCHAIN_CONFIG": {
    "USE_LIBCXX": true,
    "STATIC_RUNLIBS": true
  }
}
~~~