Update install instructions to include distro name

[maryaB-osr]

The ROS 1 environment configuration tutorial implies that switching between distros is as easy as switching out the <distro> in the source command on linux:

$ source /opt/ros/<distro>/setup.bash

Since we're trying to target macOS and Windows as well now, I was hoping we could change the instructions for macOS and Windows binary packages installation guides to include the distro name. That way, the enviroment config tutorial can say "You can switch distros by replacing <distro> in the path name..." without having to differentiate between Linux, macOS and Windows.

I'm not sure if this means just changing the instructions in the docs or actually changing something about the binary packaging for those OSs.

For more context:

Originally posted by @clalancette in #334 (comment)

Originally posted by @clalancette in #334 (comment)

[jacobperron]

I'm not sure if this means just changing the instructions in the docs or actually changing something about the binary packaging for those OSs.

I think we'd have to update the packaging jobs for macOS and Windows, so that when the downloaded archive is extracted the distro name is present in the directory name.

I'm not sure what's involved in making this change.

[tfoote]

If it's just adding the directory at the top level that is likely resolvable without changing the contents of the packaging job, just the commands to unpack the tarballs. You can use the --strip 1 option to remove the top level directory when unpacking and point it to the distro prefixed location.

[clalancette]

If it's just adding the directory at the top level that is likely resolvable without changing the contents of the packaging job, just the commands to unpack the tarballs. You can use the --strip 1 option to remove the top level directory when unpacking and point it to the distro prefixed location.

Changing the packaging jobs is somewhat difficult, because after every release we'll need to remember to update them. I think @tfoote 's suggestion about stripping them in the instructions is a good one.

[dirk-thomas]

The workspace knows its distro name already. You could simply source the workspace and use $ROS_DISTRO. That way the produced archive name can also be set to what we want it to be (rather then requiring to rename it every time when uploading it to the releases page).

[maryaB-osr]

I need some clarification here - what's the entire exact command that would change with the --strip 1 option? Also I don't see any actual command to unpack in the Windows instructions, it just says

Unpack the zip file somewhere

Which sounds like they'd be doing it using the UI?

The workspace knows its distro name already. You could simply source the workspace and use $ROS_DISTRO. That way the produced archive name can also be set to what we want it to be (rather then requiring to rename it every time when uploading it to the releases page).

@dirk-thomas What's the syntax for using $ROS_DISTRO here? Is this in addition to @tfoote 's suggestion or another option?

[dirk-thomas]

ROS_DISTRO is an environment variable being set when sourcing a workspace. It can be used in a shell with $ROS_DISTRO.

While Tully's suggestion works around the wrong naming my proposal is to actually fix the naming of the archive. That will not only make that workaround obsolete but also ensures if users download the archive from Jenkins know what is in the archive based on the name (as well as us when publishing the packages for a sync not having to rename the files).

[wjwwood]

@maryaB-osr I'm going to assign you since you opened a pull request to address this, but it's just for bookkeeping.

I also opened a separate enhancement issue here: ros2/ci#350

[maryaB-osr]

@wjwwood Got it, thanks