Building and Running tomOSii

Requirements …

… For Building tomOSii

In order to build tomOSii, you will need

all compiled in such a way that they can

  • run on your development host,

  • but produce code to be executed on the target platform, running tomOSii. tomOSii is currently supporting x86_64 with elf executables, exclusively.

Install the above tools using your distribution’s package manager or build them from source.

… For Building the Documentation

In order to build the documentation, you will need

Install Doxygen using your distribution’s package manager or build it from source. Install Sphinx, and Breathe via Python’s pip (https://pypi.org/project/pip/). The root directory of tomOSii contains a suitable requirements.txt for this purpose.

We recommend installing the above packages into a virtual environment. In order to do so, execute the following in the root directory of tomOSii:

$ python3 -m venv ./.venv                      # create a virtual environment
$ source ./.venv/bin/activate                  # activate virtual environment
$ python3 -m pip install -r requirements.txt   # install requirements

… For Running tomOSii

In order to run tomOSii, you will furthermore need

emulating an x86_64 system.

Install it using your distribution’s package manager or build it from source.

We suggest to use

as Qemu’s display.

Install it using your distribution’s package manager or build it from source.

… For Debugging tomOSii

In order to debug tomOSii, you might want to use

compiled for running on your development host, debugging processes running on the x86_64-elf target.

Install it using your distribution’s package manager or build it from source.

… For Building and Running the Unit Tests

In order to build and run the unit tests, tomOSii requires

Install those using your distribution’s package manager or build it from source.

Building

Once all the required tools are installed properly, copy Makefile.toolchain.template in the root directory of tomOSii to Makefile.toolchain and set therein the tools and their paths accordingly. Afterwards, tomOSii can be built simply by executing the following in the root directory of tomOSii:

$ make

In order to build the documentation, execute the following in the root directory of tomOSii:

$ make doc

If the above Python packages have been installed into a virtual environment, remember to activate that virtual environment before attempting to build the documentation by executing the following in the root directory of tomOSii:

$ source ./.venv/bin/activate

The documentation will be built into $BUILD_DIR/doc/. It can be accessed there via the file index.html. BUILD_DIR can be specified in Makefile.config in the root directory of tomOSii. This defaults to build.

Running, Debugging

Once tomOSii has been successfully built, it can be run by executing the following in the root directory of tomOSii:

$ make run

If you want to run tomOSii and attach the debugger gdb to it, execute the following in the root directory of tomOSii:

$ make run-gdb

This will start tomOSii in Qemu and launch gdb. tomOSii will be run and interrupted immediately.

Testing

The unit tests are built and run by executing the following in the root directory of tomOSii:

$ make test