Repository
==========

After successfully installing **kitcar-gazebo-simulation** and checking out your own branch,
you are now confronted with our repository.
Before going into any details, we will now take a step back and look at the repository's structure.

Root
----

When opening the repository in a file browser you will see the following files and directories:

.. Create the repository tree.
.. program-output::
   cd $KITCAR_REPO_PATH/kitcar-gazebo-simulation/ && tree -I __pycache__ -L 1 --dirsfirst .
   :shell:

Docs
----

The ``docs/`` directory contains our documentation.
We use `Sphinx <https://www.sphinx-doc.org/en/master/>`_ \
and `better-apidoc <https://github.com/goerz/better-apidoc>`_ \
to easily create a nice documentation.

.. tip::

   The Onboarding is also part of our documentation. You can be find the source code \
   of this page at ``docs/content/onboarding/repository.rst``.


Init
----

The ``init/`` directory contains files and scripts to install \
and setup this repository.
You've already used the ``init/init.sh`` when following our installation guide.


Simulation
----------

Interesting things happen in ``simulation/``.
Here, we write our programs, create simulated worlds and more.
Let's take a closer look:

.. Create the repository tree.
.. program-output::
   cd $KITCAR_REPO_PATH/kitcar-gazebo-simulation && tree -I __pycache__ -L 2 --dirsfirst simulation
   :shell:

The directories ``simulation/build`` and ``simulation/devel`` are automatically generated by **catkin_make** and contain compiled source code and other information used to start ROS nodes.

Models
^^^^^^

Of course, Gazebo needs many images, models and more to simulate complete worlds.
All of these resources are located in ``simulation/models/``.

.. tip::

  Gazebo looks for models and other resources at all locations defined \
  in the environment variables **$GAZEBO_MODEL_PATH** and **$GAZEBO_RESOURCE_PATH**.
  Find out where Gazebo looks for models:

  .. prompt:: bash

     echo $GAZEBO_MODEL_PATH


You will learn more about creating custom roads in the simulation in the next part of the Onboarding.
All of our roads are located in ``simulation/models/env_db``.

Utils
^^^^^

Most of our code is written in Python.
Python packages that don't have any ROS dependencies are located in ``simulation/utils/``.
You will get to know the geometry package later, it is in ``simulation/utils/geometry/``.

Source
^^^^^^

All ROS packages are defined in ``simulation/src``.
You will write your own *ROS onboarding node* within the ROS package \
``simulation/src/simulation_onboarding``.
The structure of a single ROS package will be explained in more detail later on!

However, if you take a look at `catkin workspaces <http://wiki.ros.org/catkin/workspaces>`_ \
you will notice that the ``simulation/`` folder is a **catkin workspace**.
This means that you can build our ROS packages from within ``simulation/``.

Let's try that by running

.. prompt:: bash

   catkin_make

If everything goes well you should now also see ``simulation/build`` \
and ``simulation/devel`` directories that contain generated files from all ROS packages.
When modifying ROS packages (including changes in the source code) \
you generally need to execute **catkin_make**.

.. tip::

   Writing ROS nodes in Python comes with some benefits: You don't need to compile your code!
   Instead of running **catkin_make** every time you change something in your code,
   it is usually enough to run it only when modifying the actual ROS package
   (e.g. creating a new ROS node).