README

The GNU Hurd
============

This is not the GNU Hurd.  But it might become it at some day.

Although this is called the Hurd on L4, L4 is only used as a hardware
abstraction: the kernel is Viengoos and no features of L4 are relied
on in a manner inconsistent with Viengoos' design.  If the design
proves tenable and is accepted by the community, the L4 dependency
will eventually be removed.


How to build
------------

You need at least automake 1.9 and autoconf 2.57.

To build the documentation, you also need pdflatex and some supporting
packages.  On Ubuntu Hardy (probably pretty much the same for Debian
and other Ubuntu systems), you'll need these packages installed for
the documentation build to succeed:

  * texlive-fonts-recommended
  * texlive-latex-base
  * texlive-latex-extra
  * texlive-latex-recommended
  * texlive-science


Building the code is straightforward:

$ autoreconf -i
$ mkdir test build
$ cd test/
$ ../configure --enable-l4 --host=i686-pc-viengoos-gnu \
	--enable-tests
$ make check
$ cd ../build/
$ ../configure --enable-l4 --host=i686-pc-viengoos-gnu \
	--with-newlib
$ make [to build the cross compiler]
$ make [to build Viengoos proper]
$ mkdir /l4/boot
$ install -s laden/laden /l4/boot
$ install -s viengoos/viengoos /l4/boot
$ install -s hieronymus/hieronymus /l4/boot

When configuring, you can use --enable-runtime-checks=N, 0 <= N <= 3,
to control which run-checks are executed.  Level 3 includes very
expensive consistency checks; level 0 disables all consistency checks,
the trace buffer and all debugging output except that at level 0.


If you happen to be on a multi-processor system, you can run ``make -j'' to
have several target be built in parallel.  This may save some time.  It might
even shorten the building time on one-processor system.  (No specific
measurements exist currently.)


Documentation
-------------

A ``Viengoos Developer Reference'' is available in the `doc' subdirectory.  A
PDF will be created during the build process if pdflatex is found.

Also, the header files are a good source of documentation.


L4
--

Viengoos uses Pistachio as a hardware abstraction.

Download Pistachio by cloning upstream's mercurial repository.  You
can find instructions on how to do this at:

	http://www.l4ka.org/projects/pistachio/download.php

Enter the kernel directory and run `make' to set up a build
environment.  Configure the source.  Select your platform.  Optionally
enabled the kernel debugger.  And, be sure to enable the following
option:

  Kernel -> Experimental Features -> Pager ExchangeRegisters

You'll also need to build sigma0.  It is in the user
directory.

sigma0 must be built with a different link base from the default
(0x20000), because this conflicts with GRUB.  I have successfully used
a link base of 0x40000.  Use the configure option
--with-s0-linkbase=0x40000 when configuring the user space of the L4
distribution.

You only need the ia32-kernel and sigma0 binary from the L4
distribution.  You may want to install the other programs and
utilities as well to test your L4 kernel, though.


Booting
-------

GRUB can boot Viengoos.  Set up GRUB to boot laden as the kernel, and
load the L4 kernel, sigma0, viengoos and hieronymus as modules (in
that order).

Try the debug option to laden (-D) and viengoos (-D 3) to see some
output from them.  They are relatively silent by default.

Here is an example menu.lst file for GNU GRUB:

title Viengoos
root (hd0,0)
kernel /boot/laden -D
module /boot/ia32-kernel
module /boot/sigma0
module /boot/viengoos -D 3
module /boot/hieronymus -D 3


Using the Cross-Compiler
------------------------

Does the package you want to cross-compile use the GNU build system
(`configure' script)?  If not, then...  If yes, then proceed as follows.  Do
something like ``PATH=$PATH:/where/the/viengoos/build/is/bin'' to make sure
that `i686-pc-viengoos-gnu-gcc' can be found via `$PATH'.  As the master GNU
system-guessing scripts don't know about Viengoos (yet), you have to link the
package's `config.guess' and `config.sub' to the Viengoos ones.  That's what
`fix_config_guess_and_sub' (see `Makefoo.am') does, used in
`newlib/Makefile.am', for example.  After that, configuring the to-be-built
package with ``--host=i686-pc-viengoos-gnu'' is all that *should* be needed,
for a portable package.  Otherwise you'll see things explode.