From f3f7a106ec61061afddeaaf05bc92c29d1dfcdda Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Thu, 24 Dec 2020 07:07:47 -0500 Subject: [PATCH 1/6] add windows installation Signed-off-by: Mabel Zhang --- tutorials/02_installation.md | 105 ++++++++++++++++++++++++++++------- 1 file changed, 85 insertions(+), 20 deletions(-) diff --git a/tutorials/02_installation.md b/tutorials/02_installation.md index 2538a8d6..3a7641a5 100644 --- a/tutorials/02_installation.md +++ b/tutorials/02_installation.md @@ -1,16 +1,16 @@ \page installation Installation -This tutorial describes how to install Ignition Plugin on [Ubuntu Linux](#ubuntu_install) and [macOS](#macos_install) via either a binary distribution or from source. Support for Windows is coming soon. +This tutorial describes how to install Ignition Plugin via either a binary distribution or from source. +## Ubuntu -## Ubuntu ## {#ubuntu_install} - +### Prerequisites Ignition Plugin version 1 requires Ubuntu Bionic, while version 0 can be used with Ubuntu Xenial. If you don't already have the `lsb-release` package installed, please do so now: -```{.sh} +``` sudo apt-get update sudo apt-get install lsb-release ``` @@ -18,37 +18,37 @@ sudo apt-get install lsb-release Setup your computer to accept software from [packages.osrfoundation.org](http://packages.osrfoundation.org): -```{.sh} +``` sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-stable.list' ``` Setup keys: -```{.sh} +``` wget http://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add - ``` -Install Ignition Plugin +### Binary Install -```{.sh} +``` sudo apt-get update sudo apt-get install libignition-plugin-dev ``` -**Build from source** +### Source Install Run the following to install dependencies -```{.sh} +``` sudo apt-get install libignition-cmake2-dev ``` Clone the ign-plugin repository from GitHub -```{.sh} +``` git clone https://github.com/ignitionrobotics/ign-plugin ``` Then build using CMake -```{.sh} +``` cd ign-plugin mkdir build cd build @@ -57,7 +57,9 @@ make sudo make install ``` -## macOS ## {#macos_install} +## macOS + +### Prerequisites Ignition Plugin and several of its dependencies can be installed on macOS with [Homebrew](http://brew.sh/) using the [osrf/simulation @@ -65,37 +67,37 @@ tap](https://github.com/osrf/homebrew-simulation). Ignition Plugin version 1 requires macOS High Sierra (10.13) or later, while version 0 supports Sierra (10.12) or later. -**Install Binaries using Homebrew** +### Install Binaries using Homebrew Install homebrew, which should also prompt you to install the XCode command-line tools: -```{.sh} +``` ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" ``` Run the following commands: -```{.sh} +``` brew tap osrf/simulation brew install ignition-plugin1 ``` -**Build from source using Homebrew** +### Build from source using Homebrew Run the following to install dependencies -```{.sh} +``` brew tap osrf/simulation brew install ignition-plugin1 --only-dependencies ``` Clone the ign-plugin repository from GitHub -```{.sh} +``` git clone https://github.com/ignitionrobotics/ign-plugin ``` Then build using CMake -```{.sh} +``` cd ign-plugin mkdir build cd build @@ -103,3 +105,66 @@ cmake .. make sudo make install ``` + +## Windows + +### Prerequisites + +First, follow the [ign-cmake](https://github.com/ignitionrobotics/ign-cmake) tutorial for installing Conda, Visual Studio, CMake, etc., prerequisites, and creating a Conda environment. + +Navigate to ``condabin`` if necessary to use the ``conda`` command (i.e., if Conda is not in your `PATH` environment variable. You can find the location of ``condabin`` in Anaconda Prompt, ``where conda``). + +Create if necessary, and activate a Conda environment: + +``` +conda create -n ign-ws +conda activate ign-ws +``` + +Install Ignition dependencies: + +You can view the list of dependencies, replacing `<#>` with the desired version: + +``` +conda search libignition-plugin<#> --channel conda-forge --info +``` + +Install dependencies, replacing `<#>` with the desired versions: + +``` +conda install libignition-cmake<#> --channel conda-forge +``` + +### Binary Install + +``` +conda install libignition-plugin<#> --channel conda-forge +``` + +Be sure to replace `<#>` with a number value, such as 1 or 2, depending on +which version you need. + +### Source Install + +1. Navigate to where you would like to build the library, and clone the repository. + + ``` + # Optionally, append `-b ign-plugin#` (replace # with a number) to check out a specific version + git clone https://github.com/ignitionrobotics/ign-plugin.git + ``` + +1. Configure and build + + ``` + cd ign-plugin + mkdir build + cd build + cmake .. -DBUILD_TESTING=OFF # Optionally, -DCMAKE_INSTALL_PREFIX=path\to\install + cmake --build . --config Release + ``` + +1. Optionally, install + + ``` + cmake --install . --config Release + ``` From 73e9df8c3079ea3085c4f42e22b7e574bf06c048 Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Thu, 24 Dec 2020 12:01:16 -0500 Subject: [PATCH 2/6] tweaks Signed-off-by: Mabel Zhang --- tutorials/02_installation.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/tutorials/02_installation.md b/tutorials/02_installation.md index 3a7641a5..4c4fd847 100644 --- a/tutorials/02_installation.md +++ b/tutorials/02_installation.md @@ -121,30 +121,30 @@ conda create -n ign-ws conda activate ign-ws ``` -Install Ignition dependencies: - -You can view the list of dependencies, replacing `<#>` with the desired version: +### Binary Install ``` -conda search libignition-plugin<#> --channel conda-forge --info +conda install libignition-plugin<#> --channel conda-forge ``` -Install dependencies, replacing `<#>` with the desired versions: +Be sure to replace `<#>` with a number value, such as 1 or 2, depending on +which version you need. -``` -conda install libignition-cmake<#> --channel conda-forge -``` +### Source Install -### Binary Install +1. Install Ignition dependencies: + +You can view available versions and their dependencies: ``` -conda install libignition-plugin<#> --channel conda-forge +conda search libignition-plugin* --channel conda-forge --info ``` -Be sure to replace `<#>` with a number value, such as 1 or 2, depending on -which version you need. +Install dependencies, replacing `<#>` with the desired version: -### Source Install +``` +conda install libignition-cmake<#> --channel conda-forge +``` 1. Navigate to where you would like to build the library, and clone the repository. From a882227f190fae8afd88ee68d2a274fe83a76907 Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Thu, 14 Jan 2021 02:49:59 -0500 Subject: [PATCH 3/6] backport #27 Signed-off-by: Mabel Zhang --- README.md | 15 +-------------- 1 file changed, 1 insertion(+), 14 deletions(-) diff --git a/README.md b/README.md index 27107d40..7c2d1481 100644 --- a/README.md +++ b/README.md @@ -23,20 +23,7 @@ of libraries designed to rapidly develop robot applications. ## Installation -Standard installation can be performed in UNIX systems using the following -steps: - - mkdir build/ - cd build/ - cmake .. - sudo make install - -## Uninstallation - -To uninstall the software installed with the previous steps: - - cd build/ - sudo make uninstall +See the [installation tutorial](https://ignitionrobotics.org/api/plugin/1.1/installation.html). ## Test From f20a2308013aa647ea5d041c4b16e940bdc267c5 Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Thu, 14 Jan 2021 03:09:32 -0500 Subject: [PATCH 4/6] standardize to ign-common format Signed-off-by: Mabel Zhang --- tutorials/02_installation.md | 196 +++++++++++++++++++---------------- 1 file changed, 107 insertions(+), 89 deletions(-) diff --git a/tutorials/02_installation.md b/tutorials/02_installation.md index 4c4fd847..7fa8b831 100644 --- a/tutorials/02_installation.md +++ b/tutorials/02_installation.md @@ -1,10 +1,15 @@ \page installation Installation -This tutorial describes how to install Ignition Plugin via either a binary distribution or from source. +These instructions are for installing only Ignition Plugin. +If you're interested in using all the Ignition libraries, check out this [Ignition installation](https://ignitionrobotics.org/docs/latest/install). -## Ubuntu +We recommend following the Binary Installation instructions to get up and running as quickly and painlessly as possible. -### Prerequisites +The Source Installation instructions should be used if you need the very latest software improvements, you need to modify the code, or you plan to make a contribution. + +# Ubuntu + +## Prerequisites Ignition Plugin version 1 requires Ubuntu Bionic, while version 0 can be used with Ubuntu Xenial. @@ -28,38 +33,43 @@ Setup keys: wget http://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add - ``` -### Binary Install +## Binary Installation +On Ubuntu systems, `apt-get` can be used to install `ignition-plugin`: ``` sudo apt-get update -sudo apt-get install libignition-plugin-dev +sudo apt install libignition-plugin-dev ``` -### Source Install +## Source Installation -Run the following to install dependencies -``` -sudo apt-get install libignition-cmake2-dev -``` +1. Install Ignition dependencies: + ``` + sudo apt-get install libignition-cmake2-dev + ``` -Clone the ign-plugin repository from GitHub -``` -git clone https://github.com/ignitionrobotics/ign-plugin -``` +2. Clone the repository + ``` + git clone https://github.com/ignitionrobotics/ign-plugin + ``` -Then build using CMake -``` -cd ign-plugin -mkdir build -cd build -cmake .. -make -sudo make install -``` +3. Configure and build + ``` + cd ign-plugin + mkdir build + cd build + cmake .. + make + ``` -## macOS +4. Optionally, install + ``` + sudo make install + ``` -### Prerequisites +# macOS + +## Prerequisites Ignition Plugin and several of its dependencies can be installed on macOS with [Homebrew](http://brew.sh/) using the [osrf/simulation @@ -67,104 +77,112 @@ tap](https://github.com/osrf/homebrew-simulation). Ignition Plugin version 1 requires macOS High Sierra (10.13) or later, while version 0 supports Sierra (10.12) or later. -### Install Binaries using Homebrew +## Binary Installation Using Homebrew -Install homebrew, which should also prompt you to install the XCode -command-line tools: +1. Install homebrew, which should also prompt you to install the XCode command-line tools + ``` + ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" + ``` -``` -ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" -``` +2. Run the following commands + ``` + brew tap osrf/simulation + brew install ignition-plugin1 + ``` -Run the following commands: +## Source Installation Using Homebrew -``` -brew tap osrf/simulation -brew install ignition-plugin1 -``` +1. Install dependencies + ``` + brew tap osrf/simulation + brew install ignition-plugin1 --only-dependencies + ``` -### Build from source using Homebrew +2. Clone the repository + ``` + git clone https://github.com/ignitionrobotics/ign-plugin + ``` -Run the following to install dependencies -``` -brew tap osrf/simulation -brew install ignition-plugin1 --only-dependencies -``` +3. Configure and build + ``` + cd ign-plugin + mkdir build + cd build + cmake .. + make + ``` -Clone the ign-plugin repository from GitHub -``` -git clone https://github.com/ignitionrobotics/ign-plugin -``` +4. Optionally, install + ``` + sudo make install + ``` -Then build using CMake -``` -cd ign-plugin -mkdir build -cd build -cmake .. -make -sudo make install -``` +# Windows -## Windows +## Binary Installation -### Prerequisites - -First, follow the [ign-cmake](https://github.com/ignitionrobotics/ign-cmake) tutorial for installing Conda, Visual Studio, CMake, etc., prerequisites, and creating a Conda environment. - -Navigate to ``condabin`` if necessary to use the ``conda`` command (i.e., if Conda is not in your `PATH` environment variable. You can find the location of ``condabin`` in Anaconda Prompt, ``where conda``). +Install [Conda package management system](https://docs.conda.io/projects/conda/en/latest/user-guide/install/download.html). +Miniconda suffices. Create if necessary, and activate a Conda environment: - ``` conda create -n ign-ws conda activate ign-ws ``` -### Binary Install - +Install `ignition-plugin`: ``` conda install libignition-plugin<#> --channel conda-forge ``` -Be sure to replace `<#>` with a number value, such as 1 or 2, depending on +Be sure to replace `<#>` with a number value, such as 2 or 3, depending on which version you need. -### Source Install +## Source Installation -1. Install Ignition dependencies: +### Prerequisites -You can view available versions and their dependencies: +First, follow the [ign-cmake](https://github.com/ignitionrobotics/ign-cmake) tutorial for installing Conda, Visual Studio, CMake, etc., prerequisites, and creating a Conda environment. +Navigate to ``condabin`` if necessary to use the ``conda`` command (i.e., if Conda is not in your `PATH` environment variable. You can find the location of ``condabin`` in Anaconda Prompt, ``where conda``). + +Activate the Conda environment: +``` +conda activate ign-ws +``` + +Install Ignition dependencies: + +You can view available versions and their dependencies: ``` conda search libignition-plugin* --channel conda-forge --info ``` Install dependencies, replacing `<#>` with the desired version: - ``` conda install libignition-cmake<#> --channel conda-forge ``` -1. Navigate to where you would like to build the library, and clone the repository. - - ``` - # Optionally, append `-b ign-plugin#` (replace # with a number) to check out a specific version - git clone https://github.com/ignitionrobotics/ign-plugin.git - ``` - -1. Configure and build +### Build from Source - ``` - cd ign-plugin - mkdir build - cd build - cmake .. -DBUILD_TESTING=OFF # Optionally, -DCMAKE_INSTALL_PREFIX=path\to\install - cmake --build . --config Release - ``` +This assumes you have created and activated a Conda environment while installing the Prerequisites. -1. Optionally, install - - ``` - cmake --install . --config Release - ``` +1. Navigate to where you would like to build the library, and clone the repository. + ``` + # Optionally, append `-b ign-plugin#` (replace # with a number) to check out a specific version + git clone https://github.com/ignitionrobotics/ign-plugin.git + ``` + +2. Configure and build + ``` + cd ign-plugin + mkdir build + cd build + cmake .. -DBUILD_TESTING=OFF # Optionally, -DCMAKE_INSTALL_PREFIX=path\to\install + cmake --build . --config Release + ``` + +3. Optionally, install + ``` + cmake --install . --config Release + ``` From e25ba6821689b48864589f10aefec9d3ef0fcd63 Mon Sep 17 00:00:00 2001 From: Mabel Zhang Date: Thu, 14 Jan 2021 04:12:59 -0500 Subject: [PATCH 5/6] change nesting Signed-off-by: Mabel Zhang --- tutorials/02_installation.md | 59 ++++++++++++++---------------------- 1 file changed, 23 insertions(+), 36 deletions(-) diff --git a/tutorials/02_installation.md b/tutorials/02_installation.md index 7fa8b831..f16fcd2c 100644 --- a/tutorials/02_installation.md +++ b/tutorials/02_installation.md @@ -22,13 +22,11 @@ sudo apt-get install lsb-release Setup your computer to accept software from [packages.osrfoundation.org](http://packages.osrfoundation.org): - ``` sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-stable.list' ``` Setup keys: - ``` wget http://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add - ``` @@ -43,7 +41,7 @@ sudo apt install libignition-plugin-dev ## Source Installation -1. Install Ignition dependencies: +1. Install Ignition dependencies ``` sudo apt-get install libignition-cmake2-dev ``` @@ -77,9 +75,9 @@ tap](https://github.com/osrf/homebrew-simulation). Ignition Plugin version 1 requires macOS High Sierra (10.13) or later, while version 0 supports Sierra (10.12) or later. -## Binary Installation Using Homebrew +## Binary Installation -1. Install homebrew, which should also prompt you to install the XCode command-line tools +1. Install Homebrew, which should also prompt you to install the XCode command-line tools ``` ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" ``` @@ -90,7 +88,7 @@ Sierra (10.12) or later. brew install ignition-plugin1 ``` -## Source Installation Using Homebrew +## Source Installation 1. Install dependencies ``` @@ -119,10 +117,11 @@ Sierra (10.12) or later. # Windows -## Binary Installation +## Prerequisites -Install [Conda package management system](https://docs.conda.io/projects/conda/en/latest/user-guide/install/download.html). -Miniconda suffices. +First, follow the [ign-cmake](https://github.com/ignitionrobotics/ign-cmake) tutorial for installing Conda, Visual Studio, CMake, and other prerequisites, and also for creating a Conda environment. + +Navigate to ``condabin`` if necessary to use the ``conda`` command (i.e., if Conda is not in your `PATH` environment variable. You can find the location of ``condabin`` in Anaconda Prompt, ``where conda``). Create if necessary, and activate a Conda environment: ``` @@ -130,7 +129,8 @@ conda create -n ign-ws conda activate ign-ws ``` -Install `ignition-plugin`: +## Binary Installation + ``` conda install libignition-plugin<#> --channel conda-forge ``` @@ -140,40 +140,27 @@ which version you need. ## Source Installation -### Prerequisites - -First, follow the [ign-cmake](https://github.com/ignitionrobotics/ign-cmake) tutorial for installing Conda, Visual Studio, CMake, etc., prerequisites, and creating a Conda environment. - -Navigate to ``condabin`` if necessary to use the ``conda`` command (i.e., if Conda is not in your `PATH` environment variable. You can find the location of ``condabin`` in Anaconda Prompt, ``where conda``). - -Activate the Conda environment: -``` -conda activate ign-ws -``` - -Install Ignition dependencies: - -You can view available versions and their dependencies: -``` -conda search libignition-plugin* --channel conda-forge --info -``` +This assumes you have created and activated a Conda environment while installing the Prerequisites. -Install dependencies, replacing `<#>` with the desired version: -``` -conda install libignition-cmake<#> --channel conda-forge -``` +1. Install Ignition dependencies: -### Build from Source + You can view available versions and their dependencies: + ``` + conda search libignition-plugin* --channel conda-forge --info + ``` -This assumes you have created and activated a Conda environment while installing the Prerequisites. + Install dependencies, replacing `<#>` with the desired version: + ``` + conda install libignition-cmake<#> --channel conda-forge + ``` -1. Navigate to where you would like to build the library, and clone the repository. +2. Navigate to where you would like to build the library, and clone the repository. ``` # Optionally, append `-b ign-plugin#` (replace # with a number) to check out a specific version git clone https://github.com/ignitionrobotics/ign-plugin.git ``` -2. Configure and build +3. Configure and build ``` cd ign-plugin mkdir build @@ -182,7 +169,7 @@ This assumes you have created and activated a Conda environment while installing cmake --build . --config Release ``` -3. Optionally, install +4. Optionally, install ``` cmake --install . --config Release ``` From bcd9e938878dd9e62fe48c259d7ebec1a1731fb9 Mon Sep 17 00:00:00 2001 From: John Shepherd Date: Wed, 20 Jan 2021 13:32:10 -0800 Subject: [PATCH 6/6] spacing nit Signed-off-by: John Shepherd --- README.md | 36 ---------------- tutorials/02_installation.md | 83 +++++++++++++++++++++++++++++++++++- 2 files changed, 82 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 7c2d1481..159025a5 100644 --- a/README.md +++ b/README.md @@ -24,39 +24,3 @@ of libraries designed to rapidly develop robot applications. ## Installation See the [installation tutorial](https://ignitionrobotics.org/api/plugin/1.1/installation.html). - -## Test - -Run tests as follows: - - make test - -> Tests are automatically built. To disable them, run `cmake` as follows: - - cmake .. -DBUILD_TESTING=false - -### Test coverage - -To run test coverage: - -1. Install LCOV - - sudo apt-get install lcov - -1. Build with coverage - - cd build/ - cmake .. -DCMAKE_BUILD_TYPE=coverage - make - -1. Run tests - - make test - -1. Generate coverage - - make coverage - -1. View results - - firefox coverage/index.html diff --git a/tutorials/02_installation.md b/tutorials/02_installation.md index f16fcd2c..479a0a28 100644 --- a/tutorials/02_installation.md +++ b/tutorials/02_installation.md @@ -121,7 +121,7 @@ Sierra (10.12) or later. First, follow the [ign-cmake](https://github.com/ignitionrobotics/ign-cmake) tutorial for installing Conda, Visual Studio, CMake, and other prerequisites, and also for creating a Conda environment. -Navigate to ``condabin`` if necessary to use the ``conda`` command (i.e., if Conda is not in your `PATH` environment variable. You can find the location of ``condabin`` in Anaconda Prompt, ``where conda``). +Navigate to `condabin` if necessary to use the `conda` command (i.e., if Conda is not in your `PATH` environment variable. You can find the location of `condabin` in Anaconda Prompt, `where conda`). Create if necessary, and activate a Conda environment: ``` @@ -173,3 +173,84 @@ This assumes you have created and activated a Conda environment while installing ``` cmake --install . --config Release ``` + +# Documentation + +API documentation and tutorials can be accessed at +[https://ignitionrobotics.org/libs/plugin](https://ignitionrobotics.org/libs/plugin) + +You can also generate the documentation from a clone of this repository by following these steps. + +1. You will need [Doxygen](http://www.doxygen.org/). On Ubuntu Doxygen can be installed using + ``` + sudo apt-get install doxygen + ``` + +2. Clone the repository + + ``` + git clone https://github.com/ignitionrobotics/ign-plugin + ``` + +3. Configure and build the documentation. + ``` + cd ign-plugin + mkdir build + cd build + cmake .. + make doc + ``` + +4. View the documentation by running the following command from the `build` directory. + ``` + firefox doxygen/html/index.html + ``` + +**Note** Alternatively, documentation for `ignition-plugin` can be found within the source code, and also in the [MIGRATION.md guide](https://github.com/ignitionrobotics/ign-plugin/blob/master/MIGRATION.md). + + +# Test + +Run tests as follows: +``` +make test +``` + +Tests are automatically built. To disable them, run `cmake` as follows: +``` +cmake .. -DBUILD_TESTING=false +``` + +## Test coverage + +To run test coverage: + +1. Install LCOV + + ``` + sudo apt-get install lcov + ``` + +2. Build with coverage + + ``` + cd build/ + cmake .. -DCMAKE_BUILD_TYPE=coverage + make + ``` + +3. Run tests + ``` + make test + ``` + +4. Generate coverage + ``` + make coverage + ``` + +5. View results + ``` + firefox coverage/index.html + ``` +