============
Installation
============

ROS2 installation
=================

This script does the main installation of ROS2 Foxy Fitzroy.
For more details, see `the official installation doc <https://docs.ros.org/en/foxy/Installation/Linux-Install-Binary.html>`_.

.. code-block:: bash

   # set up sources
   sudo apt update && sudo apt install curl gnupg2 lsb-release
   curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -
   sudo sh -c 'echo "deb [arch=$(dpkg --print-architecture)] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" > /etc/apt/sources.list.d/ros2-latest.list'

   # install ros package
   sudo apt update
   sudo apt install ros-foxy-desktop
   sudo apt install ros-foxy-ros-base

   # source the environment
   source /opt/ros/foxy/setup.zsh
   echo "source /opt/ros/foxy/setup.zsh" >> ~/.zshrc

   # autocompletion tool
   sudo apt install -y python3-pip
   pip3 install -U argcomplete

   # install rosdep
   sudo apt install -y python3-rosdep
   sudo rosdep init
   rosdep update

   # install colcon
   sudo apt install python3-colcon-common-extensions

   # tests : run in two consoles
   ros2 run demo_nodes_cpp talker
   ros2 run demo_nodes_cpp listener

ROS2 workspace
==============

This section describes how to create the workspace where your code will be.
For more details, see `the official doc <https://docs.ros.org/en/foxy/Tutorials/Workspace/Creating-A-Workspace.html>`_.

1. source ROS2 environment (if not already done when the terminal is launched).
#. create the workspace and source folders :

   .. code-block:: bash

      mkdir -p ~/ros_workspace/src
      cd ~/ros_workspace/src

#. clone a tutorial repo :

   .. code-block:: bash

      git clone https://github.com/ros/ros_tutorials.git -b foxy-devel

#. make sure all dependencies are fine (make sure to run it from the workspace folder) :

   .. code-block:: bash

      cd ~/ros_workspace
      rosdep install -i --from-path src --rosdistro foxy -y

#. build the repo (make sure to run it from the workspace folder)

   .. code-block:: bash

      colcon run

ROS2 : building and navigating from underlay to overlay
=======================================================

While I still haven't figured everything out of this concept (I'll come back to that later...),
here is a procedure to follow and you won't have too much problem with that concept.
But if you start to do it on your own, especially using the same terminal for building and running, well,
I'll just say this sentence from one of my teacher :

> *tu vas te faire manger comme le diable...*

So here are some tricks :

1. sourcing the underlay means sourcing the ``source opt/ros/foxy/setup.zsh``
#. sourcing the overlay means ``. install/local_setup.zsh``

Editing and building existing packages
--------------------------------------

Usually, try to have these two tabs when it comes to editing and building an existing package :

1. *build* tab : only the underlay is sourced, currently in ``~/ros_workspace``, make use only of building commands, such as ``colcon build``
2. *run* tab : both the underlay and overlay are sourced, currently wherever you want, make use of run commands, such as ``ros2 run <my_package> <my_node>``

.. warning::

   DO NEVER run a build command from the *run* tab, or a run command from the *build* tab.

   Trust me, I tried, and this did not work. I had to delete my whole workspace and start a new one from scratch...
   So unless you totally master this underlay - overlay thing, just don't ;-)

For more details, see `the official doc for creating the workspace and building a node <https://docs.ros.org/en/foxy/Tutorials/Workspace/Creating-A-Workspace.html>`_.

Creating a new package
----------------------

You can do that from the *build* tab.

1. Create the package with ``ros2 pkg create --build-type ament_cmake --node-name my_node my_package``.
#. Build it from the *build* tab
#. Open a new tab, source the underlay as usual, but this time source the overlay like this : ``. install/setup.zsh``
#. Run your node from the new tab.

For more details, see `the official doc for creating a new package <https://docs.ros.org/en/foxy/Tutorials/Creating-Your-First-ROS2-Package.html>`_.

:tag:`ROS2`
:tag:`Installation`