Visual studio code ================== Visual studio code (`VS code `__) 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 `__ 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 `__, contains three VS code extensions: - C/C++: adds the language support for developing in C and C++ (`IntelliSense `__ and `debugging `__) - 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 `__), 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 `__). 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 `__. 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 `` 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:: Win64 .. **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 with developer power shell” of the `MBsysC installation tutorial <./MBsysC.html>`__) and during Robotran project compilation through the option ``-DCMAKE_PREFIX_PATH`` (see section “Compiling in terminal Developer Command Prompt for Visual Studio (Windows)” of the `Bodies and joints instruction `__). 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:: Win64 On Windows, you have three options for selecting your compiler: - Use the classical MSVC compiler from Microsoft; - Install `Mingw-w64 `__ to use GCC and GDB on Windows; - Use the `Windows subsystem for Linux `__ (WSL2) that allows you to access a Linux distribution (such as Ubuntu) directly on Windows. .. rubric:: Microsoft Visual C++ (MSVC) compiler :name: microsoft-visual-c-msvc-compiler If you have a recent version of Visual Studio, open the Visual Studio Installer from the Windows Start menu and verify that the C++ workload is checked. If it’s not installed, then check the box and select the **Modify** button in the installer. You can also install the **Desktop development with C++** workload without a full Visual Studio IDE installation. From the Visual Studio `Downloads `__ page, scroll down until you see Tools for Visual Studio under the All Downloads section and select the download for Build Tools for Visual Studio 2022. .. figure:: figure/msvc_from_VS_build.png :alt: Download MSVC from Visual Studio installer Download MSVC from Visual Studio installer You can verify that you have correctly installed MSVC by opening the **Developer Command Prompt for Visual Studio** from the Windows start menu and typing ``cl.exe``. If MSVC is correctly installed on your computer, you shall obtained an output similar to the following screen-shot. .. figure:: figure/cl-version_output.png :alt: Output of the cl.exe command Output of the cl.exe command .. rubric:: GCC and GDB on Windows through MinGW :name: gcc-and-gdb-on-windows-through-mingw As recommended in the Visual Studio Code official tutorial, we recommend to install the MinGW-w64 via `MSYS2 `__ which provides up-to-date native builds of GCC, MinGW-w64, and other helpful C++ tools and libraries for Windows. - Start by downloading MSYS2 latest installer from `their website `__. - Run the installer and follow the steps of the installation wizard. Note that MSYS2 requires 64 bit Windows 8.1 or newer. - In the wizard, choose your desired Installation Folder. Record this directory for later. In most cases, the recommended directory is acceptable. The same applies when you get to setting the start menu shortcuts step. When complete, ensure the Run MSYS2 now box is checked and select Finish. This will open a MSYS2 terminal window for you. - In this terminal, install the MinGW-w64 toolchain by running the following command: .. code:: bash pacman -S --needed base-devel mingw-w64-ucrt-x86_64-toolchain - Accept the default number of packages in the ``toolchain`` group by pressing ``Enter``. |pacman-msys2_default_pack| - Enter ``Y`` when prompted whether to proceed with the installation. - Add the path of your MinGW-w64 ``bin`` folder to the Windows ``PATH`` environment variable. Once all these steps are done, check your MinGW installation by opening a **new** Command Prompt and type: .. code:: bash gcc -v gdb -v g++ -v If information about which version of GCC, GDB and g++ is installed on your machine, is displayed in the prompt then the installation process is finished. If it is not the case: - Make sure your PATH variable entry matches the MinGW-w64 binary location where the toolchain was installed. - If gcc has the correct output but not gdb, then you need to install the packages you are missing from the MinGW-w64 toolset. - If on compilation you are getting the “The value of miDebuggerPath is invalid.” message, one cause can be you are missing the mingw-w64-gdb package. .. rubric:: Access Ubuntu through WSL :name: access-ubuntu-through-wsl Visual Studio Code has support for working directly in WSL with the `WSL extension `__. We recommend this mode of `WSL development `__, where all your source code files, in addition to the compiler, are hosted on the Linux distro. For more background, see `VS Code Remote Development `__. First make sure you have correctly installed `Windows Subsystem for Linux `__ and the distribution of your choice (we recommend Ubuntu). Second, even though, you will use VS Code to edit the source code, it will be compiled on Linux using GNU compiler collection (GCC, GDB and g++). You must then install it on your WSL distro. From the WSL command prompt, start by running the following command from the WSL terminal 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. Once WSL distro is installed, Visual Studio Code can be used to open a project using the ``code`` command in WSL terminal with the path to your project. .. code:: bash code .. **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”. You can verify that the project is well open from the WSL extension of VS code if ``[WSL: YourDistro]`` is displayed next to your project name (see following figure where Ubuntu 22.04 distro was used). .. figure:: figure/wsl_extension-proof.png :alt: Verify WSL extension Verify WSL extension When working on WSL, make sure that all the required VS code extensions (e.g., C/C++, CMake, …) are installed and enabled on your WSL instance. .. figure:: figure/VS_code-extension_installed.png :alt: VS code extension enabled on WSL VS code extension enabled on WSL 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 consoleas already mentioned\ `above <#access-ubuntu-through-wsl>`__\ : .. code:: bash code Through the ``code`` command option, the path to your project can be absolute or relative from the current directory of your terminal session. 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 `__). .. 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 ------------- .. |pacman-msys2_default_pack| image:: figure/cpp-install-MSYS2-toolchain.png .. |CMake Tools extension command palette| image:: figure/VS_code-CMakeTools-command_palette.png