/Teaching/Operating Systems/Tutorials/Building SWEB

Building SWEB

Prerequisites and Installation

We assume you have read SSH Setup and therefore know where the upstream repository is and when/how to get to your own working repository which already contains the upstream repository.

The easiest way of hacking SWEB is by using Linux as development system and qemu as virtual machine for SWEB to run in. To compile and run SWEB you need the following components:

    • cmake
    • qemu (qemu-system-x86)
    • gcc (11 or newer)
    • g++ (11 or newer)
    • python

If you are using Ubuntu, all of them should be available as packages and you can install them with: sudo apt install cmake qemu-system-x86 gcc g++ python build-essential.

In addition to the software requirements, you should possess a fair amount of programming knowledge in C and C++. Basic knowledge of the x86-architecture can also come in handy at times.

Preparing your build environment

This step is not mandatory, but strongly recommended. It saves a lot of time and HDD/SSD life time.

SWEB supports compiling within the source directory or outside of the source directory. Compiling outside the source directory has several advantages (no binary files in the source directory, build environment in RAM, easy deletion of binary files with no risk of losing the source files, …).

As recommended here, we make /tmp a tmpfsdirectory (mount point). This way all data in/tmp will reside in RAM. Open /etc/fstaband look for a line containing /tmp similar to the following one:

tmpfs /tmp tmpfs nodev,nosuid 0 0

If there is no such line, add the above line to /etc/fstabbut make sure you don’t delete anything or your computer might not boot anymore.

After this change you need to restart your computer.

Compiling and running

Once you have the source code and all necessary tools, you are already ready to compile and run SWEB. Of course, it will not do anything terribly interesting, but you can verify that your toolchain is set up properly. To compile and run use

mkdir -p /tmp/sweb; cd /tmp/sweb; cmake /path/to/sourcecode/of/sweb; make; make qemu

This first creates a folder /tmp/sweb in which all object and binary files will be placed. We change into that directory and call cmake /path/to/sourcecode/of/sweb. CMake generates the Makefile we use to compile SWEB. make runs this generated Makefile and compiles SWEB. Finally make qemuopens qemu and boots into SWEB which will run the SWEB shell (see userspace/tests/stdin-test.c). If you want to use bochs instead, type make bochs, if you want to force qemu to use kvm, type make kvm.

Aside: Which emulator to use? We recommend using qemu, as it is much faster than bochs. If you want to use emulated hardware which is not provided by qemu, you can of course try using a different emulator.

Do not call cmake in-source, i.e. do not type cmake . in the source folder.

If you see other students using cmake .in the source folder, please inform them that this is not recommended.

Once you entered cmake . in the source folder, regular cmake calls (in a build folder, as described in this tutorial) will all fail. So, don’t do that. You will have to cleanup the repository by hand or by removing all untracked files with the slightly dangerous command git clean -d -x which will also remove all files that you forgot to commit. Better just don’t call cmake like this at all to avoid problems.

Using cmake . in the build folder is totally fine (once you initialized the build folder).

Compilation or pre-boot issues

In case the compilation process fails, you are getting file system errors or if you are stuck while loading GRUB, try to rebuild the entire project:

make mrproper; make; make qemu

Note that there is a difference between make mrproperand make clean.

Next Chapter

Special Environments

In order to build SWEB under Mac OS you need a cross compiler. We recommend you follow the instructions at https://github.com/GhostLyrics/homebrew-sweb. This is not the recommended method for the operating systems course! If you really feel you have to build SWEB under Mac OS, do so, but in case you run into troubles and need our help, expect answers like “try compiling under Linux”. On all operating systems, we recommend installing a RAM drive and placing the binary folder on the RAM drive to avoid frequent writes to your hard disk or solid state disk.
On Windows 10 / 11 it should be possible to build SWEB. To see the GUI you will need an X server like vcxsrv. And of course, you need to figure out how to make /tmp a real tmpfs folder to avoid killing your SSD.