20070320-0955

1 files changed, 80 insertions, 0 deletions

diff --git a/INSTALL b/INSTALL
new file mode 100644
index 00000000..7f86204c
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,80 @@
+Installing hosted Inferno from source
+
+First change mkconfig to reflect your host environment,
+specifically ROOT (which must be an absolute path name), SYSHOST and OBJTYPE.
+
+     Like the native kernels  _eeee_mmmm_uuuu relies on  several  auxil-
+iary libraries (the source of which it often shares with the
+native kernels).  Emu itself is built by the  _mmmm_kkkk_ffff_iiii_llll_eeee in the
+_eeee_mmmm_uuuu  platform  directory  for  the host, as described above.
+Each library has its own  _mmmm_kkkk_ffff_iiii_llll_eeee; the various components are
+made  in  the  right order by the  _mmmm_kkkk_ffff_iiii_llll_eeee at the root of the
+Inferno tree.  The   _mmmm_kkkk_ffff_iiii_llll_eeee  for  each  platform  will  also
+invoke  _mmmm_kkkk 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,  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 struc-
+ture.   POSIX  threads  have often been found to be insuffi-
+cient (poorly implemented) on some platforms, and if so  are
+avoided.  See  _kkkk_pppp_rrrr_oooo_cccc in  _eeee_mmmm_uuuu/*/_oooo_ssss._cccc.
+
+     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:  _3333_8888_6666,  _mmmm_iiii_pppp_ssss,  _pppp_oooo_wwww_eeee_rrrr (Power
+PC) and  _ssss_pppp_aaaa_rrrr_cccc.  Furthermore, all versions of   _eeee_mmmm_uuuu  can  be
+built on any processor type, in the usual way for Plan 9.
+
+     Otherwise, as distributed,  _eeee_mmmm_uuuu 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  /_tttt_oooo_oooo_llll_ssss/_pppp_llll_uuuu_gggg_iiii_nnnn and    /_uuuu_ssss_rrrr/_iiii_nnnn_tttt_eeee_rrrr_nnnn_eeee_tttt  within  the
+Inferno  tree;  they  use the version of  _eeee_mmmm_uuuu defined by the
+configuration file  /_eeee_mmmm_uuuu/_NNNN_tttt/_iiii_eeee.
+
+     All the libraries an executables can be built in a tree
+containing only the source code.  To do that for a supported
+variant of hosted Inferno, on Unix or Plan 9, do the follow-
+ing in the root of the Inferno tree:
+
+1.   Run  _mmmm_aaaa_kkkk_eeee_mmmm_kkkk._ssss_hhhh to rebuild the   _mmmm_kkkk  command,  which  is
+     used to build everything else.
+
+2.   Set  _PPPP_AAAA_TTTT_HHHH (or  _pppp_aaaa_tttt_hhhh on Plan 9)  to  include  the    _bbbb_iiii_nnnn
+     directory for the platform, which will now contain the
+     _mmmm_kkkk binary just built.  On Unix, export  _PPPP_AAAA_TTTT_HHHH.
+
+3.   Then  _mmmm_kkkk _nnnn_uuuu_kkkk_eeee to remove any extraneous object files.
+
+4.   Finally,    _mmmm_kkkk  _iiii_nnnn_ssss_tttt_aaaa_llll_llll  to  create  and  install   the
+     libraries,    _llll_iiii_mmmm_bbbb_oooo  compiler,  _eeee_mmmm_uuuu 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   _mmmm_kkkk 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    _mmmm_kkkk  to be available in the
+search path, since there is no  equivalent  of    _mmmm_aaaa_kkkk_eeee_mmmm_kkkk._ssss_hhhh.
+Otherwise  the procedure is the same.  On Plan 9, of course,
+the host system's normal version of  _mmmm_kkkk should be adequate.