diff --git a/citadel/install.md b/citadel/install.md index ad2ed9685..d1572a239 100644 --- a/citadel/install.md +++ b/citadel/install.md @@ -7,26 +7,28 @@ Citadel supports the following platforms: * 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 but not including `ign-gazebo` are currently building. + * DART physics engine is not yet supported. + * Qt (GUI functionality) is not yet supported. -Windows support is still experimental although most of the packages should work -as expected. There are no binaries for Windows at this time. The `ign-gazebo` -package is still not available for Windows; the installation should be done from -source code. The [Source Installation on Ubuntu](install_ubuntu_src) -contains some tips for Windows. ## Binary installation instructions Binary installation is the recommended method of installing Ignition. - * [Binary Installation on Ubuntu](install_ubuntu) - * [Binary Installation on MacOS Mojave (10.14)](install_osx) + * [Binary Installation on Ubuntu](install_ubuntu.md) + * [Binary Installation on MacOS Mojave (10.14)](install_osx.md) + * [Binary Installation on Windows 10](install_windows.md) ## 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 Ubuntu](install_ubuntu_src.md) + * [Source Installation on MacOS](install_osx_src.md) + * [Source Installation on Windows 10](install_windows_src.md) ## Citadel Libraries diff --git a/citadel/install_ubuntu_src.md b/citadel/install_ubuntu_src.md index 92e991cb9..05e824d75 100644 --- a/citadel/install_ubuntu_src.md +++ b/citadel/install_ubuntu_src.md @@ -54,9 +54,6 @@ 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: @@ -172,7 +169,6 @@ sudo apt-get install -y \ ### Install compiler requirements The Ignition Libraries require the gcc compiler version 8 or higher. -(Windows requires Visual Studio 2019). #### Ubuntu Bionic diff --git a/citadel/install_windows.md b/citadel/install_windows.md new file mode 100644 index 000000000..4c1e25e3e --- /dev/null +++ b/citadel/install_windows.md @@ -0,0 +1,81 @@ +# 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-common` +- `ign-msgs` +- `ign-math` +- `ign-cmake` +- `ign-fuel-tools` +- `ign-transport` +- `ign-tools` +- `ign-physics` +- `ign-plugin` + +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 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/citadel/install_windows_src.md b/citadel/install_windows_src.md new file mode 100644 index 000000000..3f4de6f28 --- /dev/null +++ b/citadel/install_windows_src.md @@ -0,0 +1,166 @@ +# Source Installation on Windows 10 + +Currently, `ign-gazebo` and `ign-launch` are 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, and then clone the repositories. + ```bash + mkdir ign-ws + cd ign-ws + curl -O https://raw.githubusercontent.com/ignition-tooling/gazebodistro/master/collection-citadel.yaml + mkdir src + vcs import src < collection-citadel.yaml + ``` + +7. Install `ign-cmake` from `conda-forge` and disable the cloned `ign-cmake` from being built. + ```bash + conda install libignition-cmake2 --channel conda-forge + touch src\ign-cmake\COLCON_IGNORE + ``` + + This is due to a linking error currently existing within the `ign-cmake` source. + See the comments [here](https://github.com/ignitionrobotics/docs/issues/96#issuecomment-742096017). + +**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 ` + ``` + + 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)