# Editor

In the following I list the steps to setup an environment based on *VSCodium*, which is based on the popular text editor Visual Studio Code (VS Code). The following instructions should also work with VS Code, though.

Even both are open source, I prefer VSCodium, because the default extension store used by VS Code (Marketplace) [contains popular extensions by Microsoft that may only be used with VS Code](project:#why-i-chose-vscodium-over-vs-code). For example GitHub Copilot is only available for VS Code.

A text editor is not enough to create programs executable by our computer. Along with the text editor we will install additional tools like *compiler*, *language server* etc. 

For the following tutorial I used a computer with an Intel x86-64 bit processor with Windows 11 OS build 26100. This information can be found to `System Information`.

Even I tried to cater for other processors and OSs, I did not test the steps on other hardware/OS, which I don't have access to.

If the following steps do not work out for you, we can find a solution in the class. If you miss something in the steps or found an error, please create an {{ '[issue]({}/-/issues)'.format(repository_url) }} or a pull request to help other students.

## Download & installation

::::{tab-set}
:::{tab-item} VSCodium Windows
```
winget install vscodium
```
:::
:::{tab-item} VSCodium on MacOs and Linux
Refer to [these instructions](https://vscodium.com/#install).
:::
:::{tab-item} VS Code Windows
```
winget install Microsoft.VisualStudioCode
```
:::
:::{tab-item} VS Code MacOS
```
brew install --cask visual-studio-code
```
:::
::::

## Customizing the editor

1. When you run for the first time, you should see a walkthrough for getting started.
1. First pick a theme that fits your environment and your taste. [A study](https://doi.org/10.1111/tgis.13038) found out that a light theme is best in a well-lit environment during the day, and dark during the night. 

   I like `Solarized Light`, because complete white strains my eyes. You can find it when you click on `Browse Color Themes` button or `See more themes`. 

   After choosing your theme you should see a ✅ beside `Choose your theme`.

1. We will leave the walkthrough without visiting other steps. We will setup other tools when we need them to understand why we need them. Click on `Go Back` on the top left corner of the tab to discard the walkthrough window. You should see the `Welcome` tab.

(creating-and-opening-a-new-folder)=
## Creating and opening a new folder

Now we will write our first program. For each program we will code, we will use a single folder. During the semester you will write also many other programs. So think about where you will place your folder.

:::{tip}
My recommended directory structure is:

```
📁 your-home-folder
├── 📁 uni
    ├── 📁 25WS
        ├── 📁 cprog
            ├── 📁 code
                ├── 📁 hello
                ├── 📁 pi-estimator
                ├── 📁 ...
```

`hello` and `pi-estimator` are individual C projects.
:::

Now we will create the folder `hello` for our first program.

1. On the `EXPLORER` tab, click on `Open Folder`. The file explorer should pop up.
1. Create the folder structure that you like as we discussed before and then `hello`.
1. In the file explorer, click on `hello` and then `Select folder`. A new window should pop-up with the title `Do you trust the authors of the files in this folder?`.
1. We can trust the folder, because there is nothing we should be suspicious of. You can read about trust [here](https://code.visualstudio.com/docs/editing/workspaces/workspace-trust).

   Tick the box for `Trust the authors of all files in the parent folder 'code'` and click on `Yes ...`. You should see your folder open but empty on the `EXPLORER` tab on the left. 
1. Hover or click with your mouse on the `EXPLORER` tab on the left. You will see the icons {{new_file}}, {{new_folder}}, {{refresh}}, {{collapse_all}}.
1. Click on {{new_file}} `New File...`. A file name prompt will be activated.
1. Enter `main.c`. In C, the root source file is named `main.c` by convention. Why? You will understand in the next steps. After the prompt `main.c` will be opened in a new tab.
1. One of the most basic things we can do with a program is to output some characters to us — this is a way of communication between the program and us. Let us do that. Write the following code by hand to get the feeling of different symbols used in C language syntax.

   :::{tip}
   Consider using the US keyboard layout for programming. Many symbols like `#`, `<`, `[`, `;`, `:` are easier to access.
   :::

   :::{literalinclude} ../c-template/src/main.c
   :language: c
   :::
1. Before you save, pay attention to the `main.c` in the tab's title. You should see a full circle similar to ⚫. This means that the file is not saved. Now save it using <kbd>Ctrl</kbd><kbd>s</kbd>. The circle should turn to a cross mark similar to ❎.

We have written code to control the behavior of a computer. This is called *source code*. 

:::{wpd} source code
a plain text computer program written in a programming language
:::


## Running source code using the terminal

Let us try to execute our code. We usually start programs by double-clicking on them in the file explorer. We will use another approach — using the *terminal*.

1. Press <kbd>Ctrl</kbd><kbd>Shift</kbd><kbd>\`</kbd>. A new window should open in the bottom of the editor with `TERMINAL` activated.

   On Windows it should show something similar to:

   ```text
   PS C:\Users\user\...\hello>
   ```
1. To execute it, write:

   ```sh
   ./main.c
   ```

   and press <kbd>Enter</kbd>. What happened? Did you see any output, e.g., *Hello!*?

   - on Windows: You will probably see that the operating system focus changes again to the editor tab with `main.c` — the same behavior that you would expect when you double-click on the file.
   - on Linux, macOS: You will probably see an error message that you don't have the permission to execute the file.

`main.c` is a source code and is in a human-readable format. It is not meant to be executed by the computer. Computer only understands *machine code*, so we have to translate our code first.

:::{wpd} machine code
code consisting of machine language instructions
:::

Why did we use a terminal to start our program, which feels primitive compared to a more graphical interface? Reason: In this course we will focus on programs that input and output data using a *text terminal*, or in short *terminal* and creating programs for the terminal are less complex than programming a graphical program as a beginner.

:::{plantuml}
:align: left

skinparam packageStyle rect

package "Text terminal" #DDDDDD {
    rectangle keyboard as K
    rectangle display as D
}

rectangle program as P

' Layout positioning
K -[hidden]down-> P
D -[hidden]down-> P

K -> P : input
P -> D : output
:::

:::{wpd} text terminal
a serial computer interface for text entry and display 
:::