Environment config tutorial

[maryaB-osr]

The goal here (and for all the tutorials) is to utilize tabs to switch between linux/osx/windows commands. I'm still trying to find a sphinx tabs extension that works.

In the mean time, it'd be good to know what the equivalent commands are in osx and windows for the commands on lines 40, 52, and 64.

Another question I have is about switching distros on osx and windows. The tutorial mentions that one of the benefits of sourcing setup files is how easy it makes it to switch between distros. However, just looking at the installation guides for osx and windows, the sourcing commands don't mention the distro.

linux: source /opt/ros/<distro>/setup.bash

osx: . ~/ros2_install/ros2-osx/setup.bash

windows: > call C:\dev\ros2\local_setup.bat

Also wondering if the advice on line 74 (to retry the installation guide if your environment variables aren't set) makes sense.

And any other general feedback is appreciated.

Signed-off-by: maryaB-osr marya@openrobotics.org

[clalancette]

Another question I have is about switching distros on osx and windows. The tutorial mentions that one of the benefits of sourcing setup files is how easy it makes it to switch between distros. However, just looking at the installation guides for osx and windows, the sourcing commands don't mention the distro.

The reason that this doesn't really show up on Windows on macOS is because neither our packaging nor our from-source instructions embed the distribution name. We should probably update those instructions to do something like:

macOS:

Extract to ~/ros2_dashing/ros2-osx

Windows:

Extract to C:\dev\ros2_dashing

One general comment I have: is it at all possible to get a preview of what these will look like "live"? It would just make reviewing them easier. Thanks.

I'll do a review of the actual changes as best I can without it.

[clalancette]

I've left a bunch of comments about the actual content.

[clalancette]

This should be:

ROS 2 relies on the notion of combining workspaces using the shell environment.

Though it occurs to me that we don't define what a workspace is in this tutorial. Do we define that elsewhere? If so, we should link to it. If not, we should add a definition here.

[maryaB-osr]

I think I asked you about the interchangeability of "workspace" and "environment" and it was unclear. So how would you define "workspace" in the context of this tutorial where we're using the word "environment"?

[clalancette]

OK, so the thing is that they are somewhat intertwined.

Generally, "environment" refers to how your shell is setup. When you first start up the shell (assuming no customizations), you'll have just a few environment variables setup: PATH for finding executables, SHELL defining what shell you are using, etc.

A "workspace" is a ROS term for where you are doing development. /opt/ros/dashing is a workspace (though a special one) that defines the core of ROS 2; we generally refer to this as an "underlay" workspace, since you layer things on top of it. When developing for a robot, you'll also typically have a local workspace (say in ~/robot_ws) that has the robot-specific code you are working on. This is generally referred to as an "overlay" workspace.

Where the environment and the workspace overlap is when you source /opt/ros/dashing/setup.bash and ~/robot_ws/install/local_setup.bash. When you do that, the workspaces will change your environment so that things that they provide can be found. They'll modify your PATH to find executables, modify LD_LIBRARY_PATH to find libraries, modify PYTHONPATH to find python modules, etc.

Let me know if this explanation makes more sense to you, or if you need further clarification here.

[mjcarroll]

Note, I cherry-picked #336 to here, just to verify Heroku behavior.

[maryaB-osr]

I was trying to apply this tutorial to everyone (all platforms) but I'm just going to go with the route @jacobperron suggested and assume Linux + installed from debians. So that means we don't need all the macOS and Windows commands as well.

[jacobperron]

Something that might be worth mentioning in this tutorial is the significance of the variable ROS_DOMAIN_ID.
It is important to set in order to avoid interference between multiple hosts on the same network.
You can read a bit about it in this obscure section of our documentation: https://index.ros.org/doc/ros2/Contributing/ROS-2-On-boarding-Guide/#choose-a-dds-domain-id

[clalancette]

I've added some more context for you.

Honestly, I preferred your previous plan of making tabs for Linux, macOS, and Windows. Just removing the latter two seems like a step backwards to me, as it is our intention to support all of those, and I think the tutorials should follow.

[clalancette]

OK, so the thing is that they are somewhat intertwined.

Generally, "environment" refers to how your shell is setup. When you first start up the shell (assuming no customizations), you'll have just a few environment variables setup: PATH for finding executables, SHELL defining what shell you are using, etc.

A "workspace" is a ROS term for where you are doing development. /opt/ros/dashing is a workspace (though a special one) that defines the core of ROS 2; we generally refer to this as an "underlay" workspace, since you layer things on top of it. When developing for a robot, you'll also typically have a local workspace (say in ~/robot_ws) that has the robot-specific code you are working on. This is generally referred to as an "overlay" workspace.

Where the environment and the workspace overlap is when you source /opt/ros/dashing/setup.bash and ~/robot_ws/install/local_setup.bash. When you do that, the workspaces will change your environment so that things that they provide can be found. They'll modify your PATH to find executables, modify LD_LIBRARY_PATH to find libraries, modify PYTHONPATH to find python modules, etc.

Let me know if this explanation makes more sense to you, or if you need further clarification here.

[clalancette]

Something that might be worth mentioning in this tutorial is the significance of the variable ROS_DOMAIN_ID.
It is important to set in order to avoid interference between multiple hosts on the same network.
You can read a bit about it in this obscure section of our documentation: https://index.ros.org/doc/ros2/Contributing/ROS-2-On-boarding-Guide/#choose-a-dds-domain-id

Oh yeah, this is a good idea. I think this should be added.

[maryaB-osr]

ROS_DOMAIN_ID.

Is it necessary to use ROS 2? It seems a little advanced. I will add it, but can I put (advanced) in the heading?

[maryaB-osr]

Honestly, I preferred your previous plan of making tabs for Linux, macOS, and Windows.

I agree that it's not the best idea, and I revoke it, but I think it's a big problem that some of the Windows solutions are basically just "google it". I can try to come up with a way to make it more tactful though. I was also worried about having more and more shortcomings like that pop up throughout the rest of the tutorials.

[clalancette]

I agree that it's not the best idea, and I revoke it, but I think it's a big problem that some of the Windows solutions are basically just "google it".

I totally agree that we shouldn't put "google it" into the tutorials. My previous comments to this effect were more along the lines of "somebody needs to do more research here to figure out what the correct solution is". And I think we should do that research before releasing the tutorial.

[jacobperron]

Is it necessary to use ROS 2? It seems a little advanced. I will add it, but can I put (advanced) in the heading?

It's necessary if you are on a network with multiple people using ROS 2, otherwise your turtle in turtlesim might move around unexpectedly if someone else is doing the tutorials at the same time as you :D

I think it's worth suggestion something like, "if your lab or office has multiple computers running ROS 2, you should coordinate with your colleagues in selecting different domain IDs".

[maryaB-osr]

The reason that this doesn't really show up on Windows on macOS is because neither our packaging nor our from-source instructions embed the distribution name. We should probably update those instructions to do something like:

@clalancette which repo would be a good place to make an issue about this?

[clalancette]

@clalancette which repo would be a good place to make an issue about this?

The from-source instructions would be in this repository, in https://github.com/ros2/ros2_documentation/blob/master/source/Installation/Dashing/ (and the other versions).

The packaging one is trickier. It may also be the case that we just fix this with documentation in this repository. For instance, in https://index.ros.org/doc/ros2/Installation/Dashing/Windows-Install-Binary/#downloading-ros-2 where we say "Unpack the zip file", it might be better to assume C:\dev\ros2-dashing to be more specific. The same goes for all of the instructions for binary archives.

[maryaB-osr]

@clalancette @jacobperron
I addressed your comments but I'm not sure if I worded things correctly, would appreciate another review :)

[jacobperron]

Looking good!

I have a few more suggestions.

[jacobperron]

Rather than linking to that on-boarding guide (which has some references intended for people working at OSRF and should probably be relocated) I think it's better to provide an explanation/how-to in this section.

Suggested change

	You can find out how to do that `here <https://index.ros.org/doc/ros2/Contributing/ROS-2-On-boarding-Guide/#choose-a-dds-domain-id>`__.
	The domain ID is used to segment the network in order to avoid interference between ROS 2 programs.
	Once you have determined a unique integer for yourself, you can set the environment variable with the following command:

Linux/macOS:

export ROS_DOMAIN_ID=<your_domain_id>

Windows:

set ROS_DOMAIN_ID <your_domain_id>

To have the setting persist between shell sessions, you can add the above command to your shell startup script (Linux/macOS). For Windows, I think you can use setx (untested):

setx ROS_DOMAIN_ID <your_domain_id>

[clalancette]

Yeah, agreed, I like the addition of this section.

[maryaB-osr]

Thanks Jacob! For now I'm going to leave a todo under this section to test it on Windows. Unfortunately don't have time for that atm, but testing will happen once all tutorials are done.

(unless that's horrible practice and there's any objections...?)

[jacobperron]

I think you can remove the TODO, since we should go through and test the tutorials anyways before the next release. If something is wrong, someone will raise an issue or PR 🤞

[clalancette]

I love the tabbed interface for Linux, macOS, and Windows. Overall, this is looking really good. I have one minor comment to fix, and after that and @jacobperron 's comment about ROS_DOMAIN_ID is fixed, I'm happy to approve.

[clalancette]

Yeah, agreed, I like the addition of this section.

[clalancette]

One more thing to fix :).

[clalancette]

This should be:

setx ROS_DOMAIN_ID <your_domain_id>

[clalancette]

This block should be removed now, since it is up in the tabbed interface.

[maryaB-osr]

Would it make sense to add under line 171: "The Windows command does this automatically" ?

[clalancette]

Oh, I see. I misread this section.

Actually, I think it would be better to put all of this language underneath the individual tabs. That way we don't have this floating section outside of the tabbed interface. Does that make sense?

[maryaB-osr]

Yup, that was my initial thought too. No reason for the tabs to only include code!