-*- Text -*-

See the file `INSTALL' for suggestions on installation.


How to Start Making Sense of the Hurd Soure Code


First, examine the directory `hurd'.  Here you will find the interface
definitions for the GNU Hurd.  Start by looking at process.defs.
These calls are implemented by the process server, which you will find
in the directory `proc'.  This will give you an idea of the general 
style of code.

Then, look at the io.defs and fs.defs files.  This interface is used
for manipulating I/O objects.  The directory `ufs' implements this
interface for the ffs filesystem format.  In addition, look at
fsys.defs, which has definitions for the translator linkage mechanism.

The file `shared.h' should be read in combination with the last half
of io.defs, to understand the shared memory I/O protocol.

By now you should have looked at hurd_types.h, which lists the various
data types used by Hurd interfaces.  The hurd_types.defs file is, by
contrast, very boring and not helpful.  You also need to look at
interrupt.defs.  

Then look at exec.defs.  This is a crucial part of how exec works.
It is implemented by the exec server in the `exec' directory.

A simple, but crucial, server is the startup server, see startup.defs. 

The interface auth.defs is the all-pervasive authentication mechanism,
implemented by the program in the `auth' directory.

The msg.defs file contains various messages that are understood by
most processes.

The term.defs interface is an extension to fs.defs for terminal files.

Sockets are implemented through socket.defs.

The core.defs, kernel_boot.defs, ifsock.defs, and newterm.defs are
special cases for particular obscurities; it's not necessary to
understand them.

If you have further questions, make sure you have tried to find the
answer on your own first.  Questions which are directed at getting
major parts of the interface changed are not welcome.


A Note on Porting

Porting the Hurd is easy.  On the other hand, there are other things
you need to port in order to port the Hurd.  You need ports of the C
library (easy), the C compiler (hard), and the Mach kernel (hard).
Fortunately, there are already ports of the C compiler to any machine
you want to run the Hurd on.  There are ports of Mach available to
many machines, with good people working on ports to more.  If you want
to help with that, send mail to mach@cs.cmu.edu, who coordinate such
efforts.  We don't have the resources to deal with it right now.  The
C library needs ports to many machines.  The good news is that such
ports can be tested Right Now, even though the Hurd isn't self
hosting, because the only interesting parts of the port are in
non-Hurd generic code.  Contact roland@gnu.ai.mit.edu if you want to
port the C library to something.

Given those ports, to port the Hurd you need to make sure the C
library Hurd code has been ported; this is not too hard at all.  The
only machine dependent parts of the Hurd proper are the exception
handling mechanisnm in diskfs (which isn't being used right now
anyway, and will be in the library at some point) and boot.  Boot is a
machine and OS dependent program used to start the Hurd from an i386
UX single server.  Porting it to some other single server or a
non-i386 one should be easy to figure out.

The programs `boot' and `mkbootfs' are highly machine dependent; it
shouldn't be too much trouble to make them work on other machines than
a 386, though.  If you do this, please let me know; I'd like to
include your code.  The program `exec' contains a little machine
dependent code (in its interpretation of a.out format).  Again, if you
make this work on some other machine, please let me know.  If you find
you need to change anything else in the Hurd directory in attempting
to port, please let me know; I'd like all the rest of the code to stay
machine-independent.


