.. |br| raw:: html

   <br/>

.. _vscode-index:

VS Code Cross-Compilation
=========================

Introduction
------------

With a toolchain created by one of our :ref:`yocto-guide-index` BSPs you are able to setup Visual Studio Code for Cross-Compilation and Cross-Platform Debugging with GDB.

"Visual Studio Code is a source-code editor made by Microsoft for Windows, Linux and macOS.
Features include support for debugging, syntax highlighting, intelligent code completion, snippets, code refactoring, and embedded Git. 
Users can change the theme, keyboard shortcuts, preferences, and install extensions that add additional functionality.

In the Stack Overflow 2021 Developer Survey, Visual Studio Code was ranked the most popular developer environment tool, with 70% of 82,000 respondents reporting that they use it."

*(Wikipedia)*


Prequisites
-----------

.. hint:: The following example was made with a **TX8M** on a Linux host.

Get VS Code
~~~~~~~~~~~

Go to https://code.visualstudio.com/ and follow the instructions to install the IDE for your system.


Host Packages
~~~~~~~~~~~~~

Install neccessary host packages:

.. prompt::
   :prompts: $

   sudo apt update
   sudo apt install build-essential gdb gdb-multiarch


Toolchain Setup
~~~~~~~~~~~~~~~

1. Build the desired image for your target. Refer to our :ref:`yocto-guide-index`.

.. note:: If you want to use *karo-image-minimal* you have to edit ``conf/local.conf``.
   Make sure to add ssh server and comment the line which makes the rootfs readonly.

.. code-block:: text

   # EXTRA_IMAGE_FEATURES += "read-only-rootfs"
   (...)
   IMAGE_FEATURES:append = " \
         ssh-server-openssh \
   "

Then run:

.. prompt::
   :prompts: $

   bitbake <image>

2. Flash the image to your board. Refer to :ref:`software-documentation/index:Flashtools`.

3. Build the SDK for previously image. Run inside your ``<build-dir>``:

.. prompt::
   :prompts: $

   bitbake <image> -c populate_sdk

4. Install the SDK to your host (example):

.. prompt::
   :prompts: $

   tmp/deploy/sdk/karo-wayland-glibc-x86_64-karo-image-weston-cortexa53-crypto-tx8m-1620-toolchain-5.15-kirkstone.sh

.. code-block:: text

   karo-wayland (Ka-Ro Linux BSP with wayland backend) SDK installer version 5.15-kirkstone
   ========================================================================================
   Enter target directory for SDK (default: /opt/karo-wayland/5.15-kirkstone): 
   You are about to install the SDK to "/opt/karo-wayland/5.15-kirkstone". Proceed [Y/n]? 
   Extracting SDK..........................................................................................
   ...........................done
   Setting it up...done
   SDK has been successfully set up and is ready to be used.
   Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
   $ . /opt/karo-wayland/5.15-kirkstone/environment-setup-cortexa53-crypto-poky-linux


VS Code Project Setup
---------------------

Project Folder
~~~~~~~~~~~~~~

Choose a project folder and open VS Code inside it.

.. prompt::
   :prompts: $

   mkdir ~/hello-world
   cd ~/hello-world
   code .

Install Extension
~~~~~~~~~~~~~~~~~

Install the C/C++ extension for debugging.

.. figure:: ./images/c-extension.png
   :scale: 80 %
   :align: left
   :figwidth: 100 %

You can instead run:

.. prompt::
   :prompts: $

   code --install-extension ms-vscode.cpptools

Sources
~~~~~~~

.. note:: **Example Project** |br|

   Download our :download:`cross-hello-world.patch <./files/cross-hello-world.patch>` and apply it inside the ``hello-world`` directory:
   
   .. prompt::
      :prompts: $

      cd ~/hello-world
      patch -p1 < cross-hello-world.patch

This will create files and a directory structure:

.. code-block:: text

   .
   ├── cross-compile.sh
   ├── deploy.sh
   ├── hello-world.c
   ├── Makefile
   └── .vscode
      ├── launch.json
      ├── settings.json
      └── tasks.json

   1 directory, 7 files

Settings
~~~~~~~~

You now have to fit the ``.vscode/settings.json`` file to your needs.


.. figure:: ./images/settings-json.png
   :scale: 100 %
   :align: left
   :figwidth: 100 %

It's enough to fit the target's **IP-address** and the **path** your SDK was installed to.

.. tip:: If you're interested in understanding the whole task and cross-compilation setup, go through the single files. They're mostly self-explanatory.
   
   More information about tasks in VS Code can be found in the official documentation.

   https://code.visualstudio.com/docs/editor/tasks


Cross-Compilation
-----------------

Open the ``hello-world.c`` file and hit :kbd:`CTRL` + :kbd:`SHIFT` + :kbd:`B`.

This will execute the ``cross-compile.sh`` script and generate the **hello-world.bin** output file.

.. figure:: ./images/cross-compile.png
   :scale: 100 %
   :align: left
   :figwidth: 100 %


Deploy to Target
----------------

Now ssh-copy the generated binary to your target and execute it.

.. prompt::
   :prompts: $

   scp hello-world.bin root@<target-ip>:/root/

On the target:

.. prompt::
   :prompts: #

   /root/hello-world.bin

.. code-block:: text

   Hello, World!


Remote Debugging
----------------

.. note:: The created tasks, ``cross-compile.sh`` and ``deploy.sh`` in the *hello-world* project take care of cross-compiling and deployment automatically.

Simply hit :kbd:`F5` to start debugging. **The debugging task depends on compilation and deployment task**, so they will be run first.

The script starts GDB on your target and the debugger stops at the execuction of main:

.. figure:: ./images/debugger.png
   :scale: 100 %
   :align: left
   :figwidth: 100 %


Breakpoints
-----------

You can now set a breakpoint by clicking in the space between line numbers and side panel. After this click "Continue" or hit :kbd:`F5` again.

.. figure:: ./images/breakpoint.png
   :scale: 100 %
   :align: left
   :figwidth: 100 %

You will now notice that the value of variable ``i`` has changed and *Hello, World!* was printed to console.

.. figure:: ./images/inspection.png
   :scale: 100 %
   :align: left
   :figwidth: 100 %

Another Continue or hit of :kbd:`F5` will finish the execution.