3 to 4 20210122 (#208)

* Add Windows installation (#196) Signed-off-by: Mabel Zhang <[email protected]> Co-authored-by: John Shepherd <[email protected]> * Prepare for 3.3.0 release (#207) Signed-off-by: Nate Koenig <[email protected]> Co-authored-by: Nate Koenig <[email protected]> Co-authored-by: Mabel Zhang <[email protected]> Co-authored-by: John Shepherd <[email protected]> Co-authored-by: Nate Koenig <[email protected]>
gazebosim · Jan 22, 2021 · 31368aa · 31368aa
1 parent 7e8a384
commit 31368aa
Show file tree

Hide file tree

Showing 3 changed files with 200 additions and 109 deletions.
diff --git 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
@@ -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
@@ -1,125 +1,229 @@
 \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
 `[optix_install_dir]/include/optixu/optixu_math_namespace.h` and comment
 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