Visual studio code
==================

Visual studio code (`VS code <https://code.visualstudio.com/>`__) is a
powerful IDE for programming that can be used to work on projects. It is
lightweight and has a lot of features that can help you to develop your
codes. It can be configured with `CMake Tools
extension <https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools>`__
to enable direct interface with CMake functionalities.

This tutorial provides instruction to configure VS code IDE to compile
and simulate Robotran C projects.

Visual studio code - Installation
---------------------------------

VS code can be downloaded from https://code.visualstudio.com/download
and follow the installation instruction provided by the tool.

C/C++ extension pack - Installation
-----------------------------------

VS code provides an extension package for programming in C or C++. This
package, `C/C++ extension
pack <https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools-extension-pack>`__,
contains three VS code extensions:

-  C/C++: adds the language support for developing in C and C++
   (`IntelliSense <https://code.visualstudio.com/docs/cpp/cpp-ide>`__
   and `debugging <https://code.visualstudio.com/docs/cpp/cpp-debug>`__)
-  C/C++ Themes [optional]: provides a theme extension to VS code that
   closely match Visual Studio themes and include colors for many of the
   new scopes.
-  CMake Tools: provides the native developer a full-featured workflow
   for CMake-based projects in VS code.

You can install directly the whole C/C++ pack or the extension
one-by-one, to do so, once you opened VS code:

-  Click on the “Extension” button in the primary side bar (located on
   the left by default) (1).
-  Search for the extension you want to install (e.g., C/C++) (2).
-  Install the extension by clicking on the appropriated button (3 or
   3’).

.. figure:: figure/VS_code-Installation.png
   :alt: Install the required extension for working with C/C++ codes.

   C/C++ extensions installation process

CMake Tools - Configuration
---------------------------

The CMake Tools extension relies on two ways to configure CMake (i.e.,
ways to provide to CMake information about the compiler on your system):

-  through CMake Presets,
-  through CMake Kits/Variants.

As using CMake presets is the recommended way for configuring CMake
Tools according to the reference tutorial (accessible
`here <https://code.visualstudio.com/docs/cpp/cmake-linux>`__), the
following tutorial will only consider this option. To avoid any
confusion, we strongly advise you to set the CMake Tools extension
options ``cmake.useCMakePresets`` to “**always**” and
``cmake.enableAutomaticKitScan`` to “**false**”. These options (as all
other options) can be changed either:

-  by using the VS code settings UI,
-  or through the JSON setting file.

The VS code user settings UI can be trigger either through the command
palette (``Ctrl + Shift + P``) and selecting the “Preferences: Open
Setting (UI)” command or by clicking on the gear symbol next to the
extension on the “Extension” panel.

.. figure:: figure/CMake_Tools-Settings.png
   :alt: Open the CMake Tools extension settings in the VS code UI.

   CMake Tools extensions settings

The JSON settings file can be opened by using the command palette
(``Ctrl + Shift + P``) and selecting the “Preferences: Open User
Settings (JSON)”.

We also recommend to set the options ``cmake.configureOnEdit`` and
``cmake.configureOnOpen`` on “**false**” to avoid uncontrolled
configuration of your project by the extension.

Finally, Robotran project have a common structure (see `Folder
structure <https://robotran-doc.git-page.immc.ucl.ac.be/TutorialModellingFeatures/c-code/ModellingFeatures/newProject.html#folder-structure>`__).
Therefore, we also recommend to set the default path to the
``${sourceDirectory}`` to both ``"${workspaceFolder}/"`` and
``"${workspaceFolder}/workR"``. This can be done in the JSON’s VS code
configuration file by adding the following setting:

.. code:: json

   "cmake.sourceDirectory": [
       "${workspaceFolder}/",
       "${workspaceFolder}/workR/"
   ],

CMakePreset - How to? for Robotran projects
-------------------------------------------

By using CMake Tools extension, the user will not have to use manually
the command ``cmake``\ and ``cmake --build`` to configure and generate
their solution. Those commands will be called by VS code using buttons.
Yet, the use of buttons does not allow to provide options to CMake
during the configuration and generation steps. To bypass this
limitation, we recommand to use `CMake
Presets <https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html>`__.

CMake Presets are JSON files (named CMakePresets.json or
CMakeUserPresets.json) used to provide configuration settings to build
projects. They are a functionality of CMake and used by VS code through
the command flag ``--preset <preset_name>`` given to the ``cmake``
and/or ``cmake --build`` (done automatically by CMake Tools extension,
so transparent for the VS code user). They can be automatically
generated by CMake Tools using the command “CMake: Add Configure Preset”
through the VS code command palette (notice that this functionality is
automaticaly triggered when opening a project where no CMakePreset.json
was found). Using the option:

-  “Custom”: it will generate a “CMakePreset.json” file in your
   ``${sourceDirectory}`` (generic path variable used by CMake Tools
   extension to define the path where the CMakeList.txt file of your
   project must be stored) folder containing the required fields
   pre-filled with default values;
-  “Create from compiler”: it will scan your computer to find the usable
   compiler. Once you have selected the dedicated compiler, CMake Tools
   extension will generate the CMakePreset.json file with the required
   compiler information.
-  “Toolchain File”: NOT CONSIDERED IN THIS TUTORIAL.

In a CMake Presets file we find at least two main fields:

-  The ``version`` fields: A required integer representing the version
   of the JSON schema.
-  The ``configurePresets`` fields: An optional array of Configure
   Preset objects. This is allowed in preset files specifying version 1
   or above.

In the ``configurePresets`` fields you will enter all the options
required for the project configuration. If an options is not mentioned
CMake will automatically detect the value to use. CMake variables such
as ``CMAKE_BUILD_TYPE``, ``CMAKE_INSTALL_PREFIX`` and
``CMAKE_PREFIX_PATH`` can be modified in the ``cacheVariables`` field
itself contained in the ``configurePresets``\ field.

.. container:: Linux

   ..

      **REMARKS:**

      Since version 1.26 of MBsysC, the user needs to define the
      installation path of MBsysC during MBsysC compilation through the
      option ``-DCMAKE_INSTALL_PREFIX`` (see section “Compiling in
      Terminal” of the `MBsysC installation tutorial <./MBsysC.html>`__)
      and during Robotran project compilation through the option
      ``-DCMAKE_PREFIX_PATH`` (see section “Compiling in terminal (Unix,
      MacOS)” of the `Bodies and joints
      instruction <https://robotran-doc.git-page.immc.ucl.ac.be/TutorialModellingFeatures/c-code/ModellingFeatures/bodiesJoint.html>`__).
      This shall be done in CMake presets through the options
      ``CMAKE_INSTALL_PREFIX`` and ``CMAKE_PREFIX_PATH``).

The ``buildPresets`` can also be used to provide building objects mainly
useful for Multi-Config generator such as Visual Studio generators. If
you use a Single-Config generator (such as MakeFile on Linux), we advise
you not the add the build preset field (expect if you know what you do)
to use the default option of CMake during the building process.

..

   **TIPS:**

   Visual Studio generators and Ninja Multi-Config can generates
   multiple configurations (Debug, Release, …) at once with
   ``CMAKE_CONFIGURATION_TYPES`` instead of only one configuration with
   ``CMAKE_BUILD_TYPE``. Therefore, by design the configuration to build
   must be define through the building options (and not by the
   ``CMAKE_BUILD_TYPE`` options for the configuration). This can be
   achieved by specifying the ``configuration`` options in the
   ``buildPresets`` associated with the dedicated configure preset (this
   is done by setting the configure preset name in the
   ``configurePreset`` options).

   .. figure:: figure/CMakePresets-buildPresets.png
      :alt: Specify the configuration to use to build the project

      Build preset field contained in the CMakePreset.json

Compiler - Installation
-----------------------

.. container:: Linux

   On Linux, you will use the g++ compiler to compile C/C++ source code
   and GDB to debug. They are not installed by default on Ubuntu
   distribution but their installation process is easy.

   First verify that it is not already installed by entering in a
   terminal the following command:

   .. code:: bash

      gcc -v

   If GCC is already installed, the previous command shall return
   something similar to:

   .. figure:: figure/gcc-version_output.png
      :alt: Output of the ``gcc -v`` command

      Output of the ``gcc -v`` command

   If the prompt returns “Command ‘gcc’ not found”, it must be installed
   manually. Start by running the following command from the terminal
   window to update the Ubuntu package lists. An out-of-date Linux
   distribution can sometimes interfere with attempts to install new
   packages.

   .. code:: bash

      sudo apt update 

   Next install the GNU compiler tools and the GDB debugger with this
   command:

   .. code:: bash

      sudo apt install build-essential

   Verify that the installation process was successful by displaying
   gcc, gdb and g++ version:

   .. code:: bash

      gcc -v
      gdb -v
      g++ -v

   It shall displays information about which version of GCC, GDB and g++
   is installed on your machine.

Day-to-day usage
----------------

Using VS code, multiple options are possibles to open your Robotran
project as your VS code workspace:

-  with the “open folder” option in VS code (File->Open Folder …)
-  using the ``code`` command in a terminal console:

.. code:: bash

   code <path/to/your/project>

Through the ``code`` command option, the path to your project can be
absolute or relative from the current directory of your terminal
session.

.. container:: Linux

   ..

      **TIPS:**

      Using the ``.`` path as option to the ``code`` command, i.e.:

      .. code:: bash

         code .

      will open VS Code in the current working folder, which becomes
      your “workspace”.

When you need to compile your project, you can use the CMake Tools
extension to configure and build your project.

First make sure that the CMake Tools extension selected the correct
active folder as its ``${sourceDirectory}``. If CMake Tools find the
CMakePreset.json file and displays the CMake Tools extension icon in the
left panel then it has selected the correct folder.

.. figure:: figure/CMake_tools-icon.png
   :alt: CMake Tools extension icon

   CMake Tools extension icon

If the extension icon is not displayed then either the CMakePreset.json
file does not exist yet or the active folder of the CMake Tools
extension is not the correct one. The active folder selected by CMake
Tools can be changed through the command palette (``Ctrl + Shift + P``)
and selecting the “CMake: Select Active Folder” command.

A CMakePreset.json file can be created thanks to the CMake Tools
extension by using the command palette (``Ctrl + Shift + P``) and
selecting the “CMake: Add Configure Preset” command (as already
explained `above <#cmakepreset---how-to-for-robotran-projects>`__).

..

   **WARNING:**

   The CMakePreset.json file must be created in the same folder as the
   CMakeList.txt file of your project.

Then, when the correct CMakePreset.json file is selected, and after
configuring the CMake preset (see section `CMakePreset - How to for
Robotran projects? <#cmakepreset---how-to-for-robotran-projects>`__),
you can configure and build your project by using:

-  The CMake Tools extension icon in the left panel of VS code (1) and
   selecting the “Configure” (2) or “Build” (3) option from the menu.
   The configure and build preset can be selected by clicking on the pen
   displayed next to the current preset name.

.. figure:: figure/VS_code-CMakeTools-icons.png
   :alt: CMake Tools extension icon in the left panel of VS code.

   CMake Tools extension icon

-  the command palette (``Ctrl + Shift + P``) and selecting the “CMake:
   Configure” (or “CMake: Build”) command. The configure and build
   preset can be selected upstream by using the command “CMake: Select
   Configure Preset” or “CMake: Select Build Preset” respectively.

|CMake Tools extension command palette|,

-  the CMake Tools extension buttons in the status bar of VS code (if
   their visibility was activated as described in the `following
   article <https://github.com/microsoft/vscode-cmake-tools/blob/main/docs/cmake-options-configuration.md>`__).

.. figure:: figure/VS_code-CMakeTools-status_bar.png
   :alt: CMake Tools extension buttons in the status bar of VS code.

   CMake Tools extension buttons in the status bar

Once the project solution is correctly build, you can run the simulation
in debug or launch by using either the buttons from the CMake Tools
extension tab on the left panel (1) and (2) or the buttons in the status
bar (3) and (4) if their visility was activated.

Tips & tricks
-------------

.. |CMake Tools extension command palette| image:: figure/VS_code-CMakeTools-command_palette.png