Setting-Up-the-Lab-Environment.md

@@ -69,14 +69,49 @@ You can now try running SyncSim:
 ```bash
 java -jar SyncSim.jar --mips
 ```
-If SyncSim starts successfully, congratulations, you are ready to start working on [lab0a](https://vesuvio-git.neteq.ltu.se/d0013e-microcomputer-engineering/lab0a). If it doesn't, let us know on Discord or at a lab session.
+If SyncSim starts successfully, then it has been set up correctly.
+
+To get started on [`lab0a`](https://vesuvio-git.neteq.ltu.se/d0013e-microcomputer-engineering/lab0a), start by browsing to the `lab0a` page. Clicking the `Fork` button will create your own copy of the lab online.
+
+NOTE: From now on any text in angle brackets (`<` and `>`) denotes parts of the commands that are specific to you. Replace the text with what is being asked for (without the brackets).
+
+Once you have forked the `lab0a` repository, you will end up on your own personal `lab0a` repo webpage (in my case, since my gitlab username is `pawdzi-7`, it's https://vesuvio-git.neteq.ltu.se/pawdzi-7/lab0a/ ). From here, press the blue `Code` button and copy the address under `Clone with HTTPS` .
+
+Now, open a terminal window and run the command 
+```bash
+git clone <THE COPIED ADDRESS HERE>
+```
+This will download your lab files to your machine.
+
+You should (assuming you haven't changed your lab repo name to something else than lab0a) now be able to run
+```bash
+cd lab0a
+```
+This will move you into your lab directory. If you have followed all of the previous steps, you should be able to run
+```bash
+make
+``` 
+to compile the lab. If everything is set up correctly, you should see something like this:
+```bash
+compiling using mips-linux-gnu-
+mips-linux-gnu-as -march=r3k -O0 lab0a.s -o test.o
+mips-linux-gnu-ld -T linker_script test.o -o a.out
+mips-linux-gnu-objdump -h -z -s -d -t a.out > mips_program.objdump
+rm test.o
+```
+
+After successfully running `make`, a `mips_program.objdump` will appear in your `lab0a` directory. This is the file you should open with SyncSim. Once the file is opened, you can open the  Code View by double clicking the Instruction Memory component, and verify that some code has been loaded (for a `lab0a` without any changes that should be a couple of labels (`_start:` and `breakx:`), some `nop` instructions and a `stop:` label with a `b 1c <stop>`. You are now ready to start working on the labs!
+
+NOTE: Each time you make changes to the source code of your program you will need to rerun `make` to recompile your program. The workflow here uses `lab0a` as an example but applies to all of the labs (with the exception of `lab4` where we will also compile some Rust code.)
+
+If you experience issues along the way, let us know in the Discord or during a lab session. One of us is available pretty much at all times.
 
 NOTE: For us to be able to help you we need to know what you're trying to do and what response you're getting from the computer. "It's not working" is difficult to work with, instead tell us which command you're trying to run and what output you are getting.
 
 
 ## Windows
 
-Assuming you've followed the [WSL guide](https://vesuvio-git.neteq.ltu.se/d0013e-microcomputer-engineering/info/-/wikis/How%20to%20Linux%20in%20Windows) successfully, you should be able to follow the Ubuntu Linux guide [here](#ubuntu)
+Assuming you've followed the [WSL guide](https://vesuvio-git.neteq.ltu.se/d0013e-microcomputer-engineering/info/-/wikis/How%20to%20Linux%20in%20Windows) successfully, you should be able to follow the Ubuntu Linux guide (and eventually the General Linux guide) [here](#ubuntu)
 
 ## macOS
 
@@ -123,7 +158,52 @@ You can now try running SyncSim:
 ```bash
 java -jar SyncSim.jar --mips
 ```
-If SyncSim starts successfully, congratulations, you are ready to start working on [lab0a](https://vesuvio-git.neteq.ltu.se/d0013e-microcomputer-engineering/lab0a). If it doesn't, let us know on Discord or at a lab session.
+If SyncSim starts successfully, then it has been set up correctly.
+
+To get started on [`lab0a`](https://vesuvio-git.neteq.ltu.se/d0013e-microcomputer-engineering/lab0a), start by browsing to the `lab0a` page. Clicking the `Fork` button will create your own copy of the lab online.
+
+NOTE: From now on any text in angle brackets (`<` and `>`) denotes parts of the commands that are specific to you. Replace the text with what is being asked for (without the brackets).
+
+Once you have forked the `lab0a` repository, you will end up on your own personal `lab0a` repo webpage (in my case, since my gitlab username is `pawdzi-7`, it's https://vesuvio-git.neteq.ltu.se/pawdzi-7/lab0a/ ). From here, press the blue `Code` button and copy the address under `Clone with HTTPS` .
+
+Now, open a terminal window and run the command 
+```bash
+git clone <THE COPIED ADDRESS HERE>
+```
+This will download your lab files to your machine.
+
+You should (assuming you haven't changed your lab repo name to something else than lab0a) now be able to run
+```bash
+cd lab0a
+```
+This will move you into your lab directory. If you have followed all of the previous steps, you should be able to run
+```bash
+make
+``` 
+to compile the lab. If everything is set up correctly, you should see something like this:
+```bash
+compiling using mips-elf-
+mips-elf-as -march=r3k -O0 lab0a.s -o test.o
+mips-elf-ld -T linker_script test.o -o a.out
+mips-elf-objdump -h -z -s -d -t a.out > mips_program.objdump
+rm test.o
+```
+
+After successfully running `make`, a `mips_program.objdump` will appear in your `lab0a` directory. This is the file you should open with SyncSim. Once the file is opened, you can open the  Code View by double clicking the Instruction Memory component, and verify that some code has been loaded (for a `lab0a` without any changes that should be a couple of labels (`_start:` and `breakx:`), some `nop` instructions and a `stop:` label with a `b 1c <stop>`. You are now ready to start working on the labs!
+
+NOTE: Each time you make changes to the source code of your program you will need to rerun `make` to recompile your program. The workflow here uses `lab0a` as an example but applies to all of the labs (with the exception of `lab4` where we will also compile some Rust code.)
+
+If you experience issues along the way, let us know in the Discord or during a lab session. One of us is available pretty much at all times.
+
+NOTE: For us to be able to help you we need to know what you're trying to do and what response you're getting from the computer. "It's not working" is difficult to work with, instead tell us which command you're trying to run and what output you are getting.
+
+### Known issues on macOS
+
+#### SyncSim returns `Error message: DataMemory: Could not find line 'Sections:' in 'mips_program.objdump'`
+In some cases, the `.objdump` file is generated in Swedish (or some other language). For now this issue can be resolved by opening the `.objdump` file in a text editor and replacing instances of `sektion` (assuming Swedish) with `section`.
+
+
+
 
 ### SDE toolchain (legacy)
 In case the above steps do not work, you can try using the tried and true (albeit deprecated) SDE toolchain. The instructions below should work under Ubuntu Linux (so, also default WSL), and similar Debian based distributions.