Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Updated documentation with new release tag #100

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Updated documentation with new release tag #100

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
495212f
Updated documentation with new version, added more examples for ros_gz
sauk2 Oct 30, 2024
35b3a44
Updated action.yml with gazebo and ros distros list
sauk2 Nov 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
222 changes: 130 additions & 92 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ The `setup-gazebo` GitHub action can be run using GitHub-hosted Ubuntu runners o

> [!NOTE]
>
> The available GitHub-hosted runners can be found [here](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories). It should be noted that the `ubuntu-24.04` runner image is a beta release. An alternative approach is using a docker container as shown in the following sections.
> The available GitHub-hosted runners can be found [here](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories). An alternative approach is using a docker container as shown in the following sections.


#### Setting up worker and installing a compatible Gazebo and Ubuntu combination
Expand All @@ -79,7 +79,7 @@ This workflow shows how to spawn a job to install Gazebo on an Ubuntu distributi
with:
node-version: '20.x'
- name: 'Setup Gazebo'
uses: gazebo-tooling/setup-gazebo@v0.2.0
uses: gazebo-tooling/setup-gazebo@v0.3.0
with:
required-gazebo-distributions: harmonic
- name: 'Test Gazebo installation'
Expand All @@ -102,7 +102,7 @@ This workflow shows how to spawn a job to install Gazebo on an Ubuntu distributi
with:
node-version: '20.x'
- name: 'Setup Gazebo'
uses: gazebo-tooling/setup-gazebo@v0.2.0
uses: gazebo-tooling/setup-gazebo@v0.3.0
with:
required-gazebo-distributions: harmonic
- name: 'Test Gazebo installation'
Expand Down Expand Up @@ -149,7 +149,7 @@ This workflow shows how to spawn one job per Gazebo release and iterates over al
with:
node-version: '20.x'
- name: 'Check Gazebo installation on Ubuntu runner'
uses: gazebo-tooling/setup-gazebo@v0.2.0
uses: gazebo-tooling/setup-gazebo@v0.3.0
with:
required-gazebo-distributions: ${{ matrix.gazebo_distribution }}
- name: 'Test Gazebo installation'
Expand All @@ -169,52 +169,52 @@ This workflow shows how to spawn one job per Gazebo release and iterates over al
```yaml
jobs:
test_gazebo:
runs-on: ubuntu-latest
container:
image: ${{ matrix.docker_image }}
strategy:
fail-fast: false
matrix:
gazebo_distribution:
- citadel
- fortress
- garden
- harmonic
include:
# Gazebo Citadel (Dec 2019 - Dec 2024)
- docker_image: ubuntu:focal
gazebo_distribution: citadel

# Gazebo Fortress (Sep 2021 - Sep 2026)
- docker_image: ubuntu:focal
gazebo_distribution: fortress

# Gazebo Garden (Sep 2022 - Nov 2024)
- docker_image: ubuntu:focal
gazebo_distribution: garden

# Gazebo Harmonic (Sep 2023 - Sep 2028)
- docker_image: ubuntu:jammy
gazebo_distribution: harmonic
steps:
- uses: actions/checkout@v4
- uses: actions/[email protected]
with:
node-version: '20.x'
- name: 'Check Gazebo installation on Ubuntu runner'
uses: gazebo-tooling/setup-gazebo@v0.2.0
with:
required-gazebo-distributions: ${{ matrix.gazebo_distribution }}
- name: 'Test Gazebo installation'
run: |
if command -v ign > /dev/null; then
ign gazebo --versions
elif command -v gz > /dev/null; then
gz sim --versions
else
echo "Neither ign nor gz command found"
exit 1
fi
runs-on: ubuntu-latest
container:
image: ${{ matrix.docker_image }}
strategy:
fail-fast: false
matrix:
gazebo_distribution:
- citadel
- fortress
- garden
- harmonic
include:
# Gazebo Citadel (Dec 2019 - Dec 2024)
- docker_image: ubuntu:focal
gazebo_distribution: citadel

# Gazebo Fortress (Sep 2021 - Sep 2026)
- docker_image: ubuntu:focal
gazebo_distribution: fortress

# Gazebo Garden (Sep 2022 - Nov 2024)
- docker_image: ubuntu:focal
gazebo_distribution: garden

# Gazebo Harmonic (Sep 2023 - Sep 2028)
- docker_image: ubuntu:jammy
gazebo_distribution: harmonic
steps:
- uses: actions/checkout@v4
- uses: actions/[email protected]
with:
node-version: '20.x'
- name: 'Check Gazebo installation on Ubuntu runner'
uses: gazebo-tooling/setup-gazebo@v0.3.0
with:
required-gazebo-distributions: ${{ matrix.gazebo_distribution }}
- name: 'Test Gazebo installation'
run: |
if command -v ign > /dev/null; then
ign gazebo --versions
elif command -v gz > /dev/null; then
gz sim --versions
else
echo "Neither ign nor gz command found"
exit 1
fi
```

#### Using pre-release and/or nightly Gazebo binaries
Expand All @@ -224,22 +224,22 @@ This workflow shows how to use binaries from [pre-release] or [nightly] Gazebo r
```yaml
jobs:
test_gazebo:
runs-on: ubuntu-latest
container:
image: ubuntu:noble
steps:
- uses: actions/checkout@v4
- uses: actions/[email protected]
with:
node-version: '20.x'
- name: 'Check Gazebo installation on Ubuntu runner'
uses: gazebo-tooling/setup-gazebo@v0.2.0
with:
required-gazebo-distributions: 'ionic'
use-gazebo-prerelease: 'true'
use-gazebo-nightly: 'true'
- name: 'Test Gazebo installation'
run: 'gz sim --versions'
runs-on: ubuntu-latest
container:
image: ubuntu:noble
steps:
- uses: actions/checkout@v4
- uses: actions/[email protected]
with:
node-version: '20.x'
- name: 'Check Gazebo installation on Ubuntu runner'
uses: gazebo-tooling/setup-gazebo@v0.3.0
with:
required-gazebo-distributions: 'ionic'
use-gazebo-prerelease: 'true'
use-gazebo-nightly: 'true'
- name: 'Test Gazebo installation'
run: 'gz sim --versions'
```

#### Installing ROS 2 and Gazebo side-by-side along with `ros_gz`
Expand All @@ -248,33 +248,71 @@ This workflow shows how to install ROS 2 using the GitHub action `ros-tooling/se

Starting with ROS 2 Jazzy, Gazebo is also available to be installed from ROS packages via [vendor packages]. When using `install-ros-gz` this action will check for availability of these Gazebo vendor packages and install them if available for the specified ROS 2 distribution. Only the default (recommended) Gazebo release is currently available for the ROS 2 releases using the vendor packages (i.e if ROS 2 Jazzy is used, only Gazebo Harmonic is the valid option). More information on vendor packages can be found in the [official documentation].

- *Installing a ROS-Gazebo combination*

This example shows the installation of ROS 2 Iron and Gazebo Harmonic which is a supported ROS-Gazebo combination.

```yaml
jobs:
test_gazebo:
env:
ROS_DISTROS: 'iron'
runs-on: ubuntu-latest
container:
image: ubuntu:jammy
steps:
- uses: actions/checkout@v4
- uses: actions/[email protected]
with:
node-version: '20.x'
- name: 'Install ROS 2 Iron'
uses: ros-tooling/[email protected]
with:
required-ros-distributions: ${{ env.ROS_DISTROS }}
- name: 'Install Gazebo Harmonic with ros_gz'
uses: gazebo-tooling/[email protected]
with:
required-gazebo-distributions: 'harmonic'
install-ros-gz: ${{ env.ROS_DISTROS }}
- name: Test Iron ros_gz installation
run: |
source /opt/ros/iron/setup.bash
ros2 pkg list | grep ros_gz
gz sim --version | grep 'version 8.[0-9*].[0-9*]'
env:
ROS_DISTROS: 'iron'
runs-on: ubuntu-latest
container:
image: ubuntu:jammy
steps:
- uses: actions/checkout@v4
- uses: actions/[email protected]
with:
node-version: '20.x'
- name: 'Install ROS 2 Iron'
uses: ros-tooling/[email protected]
with:
required-ros-distributions: ${{ env.ROS_DISTROS }}
- name: 'Install Gazebo Harmonic with ros_gz'
uses: gazebo-tooling/[email protected]
with:
required-gazebo-distributions: 'harmonic'
install-ros-gz: ${{ env.ROS_DISTROS }}
- name: Test Iron ros_gz installation
run: |
source /opt/ros/iron/setup.bash
ros2 pkg list | grep ros_gz
gz sim --version | grep 'version 8.[0-9*].[0-9*]'
```

- *Installing Gazebo through vendor packages*

This example shows the installation of ROS 2 Jazzy and Gazebo Harmonic which is a recommended ROS-Gazebo combination. In this case, Gazebo libraries are will be installed as ROS packages.

```yaml
jobs:
test_gazebo:
env:
ROS_DISTROS: 'jazzy'
runs-on: ubuntu-latest
container:
image: ubuntu:noble
steps:
- uses: actions/checkout@v4
- uses: actions/[email protected]
with:
node-version: '20.x'
- name: 'Install ROS 2 Jazzy'
uses: ros-tooling/[email protected]
with:
required-ros-distributions: ${{ env.ROS_DISTROS }}
- name: 'Install Gazebo with ros_gz'
uses: gazebo-tooling/[email protected]
with:
required-gazebo-distributions: 'harmonic'
install-ros-gz: ${{ env.ROS_DISTROS }}
- name: Test Jazzy ros_gz installation
run: |
source /opt/ros/jazzy/setup.bash
! [ $(apt list --installed gz-harmonic) ]
ros2 pkg list | grep ros_gz
gz sim --version | grep 'version 8.[0-9*].[0-9*]'
```

### macOS
Expand All @@ -293,7 +331,7 @@ This workflow shows how to install Gazebo on a macOS worker using the Homebrew p
with:
node-version: '20.x'
- name: 'Check Gazebo installation on MacOS runner'
uses: gazebo-tooling/setup-gazebo@v0.2.0
uses: gazebo-tooling/setup-gazebo@v0.3.0
with:
required-gazebo-distributions: 'harmonic'
- name: 'Test Gazebo installation'
Expand All @@ -317,7 +355,7 @@ This workflow shows how to install Gazebo on a Windows worker. The action requir
node-version: '20.x'
- uses: conda-incubator/setup-miniconda@v3
- name: 'Check Gazebo installation on Windows runner'
uses: gazebo-tooling/setup-gazebo@v0.2.0
uses: gazebo-tooling/setup-gazebo@v0.3.0
with:
required-gazebo-distributions: 'harmonic'
- name: 'Test Gazebo installation'
Expand Down
Loading