README.md

   1 HelenOS Continuous Integration Testing Scripts
   2 ==============================================
   3
   4 The purpose of this repository is to have a universal script for building
   5 and testing (almost) everything related to HelenOS. Currently, the script
   6 is able to:
   7
   8  * fetch latest versions of HelenOS and harbours (ported software)
   9  * build HelenOS for all supported architectures
  10  * build all harbours (the full matrix)
  11  * run automated tests in QEMU (selected platforms only)
  12
  13 See http://www.helenos.org/wiki/CI for more information. Nightly builds
  14 using this tool are pushed to http://ci.helenos.org/.
  15
  16 **Note:** this tool is not meant to be used for normal development of
  17 HelenOS (i.e. the "edit - incrementally compile - test" loop) but rather
  18 for pre-merge tests or automated nightly builds.
  19
  20
  21 Running
  22 -------
  23
  24 ```shell
  25 # Fetch default branches and build everything.
  26 ./build.py
  27
  28 # Limit paralellism
  29 ./build.py --jobs 3
  30
  31 # Fetch from non-default branches
  32 ./build.py --helenos-repository git@github.com:login/helenos.git
  33 ```
  34
  35 Tests
  36 -----
  37
  38 The tests are executed in QEMU and it is possible to type text
  39 into console and assert for command output.
  40
  41 See scripts in `scenarios/` directory for examples or the `test-in-vm.py`
  42 script to learn about internals.
  43
  44 ```text
  45 usage: test-in-vm.py [-h] [--headless] [--scenario FILENAME.yml] --arch
  46                      ARCHITECTURE [--memory MB] --image FILENAME
  47                      [--pass OPTION] [--vterm-dump FILENAME.txt]
  48                      [--last-screenshot FILENAME.png] [--debug]
  49
  50 Testing of HelenOS in VM
  51
  52 optional arguments:
  53   -h, --help            show this help message and exit
  54   --headless            Do not show any VM windows.
  55   --scenario FILENAME.yml
  56                         Scenario file
  57   --arch ARCHITECTURE   Emulated architecture identification.
  58   --memory MB           Amount of memory for the virtual machine.
  59   --image FILENAME      HelenOS boot image (e.g. ISO file).
  60   --pass OPTION         Extra options to pass through to the emulator
  61   --vterm-dump FILENAME.txt
  62                         Where to store full vterm dump.
  63   --last-screenshot FILENAME.png
  64                         Where to store last screenshot.
  65   --debug               Print debugging messages
  66
  67 Typical invocation will use the following arguments:
  68   --image helenos.iso
  69   --scenario scenario.yml
  70   --arch amd64               # ia32, ppc32 etc.
  71   --vterm-dump dump.txt      # all text from main vterm
  72   --last-screenshot shot.png # last VM screen
  73 ```
  74
  75 Simple test running malloc and checking its output looks like this:
  76
  77 ```yml
  78 meta:
  79   name: "tester malloc"
  80   harbours: []
  81
  82 tasks:
  83   - boot
  84   - command:
  85       args: "tester malloc1"
  86       assert:  "Test passed"
  87       negassert: "Test failed"
  88 ```
  89
  90
  91 Test checking that we are able to launch GCC (needs special image):
  92
  93 ```yml
  94 meta:
  95   name: "gcc --version"
  96   harbours:
  97      - gcc
  98
  99 tasks:
 100   - boot
 101   - command:
 102       args: "gcc --version"
 103       assert:  "GCC"
 104 ```