Dev Containers
===============

A consistent development environment is crucial for building reliable software. **Dev containers** solve this problem by encapsulating your development tools and dependencies inside Docker containers. This ensures that all developers on a project share the exact same environment—regardless of their operating system or local setup.

While dev containers are natively supported in **Visual Studio Code**, this project's setup is also compatible with other tools and workflows that support Docker and Docker Compose.

Structure
---------

The ``.devcontainer`` directory at the root of the project contains all configuration necessary to spin up a standardized development environment:

Inside the `.devcontainer` folder, you will find the following files:

- **`devcontainer.json`**: Entry point for the dev container configuration file.
- **`compose.yaml`**: Docker Compose file that defines the services that will run inside the container.
- **`Dockerfile`**: Dockerfile that defines the image that will be used to create the container.
- **`postcreate.sh`**: Script that is executed after the container is created, is used to install dependencies and configure the environment.

Usage
-----

#. Make sure you have Docker installed, up and running.
#. Install **Remote - Containers** extension in Visual Studio Code.
#. Open the project in Visual Studio Code.
#. Open the command palette (usually `Ctrl+Shift+P` or `Cmd+Shift+P`), and search for `Remote-Containers: Reopen in Container`.
#. Wait for the container to be created.

.. note::

   Your source code resides on the host machine (mapped inside the container under ``.src/workspace``).
   Changes made outside this path may not persist when the container is recreated.

Inside the container there are a few tools pre-installed to help you develop:

* ``compile_workspace.sh``: Compiles ROS2 workspace with some flags (``merge-install``, ``symlink-install``).
* ``test_workspace.sh``: Executes all tests in the workspace and validates the workspace.
* ``generate_debs.sh``: Generates Debian packages from the workspace, if ``debs/whitelist.txt`` is present will only generate the packages listed in the file and its dependencies.

For more information about tools installed in the container, check the `robotnik_ros_images <https://github.com/RobotnikAutomation/robotnik_ros_images_doc/blob/main/resources/builder/README.md>`_ repository.


Resources
---------

- `VS Code Dev Containers Documentation <https://code.visualstudio.com/docs/remote/containers>`_
- `Docker Compose <https://docs.docker.com/compose/>`_
- `Docker CLI Reference <https://docs.docker.com/engine/reference/commandline/cli/>`_

.. toctree::
    :maxdepth: 1