carbon-lang/docs/project/contribution_tools.md

Contribution tools

The Carbon language project has a number of tools used to assist in preparing contributions.

Table of contents

• Package managers
  • brew
  • go get
  • pip
• Main tools
  • Bazel and Bazelisk
  • buildifier
  • Clang and LLVM
  • pyenv and Python
  • pre-commit
• Optional tools
  • Carbon-maintained
    • new_proposal.py
    • pr_comments.py
  • GitHub
    • gh CLI
    • GitHub Desktop
  • Vim
    • vim-prettier
  • Atom
  • pre-commit enabled tools
    • black
    • codespell
    • markdown-toc
    • Prettier

Package managers

Instructions for installing tools can be helpful for installing tooling. These instructions will try to rely on a minimum of managers.

brew

brew is a package manager, and can help install several tools that we recommend. See the installation instructions.

go get

go get is Go's package manager. It will mainly be used for Linux, where brew doesn't work as well.

To install on Debian- or Ubuntu-based Linux distributions:

apt install golang

pip

pip is Python's package manager, and installed as part of pyenv and Python.

Main tools

These tools are key for contributions, primarily focused on validating contributions.

Bazel and Bazelisk

Bazel is Carbon's standard build system. Bazelisk is recommended for installing Bazel.

Our recommended way of installing is:

• Linux:

  go get github.com/bazelbuild/bazelisk
  

• MacOS:

  brew update
  brew install bazelisk
  

buildifier

Buildifier is a tool for formatting Bazel BUILD files, and is distributing separately from Bazel.

Our recommended way of installing is:

• Linux:

  go get github.com/bazelbuild/buildtools/buildifier
  

• MacOS:

  brew update
  brew install buildifier
  

Clang and LLVM

Clang and LLVM are used to compile and link Carbon. It's currently recommended to build LLVM from head in order to avoid compatibility issues in many distributions.

Please refer to LLVM's build instructions. Tips:

• When carbon-lang is checked out with submodules, the LLVM submodule is at third_party/llvm_project.

  • In other words, create your build directory at third_party/llvm_project/build.

• Carbon uses the Clang, LLD, and libc++ subprojects. A corresponding LLVM_ENABLE_PROJECTS build looks like:

  cmake -G Ninja ../llvm \
      -DLLVM_ENABLE_PROJECTS="clang;clang-tools-extra;lld;libcxx;libcxxabi;compiler-rt;libunwind" \
      -DCMAKE_BUILD_TYPE=Release \
      -DLIBCXX_ABI_UNSTABLE=ON \
      -DLLVM_ENABLE_ASSERTIONS=OFF \
      -DLIBCXX_ENABLE_ASSERTIONS=OFF \
      -DLIBCXXABI_ENABLE_ASSERTIONS=OFF
  ninja
  

pyenv and Python

pyenv is the recommended way to install Python. Our recommended way of installing both is:

brew update
brew install pyenv
pyenv install 3.8.5
pyenv global 3.8.5

# Add 'eval "$(pyenv init -)"' to your shell rc file.
echo 'eval "$(pyenv init -)"' >> ~/.zshrc
# Load the shell rc file changes.
exec $SHELL

pre-commit

We use pre-commit to run various checks. This will automatically run important checks, including formatting.

To set up pre-commit, see the installation instructions, or:

pip install pre-commit

# From within each carbon-language git repository:
pre-commit install

When you have changes to commit to git, a standard pre-commit workflow can look like:

# Let pre-commit fix style issues.
pre-commit run
# Add modifications made by pre-commit.
git add .
# Commit the changes
git commit

When modifying or adding pre-commit hooks, please run pre-commit run --all-files to see what changes.

Optional tools

Carbon-maintained

new_proposal.py

new_proposal.py is a helper for generating the PR and proposal file for a new proposal. It's documented in the proposal template.

NOTE: This requires installing the gh CLI.

pr_comments.py

pr_comments.py is a helper for scanning comments in GitHub. It's particularly intended to help find threads which need to be resolved.

Options can be seen with -h. A couple key options to be aware of are:

• --long: Prints long output, with the full comment.
• --comments-after LOGIN: Only print threads where the final comment is not from the given user. For example, use when looking for threads that you still need to respond to.
• --comments-from LOGIN: Only print threads with comments from the given user. For example, use when looking for threads that you've commented on.

NOTE: This requires the Python gql package:

pip install gql

GitHub

gh CLI

The gh CLI supports some GitHub queries, and is used by some scripts.

To install gh, run:

brew update
brew install github/gh/gh

GitHub Desktop

GitHub Desktop provides a UI for managing git repositories. See the page for installation instructions.

Vim

vim-prettier

vim-prettier is a vim integration for Prettier.

If you use vim-prettier, the .prettierrc.yaml should still apply as long as config_precedence is set to the default file-override. However, we may need to add additional settings where the vim-prettier default diverges from prettier, as we notice them.

Atom

Atom is an IDE that's mainly mentioned here for its Markdown support. See the page for installation instructions.

Some packages that may be helpful are:

• markdown-preview-enhanced: An improvement over the default-installed markdown-preview package. If using this:
  • Disable markdown-preview.
  • In the package settings, turn off 'Break On Single New Line' -- this is consistent with carbon-lang.dev and Prettier.
• prettier-atom: For Prettier integration.
• python-black: For black integration.

pre-commit enabled tools

If you're using pre-commit, it will run these tools. Installing and running them manually is optional, but may be helpful.

black

We use Black to format Python code. Although Prettier is used for most languages, it doesn't support Python.

codespell

We use codespell to spellcheck common errors. This won't catch every error; we're trying to balance true and false positives.

markdown-toc

We use markdown-toc to provide GitHub-compatible tables of contents for some documents.

If run manually, specify --bullets=- to use Prettier-compatible bullets, or always run Prettier after markdown-toc.

Prettier

We use Prettier for formatting. There is an rc file for configuration.