

.. index:: Visual Studio Code, IDE; Visual Studio Code

******************
Visual Studio Code
******************

`Visual Studio Code <https://code.visualstudio.com/>`_ is a
lightweight, yet powerful source code editor that runs on multiple
platforms.

With the `C/C++ for Visual Studio Code extension
<https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools/>`_
it is possible to use the Calypsi C compiler tool chain in Visual Studio Code.

Visual Studio Code can be tailored to use various build and debugger
tools. Its debugger integration, based on MI (Machine Interface),
is supported by the Calypsi ``db68k`` debugger.

Visual Studio Code is an excellent GUI choice for Calypsi, being actively
developed, lightweight, responsive, and highly configurable.

This guide does not fully document Visual Studio Code. For detailed
information, refer to the official `documentation <https://code.visualstudio.com/docs>`_.

Some basics on getting started are covered here, as its operation
may differ from traditional IDEs.

.. image:: ../6502/images/vscode-session.png


Installation
============

Installation is easy to do by downloading it from the official
site. After that you can update from inside Visual Studio Code
itself.

.. note::

   If you use Arch Linux or a derivative like Manjaro, install VS Code
   via its package system. The community ``code`` package currently
   cannot install the vscode-cpptools extension due to licensing.
   To make it work, install the Microsoft-branded ``visual-studio-code-bin``
   from the AUR.


Project setup
=============

In contrast to many IDEs you will not find any project setup in the
menus.

To create a new project from scratch, use ``File>Open`` and create a
new folder for your project and then press ``Open``. You now have an empty
project directory.

For an existing project, select ``File>Open``, browse to its top
folder, and press ``Open`` to load.

Project-specific files are stored in a ``.vscode`` directory within the
project. Initially, this directory is empty.


Building
========

Once the project is populated and a ``Makefile`` created, add a build
task. Select ``Tasks>Configure Tasks...``, then ``Create tasks.json
file from template``, and ``Others``. Edit the resulting ``tasks.json``
file, which may resemble:

.. code-block:: json

  {
      "version": "0.2.0",
      "tasks": [
          {
              "label": "build",
              "type": "shell",
              "command": "make -k",
              "options": {
                  "cwd": "${workspaceRoot}"
              },
              "problemMatcher": [
                  "$gcc"
              ]
          },
          {
          "label": "clean",
          "type": "shell",
          "command": "make -k clean",
          "problemMatcher": [],
          }
      ]
  }


Running the debugger
====================

The ``db68k`` debugger can be used inside Visual Studio Code. For
basic use it uses a 68000 simulator and a memory system that is
configured based on the executable image.

Configuration
-------------

Before starting the debugger, add a launch configuration.

.. code-block:: json

  {
      "version": "0.2.0",
      "configurations": [
          {
              "name": "C++ Launch",
              "type": "cppdbg",
              "request": "launch",
              "program": "${workspaceRoot}/src/myproject",
              "args": [],
              "stopAtEntry": false,
              "cwd": "${workspaceRoot}/src",
              "environment": [],
              "externalConsole": false,
              "linux": {
                  "MIMode": "lldb"
                  "miDebuggerPath": "/usr/local/bin/db68k",
                  "launchCompleteCommand": "exec-run",
                  "setupCommands": []
              },
              "osx": {
                  "MIMode": "lldb",
                  "miDebuggerPath": "/usr/local/bin/db68k",
                  "launchCompleteCommand": "exec-run",
                  "setupCommands": []
              },
              "windows": {
                  "MIMode": "lldb"
              }
          },
      ]
  }

There are a couple of things to specify here.

  #. You need to specify that you are using ``/usr/local/bin/db68k``
     as the debugger using ``miDebuggerPath``

  #. You also need to tell that you want to use ``lldb`` as ``MIMode``
     [#MI]_

The launch configuration is a text file stored in ``.vscode/launch.json``.

Running the application
-----------------------

Once configured, run your application using ``Run >> Start Debugging``
(``F5``). Consider inserting a breakpoint or interrupting execution
once started. If debugger windows (variables, call stack, etc.) don't
appear, click the bug icon to switch to the debugger view.

.. image:: ../6502/images/vscode-debug.jpg



.. rubric:: Footnotes
.. [#MI] Even though ``db68k`` is much closer to ``gdb`` than ``lldb``
         at the command level, you need to specify ``lldb`` as the MI
         mode. The reason is that in the ``gdb`` mode, Visual
         Studio Code works around a bug on UNIX style platforms for
         the MI command ``-exec-interrupt`` (which interrupts
         execution).
         The work around is to send a signal to a real UNIX
         process to interrupt it. This does not work with db68k
         as the application being debugged is not a UNIX process at all.
         Instead you need to use the ``lldb`` mode, where the MI command
         ``-exec-interrupt`` works properly, just as it does in
         ``db68k``.

         Reference https://sourceware.org/bugzilla/show_bug.cgi?id=20035
