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 HelenOS aims to be compatible with the C11 and C++14 standards, but does not
  13 aspire to be a clone of any existing operating system and trades compatibility
  14 with legacy APIs for cleaner design. Most of HelenOS components have been made
  15 to order specifically for HelenOS so that its essential parts can stay free of
  16 adaptation layers, glue code, franken-components and the maintenance burden
  17 incurred by them.
  18
  19 * [Website](http://helenos.org)
  20 * [Wiki](http://helenos.org/wiki)
  21 * [Tickets](http://www.helenos.org/report/1)
  22 * [How to contribute](http://www.helenos.org/wiki/HowToContribute)
  23
  24 ## Portability
  25
  26 HelenOS runs on seven different processor architectures and machines ranging
  27 from embedded ARM devices and single-board computers through multicore 32-bit
  28 and 64-bit desktop PCs to 64-bit Itanium and SPARC rack-mount servers.
  29
  30 ## Building
  31
  32 ### Building the toolchain
  33
  34 In order to build HelenOS, one must first build the cross-compiler toolchain
  35 (either as a root or by specifying the `CROSS_PREFIX` environment variable)
  36 by running (example for the amd64 architecture, further list of targets can be
  37 found in the `default` directory):
  38
  39 ```
  40 $ cd HelenOS/tools
  41 $ ./toolchain.sh amd64
  42 ```
  43
  44 The toolchain script will print a list of software packages that are required
  45 for the toolchain to correctly build. Make sure you install all the dependencies.
  46 Unfortunately, the script cannot install the required dependencies for you automatically
  47 since the host environments are very diverse. In case the compilation of the toolchain
  48 fails half way through, try to analyze the error message(s), add appropriate missing
  49 dependencies and try again.
  50
  51 As an example, here are some of the packages you will need for Ubuntu 12.10 (may be out of date):
  52
  53 ```
  54 $ sudo apt-get install build-essential libgmp-dev libmpfr-dev ppl-dev libmpc-dev zlib1g-dev texinfo libtinfo-dev xutils-dev
  55 ```
  56
  57 Whereas for CentOS/Fedora, you will need:
  58
  59 ```
  60 # sudo dnf group install 'Development Tools'
  61 # sudo dnf install wget texinfo libmpc-devel mpfr-devel gmp-devel PyYAML genisoimage
  62 ```
  63 In case the toolchain script won't work no matter how hard you try, let us know.
  64 Please supply as many relevant information (your OS and distribution, list of
  65 installed packages with version information, the output of the toolchain script, etc.) as
  66 possible.
  67
  68 ### Configuring the build
  69
  70 Go back to the source root of HelenOS and start the build process:
  71
  72 ```
  73 $ cd ..
  74 $ make PROFILE=amd64
  75 ```
  76
  77 Now HelenOS should automatically start building.
  78
  79 Note: If you installed the toolchain to a custom directory, make sure `CROSS_PREFIX`
  80 environment variable is correctly set.
  81
  82 ### Running the OS
  83
  84 When you get the command line back, there should be an `image.iso` file in the source
  85 root directory. If you have QEMU, you should be able to start HelenOS by running:
  86
  87 ```
  88 $ ./tools/ew.py
  89 ```
  90
  91 For additional information about running HelenOS, see
  92 [UsersGuide/RunningInQEMU](http://www.helenos.org/wiki/UsersGuide/RunningInQEMU) or
  93 [UsersGuide/RunningInVirtualBox](http://www.helenos.org/wiki/UsersGuide/RunningInVirtualBox) or
  94 see the files in tools/conf.
  95
  96 ## License
  97
  98 HelenOS is open source, free software. Its source code is available under
  99 the BSD license. Some third-party components are licensed under GPL.