From f5a57f16ee405ade058428073618402116ab5428 Mon Sep 17 00:00:00 2001 From: John Shepherd Date: Wed, 20 Jan 2021 18:10:05 -0800 Subject: [PATCH] Add Windows Installation (#82) Signed-off-by: Mabel Zhang Signed-off-by: John Shepherd Co-authored-by: Mabel Zhang --- README.md | 52 ------------- tutorials/02_install.md | 166 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 166 insertions(+), 52 deletions(-) create mode 100644 tutorials/02_install.md diff --git a/README.md b/README.md index 26b07ccb..a2a40db8 100644 --- a/README.md +++ b/README.md @@ -34,10 +34,6 @@ designed to generate realistic data from simulation environments. Ignition Senso [Usage](#usage) -[Documentation](#documentation) - -[Testing](#testing) - [Folder Structure](#folder-structure) [Code of Conduct](#code-of-conduct) @@ -155,54 +151,6 @@ Ignition Sensors requires: Please refer to the [examples directory](https://github.com/ignitionrobotics/ign-sensors/raw/master/examples/). -# Documentation - -API and tutorials can be found at [https://ignitionrobotics.org/libs/sensors](https://ignitionrobotics.org/libs/sensors). - -You can also generate the documentation from a clone of this repository by following these steps. - -1. You will need Doxygen. On Ubuntu Doxygen can be installed using - - ``` - sudo apt-get install doxygen - ``` - -2. Clone the repository - - ``` - git clone https://github.com/ignitionrobotics/ign-sensors - ``` - -3. Configure and build the documentation. - - ``` - cd ign-sensors; 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 - ``` - -# Testing - -Follow these steps to run tests and static code analysis in your clone of this repository. - -1. Follow the [source install instruction](#source-install). - -2. Run tests. - - ``` - make test - ``` - -3. Static code checker. - - ``` - make codecheck - ``` - # Folder Structure Refer to the following table for information about important directories and files in this repository. diff --git a/tutorials/02_install.md b/tutorials/02_install.md new file mode 100644 index 00000000..498444be --- /dev/null +++ b/tutorials/02_install.md @@ -0,0 +1,166 @@ +\page installation Installation + +We recommend following the binary install instructions to get up and running as quickly and painlessly as possible. + +The source install 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. + +## Binary Install + +### Ubuntu + +1. Setup your computer to accept software from 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' + wget http://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add - + sudo apt-get update + ``` + +1. Install Ignition Sensors + ``` + # This installs ign-sensors3. Change the number after libignition-sensors to the version you want + sudo apt install libignition-sensors3-dev + ``` + +### Windows + +Binary install is pending `ignition-rendering` and `ignition-sensors` being added to conda-forge. + +## Source Install + +Source installation can be performed in UNIX systems by first installing the +necessary prerequisites followed by building from source. + +### Prerequisites + +Ignition Sensors requires: + + * [Ignition CMake](https://ignitionrobotics.org/libs/cmake) + * [Ignition Math](https://ignitionrobotics.org/libs/math) + * [Ignition Common](https://ignitionrobotics.org/libs/common) + * [Ignition Transport](https://ignitionrobotics.org/libs/transport) + * [Ignition Rendering](https://ignitionrobotics.org/libs/rendering) + * [Ignition Msgs](https://ignitionrobotics.org/libs/msgs) + * [SDFormat](https://github.com/osrf/sdformat) + * [Protobuf3](https://developers.google.com/protocol-buffers/) + +### Ubuntu + +1. Make sure you are running [Ubuntu Bionic](http://releases.ubuntu.com/18.04/) or above. + +2. Install the Prerequisites. + +3. Configure to use gcc8 if that is not the default compiler + ``` + sudo apt-get install g++-8 + update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-8 800 --slave /usr/bin/g++ g++ /usr/bin/g++-8 --slave /usr/bin/gcov gcov /usr/bin/gcov-8 + ``` + +4. Clone the repository + ``` + git clone https://github.com/ignitionrobotics/ign-sensors + ``` + +5. Configure and build + ``` + cd ign-sensors; mkdir build; cd build; cmake ..; make + ``` + +6. Optionally, install the library + ``` + sudo make install + ``` + +### Windows + +#### Install 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, replacing `<#>` with the desired versions: + +``` +conda install libignition-cmake<#> libignition-common<#> libignition-math<#> libignition-transport<#> libignition-msgs<#> libignition-plugin<#> --channel conda-forge +``` + +Before [ign-rendering](https://github.com/ignitionrobotics/ign-rendering) becomes available on conda-forge, follow its tutorial to build it from source. + +#### Build from source + +1. Activate the Conda environment created in the prerequisites: + ``` + conda activate ign-ws + ``` + +1. Navigate to where you would like to build the library, and clone the repository. + ``` + # Optionally, append `-b ign-sensors#` (replace # with a number) to check out a specific version + git clone https://github.com/ignitionrobotics/ign-sensors.git + ``` + +1. Configure and build + ``` + cd ign-sensors + mkdir build + cd build + ``` + + Before `ign-rendering` becomes available on conda-forge, we need to build it from source and specify the path containing `ignition-rendering-config.cmake` in `CMAKE_PREFIX_PATH`, for cmake to find `ign-rendering`. That path could be `ign-rendering-install-path\lib\cmake\ignition-rendering4`, for example. + ``` + cmake .. -DBUILD_TESTING=OFF -DCMAKE_PREFIX_PATH=path\containing\ignition-rendering-config # Optionally, -DCMAKE_INSTALL_PREFIX=path\to\install + cmake --build . --config Release + ``` + +1. Optionally, install. You will likely need to run a terminal with admin privileges for this call to succeed. + ``` + cmake --install . --config Release + ``` + +# Documentation + +API and tutorials can be found at [https://ignitionrobotics.org/libs/sensors](https://ignitionrobotics.org/libs/sensors). + +You can also generate the documentation from a clone of this repository by following these steps. + +1. You will need Doxygen. On Ubuntu Doxygen can be installed using + ``` + sudo apt-get install doxygen + ``` + +2. Clone the repository + ``` + git clone https://github.com/ignitionrobotics/ign-sensors + ``` + +3. Configure and build the documentation. + ``` + cd ign-sensors; 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 + ``` + +# Testing + +Follow these steps to run tests and static code analysis in your clone of this repository. + +1. Run tests. + ``` + make test + ``` + +2. Static code checker. + ``` + make codecheck + ``` +