Windows installation instructions per library

[chapulina]

Related to #96.

Lots of our libraries already build and run on Windows, but we don't have tutorials on how to do that yet.

Each library has their own install tutorial, and we should add this information there. Note that this is different from the top-level tutorials install tutorials that live in this repository (that's covered by #96).

These are the tutorials to be updated:

• ign-math
• ign-common - also move Linux install tutorial from README
• ign-gazebo - also move Linux install tutorial from README
• ign-fuel-tools - already has Windows instructions, must verify they're working
• ign-gui
• ign-launch - also move Linux install tutorial from README
• ign-msgs - also move Linux install tutorial from README
• ign-physics
• ign-plugin
• ign-rendering
• ign-sensors
• ign-transport - already has Windows instructions, must verify they're working
• sdformat

[JShep1]

For the record, we have internal docs up to ign-gazebo for building with vcpkg, but are now investigating conda-forge as it has ruby support and my initial impressions are that it is far easier and quicker to get to a point where you can begin compiling. Currently, there seems to be some issues with gts finding glib.h on Windows (#96 (comment)), but I believe it may be more worth sorting these issues out to move forward with conda-forge as the default Ignition Windows package manager (and possibly blazing a trail to eventually sync ROS2 so users can have the most streamlined build process).

It's safe to say this issue is blocked on the gts/glib issue for now, ignition-cmake and ignition-math (for both vcpkg and conda-forge) are complete and documented internally. But with regards to going forward with conda-forge, ign-common is where that issues arises. As stated here, I'm going to try to find a quick local workaround to unblock forward progress with this documentation then work on the more long term solution.

[traversaro]

As stated here, I'm going to try to find a quick local workaround to unblock forward progress with this documentation then work on the more long term solution.

I do not know if I a missing something, but I think that opening a PR again the ignition-cmake repo containing the patch in https://github.com/conda-forge/libignition-cmake0-feedstock/blob/master/recipe/FindGTS.cmake.patch is a perfectly fine solution, and in general a correct bug fix for any system in which pkg-config is not available. The fact that gts is currently lacking .pc files on conda-forge is another issue that may deserved to be fixed (as mentioned in #96 (comment)), but it can be done even after https://github.com/conda-forge/libignition-cmake0-feedstock/blob/master/recipe/FindGTS.cmake.patch as been applied upstream in ignition-cmake .

[mabelzhang]

Regarding the list of tutorials, ign-cmake doesn't have such a page (because it's unreleased?), but ign-math depends on ign-cmake, right? Should we put the ign-cmake Windows instructions in https://github.com/ignitionrobotics/ign-cmake/blob/ign-cmake2/README.md ? Then ign-math's doesn't need to talk about ign-cmake.

[chapulina]

Regarding the list of tutorials, ign-cmake doesn't have such a page

Ah nice catch, this is part of #53

Should we put the ign-cmake Windows instructions in https://github.com/ignitionrobotics/ign-cmake/blob/ign-cmake2/README.md ?

Yeah let's put it in the README for now

[chapulina]

let's put it in the README for now

Actually I went ahead and added tutorial generation for ign-cmake, so you could target that if you want: gazebosim/gz-cmake#137

[mabelzhang]

Thanks! I targeted that page for ign-cmake.

Should we duplicate the installation instructions to all the READMEs? That might get more visibility since that shows up on https://ignitionrobotics.org/libs/ . I can copy the text from the tutorials over to the READMEs for all the PRs once the texts are reviewed.

ign-common also doesn't seem to have an installation tutorial, but does have a README, so we'd be duplicating the Ubuntu stuff from the README to a new installation tutorial.

[chapulina]

Should we duplicate the installation instructions to all the READMEs?

We did a good push deduplicating the install instructions on #14, but as you pointed out, we missed some libraries. I reopened it with a list of the libraries that are left. Maybe some of those can be tackled as the Windows tutorials are added?

[mabelzhang]

Nice. Yeah I can do that while I'm at it.

[mabelzhang]

I've opened PRs for everything other than ign-gazebo and ign-launch, as referenced in the list above.
The two extra PRs not in the original list are for ign-cmake and ign-tools (that's why both lists have 13 items).

In order to have binary install instructions for everything, we need to add libignition-rendering, libignition-sensors, libignition-gui to conda-forge. These already compile on Windows.
Then libignition-gazebo and libignition-launch, once we can compile them on Windows.

List of ignition libraries currently on conda-forge: https://github.com/conda-forge?q=libignition&type=&language=
(Except for sdformat, which is libsdformat. Not sdf which apparently is the Scientific Data Format.)

While I was at it, I tried to make the tutorials somewhat uniform, but there were a few that looked very minimalist that I didn't flesh out - ign-tools, ign-msgs, sdformat. They don't have prerequisites and binary install sections like others even for Ubuntu. It'd take more effort to write those.

Should I target the release branch or main? I targeted release branch for all except ign-plugin - because its tutorial and README consolidation hasn't been backported to the release branch. Hopefully that was correct, otherwise it's just documentation and should be easy to retarget to main.

[mabelzhang]

Looks like the missing libraries are being tracked here conda-forge/staged-recipes#13551

[chapulina]

Awesome, thanks @mabelzhang !

Should I target the release branch or main?

The Citadel branches would be ideal wherever possible, because that's the LTS. But don't worry if you've been targeting Dome, we can backport as needed.

[mabelzhang]

I checked all the available versions on conda-forge (conda search libignition-<lib><#> -c conda-forge). All the packages with feedstock have both Citadel and Dome versions.

So I can retarget all the libraries with Conda feedstock to Citadel, and leave the ones without feedstock (ign-rendering, ign-sensors, ign-gui) targeted to Dome? Double-checking if that's what we want.

This would be the result:

• ign-cmake2 (same for C & D)
• ign-math6 (same for C & D)
• ign-common3 (same for C & D)
• ign-tools1 (C)
• ign-msgs5 (C)
• sdformat9 (C)
• ign-transport8 (C)
• ign-plugin1 (same for C & D; also backport Removed repeated installation instructions gz-plugin#27 from main)
• ign-physics2 (C)
  ign-rendering4 (D)
• ign-fuel-tools4 (C)
  ign-sensors4 (D)
  ign-gui4 (D)

[chapulina]

So I can retarget all the libraries with Conda feedstock to Citadel, and leave the ones without feedstock (ign-rendering, ign-sensors, ign-gui) targeted to Dome?

I think it would be nice to target them all at Citadel, and then we can forward-port everything to Dome where needed. That should lay the groundwork for the top-level tutorial (#126) to target Citadel.

[mabelzhang]

Okay cool will retarget all to Citadel then. These three in the list above will be modified to

• ign-rendering3 (C)
• ign-sensors3 (C)
• ign-gui3 (C)

[chapulina]

Deployed tutorials:

• https://ignitionrobotics.org/api/math/6.8/install.html
• https://ignitionrobotics.org/api/plugin/1.1/installation.html
• https://ignitionrobotics.org/api/msgs/5.6/install.html
• https://ignitionrobotics.org/api/transport/8.2/installation.html
• https://ignitionrobotics.org/api/rendering/3.2/installation.html
• https://ignitionrobotics.org/api/sensors/3.1/installation.html
• https://ignitionrobotics.org/api/gui/3.4/install.html
• https://ignitionrobotics.org/api/physics/2.3/installation.html

More:

• https://ignitionrobotics.org/api/common/3.10/install.html
• https://ignitionrobotics.org/api/fuel_tools/4.3/install.html
• https://github.com/osrf/sdformat/tree/sdf9#windows

We're just missing ign-gazebo and ign-launch, which are pending gazebosim/gz-sim#168 and gazebosim/gz-launch#89