Skip to content

Commit 209b5c8

Browse files
jaagutjaagut
committed
feat: update setup script and installation instructions for easier setup
- Add a workflow that validates the setup script twice a month
1 parent b054590 commit 209b5c8

5 files changed

Lines changed: 179 additions & 97 deletions

File tree

‎.github/workflows/setup-script.yml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
name: Setup script
2+
3+
on:
4+
schedule:
5+
# Run approximately twice a month.
6+
- cron: "17 4 1,15 * *"
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
setup:
14+
runs-on: ubuntu-latest
15+
timeout-minutes: 90
16+
env:
17+
PSModulePath: "" # Otherwise colcon might think that PowerShell is being used
18+
19+
steps:
20+
- name: Download and run setup script
21+
run: |
22+
cd "$(mktemp -d)"
23+
curl -fsSL https://raw.githubusercontent.com/bit-bots/bitbots_main/main/scripts/bitbots_setup.sh \
24+
--output "${RUNNER_TEMP}/bitbots_setup.sh"
25+
bash "${RUNNER_TEMP}/bitbots_setup.sh" --https

‎README.md‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,17 +17,28 @@ The workspace is managed using the [pixi](https://pixi.sh) package manager. This
1717

1818
Full step-by-step instructions for installing the Bit-Bots software stack and ROS 2 can be found in our [documentation](https://docs.bit-bots.de/meta/manual/tutorials/install_software_ros2.html).
1919

20+
We assume a modern Linux distribution with a recent version of `curl` and `git` installed. The setup script should work on any Linux distribution, but we only test on Ubuntu.
21+
22+
From the directory where you want to clone `bitbots_main`, download and run the setup script:
23+
24+
```shell
25+
curl -fsSL https://raw.githubusercontent.com/bit-bots/bitbots_main/main/scripts/bitbots_setup.sh \
26+
--output /tmp/bitbots_setup.sh
27+
bash /tmp/bitbots_setup.sh
28+
```
29+
30+
This clones the repository using SSH, installs Pixi and all dependencies, and builds the workspace.
31+
If cloning with SSH fails, the script offers to retry using HTTPS.
32+
Pass `--https` to clone with HTTPS immediately; `--ssh` explicitly selects the default SSH method.
33+
34+
## Using the workspace
35+
2036
Run the following command inside this repository to build the workspace.
21-
All dependencies will be installed automatically.
22-
Make sure you have [pixi](https://pixi.sh) installed.
23-
A few optional proprietary dependencies will be needed for full functionality, see the documentation for details.
2437

2538
``` shell
2639
pixi run build
2740
```
2841

29-
## Using the workspace
30-
3142
To activate the workspace run the following command in the terminal you want to use:
3243

3344
``` shell

‎scripts/bitbots_setup.sh‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
#!/usr/bin/env bash
2+
set -Eeuo pipefail
3+
4+
readonly DEFAULT_BRANCH="main"
5+
readonly REPO_URL_SSH="git@github.com:bit-bots/bitbots_main.git"
6+
readonly REPO_URL_HTTPS="https://github.com/bit-bots/bitbots_main.git"
7+
8+
branch="$DEFAULT_BRANCH"
9+
branch_explicit=false
10+
clone_method="ssh"
11+
clone_method_explicit=false
12+
13+
usage() {
14+
echo "Usage: $0 [--ssh | --https] [branch]" >&2
15+
}
16+
17+
parse_args() {
18+
for arg in "$@"; do
19+
case "$arg" in
20+
--ssh | --https)
21+
local method="${arg#--}"
22+
if $clone_method_explicit && [[ "$clone_method" != "$method" ]]; then
23+
echo "Only one clone method can be selected." >&2
24+
usage
25+
exit 2
26+
fi
27+
clone_method="$method"
28+
clone_method_explicit=true
29+
;;
30+
-*)
31+
echo "Unknown option: $arg" >&2
32+
usage
33+
exit 2
34+
;;
35+
*)
36+
if $branch_explicit; then
37+
echo "Only one branch can be selected." >&2
38+
usage
39+
exit 2
40+
fi
41+
branch="$arg"
42+
branch_explicit=true
43+
;;
44+
esac
45+
done
46+
}
47+
48+
ask_question() {
49+
local response
50+
51+
while true; do
52+
read -r -p "$1 [Y/n]: " response
53+
case "$response" in
54+
[Yy] | [Yy][Ee][Ss] | "") return 0 ;;
55+
[Nn] | [Nn][Oo]) return 1 ;;
56+
*) echo "Please answer yes or no." ;;
57+
esac
58+
done
59+
}
60+
61+
setup_pixi() {
62+
command -v pixi >/dev/null && return
63+
64+
command -v curl >/dev/null || {
65+
echo "Required command not found: curl" >&2
66+
exit 1
67+
}
68+
echo "Installing Pixi..."
69+
curl -fsSL https://pixi.sh/install.sh | bash
70+
export PATH="$HOME/.pixi/bin:$PATH"
71+
command -v pixi >/dev/null || {
72+
echo "Pixi installation completed, but pixi is not available on PATH." >&2
73+
exit 1
74+
}
75+
}
76+
77+
clone_repo() {
78+
local target="$PWD/bitbots_main"
79+
80+
if [[ -e "$target" ]]; then
81+
git -C "$target" rev-parse --is-inside-work-tree >/dev/null 2>&1 || {
82+
echo "Cannot clone: $target already exists and is not a Git repository." >&2
83+
exit 1
84+
}
85+
git -C "$target" switch "$branch"
86+
return
87+
fi
88+
89+
echo "Cloning bitbots_main branch '$branch'..."
90+
if [[ "$clone_method" == "https" ]]; then
91+
git clone --branch "$branch" --single-branch "$REPO_URL_HTTPS" "$target"
92+
elif git clone --branch "$branch" --single-branch "$REPO_URL_SSH" "$target"; then
93+
:
94+
else
95+
echo "SSH clone failed. This may mean your SSH keys are not set up for GitHub."
96+
echo "See: https://docs.github.com/en/authentication/connecting-to-github-with-ssh"
97+
if [[ ! -t 0 ]]; then
98+
echo "Cannot ask to retry with HTTPS because standard input is not interactive." >&2
99+
echo "Re-run the script with --https." >&2
100+
exit 1
101+
fi
102+
if ask_question "Continue with an HTTPS clone instead?"; then
103+
git clone --branch "$branch" --single-branch "$REPO_URL_HTTPS" "$target"
104+
else
105+
echo "Set up your SSH keys and re-run this script." >&2
106+
exit 1
107+
fi
108+
fi
109+
}
110+
111+
main() {
112+
parse_args "$@"
113+
114+
command -v git >/dev/null || {
115+
echo "Required command not found: git" >&2
116+
exit 1
117+
}
118+
setup_pixi
119+
120+
clone_repo
121+
122+
cd "$PWD/bitbots_main"
123+
echo "Installing dependencies..."
124+
pixi install
125+
echo "Running full build..."
126+
pixi run build
127+
}
128+
129+
main "$@"

‎scripts/setup.sh‎

Lines changed: 0 additions & 86 deletions
This file was deleted.

‎src/bitbots_misc/bitbots_docs/docs/manual/tutorials/installation.rst‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,19 @@ In this tutorial, we will learn how to install all dependencies and build our so
88

99
**Prerequisites**
1010

11-
- You have an existing GitHub account and added a SSH key to your account.
11+
- Modern Linux distribution with a recent version of `curl` and `git` installed.
1212

13-
If you have not previously set up any of our software stack, you can use the following command to install and setup everything in one go:
13+
To install our software at your current directory, run the following command:
1414

1515
.. code-block:: bash
1616
17-
mkdir -p ~/git/bitbots \
18-
&& cd ~/git/bitbots \
19-
&& curl -fsSL https://raw.githubusercontent.com/bit-bots/bitbots_main/main/scripts/setup.sh > /tmp/setup.sh \
20-
&& bash /tmp/setup.sh
17+
curl -fsSL https://raw.githubusercontent.com/bit-bots/bitbots_main/main/scripts/bitbots_setup.sh \
18+
--output /tmp/bitbots_setup.sh
19+
bash /tmp/bitbots_setup.sh
20+
21+
This clones the repository using SSH, installs Pixi and all dependencies, and builds the workspace.
22+
If cloning with SSH fails, the script offers to retry using HTTPS.
23+
Pass ``--https`` to clone with HTTPS immediately; ``--ssh`` explicitly selects the default SSH method.
2124

2225
Manual steps with in depth explanation
2326
--------------------------------------

0 commit comments

Comments
 (0)