Setting Up the Development Environment#

The development environment may vary depending on the repository you want to contribute to. This document describes the setup for the `score` repository. Others should be similar.

Devcontainer Setup#

The recommended way to set up the development environment is by using the provided devcontainer. The devcontainer includes all necessary tools and dependencies pre-configured for development, as not everything can be installed via Bazel.

To use the devcontainer:

  1. Ensure you have Docker installed and running on your system.

  2. Open the project in a devcontainer capable editor of your choice.

  3. e.g. for VSCode (see IDE section below for more details):

    • Install the “Remote - Containers” extension in VS Code if not already installed.

    • Open the project in VS Code.

    • When prompted, select “Reopen in Container” to build and start the devcontainer. Alternatively, you can open the Command Palette (Ctrl+Shift+P) and select “Remote-Containers: Reopen in Container”.

This approach simplifies the setup process and ensures a consistent development environment.

Note: buildifier and autocompletion are not yet provided via the devcontainer or via bazel, so you will need to set them up manually. See below.

Manual Setup#

If you prefer to set up the development environment manually, follow the steps below:

General Setup#

  • Install the required dependencies for your operating system. This includes:

    • Bazelisk

    • Python 3.x

    • Graphviz/Dot (for generating diagrams)

    Check Dockerfile for an accurate list and exemplary instructions.

  • Clone the score repository to your hard drive.

Additional assistance for working with Bazel is provided by the following tools:

Buildifier#

Buildifier is a tool which can format .bzl files. Additional info and installation instructions are provided on github

In short:

  • download binary

  • renamed binary to buildifier

  • place it somewhere in the system path e.g.

    • ~/.local/bin (no root required)

    • /usr/local/bin

Autocompletion in the Shell#

How to activate autocompletion in bash and zsh is described here

Basically following steps need to be performed:

  1. Navigate to project workspace folder

  2. Determine bazel version

    bazel --version

  3. Build and install the bash completion:

    • Change to any temporary directory and execute

    git clone https://github.com/bazelbuild/bazel.git
cd bazel
git checkout <VERSION_OF_BAZEL>
USE_BAZEL_VERSION=<VERSION_OF_BAZEL> bazel build //scripts:bash_completion
sudo cp bazel-bin/scripts/bazel-complete.bash /etc/bash_completion.d/
cd ..
rm -rf bazel

Graphviz/Dot Installation#

Graphviz/Dot is mandatory for local development (outside the devcontainer). To install it on a Linux system using apt, execute the following command:

sudo apt update && sudo apt install graphviz

This ensures that all necessary dependencies for generating diagrams are available during development.

IDE Support#

Currently as a goal for this project the IDE shall provide support for most of the languages which are used in this project. For this Project VS Code is selected as the primary IDE. This means that only VS code will be checked in case of breaking changes!

Other IDE integrations are provided on a community best effort basis.

Python Environment#

The tooling environment, which includes all essential python packages for docs can be built in a virtual python environment which is located in <workspace_root/.venv_dovs>. It needs be build first:

bazel run //docs:ide_support

Later the different IDEs shall be configured to use the tools which were installed into this virtual environment.

IDE Guides#