# Running and debugging

Typing each time commands to the terminal to compile and run our program is not necessary. Many IDEs feature a shortcut like <kbd>F5</kbd> which combines compilation and inspection of our program. The latter is a natural process of program development, because we engineers make errors and introduce so called *bugs* into our program.

:::{wpd} debugging
the process of finding the root cause, workarounds, and possible fixes for bugs.
:::

:::{wpd} bug
a design defect in an engineered system
:::


In this section we will install and configure extension [CodeLLDB](https://github.com/vadimcn/codelldb), which uses the [LLDB debugger](https://lldb.llvm.org/) that is part of the clang project. Then we will create a [debug configuration](https://code.visualstudio.com/docs/debugtest/debugging-configuration) that will be used upon <kbd>F5</kbd>.

<!-- technical detail: CodeLLDB uses its own lldb to guarantee compatibility. It is possible to configure a custom LLDB library though, which I did not try. -->

## Installing CodeLLDB

1. Install `CodeLLDB` extension from the author `vadimcn` in the editor.
1. Click on `Restart Extensions`

## Creating a launch configuration

:::{warning}
If the following steps do not work, skip these and create `launch.json` by creating a new file and copy pasting the content at the end of this section.

Details [here](https://github.com/vadimcn/codelldb/issues/1310). 
:::

So let us add a configuration which will describe what happens if we press <kbd>F5</kbd>.

1. Go back to `main.c` tab.
1. Press <kbd>F5</kbd>. You should see a popup window stating `Cannot start debugging because no launch configuration has been provided.`.
1. Click `OK`. A `launch.json` will be created in your project folder under `.vscode` folder. It will contain the configuration documented [here](https://github.com/vadimcn/codelldb/blob/master/MANUAL.md#starting-a-new-debug-session).
1. `configurations` contains a configuration named `Debug`. Our executable program should be assigned to `program`.

   Now substitute the name of your program for `<executable file>`. If you cannot remember it, take a peek [to the previous section where we compiled and run our program](project:#running-your-program).

1. We want to work in an edit, debug cycle, however our launch configuration is not aware of the fact that our program must be compiled before running and debugging. So add the following line to your configuration so that the default build task is executed before debug:

   ```
   "preLaunchTask": "${defaultBuildTask}",
   ```
1. You can remove `cwd` (current working directory) line, because we will use the default setting.

After these changes, your `launch.json` should look like this without the comments on the top *for Windows*. Change `a.exe` to `a.out` for other operating systems.

:::{literalinclude} ../c-template/.vscode/launch.json
:language: json
:::

Debugging takes care of running our program. Our default build task builds our program without running. That is the reason why we specified `${defaultBuildTask}`.

In the next section, we will try our configuration. You don't have to save `launch.json`. Project files are typically saved when you press <kbd>F5</kbd>.

## Starting a debug session

1. Click on the tab `main.c`.
1. Press <kbd>F5</kbd>. `Run and debug` bar will be activated. Additionally, you should see some output in the `Debug console` below as follows:

   ```text
   ...
   Process exited with code 0.
   ```
   
   And in the terminal the hello message.
   
   :::{card} Troubleshooting
   1. Symptom: You get an error, e.g., `${defaultBuildTask} not found`.
   
      Solution: Check if you have CodeLLDB extension installed.
   
   1. Symptom: You start a debugging session, but it starts not the program that you have open in your editor.
   
      Solution: Pay attention [your directory hierarchy is correct](creating-and-opening-a-new-folder). You must **open the parent directory of the project** and not the directory above the parent directory.
      
      Also pay attention that you don't have two projects open in your workspace.
   :::

Now you can edit your code and run & debug it again and again in cycle.

Debugger can also inspect our code by placing red *breakpoints*, which we will introduce later. For now, we will use the debugging feature for a convenient way of compiling and running our code.

## Appendix

- [CodeLLDB manual](https://github.com/vadimcn/codelldb/blob/master/MANUAL.md)
- [`launch.json` reference](https://code.visualstudio.com/docs/cpp/launch-json-reference)