INSTALL

Installing hosted Inferno from source

Overview

     Like the native kernels  emu relies on  several  auxil-
iary libraries (the source of which it often shares with the
native kernels).  Emu itself is built by the  mkfile in the
emu subdirectory containing the platform-specific source for
the host platform.  Each library has its own    mkfile;  the
various  components  are  made  in  the  right order by the
mkfile at the root of the Inferno tree.   The    mkfile  for
each  platform  will also invoke  mk recursively to make the
appropriate libraries for a given configuration.

     The Unix emu variant generally is  covered  by  `POSIX'
(with  common  extensions)  but  each Unix port has one file
that   differs   considerably   for   each   port,    namely
emu/platform/os.c, the differences corresponding to the dif-
ferent ways  under  Unix  of  implementing  kernel-scheduled
threads efficiently.

     There  are  working  emu  versions   for   FreeBSD/386,
Irix/mips,  Linux/386, NetBSD/386, MacOSX/386, MacOSX/power,
Plan 9, Solaris/sparc, and Windows (NT,  2000  and  Explorer
plug-in).   Each platform typically uses mechanisms specific
to the host operating system to implement Inferno's internal
thread/process  structure.   POSIX  threads  have often been
found to be insufficient (poorly implemented) on some  plat-
forms, and if so are avoided.  See  kproc in  emu/*/os.c.

     Source is included for ports to HP/UX  (S800  architec-
ture),  Solaris/386, and Unixware, in case someone wishes to
take them up now, but we have not determined their fitness.

     The Plan 9 hosted implementation is unusual in that  it
supports several processor types:  386,  mips,  power (Power
PC) and  sparc.  Furthermore, all versions of   emu  can  be
built on any processor type, in the usual way for Plan 9.

     Otherwise, as distributed,  emu for a platform can only
be built when running on that platform.

     One unusual variant makes the whole of Inferno a  plug-
in  for Microsoft's Internet Explorer, giving the same envi-
ronment for Inferno applications running in an HTML page  as
is  provided by hosted or native Inferno.  That is, there is
not a distinct `applet' environment with special programming
interfaces.   The  source for the various plug-in components
is found in  /tools/plugin and    /usr/internet  within  the
Inferno  tree;  they  use the version of  emu defined by the
configuration file  /emu/Nt/ie.

Build steps

     All the libraries and executables can  be  built  in  a
tree containing only the source code.  To do that for a sup-
ported variant of hosted Inferno, on Unix or Plan 9, do  the
following in the root of the Inferno tree:

1    Edit    mkconfig  to  reflect  your  host  environment,
     specifically  ROOT  (which  must  be  an  absolute path
     name), SYSHOST and OBJTYPE.  The comments in  the  file
     should help you choose.

2    Run  makemk.sh to rebuild the   mk  command,  which  is
     used to build everything else.

3    Set  PATH (or  path on Plan 9)  to  include  the    bin
     directory for the platform, which will now contain the
     mk binary just built.  On Unix, export  PATH.

4    Then  mk nuke to remove any extraneous object files.

5    Finally,    mk  install  to  create  and  install   the
     libraries,    limbo  compiler,  emu for hosted Inferno,
     and auxiliary commands.  The rules do that in an  order
     that ensures that the commands or libraries needed by a
     later stage are built and installed first.  (Note  that
     a  plain   mk will not suffice, because it does not put
     the results in the search path.)

Doing something similar  on  Windows  or  Plan  9  currently
requires  the  executable  for    mk  to be available in the
search path, since there is no  equivalent  of    makemk.sh.
Otherwise  the procedure is the same.  On Plan 9, of course,
the host system's normal version of  mk should be adequate.