Skip to content
Snippets Groups Projects
Unverified Commit 8746ed46 authored by Andrew Newdigate's avatar Andrew Newdigate
Browse files

chore: apply copier template 

This updates the developer documentation for initial setup to recommend
using rtx over asdf.

See https://gitlab.com/gitlab-com/runbooks/-/issues/134 for more details.
parent 231aa790
No related branches found
No related tags found
No related merge requests found
Pipeline #17134412 passed
Stage: validate
Hide whitespace changes
Inline Side-by-side
Showing
with 47 additions and 27 deletions
docs/developer-setup.md
+ 47
− 27
View file @ 8746ed46
@@ -22,7 +22,7 @@ Once 1password-cli is installed you can verify the installation using:
op --version
```
 
Note that v2 of the 1password-cli is required.
**Note: v2 of the 1password-cli is required.**
 
### Step 2: Setup Development Libraries
 
@@ -61,32 +61,52 @@ If it is not running, it is likely that it is not installed, so continue with th
softwareupdate --install-rosetta --agree-to-license
```
 
### Step 3: Install `asdf`
### Step 3.1: Uninstall `asdf` before installing `rtx`
 
Installation instructions for `asdf` can be found at <https://asdf-vm.com/guide/getting-started.html#_1-install-dependencies>.
The Infrastructure department is currently migrating from `asdf` to `rtx`. See [gitlab-com/runbooks#134](https://gitlab.com/gitlab-com/runbooks/-/issues/134) for details of the migration. Many projects now support both `rtx` and `asdf`, but if you're experiencing errors running `scripts/install-asdf-plugins.sh` on a project, please leave a comment on [gitlab-com/runbooks#134](https://gitlab.com/gitlab-com/runbooks/-/issues/134).
 
If you're running on macos, the recommended approach is to use Homebrew:
**It is not recommended that you run `asdf` alongside `rtx`.**
 
```shell
brew install asdf
Please ensure that you uninstall `asdf` before installing `rtx`.
To uninstall `asdf`, full instructions are available at <https://asdf-vm.com/manage/core.html#uninstall>.
For MacOS users who installed `asdf` with Homebrew, remove any includes of `asdf` from your Shell initialization, then use Homebrew to remove `asdf`:
```console
$ # find asdf references in your shell rc files
$ grep -Er 'asdf.(ba)?sh' ~/.bash_profile ~/.bashrc ~/.zshrc ~/.oh-my-zsh/custom/*
$ # edit the files to delete any references
$ vi ...
$ # now, uninstall asdf
$ brew uninstall asdf --force
$ # open a new terminal before continuing...
```
 
Linux users should follow the instructions for their package manager in [the ASDF documentation](https://asdf-vm.com/guide/getting-started).
### Step 3.2: Install `rtx`
 
#### Step 3.5: Hook `asdf` into your shell
[`rtx`](https://github.com/jdx/rtx) is a polyglot runtime manager. It is compatible with [`asdf`](https://asdf-vm.com/) and relies on the `asdf` plugin ecosystem, but has some advantages over `asdf` in that it generally requires fewer shims and is faster.
 
Once you've installed `asdf`, add the following line to your shell. Remember to restart your terminal for the change to take affect.
 
### Macos with Homebrew
If you're running on MacOS, the recommended approach is to use Homebrew:
 
```shell
. $(brew --prefix asdf)/asdf.sh
brew install rtx
```
 
### Linux
Linux users should follow the instructions for their package manager in [the rtx documentation](https://github.com/jdx/rtx#apt).
#### Step 3.3: Hook `rtx` into your shell
Once you've installed `rtx`, add the following line to your shell. Remember to restart your terminal for the change to take affect.
 
```shell
. <path to asdf install>/asdf.sh
# bash
echo 'eval "$('$(which rtx)' activate bash)"' >> ~/.bashrc
# zsh
echo 'eval "$('$(which rtx)' activate zsh)"' >> ~/.zshrc
# fish
echo 'rtx activate fish | source' >> ~/.config/fish/config.fish
```
 
Did you remember to restart your terminal? Good.
@@ -99,7 +119,7 @@ Install all the plugins by running:
./scripts/install-asdf-plugins.sh
```
 
This will install required `asdf` plugins, and install the correct versions of the development tools.
This will install required `asdf`/`rtx` plugins, and install the correct versions of the development tools.
 
Note that after pulling changes to the repository, you may sometimes need to re-run `./scripts/install-asdf-plugins.sh` to update your locally installed plugins and tool-versions.
 
@@ -107,43 +127,43 @@ Note that after pulling changes to the repository, you may sometimes need to re-
 
We use CI checks to ensure that tool versions used in GitLab-CI and on developer instances don't go out of sync.
 
### Keeping Versions in Sync between GitLab-CI and `asdf`.
### Keeping Versions in Sync between GitLab-CI and `.tool-versions`.
 
`asdf` (and `.tool-versions` generally) is the SSOT for tool versions used in this repository.
The `.tool-versions` file is the SSOT for tool versions used in this repository.
To keep `.tool-versions` in sync with `.gitlab-ci.yml`, there is a helper script,
`./scripts/update-asdf-version-variables`.
`./scripts/update-asdf-version-variables.sh`.
 
#### Process for updating a Tool Version
 
```shell
./scripts/update-asdf-version-variables
./scripts/update-asdf-version-variables.sh
```
 
1. Update the version in `.tool-versions`
1. Run `asdf install` to install latest version
1. Run `./scripts/update-asdf-version-variables` to update a refresh of the `.gitlab-ci-asdf-versions.yml` file
1. Run `rtx install` to install latest version
1. Run `./scripts/update-asdf-version-variables.sh` to update a refresh of the `.gitlab-ci-asdf-versions.yml` file
1. Commit the changes
1. A CI job (see [`asdf-tool-versions.md`](../asdf-tool-versions.md)) will validate the changes.
 
# Diagnosing `asdf` setup issues
# Diagnosing `rtx` setup issues
 
## `asdf` plugins don't return versions as expected
## `asdf`/`rtx` plugins don't return versions as expected
 
To avoid installing dependencies, `asdf` plugins often rely on basic Unix text processing utilities like `grep`, `sed` and `awk` to parse JSON. Many rely on the fact that responses from the GitHub API are pretty-printed JSON, not minimised (or machine parsable) JSON. However, the GitHub API will only pretty-print JSON when it detects the User-Agent request header as being `curl`. For other user agents, the response will be minimised for efficiency.
To avoid installing dependencies, `asdf`/`rtx` plugins often rely on basic Unix text processing utilities like `grep`, `sed` and `awk` to parse JSON. Many rely on the fact that responses from the GitHub API are pretty-printed JSON, not minimised (or machine parsable) JSON. However, the GitHub API will only pretty-print JSON when it detects the User-Agent request header as being `curl`. For other user agents, the response will be minimised for efficiency.
 
Ensure that you haven't overridden your `curl` user-agent on your workstation.
 
Check your `.curlrc` for the `user-agent` setting. Additionally, running `curl https://api.github.com/orgs/gitlabhq` should return pretty-printed JSON. If the response contains minimised JSON, many `asdf` plugins may not work as expected.
Check your `.curlrc` for the `user-agent` setting. Additionally, running `curl https://api.github.com/orgs/gitlabhq` should return pretty-printed JSON. If the response contains minimised JSON, many `asdf`/`rtx` plugins may not work as expected.
 
## Plugins require other asdf tools
## `asdf`/`rtx` plugins require other `asdf`/`rtx` plugins
 
If you find that a plugin is failing to install, it sometimes helps to setup a global default. Care has been taken to avoid this situation, but if you're stuck, give it a try:
 
```shell
# If a plugin is complaining that it cannot compile because golang hasn't been configured...
# set the global version of golang the same as the current version
asdf global golang $(asdf current golang|awk '{ print $2 }')
asdf install
rtx global golang $(rtx current golang)
rtx install
```
 
If this happens, please open an issue in the appropriate tracker, so that a better long-term solution can be applied.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment