What is the difference between local_setup.bash and setup.bash

Question

In ROS2, we always source the local_setup.bash while working with the original parent workspace. Now lets say if i create an overlay workspace and create my own package, then while trying to build it, shall i source the local_setup.bash or the setup.bash.

My observation : if i start a new terminal and try these commands :

cd ~/ros2_overlay_ws/
source install/ local_setup.bash
ament build

This gives me an error stating ament: command not found

But if i source the setup.bash file instead, the build is successfull. wehereas i thought local_setup.bash file is used for sourcing the current variables to the current path. So it sould have built with the local_setup.bash Could anyone please clear out the differences ?

---

Originally posted by aks on ROS Answers with karma: 667 on 2018-05-29

Post score: 7

Answer 1

To answer the actual question first:

• The local_setup.<ext> script sets up the environment for all package in the prefix path where that script is. It doesn't include any parent workspaces.
• The setup.<ext> script on the other hand sources the local_setup.<ext> script for all workspaces which were sourced in the environment when this workspace was built. And then it also sources the sibling local_setup.<ext> script.

What does that mean:

• If you want to source the first workspace (e.g. /opt/ros/ardent) it doesn't make any difference because that workspace doesn't have any parent workspaces.

• If you have built your own workspace ~/ws after sourcing /opt/ros/ardent you can do either of the following:

  • Source ~/ws/install/setup.<ext> to setup the environment to include paths from /opt/ros/ardent as well as ~/ws/install.

  • That is the same as if you would source /opt/ros/ardent/(local_)setup.<ext> first and then ~/ws/install/local_setup.<ext>.

---

Originally posted by Dirk Thomas with karma: 16276 on 2018-05-29

This answer was ACCEPTED on the original site

Post score: 11

---

Original comments

Comment by fredBeauj on 2021-06-02:
In case someone needs it: essentially the same info from the colcon documentation

Answer 2

You should source setup.bash of the original (underlay) workspace before building the overlay workspace. Once you have built the overlay workspace, you should be able to source setup.bash, which will chain the underlay and the overlay together.

From the ament documentation:

The different shell scripts in the root of the install space are generated by the ament tool. The local_setup.* files only iterate over all packages in the install space (by reading the list of packages in the ament index) and source their package specific setup files. The setup.* files also consider workspaces outside of this install space (by reading the list of parent_prefixp_path in the ament index) and source them before the local_setup.* files.

---

Originally posted by mjcarroll with karma: 6414 on 2018-05-29

This answer was NOT ACCEPTED on the original site

Post score: 2

---

Original comments

Comment by aks on 2018-05-29:
Once you have built the overlay workspace, you should be able to source setup.bash, which will chain the underlay and the overlay together.

Did you mistype it here, i would be able to source local_setup.bash after building the overlay space ?

Comment by mjcarroll on 2018-05-29:
If you source local_setup.bash of the overlay, it will only consider the packages available in the overlay when adding to the environment. setup.bash will source the underlay and then the overlay, giving you an environment with both workspaces in it.

Comment by aks on 2018-05-29:
@mjccarroll yes exactly this is what i meant. But in this case why should i use setup.bash to source my overlay space ? this should be possible with local_setup.bash

Comment by mjcarroll on 2018-05-29:
local_setup.sh exclusively sources the overlay, you will not have any other packages visible from the other workspace. My understanding is that this is not your desired behavior?

Comment by aks on 2018-05-29:
yes,in my case it is the other way round happening which is a bit confusing.

Comment by felixf4xu on 2023-07-17:
@mjccarroll I'm confused by your wording of "overlay" and "underlay".