20081024-1642

3 files changed, 174 insertions, 9 deletions

diff --git a/doc/INSTALL.ms b/doc/INSTALL.ms
new file mode 100644
index 00000000..0cfecf2d
--- /dev/null
+++ b/doc/INSTALL.ms
@@ -0,0 +1,148 @@
+.\" this is an extract of port.ms: change that too if needed
+.pl 9999
+.SH
+Installing hosted Inferno from source
+.SH
+Overview
+.PP
+Like the native kernels
+.CW emu
+relies on several auxiliary libraries (the source of which
+it often shares with the native kernels).
+Emu itself is built by the
+.CW mkfile
+in the
+.CW emu
+subdirectory containing the platform-specific source for the host platform.
+Each library has its own
+.CW mkfile ;
+the various components are made in the right order by the
+.CW mkfile
+at the root of the Inferno tree.
+The
+.CW mkfile
+for each platform will also invoke
+.CW mk
+recursively to make the appropriate libraries
+for a given configuration.
+.PP
+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 \f5emu/\fP\fIplatform\fP\f5/os.c\fP, the differences
+corresponding to the different ways under Unix of implementing kernel-scheduled
+threads efficiently.
+.PP
+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 platforms, and if so are avoided.
+See
+.CW kproc
+in
+.CW emu/*/os.c .
+.PP
+Source is included for ports to HP/UX (S800 architecture),
+Solaris/386, and Unixware, in case someone wishes to take them up now,
+but we have not determined their fitness.
+.PP
+The Plan 9 hosted implementation is unusual in that it supports
+several processor types:
+.CW 386 ,
+.CW mips ,
+.CW power
+(Power PC)
+and
+.CW sparc .
+Furthermore, all versions of
+.CW emu
+can be built on any processor type, in the usual way for Plan 9.
+.PP
+Otherwise, as distributed,
+.CW emu
+for a platform can only be built when running on that platform.
+.PP
+One unusual variant makes the whole of Inferno a plug-in for Microsoft's
+Internet Explorer, giving the same environment 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
+.CW /tools/plugin
+and
+.CW /usr/internet
+within the Inferno tree; they use the version of
+.I emu
+defined by the configuration file
+.CW /emu/Nt/ie .
+.SH
+Build steps
+.PP
+All the libraries and 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 following
+in the root of the Inferno tree:
+.nr Ci 0 +1
+.de Xx
+.IP \\n+(Ci
+..
+.Xx
+Edit
+.CW 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.
+.Xx
+Run
+.CW makemk.sh
+to rebuild the
+.CW mk
+command, which is used to build everything else.
+.Xx
+Set
+.CW PATH
+(or
+.CW path
+on Plan 9)
+to include the
+.CW bin
+directory for the platform, which will now contain the
+.CW mk
+binary just built.
+On Unix, export
+.CW PATH .
+.Xx
+Then
+.CW "mk nuke"
+to remove any extraneous object files.
+.Xx
+Finally,
+.CW "mk install"
+to create and install the libraries,
+.CW limbo
+compiler,
+.CW 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
+.CW mk
+will not suffice, because it does not put the results in the search path.)
+.LP
+Doing something similar on Windows or Plan 9 currently requires the executable for
+.CW mk
+to be available in the search path,
+since there is no equivalent of
+.CW makemk.sh .
+Otherwise the procedure is the same.
+On Plan 9, of course, the host system's normal version of
+.CW mk
+should be adequate.
diff --git a/doc/port.ms b/doc/port.ms
index 0d11a578..e495101f 100644
--- a/doc/port.ms
+++ b/doc/port.ms
@@ -31,7 +31,10 @@ The source for
 .CW mk
 itself is included in
 .CW utils/mk .
-(It must be compiled manually on the initial port to a new host environment.)
+It is included ready-made in the full and source-only distributions, to make life easier.
+It must be compiled manually only on the initial port to a new host environment;
+instructions for that are given below.
+.PP
 .NH 1
 The C compilers
 .PP
@@ -189,17 +192,19 @@ with a subdirectory for each hosted platform:
 .CW FreeBSD ,
 .CW Irix ,
 .CW Linux ,
+.CW MacOSX ,
+.CW NetBSD ,
 .CW Nt
 (for all Windows platforms, including the Internet Explorer plug-in),
-.CW MacOSX ,
 .CW Plan9 ,
+.CW Solaris ,
 and so on.
 Each platform directory has a
 .CW mkfile
 and one or more configuration files of the form described by
 .I config (6).
 An executable for a particular host type is built on that host type,
-under the host's own command interpreter, not under Inferno.
+using the host's own command interpreter, not under Inferno.
 Move to the
 .CW emu
 subdirectory appropriate to that host,
@@ -220,7 +225,7 @@ Emu itself is built by the
 .CW mkfile
 in the
 .CW emu
-platform directory for the host, as described above.
+subdirectory containing the platform-specific source for the host platform.
 Each library has its own
 .CW mkfile ;
 the various components are made in the right order by the
@@ -244,6 +249,8 @@ for
 FreeBSD/386,
 Irix/mips,
 Linux/386,
+NetBSD/386,
+MacOSX/386,
 MacOSX/power,
 Plan 9,
 Solaris/sparc,
@@ -290,16 +297,26 @@ within the Inferno tree; they use the version of
 defined by the configuration file
 .CW /emu/Nt/ie .
 .PP
-All the libraries an executables can be built in a tree containing only the source code.
+All the libraries and 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 following
 in the root of the Inferno tree:
-.IP 1.
+.nr Ci 0 +1
+.de Xx
+.IP \\n+(Ci
+..
+.Xx
+Edit
+.CW 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.
+.Xx
 Run
 .CW makemk.sh
 to rebuild the
 .CW mk
 command, which is used to build everything else.
-.IP 2.
+.Xx
 Set
 .CW PATH
 (or
@@ -312,11 +329,11 @@ directory for the platform, which will now contain the
 binary just built.
 On Unix, export
 .CW PATH .
-.IP 3.
+.Xx
 Then
 .CW "mk nuke"
 to remove any extraneous object files.
-.IP 4.
+.Xx
 Finally,
 .CW "mk install"
 to create and install the libraries,
diff --git a/doc/port.pdf b/doc/port.pdf
index 3d5795ff..e4111709 100644
--- a/doc/port.pdf
+++ b/doc/port.pdf