Building, testing and distributing systems

In this tutorial we guide you into installing the required tools to start using haskus-system to create your own systems, to test them within QEMU and to distribute them.

Installing dependencies

You need to install several programs and libraries before you can start using haskus-system. Most of them are very common and are required to build a Linux kernel.

Please install the following packages:

  • git

  • Stack

  • make

  • gcc

  • binutils

  • static libraries (e.g., glibc-static and zlib-static packages on Fedora)

  • (un)packing tools: lzip, gzip, tar, cpio

  • QEMU

Installing haskus-system-build tool

To get started, you need to install the haskus-system-build program. It is available on Hackage in the haskus-system-build package. You can install it from here using your favorite method or install the latest version from source as follows:

> git clone https://github.com/haskus/haskus-system.git
> cd haskus-system
> stack install haskus-system-build

Using this method will install the program into ~/.local/bin. Be sure to add this path to your $PATH environment variable.

Starting a new project

To start a new project, enter a new directory and use the init command:

> mkdir my-project
> cd my-project
> haskus-system-build init

It downloads the default system template into the current directory. It is composed of 4 files:

> find . -type f
./stack.yaml
./src/Main.hs
./my-system.cabal
./system.yaml

src/Main.hs

This the system code. For now it’s only a simple program that prints the “Hello World” string in the kernel console, waits for a key press and then shutdowns the system.

import Haskus.System

main :: IO ()
main = runSys <| do

   -- Initialize the terminal
   term <- defaultTerminal

   -- print a string on the standard output
   writeStrLn term "Hello World!"

   -- wait for a key to be pressed
   waitForKey term

   -- shutdown the computer
   powerOff_

my-system.cabal

This is the package configuration file that has been tweaked to build valid executables (use static linking, etc.)

stack.yaml

This is Stack configuration file with the required dependencies on Haskus packages.

system.yaml

This is the haskus-system-build configuration file.

linux:
   source: tarball
   version: 4.11.3
   options:
      enable:
         - CONFIG_DRM_BOCHS
         - CONFIG_DRM_RADEON
         - CONFIG_DRM_NOUVEAU
   make-args: "-j8"

ramdisk:
   init: my-system

qemu:
   # Select a set of options for QEMU:
   #  "default": enable recommended options
   #  "vanilla": only use required settings to make tests work
   profile: vanilla
   options: ""
   kernel-args: ""

As you can see, it contains a Linux kernel configuration, a reference to our system as being the ramdisk “init” program and some QEMU configuration. The selected Linux kernel will be automatically downloaded and built with the given options in the following steps.

Building and Testing

Now let’s try the system within QEMU:

> haskus-system-build test

On the first execution, this command downloads and builds everything required to test the system so it can take quite some time. Then QEMU’s window should pop up with our system running in it.

On following executions building is much faster because the tool reuses previously built artefacts (in particular the Linux kernel) if the configuration hasn’t changed.

If you only want to build without launching QEMU, use the build command:

> haskus-system-build build

Distributing and testing on real computers

This tutorial wouldn’t be complete without an exaplanation of how to distribute your system to other people. We obviously don’t want them to build it from source.

Physical distribution

You can easily distribute your system on a bootable storage device (e.g. USB stick). To do that, you only have to install your system on an empty storage device.

Warning: data on the device will be lost! Don’t do that if you don’t know what you are doing!

To install your system on the device whose device file is /dev/sde:

> haskus-system-build make-device --device /dev/sde

Note that you have to be in the sudoers list to access the device.

ISO image distribution

Another distribution method is to create an ISO image that you can distribute online or burn on CD/DVD.

> haskus-system-build make-iso
...
ISO image: .system-work/iso/my-system.iso

Note that you can test the ISO image with QEMU before you ship it:

> haskus-system-build test-iso

This allows you to test the boot-loader configuration.