This page lists the prerequisites for working with the repository. In general, you have three options to get your development setup up and running:
- Remotely using GitHub Codespaces
- Using Visual Studio Code and dev containers
- Locally by installing all prerequisites on your machine
We will walk you through the options in the following sections.
📝 Tip - We recommend the usage of GitHub Codespaces or dev containers in Visual Studio Code as they are the most convenient way to get started.
Depending on the task you need to perform, you may need to install more tools, but basic prerequisites should be sufficient for most contributors to get started.
We support developing on macOS, Linux and Windows with WSL.
If you get stuck with any development setup option, please ask for help in our forum.
The following sections describe the aforementioned alternatives of development setups in more detail. We recommend to use of GitHub Codespaces or dev containers in VS Code as they are the most convenient way to get started.
The easiest way to get started is using our pre-built GitHub Codespace.
The steps to execute are:
-
Press this button
-
There is no second step - you are ready to contribute 😎
Note - When using GitHub Codespaces cost can occur on your side after you have used up the monthly included storage and core hours for your account. You find more details here.
To use the dev container you must have the following tools installed and running locally:
📝 Tip - If you are new to dev containers you find more information about developing inside a container here and a comprehensive tutorial here.
To get the dev container up and running
-
If not already done, clone your fork of the Project Radius repository to your local file system and open the folder with VS Code. The best way to do so is either to launch VS Code and open the folder via the File -> Open Folder menu or to start VS Code from the command shell with
code ., which opens the current directory as a folder in VS Code. -
Click the "X"-like button in VS Code to open a remote window
-
Select the option "Reopen in Container" in the command palette
The dev container will be started automatically.
When doing this the first time this might take a bit as all dependencies need to be downloaded and installed in your container - so grab a cup of ☕ and enjoy the work done by the container.
Once the container is up and running you can start with your contribution.
Contributing to Radius requires several tools to get started. This section lists them grouped by their context
📝 Tip - If your are using GitHub Codespaces or VS Code and Dev Container, all these tools are already in place and available out-of-the-box.
You can choose whichever editor you are most comfortable for working on Go code. If you don't have a code editor set up for Go, we recommend VS Code. The experience with VS Code is high-quality and approachable for newcomers.
Alternatively, you can choose whichever editor you are most comfortable for working on Go code. Feel free to skip this section if you want to make another choice.
Install both of these and then follow the steps in the Quick Start for the Go extension.
The extension will walk you through an automated install of some additional tools that match your installed version of Go.
This is the list of core dependencies to install for the most common tasks. In general we expect all contributors to have all of these tools present:
For make we advice the following installation steps depending on you OS.
Install the build-essential package:
sudo apt-get install build-essentialUsing Xcode:
xcode-select --installUsing Homebrew:
brew install makeTo build our containers, you also need Docker.
The following tools are required depending on the task at hand.
The easiest way to run Radius is on Kubernetes. To do this you will need the ability to create a Kubernetes cluster as well as to install kubectl to control that cluster, you probably also want Helm to install things in your cluster. There are many ways to create a Kubernetes cluster that you can use for development and testing. If you don't have a preference we recommend kind.
You might want tools that can help debug Kubernetes problems and understand what's going on in the cluster. Here are some recommendations from the team:
Radius includes integration with Dapr. To use work on these features, you'll need to install the Dapr CLI.
The default go test output can be hard to read when you have many tests. We recommend gotestsum as a tool to solve this. Our make test command will automatically use gotestsum if it is available.
Independent of the setup option you have chosen, you can now test your tooling. If not already done, navigate to the cloned project in your command shell and build the main outputs using make:
make build && make lintRunning these steps will run our build and lint steps and verify that the tools are installed correctly. If you get stuck or suspect something is not working in these instructions please open an issue.
Our code generation targets are used to update generated OpenAPI specs and generated Go code based on those OpenAPI specs. Additionally, some Go code is generated mocks or Kubernetes API types.
If you were trying to run make generate and ran into an error, then one of the below is likely missing.
Enter the following commands to install all of the required tools.
cd typespec && npm ci
npm install -g autorest
npm install -g oav
go install sigs.k8s.io/controller-tools/cmd/[email protected]
go install go.uber.org/mock/[email protected]