From 31368aae06120798446b3ef90c0012fe45d45c0f Mon Sep 17 00:00:00 2001 From: Nate Koenig Date: Fri, 22 Jan 2021 15:13:11 -0800 Subject: [PATCH] 3 to 4 20210122 (#208) * Add Windows installation (#196) Signed-off-by: Mabel Zhang Co-authored-by: John Shepherd * Prepare for 3.3.0 release (#207) Signed-off-by: Nate Koenig Co-authored-by: Nate Koenig Co-authored-by: Mabel Zhang Co-authored-by: John Shepherd Co-authored-by: Nate Koenig --- Changelog.md | 17 +++ README.md | 34 +----- tutorials/02_install.md | 258 ++++++++++++++++++++++++++++------------ 3 files changed, 200 insertions(+), 109 deletions(-) diff --git a/Changelog.md b/Changelog.md index beaf68e34..114ef183c 100644 --- a/Changelog.md +++ b/Changelog.md @@ -99,6 +99,23 @@ 1. Add support for transparency based on textures alpha channel for ogre1 and ogre2 * [BitBucket pull request 229](https://osrf-migration.github.io/ignition-gh-pages/#!/ignitionrobotics/ign-rendering/pull-requests/229) +### Ignition Rendering 3.3.0 (2021-01-22) + +1. Add Windows installation. + * [Pull request 196](https://github.com/ignitionrobotics/ign-rendering/pull/196) + +1. Make flaky VisualAt test more verbose. + * [Pull request 174](https://github.com/ignitionrobotics/ign-rendering/pull/174) + +1. Resolve updated codecheck issues. + * [Pull request 173](https://github.com/ignitionrobotics/ign-rendering/pull/173) + +1. Fix crash due to NaN pose values. + * [Pull request 169](https://github.com/ignitionrobotics/ign-rendering/pull/169) + +1. Improve fork experience. + * [Pull request 165](https://github.com/ignitionrobotics/ign-rendering/pull/165) + ### Ignition Rendering 3.2.0 (2020-10-13) 1. Add Custom Render Engine support diff --git a/README.md b/README.md index e9474ec47..3fb9983ab 100644 --- a/README.md +++ b/README.md @@ -30,10 +30,6 @@ of libraries designed to rapidly develop robot applications. [Usage](#usage) -[Documentation](#documentation) - -[Testing](#testing) - [Folder Structure](#folder-structure) [Code of Conduct](#code-of-conduct) @@ -57,37 +53,11 @@ See the [installation tutorial](https://ignitionrobotics.org/api/rendering/4.0/i # Usage The Ign Rendering API can be found in the documentation. See the -[Documentation](#documentation) section on how to build the -documentation files using Doxygen. +[installation tutorial](https://ignitionrobotics.org/api/rendering/4.0/installation.html) +on how to build the documentation files using Doxygen. You can also take a look at the sample applications in the `examples` folder. -# Documentation - -API documentation can be generated using Doxygen - - sudo apt install -y doxygen - -Build documentation - - cd build - make doc - -View documentation - - firefox doxygen/html/index.html - -# Testing - -Tests can be run by building the `test` target: - - cd build - make test - -To run tests specific to a render engine, set the `RENDER_ENGINE_VALUES` environment variable, e.g. - - RENDER_ENGINE_VALUES=ogre2 make test - # Folder Structure * `include/ignition/rendering`: Contains all the public header files which will be installed diff --git a/tutorials/02_install.md b/tutorials/02_install.md index d7d7720d5..fec7243e7 100644 --- a/tutorials/02_install.md +++ b/tutorials/02_install.md @@ -1,108 +1,110 @@ \page installation Installation -[Install](#install) +These instructions are for installing only Ignition Rendering. +If you're interested in using all the Ignition libraries, check out this [Ignition installation](https://ignitionrobotics.org/docs/latest/install). -* [Binary Install](#binary-install) +We recommend following the Binary Install instructions to get up and running as quickly and painlessly as possible. -* [Source Install](#source-install) +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. - * [Prerequisites](#prerequisites) +# Ubuntu - * [Building from Source](#building-from-source) +## Binary Installation -We recommend following the [Binary Install](#binary-install) instructions to get up and running as quickly and painlessly as possible. - -The [Source Install](#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 +Install dependencies: +``` +sudo apt-get update +sudo apt-get -y install wget lsb-release gnupg +``` -Setup your computer to accept software from packages.osrfoundation.org: +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' +``` - sudo apt -y install wget lsb-release gnupg - 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 update +Setup keys: +``` +wget http://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add - +``` -Install Ignition Rendering: +Install: +``` +sudo apt-get update +sudo apt-get install libignition-rendering<#>-dev +``` - # This installs ign-rendering3. Change the number after libignition-rendering to the version you want - sudo apt install libignition-rendering3-dev +Be sure to replace `<#>` with a number value, such as `1` or `2`, depending on which version you need. -## Source Install +## Source Installation ### Prerequisites -#### Ubuntu Bionic 18.04 or above +Ubuntu Bionic 18.04 or above: Install dependencies: - - sudo apt -y install wget lsb-release gnupg - 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 update - sudo apt install -y \ - g++-8 \ - cmake \ - pkg-config \ - git \ - libglew-dev \ - libfreeimage-dev \ - freeglut3-dev \ - libxmu-dev \ - libxi-dev \ - libignition-cmake2-dev \ - libignition-math6-dev \ - libignition-common3-dev \ - libignition-plugin-dev - sudo 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 - -Clone source code - - # This checks out the `master` branch. You can append `-b ign-rendering#` (replace # with a number) to checkout a specific version - git clone http://github.com/ignitionrobotics/ign-rendering - -#### Supported Rendering Engines +``` +sudo apt -y install wget lsb-release gnupg +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 update +sudo apt install -y \ + g++-8 \ + cmake \ + pkg-config \ + git \ + libglew-dev \ + libfreeimage-dev \ + freeglut3-dev \ + libxmu-dev \ + libxi-dev \ + libignition-cmake2-dev \ + libignition-math6-dev \ + libignition-common3-dev \ + libignition-plugin-dev +sudo 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 +``` + +### Supported Rendering Engines Ignition Rendering will look for rendering libraries installed in the system and build the relevant plugins if dependencies are found. **OGRE 1.x** - - # this installs ogre 1.9. Alternatively, you can install 1.8 - sudo apt-get install libogre-1.9-dev +``` +# this installs ogre 1.9. Alternatively, you can install 1.8 +sudo apt-get install libogre-1.9-dev +``` **OGRE 2.x (supported in Versions >= ign-rendering1)** Add OSRF packages if you have not done so already: - - sudo apt -y install wget lsb-release gnupg - 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 update +``` +sudo apt -y install wget lsb-release gnupg +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 update +``` Install OGRE 2.1 debs - - sudo apt install libogre-2.1-dev +``` +sudo apt install libogre-2.1-dev +``` **OptiX (experimental)** Download and install by following instructions on NVIDIA website -CUDA: - -http://docs.nvidia.com/cuda +CUDA: http://docs.nvidia.com/cuda -OptiX: - -https://developer.nvidia.com/optix +OptiX: https://developer.nvidia.com/optix Update `LD_LIBRARY_PATH` and add an `OPTIX_INSTALL_DIR` environment variables so that ign-rendering can find Optix, e.g. if you installed version 4.0.2 in HOME/optix: - - export LD_LIBRARY_PATH=${HOME}/optix/NVIDIA-OptiX-SDK-4.0.2-linux64/lib64:${LD_LIBRARY_PATH} - export OPTIX_INSTALL_DIR=${HOME}/optix/NVIDIA-OptiX-SDK-4.0.2-linux64 +``` +export LD_LIBRARY_PATH=${HOME}/optix/NVIDIA-OptiX-SDK-4.0.2-linux64/lib64:${LD_LIBRARY_PATH} +export OPTIX_INSTALL_DIR=${HOME}/optix/NVIDIA-OptiX-SDK-4.0.2-linux64 +``` Note: If you encounter errors about different exception specifiers in optix math when building Ign Rendering OptiX plugin, edit @@ -110,16 +112,118 @@ when building Ign Rendering OptiX plugin, edit out the section that defines `fminf`, fmaxf, and `copysignf` (for optix sdk 4.0.2, comment out lines 167-206). +### Build from Source + +1. Clone the repository + ``` + # Optionally, append `-b ign-rendering#` (replace # with a number) to check out a specific version + git clone http://github.com/ignitionrobotics/ign-rendering + ``` + +2. Configure and build + ``` + cd ign-rendering + mkdir build + cd build + cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install/dir + make + ``` + Replace `/path/to/install/dir` to whatever directory you want to install this package to + +3. Optionally, install + ``` + make install + ``` + +# Windows + +On Windows, only OGRE 1 is currently supported. + +## Prerequisites + +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: +``` +conda create -n ign-ws +conda activate ign-ws +``` + +## Binary Installation + +`libignition-rendering<#>` Conda feedstock is not yet available, pending [conda-forge/staged-recipes#13551](https://github.com/conda-forge/staged-recipes/issues/13551). + +## Source Installation + +This assumes you have created and activated a Conda environment while installing the Prerequisites. + +1. Install dependencies: + ``` + conda install ogre --channel conda-forge + ``` + +2. Install Ignition dependencies: + + You can view available versions and their dependencies: + ``` + conda search libignition-rendering* --channel conda-forge --info + ``` + + Install dependencies, replacing `<#>` with the desired versions: + ``` + conda install libignition-cmake<#> libignition-common<#> libignition-math<#> libignition-plugin<#> --channel conda-forge + ``` + +3. Navigate to where you would like to build the library, and clone the repository. + ``` + # Optionally, append `-b ign-rendering#` (replace # with a number) to check out a specific version + git clone https://github.com/ignitionrobotics/ign-rendering.git + ``` + +4. Configure and build + ``` + cd ign-rendering + mkdir build + cd build + cmake .. -DBUILD_TESTING=OFF # Optionally, -DCMAKE_INSTALL_PREFIX=path\to\install + cmake --build . --config Release + ``` + +5. Optionally, install + ``` + cmake --install . --config Release + ``` + +# Documentation + +API documentation can be generated using Doxygen + ``` + sudo apt install -y doxygen + ``` + +Build documentation + ``` + cd build + make doc + ``` -### Building from source +View documentation + ``` + firefox doxygen/html/index.html + ``` -Build and install as follows: +# Testing + +Tests can be run by building the `test` target: + ``` + cd build + make test + ``` - cd ign-rendering - mkdir build - cd build - cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install/dir - make -j4 - make install +To run tests specific to a render engine, set the `RENDER_ENGINE_VALUES` environment variable, e.g. + ``` + RENDER_ENGINE_VALUES=ogre2 make test + ``` -Replace `/path/to/install/dir` to whatever directory you want to install this package to