Workspace setup
===============

Similar to how ROS2 files are installed in :code:`/opt/ros/{ROS_DISTRO}` so that you can have several distributions installed simultaneously, you can also have many separate workspaces in your system.

In addition, because files in the :code:`/opt` folder require superuser privileges (for good reasons), having a user-wide workspace is the accepted practice. They call this an **overlay**.

Setting up
----------

In ROS2, a workspace is nothing more than a folder in which all your packages are contained.

No, really, you just need to make a folder, e.g. the one we will use throughout these tutorials.

.. code :: console

   cd ~
   mkdir -p ros2_tutorial_workspace/src
   
It is common practice to have all source files inside the :code:`src` folder, so we will also do so for these tutorials. Nonetheless, it is not a strict requirement.
   
First build
-----------

Regardless of it being a currently empty project, we run :program:`colcon` once to set up the environment and illustrate a few things.
The program :program:`colcon` is the build system of ROS2 and will be described in more detail later.

For now, run

.. code :: console

   cd ~/ros2_tutorial_workspace
   colcon build
   
for which the output will be something similar to

.. code :: console

   Summary: 0 packages finished [0.17s]
   
given that we have an empty workspace, no surprise here.

The folders :code:`build`, :code:`install`, and :code:`log` have been generated automatically by :program:`colcon`. The project structure becomes as follows.

.. code-block:: console
   :emphasize-lines: 3,4,5
   
   ros2_tutorial_workspace/
     └── src/
     └── build/
     └── install/
     └── log/
    
Inside the :code:`install` folder lie all programs etc generated by the project that can be accessed by the users.     

Do the following just once, so that all terminal windows automatically source this new workspace for you.

.. code :: console

   echo "# Source the ROS2 overlay, as instructed in https://ros2-tutorial.readthedocs.io" >> ~/.bashrc
   echo "source ~/ros2_tutorial_workspace/install/setup.bash" >> ~/.bashrc
   source ~/.bashrc
   
However, since our workspace is currently empty, there's not much we can do with it. Let's add some content.