Skip to content

Commit 17ad1e8

Browse files
xela-95xela-95
authored
Merge pull request #157 from robotology/doc/update-readme-installation
Update installation instructions
2 parents 30ae221 + 221c0b6 commit 17ad1e8

File tree

2 files changed

+133
-90
lines changed

2 files changed

+133
-90
lines changed

‎README.md

+16-90
Original file line numberDiff line numberDiff line change
@@ -14,114 +14,41 @@
1414

1515
## Installation
1616

17-
At the moment we do not provide any binary for `gz-sim-yarp-plugins`, so you need to compile it from source, either
18-
installing the dependencies with conda-forge on Linux, macOS or Windows, or apt on Ubuntu.
17+
### conda (recommended)
1918

20-
### Compile from source using conda-forge dependencies on Linux, macOS or Windows
19+
You can easily install the C++ and Python library with via [`conda-forge`](https://conda-forge.org) using the following command:
2120

22-
Create and activate an environment with the required dependencies:
23-
24-
~~~
25-
mamba create -c conda-forge -n gsypdev libgz-sim8 yarp ycm-cmake-modules cmake ninja pkg-config cmake compilers gtest
26-
mamba activate gsypdev
27-
~~~
28-
29-
All the commands in this README should be executed in a terminal with the activated environment.
30-
31-
Then, compile gz-sim-yarp-plugins itself, using the following commands on Linux and macOS:
32-
33-
~~~
34-
git clone https://github.dev/robotology/gz-sim-yarp-plugins
35-
mkdir build
36-
cd build
37-
cmake -GNinja -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX -DCMAKE_PREFIX_PATH=$CONDA_PREFIX ..
38-
ninja
39-
ninja install
40-
~~~
41-
42-
or the following commands on Windows:
43-
44-
~~~
45-
git clone https://github.dev/robotology/gz-sim-yarp-plugins
46-
mkdir build
47-
cd build
48-
cmake -GNinja -DCMAKE_INSTALL_PREFIX=%CONDA_PREFIX%\Library -DCMAKE_PREFIX_PATH=%CONDA_PREFIX%\Library ..
49-
ninja
50-
ninja install
51-
~~~
52-
53-
### Compile from source using apt dependencies on Linux, macOS or Windows
54-
55-
First install some necessary dependencies from apt
56-
57-
~~~
58-
sudo apt-get update
59-
sudo apt-get install lsb-release wget gnupg cmake pkg-config ninja-build build-essential libgtest-dev
60-
~~~
61-
62-
Then install Gazebo Harmonic:
21+
```bash
22+
conda install -c conda-forge gz-sim-yarp-plugins
23+
```
6324

64-
~~~
65-
sudo wget https://packages.osrfoundation.org/gazebo.gpg -O /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg
66-
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gazebo-stable.list > /dev/null
67-
sudo apt-get update
68-
sudo apt-get install gz-harmonic
69-
~~~
25+
If you are not familiar with conda or conda-forge, you can read an introduction document in [conda-forge overview](https://github.com/robotology/robotology-superbuild/blob/master/doc/conda-forge.md#conda-forge-overview).
7026

71-
Then, you need to install [`ycm-cmake-modules`](https://github.com/robotology/ycm) and [`yarp`](https://github.com/robotology/yarp), for which no apt binaries are available. You can install them easily via the `robotology-superbuild`, or otherwise with the following commands:
27+
### robotology-superbuild (advanced)
7228

73-
~~~
74-
mkdir ~/gsyp_ws
75-
cd ~/gsyp_ws
76-
git clone https://github.com/robotology/ycm
77-
git clone https://github.com/robotology/yarp
78-
cd ycm
79-
mkdir build
80-
cd build
81-
cmake -GNinja -DCMAKE_INSTALL_PREFIX=~/gsyp_ws/install -DCMAKE_PREFIX_PATH=~/gsyp_ws/install ..
82-
ninja
83-
ninja install
84-
cd ~/gsyp_ws/yarp
85-
cd yarp
86-
git checkout v3.9.0
87-
mkdir build
88-
cd build
89-
cmake -GNinja -DCMAKE_INSTALL_PREFIX=~/gsyp_ws/install -DCMAKE_PREFIX_PATH=~/gsyp_ws/install ..
90-
ninja
91-
ninja install
92-
~~~
29+
You may want to install `gz-sim-yarp-plugins` through the [robotology-superbuild](https://github.com/robotology/robotology-superbuild), an easy way to download, compile and install the robotology software on multiple operating systems, using the [CMake](https://www.cmake.org) build system and its extension [YCM](http://robotology.github.io/ycm). To get `gz-sim-yarp-plugins` when using the `robotology-superbuild`, please enable the `ROBOTOLOGY_USES_GZ_SIM` CMake option of the superbuild.
9330

94-
Then, install `gz-sim-yarp-plugins` itself:
31+
### Build from source (advanced)
9532

96-
~~~
97-
git clone https://github.dev/robotology/gz-sim-yarp-plugins
98-
mkdir build
99-
cd build
100-
cmake -GNinja -DCMAKE_INSTALL_PREFIX=~/gsyp_ws/install -DCMAKE_PREFIX_PATH=~/gsyp_ws/install ..
101-
ninja
102-
ninja install
103-
~~~
33+
If you want to build `gz-sim-yarp-plugins` directly from source, you can check the documentation in [`docs/build-from-source.md`](docs/build-from-source.md).
10434

10535
## Usage
10636

107-
To notify Gazebo of the new plugins compiled, it is necessary to modify the `GZ_SIM_SYSTEM_PLUGIN_PATH` environment variable, for example on Linux:
37+
Once the plugins are available, you can see how to use the different plugins by looking in the directories contained in the [tutorial](tutorial/) folder of this repo. Each directory is an example, and contains a README that shows how to run that example.
10838

109-
~~~
110-
export GZ_SIM_SYSTEM_PLUGIN_PATH=${GZ_SIM_SYSTEM_PLUGIN_PATH}:<install_location>/lib
111-
~~~
112-
113-
where `<install_location>` is the directory passed to `CMAKE_INSTALL_PREFIX` during the CMake configuration.
114-
115-
Once the plugins are available, you can see how to use the different plugins by looking in the directories contained in the `tutorial` folder of this repo. Each directory is an example, and contains a README that shows how to run that example.
39+
### Migrating from Gazebo Classic and `gazebo-yarp-plugins`
11640

11741
If you are migrating from an existing project made for Gazebo Classic and `gazebo-yarp-plugins`, check out the [migration guide](docs/how-to-migrate-from-gazebo-classic.md).
11842

11943
### How to specify Yarp configurations
44+
12045
There are two ways to specify the Yarp configuration of a plugin:
46+
12147
- `yarpConfigurationString`: it allows to directly specify the configuration in a string that must follow the [standard data representation format](https://www.yarp.it/latest/data_rep.html);
12248
- `yarpConfigurationFile`: it specifies the location of a [Yarp configuration file](https://www.yarp.it/latest/yarp_config_files.html).
12349

12450
Concerning `yarpConfigurationFile`, the preferred way to specify the path to the configuration file is by using [Gazebo URIs](https://gazebosim.org/api/common/6/classgz_1_1common_1_1URI.html). A URI has the following general scheme:
51+
12552
```
12653
scheme:[//authority]path[?query][#fragment]
12754
```
@@ -166,7 +93,6 @@ For more details, check how the tests are run as part of the Continuous Integrat
16693
Refer to the [Contributing page](CONTRIBUTING.md).
16794

16895
## Maintainers
96+
16997
- Silvio Traversaro ([@traversaro](https://github.com/traversaro))
17098
- Alessandro Croci ([@xela-95](https://github.com/xela-95))
171-
172-

‎docs/build-from-source.md

+117
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Build gz-sim-yarp-plugins from source
2+
3+
## Table of Contents
4+
5+
- [Dependencies](#dependencies)
6+
- [Compile from source using conda-forge dependencies on Linux, macOS or Windows](#compile-from-source-using-conda-forge-dependencies-on-linux-macos-or-windows)
7+
- [Compile from source using apt dependencies on Linux, macOS or Windows](#compile-from-source-using-apt-dependencies-on-linux-macos-or-windows)
8+
- [Usage](#usage)
9+
10+
## Dependencies
11+
12+
`gz-sim-yarp-plugins` is a fairly classical C++ project build with CMake, so it should be quite easy to build if you are already familiar with how you build C++ projects with CMake.
13+
If you are not familiar with the use of CMake, you can check some documentation on <https://cmake.org/runningcmake/> or <https://cgold.readthedocs.io>.
14+
15+
Before building `gz-sim-yarp-plugins`, you need to install its dependencies, the main ones being:
16+
17+
- [Modern Gazebo](https://gazebosim.org/home)
18+
- [YARP](https://yarp.it/latest//)
19+
- [YCM CMake Modules](https://robotology.github.io/ycm/gh-pages/latest/index.html#)
20+
21+
in addition to the usual dependencies used to configure, compile and test C++ packages.
22+
23+
## Compile from source using conda-forge dependencies on Linux, macOS or Windows
24+
25+
If you are using conda (or mamba), the dependencies of `gz-sim-yarp-plugins` can be installed with:
26+
27+
```bash
28+
conda install -c conda-forge libgz-sim8 yarp ycm-cmake-modules cmake ninja pkg-config cmake compilers gtest
29+
```
30+
31+
This command should be executed in a terminal with the environment activated.
32+
33+
### Build
34+
35+
You can then compile abd install `gz-sim-yarp-plugins` itself, using the following commands on **Linux** and **macOS**:
36+
37+
```bash
38+
git clone https://github.dev/robotology/gz-sim-yarp-plugins
39+
mkdir build
40+
cd build
41+
cmake -GNinja -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX -DCMAKE_PREFIX_PATH=$CONDA_PREFIX ..
42+
ninja
43+
ninja install
44+
```
45+
46+
or the following commands on **Windows**:
47+
48+
```bash
49+
git clone https://github.dev/robotology/gz-sim-yarp-plugins
50+
mkdir build
51+
cd build
52+
cmake -GNinja -DCMAKE_INSTALL_PREFIX=%CONDA_PREFIX%\Library -DCMAKE_PREFIX_PATH=%CONDA_PREFIX%\Library ..
53+
ninja
54+
ninja install
55+
```
56+
57+
## Compile from source using apt dependencies on Linux, macOS or Windows
58+
59+
If you are using an apt-based distribution such as Ubuntu and you want to use apt, the dependencies can be installed via:
60+
61+
```bash
62+
sudo apt-get update
63+
sudo apt-get install lsb-release wget gnupg cmake pkg-config ninja-build build-essential libgtest-dev
64+
```
65+
66+
and then install Gazebo Harmonic:
67+
68+
```bash
69+
sudo wget https://packages.osrfoundation.org/gazebo.gpg -O /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg
70+
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gazebo-stable.list > /dev/null
71+
sudo apt-get update
72+
sudo apt-get install gz-harmonic
73+
```
74+
75+
Then, you need to install [`ycm-cmake-modules`](https://github.com/robotology/ycm) and [`yarp`](https://github.com/robotology/yarp), for which no apt binaries are available. You can install them easily via the `robotology-superbuild`, or otherwise with the following commands:
76+
77+
```bash
78+
mkdir ~/gsyp_ws
79+
cd ~/gsyp_ws
80+
git clone https://github.com/robotology/ycm
81+
git clone https://github.com/robotology/yarp
82+
cd ycm
83+
mkdir build
84+
cd build
85+
cmake -GNinja -DCMAKE_INSTALL_PREFIX=~/gsyp_ws/install -DCMAKE_PREFIX_PATH=~/gsyp_ws/install ..
86+
ninja
87+
ninja install
88+
cd ~/gsyp_ws/yarp
89+
cd yarp
90+
git checkout v3.9.0
91+
mkdir build
92+
cd build
93+
cmake -GNinja -DCMAKE_INSTALL_PREFIX=~/gsyp_ws/install -DCMAKE_PREFIX_PATH=~/gsyp_ws/install ..
94+
ninja
95+
ninja install
96+
```
97+
98+
Then, build and install `gz-sim-yarp-plugins` itself:
99+
100+
```bash
101+
git clone https://github.dev/robotology/gz-sim-yarp-plugins
102+
mkdir build
103+
cd build
104+
cmake -GNinja -DCMAKE_INSTALL_PREFIX=~/gsyp_ws/install -DCMAKE_PREFIX_PATH=~/gsyp_ws/install ..
105+
ninja
106+
ninja install
107+
```
108+
109+
## Usage
110+
111+
To notify Gazebo of the new plugins compiled, it is necessary to modify the `GZ_SIM_SYSTEM_PLUGIN_PATH` environment variable, for example on Linux:
112+
113+
~~~
114+
export GZ_SIM_SYSTEM_PLUGIN_PATH=${GZ_SIM_SYSTEM_PLUGIN_PATH}:<install_location>/lib
115+
~~~
116+
117+
where `<install_location>` is the directory passed to `CMAKE_INSTALL_PREFIX` during the CMake configuration.

0 commit comments

Comments
 (0)