From 90306fa4737fcc6aaaa7fc0cb7e40c1917db125a Mon Sep 17 00:00:00 2001 From: Louise Poubel Date: Wed, 21 Apr 2021 11:43:32 -0700 Subject: [PATCH] Fortress (#174) Signed-off-by: Louise Poubel Co-authored-by: Ashton Larkin <42042756+adlarkin@users.noreply.github.com> --- .github/labeler.yml | 3 + edifice/install.md | 2 +- fortress/index.yaml | 43 ++++++ fortress/install.md | 57 ++++++++ fortress/install_osx.md | 37 +++++ fortress/install_osx_src.md | 245 ++++++++++++++++++++++++++++++++ fortress/install_ubuntu.md | 43 ++++++ fortress/install_ubuntu_src.md | 242 +++++++++++++++++++++++++++++++ fortress/install_windows.md | 82 +++++++++++ fortress/install_windows_src.md | 154 ++++++++++++++++++++ index.yaml | 4 + releases.md | 2 +- tools/branch_comparisons.md | 2 +- 13 files changed, 913 insertions(+), 3 deletions(-) create mode 100644 fortress/index.yaml create mode 100644 fortress/install.md create mode 100644 fortress/install_osx.md create mode 100644 fortress/install_osx_src.md create mode 100644 fortress/install_ubuntu.md create mode 100644 fortress/install_ubuntu_src.md create mode 100644 fortress/install_windows.md create mode 100644 fortress/install_windows_src.md diff --git a/.github/labeler.yml b/.github/labeler.yml index a89836ad1..8df0f9fd9 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -10,3 +10,6 @@ 🏢 edifice: - edifice/* - edifice/**/* +🏯 fortress: + - fortress/* + - fortress/**/* diff --git a/edifice/install.md b/edifice/install.md index 95fdabede..eacf1c648 100644 --- a/edifice/install.md +++ b/edifice/install.md @@ -39,7 +39,7 @@ collection assures that all libraries are compatible and can be used together. | ------------------ |:-------------:| | ign-cmake | 2.x | | ign-common | 4.x | -| ign-fuel_tools | 6.x | +| ign-fuel-tools | 6.x | | ign-gazebo | 5.x | | ign-gui | 5.x | | ign-launch | 4.x | diff --git a/fortress/index.yaml b/fortress/index.yaml new file mode 100644 index 000000000..9fccdb83a --- /dev/null +++ b/fortress/index.yaml @@ -0,0 +1,43 @@ +# This file is an index of the pages to display on the documentation website +# (https://ignitionrobotics.org/docs). The order of the pages in this file +# is reflected on the website's left sidebar. +# +# Components of the index: +# +# 1. "pages:" The master list of pages +# +# 2. Each page has a +# a. "name:" This should be a short url-friendly and unique name. It will +# be used in the website url. +# +# b. "title:" This is a human-friendly title for the page. This title will +# be displayed on the website's left side bar. +# +# c. "file:" The markdown file that contains the page's content. +pages: + - name: install + title: Install + file: install.md + description: Fortress installation instructions + children: + - name: install_ubuntu + title: Binary Ubuntu Install + file: install_ubuntu.md + - name: install_osx + title: Binary macOS Install + file: install_osx.md + - name: install_windows + title: Binary Windows Install + file: install_windows.md + - name: install_ubuntu_src + title: Ubuntu Source Install + file: install_ubuntu_src.md + - name: install_osx_src + title: macOS Source Install + file: install_osx_src.md + - name: install_windows_src + title: Windows Source Install + file: install_windows_src.md + - name: troubleshooting + title: Troubleshooting + file: troubleshooting.md diff --git a/fortress/install.md b/fortress/install.md new file mode 100644 index 000000000..416379f2e --- /dev/null +++ b/fortress/install.md @@ -0,0 +1,57 @@ +# Fortress Installation + +Until the official release, Fortress can be compiled from source or installed +from nightly debian packages on Linux. + +Fortress supports the following platforms: + + * Ubuntu Bionic amd64 and Focal on amd64 + * MacOS Mojave and Catalina + * Ignition currently only works in headless mode + (GUI does not render; instead of using `ign gazebo fuel.sdf` command, use + `ign gazebo -s fuel.sdf` to start the server only). + * Windows 10 + * Ignition command line utilities are not yet supported. + * All packages up to `ign-gazebo` can be built. + * DART physics engine is not yet supported. + * Qt (GUI functionality) is not yet supported. + +## Binary installation instructions + +Binary installation is the recommended method of installing Ignition. + + * [Binary Installation on Ubuntu](install_ubuntu) + * [Binary Installation on macOS](install_osx) + * [Binary Installation on Windows](install_windows) + +## Source Installation instructions + +Source installation is recommended for users planning on altering Ignition's source code (advanced). + + * [Source Installation on Ubuntu](install_ubuntu_src) + * [Source Installation on macOS](install_osx_src) + * [Source Installation on Windows](install_windows_src) + +## Fortress Libraries + +The Fortress collection is composed of many different Ignition libraries. The +collection assures that all libraries are compatible and can be used together. + +| Library name | Version | +| ------------------ |:-------------:| +| ign-cmake | 2.x | +| ign-common | 4.x | +| ign-fuel-tools | 7.x | +| ign-gazebo | 6.x | +| ign-gui | 6.x | +| ign-launch | 5.x | +| ign-math | 6.x | +| ign-msgs | 8.x | +| ign-physics | 5.x | +| ign-plugin | 1.x | +| ign-rendering | 6.x | +| ign-sensors | 6.x | +| ign-tools | 1.x | +| ign-transport | 11.x | +| ign-utils | 1.x | +| sdformat | 12.x | diff --git a/fortress/install_osx.md b/fortress/install_osx.md new file mode 100644 index 000000000..1d04df1a7 --- /dev/null +++ b/fortress/install_osx.md @@ -0,0 +1,37 @@ +# Binary Installation on MacOS + +All the Fortress binaries are available in Mojave and Catalina using the +[homebrew package manager](https://brew.sh/). + +Up to Fortress's release date, the binaries should be considered unstable. + +The homebrew tool can be installed using: + +```bash +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" +``` + +After installing the homebrew package manager, Ignition Fortress can be installed running: + +```bash +brew tap osrf/simulation +brew install ignition-fortress +``` + +All libraries should be ready to use and the `ign gazebo` app ready to be executed. + +Head back to the [Getting started](/docs/all/getstarted) +page to start using Ignition! + +## Uninstalling binary install + +If you need to uninstall Ignition or switch to a source-based install once you +have already installed the library from binaries, run the following command: + +```bash +brew uninstall ignition-fortress +``` + +## Troubleshooting + +See [Troubleshooting](troubleshooting) diff --git a/fortress/install_osx_src.md b/fortress/install_osx_src.md new file mode 100644 index 000000000..b6c7387af --- /dev/null +++ b/fortress/install_osx_src.md @@ -0,0 +1,245 @@ +# Source Installation on MacOS + +This tutorial will work for MacOS Mojave 10.14 and MacOS Catalina 10.15. + +## Install tools + +The use of some additional tools is recommended to help with the source compilation, +although other ways of correctly getting and building the sources are also possible. + +The easiest way to get the sources of all libraries is to use +[vcstool](https://github.com/dirk-thomas/vcstool). + +To compile all the different libraries and ign-gazebo in the right order +[colcon](https://colcon.readthedocs.io/en/released/) is recommended. +The colcon tool is available on all platforms using pip (or pip3, if pip fails). + +## Python3 from homebrew + +Tools and dependencies for Fortress can be installed using the [homebrew package manager](https://brew.sh/). +The homebrew tool can be installed by entering the following in a terminal: + +```bash +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" +``` + +Fortress is compatible with Python3; it can be installed by running the following in a terminal: + +```bash +brew install python3 +``` + +## vcstool and colcon from pip + +PIP is available on all platforms: + +```bash +python3 -m pip install vcstool +``` + +```bash +python3 -m pip install -U colcon-common-extensions +``` + +## Getting the sources + +The first step is to create a developer workspace in which `vcstool` and +`colcon` can work: + +```bash +mkdir -p ~/workspace/src +cd ~/workspace/src +``` + +All the sources of ignition-fortress are declared in a yaml file. Download +it to the workspace: + +```bash +wget https://raw.githubusercontent.com/ignition-tooling/gazebodistro/master/collection-fortress.yaml +``` + +Use `vcstool` to automatically retrieve all the Ignition libraries sources from +their repositories: + +```bash +vcs import < collection-fortress.yaml +``` + +The src subdirectory should contain all the sources ready to be built. + + +## Install dependencies + +Add `osrf/simulation` to Homebrew formulae + +```bash +brew update +brew tap osrf/simulation +``` + +Install all dependencies: + +Dependency for Ogre: + +```bash +brew cask install xquartz +``` + +General dependencies: + +```bash +brew install assimp boost bullet cmake cppzmq dartsim@6.10.0 doxygen eigen fcl ffmpeg flann freeimage freetype gflags google-benchmark gts ipopt irrlicht jsoncpp libccd libyaml libzzip libzip nlopt ode open-scene-graph ossp-uuid ogre1.9 ogre2.1 pkg-config protobuf qt qwt rapidjson ruby tbb tinyxml tinyxml2 urdfdom zeromq +``` + +`dartsim@6.10.0` and `qt5` are not sym-linked. To use those dependencies when building +`ignition-physics2` and `ignition-gui3`, run the following after installation to add them to `/use/local`: + +```bash +# dartsim@6.10.0 +export CMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH}:/usr/local/opt/dartsim@6.10.0 +export DYLD_FALLBACK_LIBRARY_PATH=${DYLD_FALLBACK_LIBRARY_PATH}:/usr/local/opt/dartsim@6.10.0/lib:/usr/local/opt/octomap/local +export PKG_CONFIG_PATH=${PKG_CONFIG_PATH}:/usr/local/opt/dartsim@6.10.0/lib/pkgconfig +# qt5 +export CMAKE_PREFIX_PATH=${CMAKE_PREFIX_PATH}:/usr/local/opt/qt +``` + +### Install compiler requirements + +The Ignition Libraries require the Xcode 10 compiler on MacOS Mojave. + +On Mac machines, gcc is acquired by installing Xcode command line tools. +The required version of Xcode for Fortress is Xcode 10.3, which can be downloaded from +[Apple Developer Site](https://developer.apple.com/download/more/). +You will need to sign in to your Apple account and download the Mojave version of +Xcode command line tools. Command line tools can also be obtained by downloading +Xcode from the Apple App Store (installing the full app may take over an hour). + +## Building the Ignition Libraries in MacOS Catalina (10.15) + +If you want to compile Ignition Libraries in MacOS Catalina (10.15) you will need to apply some patches in your filesystem: + + - `/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.15.sdk/System/Library/Frameworks/Ruby.framework/Headers/ruby/ruby/intern.h` + +Create a file called `intern.patch` with the following content: + +```patch +--- intern.h 2019-12-16 18:17:08.000000000 +0100 ++++ /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.15.sdk/System/Library/Frameworks/Ruby.framework/Headers/ruby/ruby/intern.h +@@ -14,6 +14,10 @@ + #ifndef RUBY_INTERN_H + #define RUBY_INTERN_H 1 + ++#if __cplusplus > 199711L ++#define register // Deprecated in C++11. ++#endif // #if __cplusplus > 199711L ++ + #if defined(__cplusplus) + extern "C" { + #if 0 +``` + +Now we can apply the patch: + +```{.sh} +sudo patch -p0 < intern.patch +``` + + - `/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.15.sdk/System/Library/Frameworks/Ruby.framework/Headers/ruby/ruby/config.h` + +Create a file called `config.patch` with the following content: + +```patch +--- config.h 2019-12-16 18:19:13.000000000 +0100 ++++ /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.15.sdk/System/Library/Frameworks/Ruby.framework/Headers/ruby/ruby/config.h +@@ -410,6 +410,6 @@ + #define RUBY_PLATFORM_CPU "x86_64" + #endif /* defined __x86_64__ &&! defined RUBY_PLATFORM_CPU */ + #define RUBY_PLATFORM_OS "darwin19" +-#define RUBY_ARCH"universal-"RUBY_PLATFORM_OS +-#define RUBY_PLATFORM"universal."RUBY_PLATFORM_CPU"-"RUBY_PLATFORM_OS ++#define RUBY_ARCH "universal-" RUBY_PLATFORM_OS ++#define RUBY_PLATFORM "universal." RUBY_PLATFORM_CPU "-" RUBY_PLATFORM_OS + #endif /* INCLUDE_RUBY_CONFIG_H */ +``` + +Now we can appply the patch: + +```{.sh} +sudo patch -p0 < config.patch +``` + +## Building the Ignition Libraries + +Once the compiler and all the sources are in place it is time to compile them. +Start the procedure by changing into the workspace and listing the packages +recognized by `colcon`: + +```bash +cd ~/workspace/ +colcon graph +``` + +`colcon graph` should list the Ignition libraries with an +[interdependency diagram](https://colcon.readthedocs.io/en/released/reference/verb/graph.html#example-output). +If that is the case, then you are ready +to build the whole set of libraries: + +```bash +colcon build --merge-install +``` + +To speed up the build process, you could also disable tests by using + +```bash +colcon build --cmake-args -DBUILD_TESTING=OFF --merge-install +``` + +To build a specific package with all its dependent packages: + +```bash +colcon build --merge-install --packages-up-to PACKAGE_NAME +``` + +To build a single package: + +```bash +colcon build --merge-install --packages-select PACKAGE_NAME +``` + +Visit [colcon documentation](https://colcon.readthedocs.io/en/released/#) to view more `colcon` build and test options. + +If there are no errors, all the binaries should be ready to use. + +## Using the workspace + +The workspace needs to be sourced every time a new terminal is used. + +Run the following command to source the workspace in bash: + +```bash +. ~/workspace/install/setup.bash +``` + +Or in zsh: + +```zsh +. ~/workspace/install/setup.zsh +``` + +This is the end of the source install instructions; head back to the [Getting started](getting_started.html) +page to start using Ignition! + +## Uninstalling source-based install + +If you need to uninstall Ignition or switch to a binary-based install once you +have already installed the library from source, navigate to your source code +directory's build folders and run `make uninstall`: + +```bash +cd /workspace +sudo make uninstall +``` + +## Troubleshooting + +See [Troubleshooting](troubleshooting) diff --git a/fortress/install_ubuntu.md b/fortress/install_ubuntu.md new file mode 100644 index 000000000..f69ea28f1 --- /dev/null +++ b/fortress/install_ubuntu.md @@ -0,0 +1,43 @@ +# Binary Installation on Ubuntu + +Fortress binaries are provided for Ubuntu Bionic and Focal. All of the Fortress +binaries are hosted in the osrfoundation repository. To install all of them, +the metapackage `ignition-fortress` can be installed. + +Up to Fortress's release date, the binaries should be considered unstable. + +First install some necessary tools: + +```bash +sudo apt-get update +sudo apt-get install lsb-release wget gnupg +``` + +Then install Ignition Fortress: + + +```bash +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 sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-nightly `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-nightly.list' +wget http://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add - +sudo apt-get update +sudo apt-get install ignition-fortress +``` + +All libraries should be ready to use and the `ign gazebo` app ready to be executed. + +Head back to the [Getting started](/docs/all/getstarted) +page to start using Ignition! + +## Uninstalling binary install + +If you need to uninstall Ignition or switch to a source-based install once you +have already installed the library from binaries, run the following command: + +```bash +sudo apt remove ignition-fortress && sudo apt autoremove +``` + +## Troubleshooting + +See [Troubleshooting](troubleshooting) diff --git a/fortress/install_ubuntu_src.md b/fortress/install_ubuntu_src.md new file mode 100644 index 000000000..242cdea8d --- /dev/null +++ b/fortress/install_ubuntu_src.md @@ -0,0 +1,242 @@ +# Source Installation on Ubuntu + +These instructions apply to Ubuntu Bionic (18.04) and Focal (20.04). + +## Install tools + +The use of some additional tools is recommended to help with the source compilation, +although other ways of correctly getting and building the sources are also possible. + +The easiest way to get the sources of all libraries is to use +[vcstool](https://github.com/dirk-thomas/vcstool). + +To compile all the different libraries and ign-gazebo in the right order +[colcon](https://colcon.readthedocs.io/en/released/) is recommended. +The colcon tool is available on all platforms using pip (or pip3, if pip fails). + +Some tools require Python 3.5 (or higher) which is not the default option on some +platforms (like Ubuntu Focal). The Python +[virtualenv](https://virtualenv.pypa.io/en/latest/) could be a useful solution in +cases where the default option cannot be easily changed. + +## Generic tools + +Install tools needed by this tutorial: + +```bash +sudo apt install python3-pip wget lsb-release gnupg +``` + +## vcstool and colcon from pip + +PIP is available on all platforms: + +```bash +pip install vcstool || pip3 install vcstool +``` + +```bash +pip install -U colcon-common-extensions || pip3 install -U colcon-common-extensions +``` + +Check that no errors were printed while installing with PIP. If your system is not recognising the commands, and you're using a system that is compatible with Debian or Ubuntu packages, see the instructions below to install using `apt`. + +After installing `vcstool` and `colcon` with PIP, you may need to add their executables to your `$PATH`. +Check where the installation of these packages took place: + +```bash +pip show vcstool || pip3 show vcstool | grep Location + +pip show colcon-common-extensions || pip3 show colcon-common-extensions | grep Location +``` + +If your install path is prefixed with `$HOME/.local`, you'll probably need to add the executables within this directory to your `$PATH` in order to avoid "command not found" errors when using `vcstool` and `colcon` later on: + +```bash +export PATH=$PATH:$HOME/.local/bin/ +``` + +## vcstool and colcon from apt + +An alternative method is to use the `.deb` packages available on Debian or Ubuntu: + +```bash +sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list' +sudo -E apt-key adv --keyserver hkp://ha.pool.sks-keyservers.net:80 --recv-key C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654 +sudo apt-get update +sudo apt-get install python3-vcstool python3-colcon-common-extensions +``` + +## Git + +Ignition libraries use `git` for version control, so it must be available +in the system for `vcstool` to work properly. + +```bash +sudo apt-get install git +``` + +## Getting the sources + +The instructions below use some UNIX commands to manage directories but the +equivalent alternatives on Windows should provide the same result. + +The first step is to create a developer workspace in which `vcstool` and +`colcon` can work: + +```bash +mkdir -p ~/workspace/src +cd ~/workspace/src +``` + +All the sources of ignition-fortress are declared in a yaml file. Download +it to the workspace: + +```bash +wget https://raw.githubusercontent.com/ignition-tooling/gazebodistro/master/collection-fortress.yaml +``` + +Use `vcstool` to automatically retrieve all the Ignition libraries sources from +their repositories: + +```bash +vcs import < collection-fortress.yaml +``` + +The src subdirectory should contain all the sources ready to be built. + +## Install dependencies + +Before compiling it is necessary to install all the dependencies of the different +packages that compose the Fortress collection. Every platform has a different +method to install software dependencies. + +Add `packages.osrfoundation.org` to the apt sources list: + +```bash +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 +``` + +The command below will install all dependencies in Ubuntu Bionic or Focal: + +```bash +sudo apt -y install \ + $(sort -u $(find . -iname 'packages-'`lsb_release -cs`'.apt' -o -iname 'packages.apt' | grep -v '/\.git/') | sed '/ignition\|sdf/d' | tr '\n' ' ') +``` + +### Install compiler requirements + +The Ignition Libraries require the gcc compiler version 8 or higher. +(Windows requires Visual Studio 2019). + +#### Ubuntu Bionic + +Ubuntu Bionic's default compiler version is not high enough, so the following +steps are needed to upgrade. These are not needed on Ubuntu Focal. + +To install `gcc` version 8 on Ubuntu Bionic: + +```bash +sudo apt-get install g++-8 +``` + +Set `gcc-8` and `g++-8` to be the default compilers. + +```bash +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 +``` + +At this point `gcc` and `g++` should both report version 8. Test this with +the following commands. + +```bash +gcc -v +g++ -v +``` + +## Building the Ignition Libraries + +Once the compiler and all the sources are in place it is time to compile them. +Start the procedure by changing into the workspace and listing the packages +recognized by `colcon`: + +```bash +cd ~/workspace/ +colcon graph +``` + +`colcon graph` should list the Ignition libraries with an +[interdependency diagram](https://colcon.readthedocs.io/en/released/reference/verb/graph.html#example-output). +If that is the case, then you are ready +to build the whole set of libraries: + +```bash +colcon build --merge-install +``` + +To speed up the build process, you could also disable tests by using + +```bash +colcon build --cmake-args -DBUILD_TESTING=OFF --merge-install +``` + +To build a specific package with all its dependent packages: + +```bash +colcon build --merge-install --packages-up-to PACKAGE_NAME +``` + +To build a single package: + +```bash +colcon build --packages-select PACKAGE_NAME +``` + +Visit [colcon documentation](https://colcon.readthedocs.io/en/released/#) to view more `colcon` build and test options. + +If there are no errors, all the binaries should be ready to use. + +## Using the workspace + +The workspace needs to be sourced every time a new terminal is used. + +Run the following command to source the workspace in bash: + +```bash +. ~/workspace/install/setup.bash +``` + +Or in zsh: + +```zsh +. ~/workspace/install/setup.zsh +``` + +This is the end of the source install instructions; head back to the [Getting started](getting_started.html) +page to start using Ignition! + +## Uninstalling source-based install + +A source-based install can be "uninstalled" using several methods, depending on +the results you want: + + 1. If you installed your workspace with `colcon` as instructed above, "uninstalling" + could be just a matter of opening a new terminal and not sourcing the + workspace's `setup.sh`. This way, your environment will behave as though + there is no Ignition install on your system. + + 2. If, in addition to not wanting to use the libraries, you're also trying to + free up space, you can delete the entire workspace directory with: + + ```bash + rm -rf ~/workspace + ``` + + 3. If you want to keep the source code, you can remove the + `install` / `build` / `log` directories as desired, leaving the `src` directory. + +## Troubleshooting + +See [Troubleshooting](troubleshooting) diff --git a/fortress/install_windows.md b/fortress/install_windows.md new file mode 100644 index 000000000..ac5b8a2f7 --- /dev/null +++ b/fortress/install_windows.md @@ -0,0 +1,82 @@ +# Binary Installation on Windows 10 + +Only the following Ignition packages are currently available on `conda-forge`, +the package manager Ignition uses for Windows binary installations: +- `ign-cmake` +- `ign-common` +- `ign-fuel-tools` +- `ign-math` +- `ign-msgs` +- `ign-physics` +- `ign-plugin` +- `ign-rendering` +- `ign-tools` +- `ign-transport` + +The above mentioned Ignition packages are available in Windows 10 using the [conda-forge package manager](https://conda-forge.org/), +and the Ignition feedstock recipes can be found [here](https://github.com/conda-forge?q=libignition&type=&language=). + +The remaining packages currently have an [outstanding ticket](https://github.com/conda-forge/staged-recipes/issues/13551), +and will not be supported until they are added to the `conda-forge` feedstock. + +Additionally, command line tools, the DART physics engine, and some tests are not currently supported in Windows. + +In order to use `conda-forge`, you will need to +1. Install a [Conda package management system](https://docs.conda.io/projects/conda/en/latest/user-guide/install/download.html). + Miniconda suffices. You will likely want to check the box to add `conda` to your `PATH` + during the installation process so that you won't have to do this step manually. + +2. Open a Windows command prompt, being sure to have `conda` added to your + Windows `PATH` system environment variable (you may also need to open + a new command prompt to see any `PATH` changes reflected). + + If you did not add Conda to your `PATH` environment variable + during Conda installation, you may need to navigate to the + location of `condabin` in order to use the `conda` command. + To find `condabin`, search for "Anaconda Prompt" in the + Windows search field near the Windows button, open it, run + `where conda`, and look for a line containing the directory `condabin`. + +3. Create and activate a new Conda environment: + ```bash + conda create -n ign-ws + conda activate ign-ws + ``` +4. Install desired Ignition packages, since all of Ignition isn't currently supported, you will need to choose which package(s) +you want to install based on your application. + ```bash + conda install libignition-<#> --channel conda-forge + ``` + Be sure to replace `` with your desired package name (ie, common, msgs, etc.) + and `<#>` with the release version. If left unspecified, `conda-forge` will install the + most recently stable release packages. Be sure to check the + [high level install instructions](install) for corresponding version numbers. + +**Note** + +You can view all available versions of a specific package with: +```bash +conda search libignition-* --channel conda-forge +``` +and view their dependencies with +```bash +conda search libignition-* --channel conda-forge --info +``` +and install a specific minor version with +```bash +conda install libignition-=.. --channel conda-forge +``` +where `` is the major release number, `` is the minor release number, and ` --channel conda-forge +``` + +## Troubleshooting + +See [Troubleshooting](troubleshooting) diff --git a/fortress/install_windows_src.md b/fortress/install_windows_src.md new file mode 100644 index 000000000..e2b09c165 --- /dev/null +++ b/fortress/install_windows_src.md @@ -0,0 +1,154 @@ +# Source Installation on Windows 10 + +Currently, `ign-launch` is not supported on Windows 10. + +Additionally, command line tools, DART physics engine, and GUI capabilities are +not currently supported in Windows. These functionalities correspond to the currently +building packages `ign-tools`, `ign-physics`, and `ign-gui`, respectively. + +**Note** + +You will still be able to use `TPE` as a physics engine +(see [here](https://ignitionrobotics.org/api/physics/2.2/physicsplugin.html) for more information on `TPE`). + +## Install dependencies + +1. Install a [Conda package management system](https://docs.conda.io/projects/conda/en/latest/user-guide/install/download.html). + Miniconda suffices. You will likely want to check the box to add `conda` to your `PATH` + during the installation process so that you won't have to do this step manually. + +2. Install [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/). + The Community version is free for students, open-source developers, and personal + development. Check "Desktop development with C++" in the Workloads tab, + and uncheck "C++ Cmake Tools." We will install cmake via Conda. + +3. Open a Visual Studio Command Prompt (search for "x64 Native Tools Command Prompt + for VS 2019" in the Windows search field near the Windows button). Optionally, + right-click and pin to the task bar for quick access in the future. + + If you did not add Conda to your `PATH` environment variable during Conda installation, + you may need to navigate to the location of `condabin` in order to use the `conda` command. + To find `condabin`, search for "Anaconda Prompt" in the Windows search field near the + Windows button, open it, run `where conda`, and look for a line containing the directory `condabin`. + +4. Navigate to your `condabin`, if necessary, and then create and activate a Conda environment: + ```bash + conda create -n ign-ws + conda activate ign-ws + ``` + + Once you have activate an environment, a prefix like `(ign-ws)` will be prepended to + your prompt, and you can use the `conda` command outside of the `condabin` directory. + + You can use `conda info --envs` to see all of your environments. + + To remove an environment, use `conda env remove --name `. + +5. Install dependencies: + + ```bash + conda install cmake git vcstool curl pkg-config ^ + colcon-common-extensions eigen freeimage gts ^ + glib dlfcn-win32 ffmpeg ruby tinyxml2 tinyxml ^ + protobuf urdfdom zeromq cppzmq ogre jsoncpp ^ + libzip qt --channel conda-forge + ``` + +6. Navigate to where you would like to build the library, create and enter your workspace directory, + create the `src` directory which will contain the Ignition source code. + ```bash + mkdir ign-ws + cd ign-ws + mkdir src + ``` + +7. Then clone the repositories + ```bash + # CMD + curl -sk https://raw.githubusercontent.com/ignition-tooling/gazebodistro/master/collection-fortress.yaml -o collection-fortress + vcs import src < collection-fortress + + # PowerShell + curl https://raw.githubusercontent.com/ignition-tooling/gazebodistro/master/collection-fortress.yaml -o collection-fortress + vcs import --input collection-fortress src + ``` + +## Building the Ignition Libraries + +Once the compiler and all the sources are in place it is time to compile them. +Start the procedure by navigating to your workspace and listing the packages +recognized by `colcon`: + +```bash +colcon graph +``` + +`colcon graph` should list the Ignition libraries with an +[interdependency diagram](https://colcon.readthedocs.io/en/released/reference/verb/graph.html#example-output). +If that is the case, then you are ready to build the whole set of libraries: + +```bash +colcon build --cmake-args -DBUILD_TESTING=OFF --merge-install --packages-up-to ignition-gazebo5 +``` +Tests are turned off as they are not currently supported on Windows. + +**Note:** All of the Ignition packages up to, but not including `ign-gazebo` +are currently building. The above command should successfully build all packages except for `ign-gazebo`. + +To build a specific package with all its dependent packages: + +```bash +colcon build --merge-install --packages-up-to PACKAGE_NAME +``` + +To build a single package: + +```bash +colcon build --packages-select PACKAGE_NAME +``` + +Visit [colcon documentation](https://colcon.readthedocs.io/en/released/#) to view more `colcon` build and test options. + +If there are no errors, all the binaries should be ready to use. + +## Using the workspace + +The workspace needs to be sourced every time a new terminal is used. + +Run the following command to source the workspace: + +```bash +# CMD +call install\setup.bat + +#PowerShell +.\install\setup.ps1 +``` + +This is the end of the source install instructions; head back to the [Getting started](/docs/all/getstarted) +page to start using Ignition! + +## Uninstalling source-based install + +A source-based install can be "uninstalled" using several methods, depending on +the results you want: + + 1. If you installed your workspace with `colcon` as instructed above, "uninstalling" + could be just a matter of opening a new terminal and not sourcing the + workspace's `setup.bat`. This way, your environment will behave as though + there is no Ignition install on your system. + + 2. If, in addition to not wanting to use the libraries, you're also trying to + free up space, you can delete the entire workspace directory from within + your `conda` environment with: + + ```bash + rm -rf + ``` + + 3. If you want to keep the source code, you can remove the + `install` / `build` / `log` directories as desired, leaving the `src` directory. + +## Troubleshooting + +See [Troubleshooting](troubleshooting) diff --git a/index.yaml b/index.yaml index 7ef40b7a2..9e99e2ba1 100644 --- a/index.yaml +++ b/index.yaml @@ -40,6 +40,10 @@ pages: file: architecture.md description: Ignition Gazebo's architecture overview. releases: + - name: fortress + lts: true + eol: false + description: Upcoming release, under development. - name: edifice lts: false eol: false diff --git a/releases.md b/releases.md index 8d08dae07..2d38b3741 100644 --- a/releases.md +++ b/releases.md @@ -19,6 +19,6 @@ An Ignition release follows the form "Ignition Codename", for example Ignition A | Citadel | Dec, 2019 | Dec, 2024 | LTS | | Dome | Sep, 2020 | Dec, 2021 | | | Edifice | Mar, 2021 | Mar, 2022 | | -| Ignition-F | Sep, 2021 | Sep, 2026 | LTS | +| Fortress | Sep, 2021 | Sep, 2026 | LTS | | Ignition-G | Sep, 2022 | Sep, 2024 | | | Ignition-H | Sep, 2023 | Sep, 2028 | LTS | diff --git a/tools/branch_comparisons.md b/tools/branch_comparisons.md index 6a1ded1c3..c4dfe1ec9 100644 --- a/tools/branch_comparisons.md +++ b/tools/branch_comparisons.md @@ -15,7 +15,7 @@ See the instructions on the * **C**: Citadel * **D**: Dome -* **D**: Edifice +* **E**: Edifice * **main**: main branch Library | C ➡️ D | D ➡️ E | E ➡️ main