Windows top level build instructions (#126)

Signed-off-by: John Shepherd <[email protected]>

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
 

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
 

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-<package_name><#> --channel conda-forge
+  ```
+  Be sure to replace `<package_name>` 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-<package_name>* --channel conda-forge
+```
+and view their dependencies with
+```bash
+conda search libignition-<package_name>* --channel conda-forge --info
+```
+and install a specific minor version with
+```bash
+conda install libignition-<package_name>=<major>.<minor>.<patch> --channel conda-forge
+```
+where `<major>` is the major release number, `<minor>` is the minor release number, and `<patch` is the patch release number.
+
+## 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
+conda uninstall libignition-<package_name> --channel conda-forge
+```
+
+## Troubleshooting
+
+See [Troubleshooting](troubleshooting)

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 <env_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-<package_name>* --channel conda-forge
+```
+and view their dependencies with
+```bash
+conda search libignition-<package_name>* --channel conda-forge --info
+```
+and install a specific minor version with
+```bash
+conda install libignition-<package_name>=<major>.<minor>.<patch> --channel conda-forge
+```
+where `<major>` is the major release number, `<minor>` is the minor release number, and `<patch` is the patch release number.
+
+## 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-gazebo3
+```
+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
+call install\setup.bat
+```
+
+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 <workspace_name>
+     ```
+
+  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)