# Programming 2: Software Installation
A guide for installing all required software. (Last update: 2024-04-18)
If you encounter any troubles during this guide, use the [forum](https://forum24.prog2.de/c/technicalities/) to ask questions and/or check out the [troubleshooting](#Troubleshooting) section.
If you have a question you don't want to share with other students, consult the [technicians](https://forum24.prog2.de/new-message?groupname=Technicians).
## In-Person help for troubleshooting
Check out our next Office-Hour:
- Friday, 19.04, 12:00-14:00, E1.3 SR 016
# General
You'll need at least the following software during the programming 2 course:
- **Git** version control system
- **Java JDK**
- **C compiler**
- **Mars** MIPS simulator
:::warning
:warning: This guide contains lots of commands. If one of them fails, stop there and **call for help immediately**!. Do not continue as this will only make debugging more difficult for us! :warning:
:::
Some of this software is installed using a package manager.
Please note that Mars will require a working Java installation in beforehand.
:::info
:information_source: This guide looks super long. Please don't be intimidated by that. This is due to the fact that it supports several operating systems. Even though it should be obvious: do only follow the instructions for your OS. (Except for WSL, but we'll come to that later).
:::
## Package managers
For Windows, we're using chocolatey, for Mac we use brew.
You'll need these for some steps in this guide.
### Windows: Installing chocolatey
Open a Powershell **as administrator**.
To do so, search in the windows start menu for `powershell`, right-klick the entry and select "Run as admin".
:::warning
:warning: The following will not work if you do not run the terminal as administrator!
:::
Please run
```powershell=
choco -v
```
to check whether you have chocolatey already installed.
If it prints a version number, you have chocolatey already installed and you can skip this section.
Otherwise install chocolatey using the following command:
```powershell=
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
```
**Now close all your open terminals. The `choco`-command will be available in a new terminal.**
:::warning
:warning: The `choco`-command will only be available in terminals you started after the installation.
:::
Details on installing chocolatey can be found here: https://chocolatey.org/install#individual
:::success
:white_check_mark: You have successfully installed chocolatey. Now continue with [Git](#Git).
:::
### Mac: Installing brew
This can be easily done using the following command:
```bash=
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
Afterwards, run the following 2 commands to enable brew:
```bash=
(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
```
More information can be found here: https://brew.sh/
:::success
:white_check_mark: You have successfully installed brew. Now continue with [Git](#Git).
:::
# Git
To install git, please now jump to the section of your OS.
## Installing Git
### Windows
We recommend to use `winget` to install it.
To do this, open a Powershell and enter
```powershell=
winget install Git.Git
```
**Now close all your open terminals. The `git`-command will be available in a new terminal.**
:::success
:white_check_mark: You have successfully installed git. Now continue with [configuring Git](#Configuring-Git).
:::
### Linux
- Ubuntu / Debian and alike
```bash=
sudo apt-get install git
```
- Archlinux
```bash=
pacman -S git
```
- Fedora
```bash=
dnf install git
```
- CentOS
```bash=
yum install git
```
:::success
:white_check_mark: You have successfully installed git. Now continue with [configuring Git](#Configuring-Git).
:::
### Mac
Please install `git` using `brew`.
You probably need to install `brew` first.
```shell=
brew install git
```
then follow the instructions on screen.
**Now close all your open terminals. The `git`-command will be available in a new terminal.**
:::success
:white_check_mark: You have successfully installed git. Now continue with [configuring Git](#Configuring-Git).
:::
## Configuring Git
First, you have to set your username and e-mail and username.
We recommend that you use your real name and your `@stud.uni-saarland.de` e-mail address.
To do so, run:
```bash=
git config --global user.name "Your name here"
git config --global user.email "your student email here"
```
:::success
:white_check_mark: You have now configured git. Now continue with creating an SSH-Key.
:::
### Creating an SSH-Key
:::info
:information_source: You only need to create an SSH-Key if you don't already have one.
We recommend `ed25519` keys. If you're using rsa-keys, we recommend a minimum key length of 4096.
:::
After you've installed git, run the following command to generate your personal SSH-key.
```bash=
ssh-keygen -t ed25519
```
:::info
:information_source: This command will ask you a few questions. Answer them like described below:
:::
```
Enter file in which to save the key (/home/florian/.ssh/id_ed25519):
```
Press enter to keep the proposed default directory and filename (recommended)
```
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
```
Press enter for no passphrase. (2x) (recommended)
:::warning
:warning: If you do assign a passphrase, you'll have to enter it every time you do a git pull or git push (a lot of times). Keep that in mind. This procedure is safe without a password unless you plan to leave your notebook running unattended and unlocked at campus (which is not recommended).
:::
:::success
:white_check_mark: You'll need the content of this file later. Remember this location:
```
Your public key has been saved in /home/your-username/.ssh/id_ed25519.pub
```
:::
#### Copying your SSH Key to the clipboard
Now use the following command to print the contents of this file to your terminal:
```bash=
cat ~/.ssh/id_ed25519.pub
```
Copy your private key from there to your clipboard. Ctrl+C sometimes doesn't work, use right-click and select copy.
Leave this terminal open.
You will need this key in the next step.
Alternatively you can open this file using your favorite text editor and copy it from there.
:::info
:information_source: The contents of this file look **like** this:
```
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMJMQGSZXKSJCBpTWOv0AcKVjG+rLDEuXrgURxrUZO9j florian@belanna
```
Do **not** copy this string from here! This is an **example**!
:::
:::danger
:x: If you see something like this, you opened the wrong file!
```
-----BEGIN OPENSSH PRIVATE KEY-----
(...)
-----END OPENSSH PRIVATE KEY-----
```
The file without the `.pub` ending contains your **private** key.
This is what you have opened by accident here.
Do never share this file with others.
:::
:::success
:white_check_mark: You have successfully created your SSH key and copied it to your clipboard. Now continue with [adding your SSH-Key to Gitlab](#Adding-your-SSH-Key-to-Gitlab).
:::
:::info
:information_source: The default locations for your public ssh key are:
```
# Linux and MacOS
~/.ssh/id_ed25519.pub
/home/your_username/.ssh/id_ed25519.pub # the absolute path contains your username
# Windows
C:\Users\your_username\.ssh\id_ed25519.pub
```
:::
### Adding your SSH-Key to Gitlab
1) First, register at our gitlab instance.
You can omit this step if you already have an account there.
Go to https://dgit.cs.uni-saarland.de/users/sign_up
And sign up using your `@stud.uni-saarland.de` e-mail address.
:::warning
:warning: Do not forget the @stud. Student e-mail addresses look like this:
`xxzz00001@stud.uni-saarland.de`
:::
2) Make sure you are logged in to https://dgit.cs.uni-saarland.de.
3) Then go to **Preferences** -> **SSH Keys** (https://dgit.cs.uni-saarland.de/-/profile/keys)
:::success
:::
**SSH Keys**
:::success
:::
4) Klick **Add new key**
:::success
:::
5) Paste the contents of your `id_ed25519.pub` file to the **Key**-section.
If you don't have it in your clipboard anymore, check out the previous section [here](#Copying-your-SSH-Key-to-the-clipboard).
:::warning
:warning: Make sure you don't accidentally copy line breaks or add whitespaces to your key.
Keys are always one-liner. (Auto-wrapping at the max width of the field is no line break.)
Make sure you enter a **Title** and remove the **Expiration date**.
:::
:::success
:::
6) Klick **Add key**.
:::success
:white_check_mark: You've just successfully added your SSH-Key to Gitlab. Now continue with installing the Java JDK. If you've just added the SSH-Key of your **WSL** installation, [use this link](#Installing-gcc-inside-the-WSL) to get back to the gcc installation process.
:::
# Java JDK
We're going to use the Temurin JDK in Version **21** (LTS).
:::info
:information_source: We need a JDK (Java Development Kit), **not** a JRE (Java Runtime Environment).
:::
## Installing the Java JDK
To install a JDK, please jump to the section of your OS.
The general setup manual may provide some useful help and can be found here:
https://adoptium.net/installation/
### Windows
We recommend to use `winget` to install it.
To do this, open a Powershell and enter
```powershell=
winget install EclipseAdoptium.Temurin.21.JDK
```
then follow the instructions on screen.
**Now close all your open terminals. The `java`-command will be available in a new terminal.**
:::success
:white_check_mark: You've successfully installed the Java JDK. Now continue with [verifying your Java version](#Verifying-your-Java-version)
:::
### Linux
We recommend that you use your distro's package manager to install the JDK.
More instructions on this can be found at the following link.
Please make sure to install version **21**.
:::warning
:warning: Most of the commands described at the following link need to be run as root. You can become root by entering the following command: `sudo -i`. Enter your password. Follow the instructions.
:warning: This is a root shell. Don't mess with it. It has the potential to destroy your system! :warning:
:::
https://adoptium.net/installation/linux/
:::success
:white_check_mark: You've successfully installed the Java JDK. Now continue with [verifying your Java version](#Verifying-your-Java-version)
:::
### Mac
Please go to the download page and download the `.pkg` file matching your architecture.
Download page: https://adoptium.net/temurin/releases/?os=mac&package=jdk&version=21
- Macs with **M1** processor or newer use the `aarch64` pkg file.
- Macs with **Intel** processors use the `x64` pkg file.
Follow the instructions here:
https://adoptium.net/installation/macOS/
**Now close all your open terminals. The `java`-command will be available in a new terminal.**
:::success
:white_check_mark: You've successfully installed the Java JDK. Now continue with [verifying your Java version](#Verifying-your-Java-version)
:::
## Verifying your Java version
After installing the JDK and **closing all your terminals**, please verify your java version using
```bash=
java -version
```
in a **new terminal**. It should yield something like this:
```
openjdk 21.0.2 2024-01-16 LTS
OpenJDK Runtime Environment Temurin-21.0.2+13 (build 21.0.2+13-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.2+13 (build 21.0.2+13-LTS, mixed mode, sharing)
```
Check whether for the version `21.0.2` and `Temurin`.
If the output contains these strings, your version is right.
The other things will not neccessarily look like the output above.
:::success
:white_check_mark: You've just verified that your Java version is right. Now continue with setting up the [C compiler](#C-compiler).
:::
# C compiler
We will use the `gcc` C compiler.
This compiler comes in several versions.
Please use a `gcc` version of 9.4 or newer.
You can check your `gcc` version using the following command **in a new terminal**:
```bash
gcc --version
```
:::success
:white_check_mark: If this prints anything greater than 9.4, you're already good to go. In this case go ahead to set up [Mars](#Mars). Otherwise, continue here.
:::
If it prints something smaller than 9.4, your operating system may be outdated or you have updates pending. Try installing updates then.
If the command `gcc` was not found, please jump to the section matching your OS.
## Windows
Unfortunately it is a bit convoluted to install gcc on Windows.
Check out the following [comparison](#Comparison-MinGW-vs-WSL) in order to choose the right way for you. If you're unsure, which one to use, use WSL as it is close to the other platforms.
:::info
:information_source: There are two ways of using gcc on windows:
- [Use gcc in the Windows Subsystem for Linux (**WSL**)](#Windows-Subsystem-for-Linux-WSL)
- [Installing gcc using chocolatey (**MinGW**)](#Comparison-MinGW-vs-WSL)
Choose **one** way and follow the instructions for it. **Remember** the choice you took. **Do not install both!** This will only create confusion for you and your tutors.
:::
### Windows Subsystem for Linux (WSL)
#### Installing the WSL
Open a Powershell **as administrator** and run the following:
```powershell=
wsl --install --distribution ubuntu
```
Follow the instructions on screen, then **reboot** your machine.
More information on this can be found here: https://learn.microsoft.com/en-us/windows/wsl/install
**After the reboot**, you'll be asked for a username and password.
:::warning
:warning: When asked for a password in an linux environment, you can type but won't get any feedback like stars or dots as you type. Everything works as expected, you just don't see what you are typing.
:::
You can choose them freely. For usernames: keep them simple and do not use uppercase, special characters or whitespaces in them.
:::success
:white_check_mark: You've just installed the WSL. Go ahead with installing gcc inside the WSL.
:::
#### Installing gcc inside the WSL
Open a WSL Terminal.
To do so, start ubuntu from the start menu.
You are now within an ubuntu environment.
Please do the following things now:
1) **Update the ubuntu inside WSL**
To do so, please run:
```bash=
sudo apt update
sudo apt upgrade -y
```
2) **Set up Git inside WSL**
Please follow the instructions for [setting up git](#Git) until you've added the SSH-Key of your WSL to Gitlab.
Yes, you're doing it again, but this time inside the WSL.
**Please remember to come back here afterwards!** (There is a link back in the checkbox at the end of the "Adding your SSH-Key to Gitlab"-section.)
:::info
:information_source: While working within the WSL, always follow the instructions for **Ubuntu**.
:::
3) **Install gcc**
Please follow the instructions for [installing gcc on Linux (Ubuntu)](#Linux2). And read the following box.
:::success
:white_check_mark: You will successfully install gcc within the WSL. There is no need to come back here, just continue with the [Mars](#Mars) installation afterwards.
:::
### Installing gcc using chocolatey (MinGW)
:::danger
:x: Do not continue with this section if you have just set up WSL!!
!1!!111 :x:
:::
To install gcc run the following command in a Powershell **as administrator**.
:::warning
:warning: The following will not work if you do not run the terminal **as administrator**!
:::
```powershell=
choco install make mingw
```
**Now close all your open terminals. The `gcc`-command will be available in a new terminal.**
:::warning
:warning: The `gcc`-command will only be available in terminals you started after the installation.
:::
The description of the `mingw`-package can be found here: https://community.chocolatey.org/packages/mingw
:::success
:white_check_mark: You have successfully installed gcc using the MinGW method. Please go [back](#C-compiler) and check your version again. Then continue with setting up [Mars](#Mars).
:::
### Comparison MinGW vs WSL
| | MinGW | WSL |
| - | - | - |
| compiled binaries | `.exe` you can run on windows | Binaries executable only in the WSL and on Linux |
| Git setup | Only one system wide setup needed (as explained above) | Git needs to be setup in the WSL again.|
| workflow | You work within your normal Windows. You can edit files with any editor of your choice. You will use a Windows shell like cmd or PowerShell. | You open the WSL Terminal and work in there as if your OS was Ubuntu. You'll only work in WSL. You'll connect your VS Code to WSL. You keep your code in WSL and do Git actions only in WSL, either on the command line or from within VS Code. |
| compatibility | Should work on any Windows version. No issues with virtualization. | May causes issues with virtualization. May not work if you need VirtualBox working as well. |
| estimated struggle | Experience shows that MinGW causes some bonus struggle people using Linux or WSL don't have. We don't know details yet but try to do our best to keep it low and help you out. | You'll need to set up a file sharing method between the WSL and Windows. Also there is the need for a second Git setup. You may become confused of the different terminals (Windows and Linux) and be confused on which terminal to use for Git and where. |
**Conclusion:** Each method is complicated. **Take the method you're feeling most comfortable with.** There will be **support for both methods**.
If you're already familiar with WSL, use WSL.
If you are keen on writing C applications for Windows, use MinGW.
:::success
:white_check_mark: You now understand the differences of the installation methods. Please go [back](#Windows) and choose the one you want to follow.
:::
## Linux
As `gcc` is a basic tool for almost every linux distribution, it should be easy to install it.
Since we only require a version of 9.4 or newer and 9.4 was released in 2021, your distributions gcc should already be ok.
To install it, please run the matching command for your distribution:
- Ubuntu / Debian and alike
```bash=
sudo apt-get install build-essential
```
- Archlinux
```bash=
pacman -S base-devel
```
- Fedora
```bash=
dnf install make gcc
```
- CentOS
```bash=
yum install make gcc
```
:::success
:white_check_mark: You just installed gcc. Please go [back](#C-compiler) and check your gcc version again. Then continue with setting up [Mars](#Mars).
:::
## Mac
Please install `gcc` using `brew`.
You probably need to install `brew` first.
```shell=
brew install make gcc
```
**Now close all your open terminals. The `gcc`-command will be available in a new terminal.**
More information can be found here: https://formulae.brew.sh/formula/gcc#default
:::success
:white_check_mark: You just installed gcc. Please go [back](#C-compiler) and check your gcc version again. Then continue with setting up [Mars](#Mars).
:::
# Mars
Mars is just shipped as an executable java jar file.
You will need Mars in Version 4.5 for the project.
Please download it here: https://dcloud.cs.uni-saarland.de/s/3qoAc8sTzNoYqGn
Please store the `Mars4_5.jar` file somewhere, where you'll find it later.
This may be a directory you dedicated to Programming 2 course stuff.
:::info
:information_source: We recommend that you create a directory for storing all your Programming 2 course related stuff in there. It should be easily accessible.
Our recommended paths for this are:
- Windows: C:\Users\your-username\prog2
- Linux/MacOS: /home/your-username/prog2
You can easily access this directory using a terminal in both Windows and Linux/Mac OS.
To do so, open a new terminal and type: `cd prog2`.
:::
To run Mars, try double-clicking the `Mars4_5.jar` file.
If this doesn't work, open a Terminal or Powershell (**not WSL**).
Navigate to the directory in which you put `Mars4_5.jar` and start it from there:
```bash
cd prog2
java -jar Mars4_5.jar
```
This command works on all operating systems.
:::success
:white_check_mark: **The final success:** You have just successfully installed Mars and survived this guide. Congratulations, you are done.
I hope you will do well in Programming 2. I'm looking forward to seeing you there. If you do have some comments, feedback or questions, feel free to use the [forum](https://forum24.prog2.de/c/technicalities/) to let us know.
Best,
Florian
:::
# Troubleshooting
Some errors which happened and how you can probably fix them. To get further assistance, check out the [forum](https://forum24.prog2.de/c/technicalities/).
## winget not found
Thanks for trying this out, Timm.
Try to install it from the Microsoft Store using the following link:
https://apps.microsoft.com/detail/9nblggh4nns1?rtc=1&hl=de-de&gl=DE
More Infos: https://github.com/microsoft/winget-cli#microsoft-store-recommended
If this doesn't work and there is no way of getting winget to work, you can also install Git and Temurin JDK using choco with the following commands:
```powershell=
choco install git
choco install temurin
```
## git not found on winget
Thank you, Maksym.
Try this:
```powershell=
winget install Git.Git --source winget
```
## build-essentials not found
The typo was fixed, the package is called `build-essential`.
I thank all who reported this. :)
And apologize to all who had to go through the missing `sudo` issue before I fixed it.
## Java version is wrong or string does not contain "temurin"
Please check the output of
- Windows:
```powershell=
(Get-Command java).path
```
If this doesn't contain "Eclipse Adoptium", check if you have other Java versions installed and remove them.
If this didn't help, use
```powershell=
winget remove EclipseAdoptium.Temurin.21.JDK
```
to remove Temurin and follow the guide to reinstall it.
Thank you for trying this, George.
- Linux:
Run the following command and select the correct installation
```bash=
sudo update-alternatives --config java
```
## WSL issues
Try to run
```powershell=
wsl update
```