The Carbon language project has a number of tools used to assist in preparing contributions.
These commands should help set up a development environment on your machine.
# Update apt.
sudo apt update
# Install tools.
sudo apt install \
bazel \
clang \
gh \
libc++-dev \
lld \
python3 \
zlib1g-dev
# Install pre-commit.
pip3 install pre-commit
# Set up git.
# If you don't already have a fork:
gh repo fork --clone carbon-language/carbon-lang
cd carbon-lang
pre-commit install
# Run tests.
bazel test //...:all
NOTE: Most LLVM 14+ installs should build Carbon. If you're having issues, see troubleshooting build issues.
# Install Hombrew.
/bin/bash -c "$(curl -fsSL \
https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# IMPORTANT: Make sure `brew` is added to the PATH!
# Install Homebrew tools.
brew install \
bazelisk \
gh \
llvm \
python@3.10
# IMPORTANT: Make sure `llvm` is added to the PATH! It's separate from `brew`.
# Install pre-commit.
pip3 install pre-commit
# Set up git.
gh repo fork --clone carbon-language/carbon-lang
cd carbon-lang
pre-commit install
# Run tests.
bazel test //...:all
NOTE: On macOS, you should end up adding rc file lines similar to:
# For `brew`, `gh`, and other tools: export PATH="${HOME}/.brew/bin:${PATH}" # For `llvm`: export PATH="$(brew --prefix llvm)/bin:${PATH}"
These tools are essential for work on Carbon.
- Package managers
apt
(for Debian or Ubuntu)- To upgrade versions of
apt
packages, it will be necessary to periodically runsudo apt update && sudo apt upgrade
.
- To upgrade versions of
- Homebrew (for macOS)
- To upgrade versions of
brew
packages, it will be necessary to periodically runbrew upgrade
.
- To upgrade versions of
python3
andpip3
- Carbon requires Python 3.9 or newer.
- To upgrade versions of
pip3
packages, it will be necessary to periodically runpip3 list --outdated
, thenpip3 install -U <package>
to upgrade desired packages. - When upgrading, version dependencies may mean packages should be outdated, and not be upgraded.
- Main tools
- Bazel
- NOTE: See the bazelisk config for a supported version.
- Bazelisk (for macOS): Handles Bazel versions.
- Clang and LLVM
- NOTE: Most LLVM 14+ installs should build Carbon. If you're having issues, see troubleshooting build issues.
- gh CLI: Helps with GitHub.
- pre-commit: Validates and cleans up git commits.
- Bazel
- Libraries
- zlib1g-dev: Used as a library, but not installed on all Linux systems.
pre-commit is typically set up using
pre-commit install
. When set up in this mode, it will check for issues when
git commit
is run. A typical commit workflow looks like:
git commit
to try committing files. This automatically executespre-commit run
, which may fail and leave files modified for cleanup.git add .
to add the automatically modifications done bypre-commit
.git commit
again.
You can also use pre-commit run
to check pending changes without git commit
,
or pre-commit run -a
to run on all files in the repository.
NOTE: Some developers prefer to run
pre-commit
ongit push
instead ofgit commit
because they want to commit files as originally authored instead of with pre-commit modifications. To switch, runpre-commit uninstall && pre-commit install -t pre-push
.
These tools aren't necessary to contribute to Carbon, but can be worth considering if they fit your workflow.
- GitHub Desktop: A UI for managing GitHub repositories.
rs-git-fsmonitor
and Watchman: Helps makegit
run faster on large repositories.- WARNING: Bugs in
rs-git-fsmonitor
and/or Watchman can result inpre-commit
deleting files. If you see files being deleted, disablers-git-fsmonitor
withgit config --unset core.fsmonitor
.
- WARNING: Bugs in
- vim-prettier: A vim integration for Prettier, which we use for formatting.
- Visual Studio Code: A code editor.
- We provide recommended extensions to assist
Carbon development. Some settings changes must be made separately:
- Python › Formatting: Provider:
black
- Python › Formatting: Provider:
- WARNING: Visual Studio Code modifies the
PATH
environment variable, particularly in the terminals it creates. ThePATH
difference can causebazel
to detect different startup options, discarding its build cache. As a consequence, it's recommended to use either normal terminals or Visual Studio Code to runbazel
, not both in combination. Visual Studio Code can still be used for other purposes, such as editing files, without interfering withbazel
. - DevContainers: A
way to use Docker for build environments.
- After following the installation instructions, you should be prompted to use Carbon's devcontainer with "Reopen in container".
- We provide recommended extensions to assist
Carbon development. Some settings changes must be made separately:
We primarily test against apt.llvm.org and Homebrew installations. However, you can build and install LLVM yourself if you feel more comfortable with it. The essential CMake options to pass in order for this to work reliably include:
-DLLVM_ENABLE_PROJECTS=clang;clang-tools-extra;lld
-DLLVM_ENABLE_RUNTIMES=compiler-rt;libcxx;libcxxabi;libunwind
-DRUNTIMES_CMAKE_ARGS=-DLLVM_ENABLE_PER_TARGET_RUNTIME_DIR=OFF;-DCMAKE_POSITION_INDEPENDENT_CODE=ON;-DLIBCXX_ENABLE_STATIC_ABI_LIBRARY=ON;-DLIBCXX_STATICALLY_LINK_ABI_IN_SHARED_LIBRARY=OFF;-DLIBCXX_STATICALLY_LINK_ABI_IN_STATIC_LIBRARY=ON;-DLIBCXX_USE_COMPILER_RT=ON;-DLIBCXXABI_USE_COMPILER_RT=ON;-DLIBCXXABI_USE_LLVM_UNWINDER=ON
Many build issues result from the particular options clang
and llvm
have
been built with, particularly when it comes to system-installed versions. If you
run clang --version
, you should see at least version 14. If you see an older
version, please update.
System installs of macOS typically won't work, for example being an old LLVM version or missing llvm-ar; setup commands includes LLVM from Homebrew for this reason.
It may be necessary to run bazel clean
after updating versions in order to
clean up cached state.
If you're having trouble resolving issues, please ask on #build-help, providing the output of the following diagnostic commands:
echo $CC
which clang
clang --version
grep llvm_bindir $(bazel info workspace)/bazel-execroot/external/bazel_cc_toolchain/clang_detected_variables.bzl
# If on macOS:
brew --prefix llvm
These commands will help diagnose potential build issues by showing which tooling is in use.
Pass -c dbg
to bazel build
in order to compile with debugging enabled. For
example:
bazel build -c dbg //explorer
Then debugging works with GDB:
gdb bazel-bin/explorer/explorer
Note that LLVM uses DWARF v5 debug symbols, which means that GDB version 10.1 or newer is required. If you see an error like this:
Dwarf Error: DW_FORM_strx1 found in non-DWO CU
It means that the version of GDB used is too old, and does not support the DWARF v5 format.
Bazel sandboxes builds, which on MacOS makes it hard for the debugger to locate
symbols on linked binaries when debugging. See this
Bazel issue
for more information. To workaround, provide the --spawn_strategy=local
option
to Bazel for the debug build, like:
bazel build --spawn_strategy=local -c dbg //explorer
You should then be able to debug with lldb
.
If this build command doesn't seem to produce a debuggable binary you might need
to both clear the build disk cache and clean the build. Running
scripts/clean_disk_cache.sh
may not be enough, you might try deleting all the
files within the disk cache, typically located at
~/.cache/carbon-lang-build-cache
. Deleting the disk cache, followed by a
bazel clean
should allow your next rebuild, with the recommended options, to
supply the symbols for debugging.
For debugging on MacOS using VSCode, some people have had success using the
CodeLLDB extension. In order for LLDB to connect the project source files with
the symbols you will need to add a "sourceMap": { ".": "${workspaceRoot}" }
line to the CodeLLDB launch.json
configuration, for example:
{
"version": "0.2.0",
"configurations": [
{
"name": "explorer",
"type": "lldb",
"request": "launch",
"program": "${workspaceRoot}/bazel-bin/explorer/explorer",
"args": [],
"cwd": "${workspaceRoot}",
"sourceMap": {
".": "${workspaceRoot}"
}
}
]
}