README.md

   1 # HelenOS
   2
   3 HelenOS is a portable microkernel-based multiserver operating
   4 system designed and implemented from scratch. It decomposes key
   5 operating system functionality such as file systems, networking,
   6 device drivers and graphical user interface into a collection of
   7 fine-grained user space components that interact with each other
   8 via message passing. A failure or crash of one component does not
   9 directly harm others. HelenOS is therefore flexible, modular,
  10 extensible, fault tolerant and easy to understand.
  11
  12 ![screenshot](http://www.helenos.org/raw-attachment/wiki/Screenshots/newgui-aio.png "Screenshot")
  13
  14 HelenOS aims to be compatible with the C11 and C++14 standards, but does not
  15 aspire to be a clone of any existing operating system and trades compatibility
  16 with legacy APIs for cleaner design. Most of HelenOS components have been made
  17 to order specifically for HelenOS so that its essential parts can stay free of
  18 adaptation layers, glue code, franken-components and the maintenance burden
  19 incurred by them.
  20
  21 * [Website](http://helenos.org)
  22 * [Wiki](http://helenos.org/wiki)
  23 * [Tickets](http://www.helenos.org/report/1)
  24 * [How to contribute](http://www.helenos.org/wiki/HowToContribute)
  25
  26 ## Portability
  27
  28 HelenOS runs on eight different processor architectures and machines ranging
  29 from embedded ARM devices and single-board computers through multicore 32-bit
  30 and 64-bit desktop PCs to 64-bit Itanium and SPARC rack-mount servers.
  31
  32 ## Building
  33
  34 ### Building the toolchain
  35
  36 In order to build HelenOS, one must first build the cross-compiler toolchain
  37 (the default installation location can be overridden by specifying the
  38 `CROSS_PREFIX` environment variable) by running (example for the amd64
  39 architecture, further list of targets can be found in the `default` directory):
  40
  41 ```
  42 $ cd HelenOS/tools
  43 $ ./toolchain.sh amd64
  44 ```
  45
  46 The toolchain script will print a list of software packages that are required
  47 for the toolchain to correctly build. Make sure you install all the dependencies.
  48 Unfortunately, the script cannot install the required dependencies for you automatically
  49 since the host environments are very diverse. In case the compilation of the toolchain
  50 fails half way through, try to analyze the error message(s), add appropriate missing
  51 dependencies and try again.
  52
  53 As an example, here are some of the packages you will need for Ubuntu 16.04:
  54
  55 ```
  56 $ sudo apt install build-essential wget texinfo flex bison dialog python-yaml genisoimage
  57 ```
  58
  59 Whereas for CentOS/Fedora, you will need:
  60
  61 ```
  62 # sudo dnf group install 'Development Tools'
  63 # sudo dnf install wget texinfo PyYAML genisoimage flex bison
  64 ```
  65
  66 In case the toolchain script won't work no matter how hard you try, let us know.
  67 Please supply as many relevant information (your OS and distribution, list of
  68 installed packages with version information, the output of the toolchain script, etc.) as
  69 possible.
  70
  71 ### Configuring the build
  72
  73 Since the summer of 2019, HelenOS uses the Meson build system.
  74 Make sure you have a recent-enough version of Meson and Ninja.
  75 The safest bet is installing both using `pip3` tool.
  76
  77 ```sh
  78 $ pip3 install ninja
  79 $ pip3 install meson
  80 ```
  81
  82 Meson does not support in-tree builds, so you have to create a directory
  83 for your build. You can have as many build directories as you want, each with
  84 its own configuration. `cd` into your build directory and run `configure.sh`
  85 script which exists in the source root. `configure.sh` can be run with a profile
  86 name, to use one of the predefined profiles, or without arguments for interactive
  87 configuration.
  88
  89 ```sh
  90 $ git clone https://github.com/HelenOS/helenos.git
  91 $ mkdir -p build/amd64
  92 $ cd build/amd64
  93 $ ../../helenos/configure.sh amd64
  94 ```
  95
  96 Note: If you installed the toolchain to a custom directory, make sure `CROSS_PREFIX`
  97 environment variable is correctly set.
  98
  99 Once configuration is finished, use `ninja` to build HelenOS.
 100 Invoking `ninja` without arguments builds all binaries and
 101 debug files, but not bootable image. This is because during
 102 development, most builds are incremental and only meant to check
 103 that code builds properly. In this case, the time-consuming process of
 104 creating a boot image is not useful and takes most time. This behavior
 105 might change in the future.
 106
 107 In case you want to rebuild the bootable image, you must invoke
 108 `ninja image_path`. This also emits the name of the bootable image into the
 109 file `image_path` in build directory.
 110
 111 ```
 112 $ ninja
 113 $ ninja image_path
 114 ```
 115
 116 Now HelenOS should automatically start building.
 117
 118 ### Running the OS
 119
 120 When you get the command line back, there should be an `image.iso` file in the build
 121 root directory. If you have QEMU, you should be able to start HelenOS by running:
 122
 123 ```
 124 $ ./tools/ew.py
 125 ```
 126
 127 For additional information about running HelenOS, see
 128 [UsersGuide/RunningInQEMU](http://www.helenos.org/wiki/UsersGuide/RunningInQEMU) or
 129 [UsersGuide/RunningInVirtualBox](http://www.helenos.org/wiki/UsersGuide/RunningInVirtualBox) or
 130 see the files in tools/conf.
 131
 132 ## Contributing
 133
 134 There is a whole section of our wiki devoted to
 135 [how to contribute to HelenOS](http://www.helenos.org/wiki/HowToContribute).
 136 But to highlight the most important points, you should subscribe to
 137 our mailing list and if you have an idea for contributing, discuss it
 138 with us first so that we can agree upon the design.
 139
 140 Especially if you are a first time contributor, blindingly shooting
 141 a pull request may result in it being closed on the grounds that it
 142 does not fit well within the grand scheme of things. That would not
 143 be efficient use of time.
 144
 145 Communicating early and often is the key to successful acceptance of
 146 your patch/PR.
 147
 148 ## License
 149
 150 HelenOS is open source, free software. Its source code is available under
 151 the BSD license. Some third-party components are licensed under GPL.