

    These notes are intended to help you get the X11 server running on your
Apollo system.  They also contain some hints to help you with the other
components of the X11 software.  We assume you are familiar with the structure
of the X system; ideally you have experience with Version 10 of X, or prior
versions of X11.


SYSTEM REQUIREMENTS
-------------------

    Hardware requirements:  An Apollo node with keyboard 2 or 3, including a
mouse.

    Software requirements:  At least SR9.6.  SR9.5 is no longer adequate.

    Software considerations:

    If you are running SR9.6, you may have trouble with using local TCP/IP
connections, due to a TCP/IP bug.

    Whether you are running SR9.6 or SR9.7, you may have trouble with the C
preprocessor (/usr/lib/cpp), if you use the imake utility program (this is not
required).

    We have provided a tape from the Apollo user group, ADUS, based on X.V11R1,
which contains a better SR9.6 /lib/streams (for the TCP/IP bug), and a set of
makefiles which have been customized for Apollo, in addition to already-made
binaries.  We expect to do this again for X.V11R2, though we cannot now say when
this tape will be available.

    This implementation of the server runs in color on Apollo color displays. 
On monochrome displays it is still the typical "dumb monochrome" port.  You can
also choose to run the monochrome version on a color display via use of command
line options to the server; see the Xapollo(8) man page for details.  The color
code uses Apollo native graphics calls.


GETTING ORIENTED
----------------

    Top level directories are:

        clients         client program sources
        demos           demo client program sources
        doc             documentation
        extensions      code for portable extensions
        fonts           sources and compiler sources for server fonts
        hacks           client programs classified as hacks
        include         include files needed by both client and server code
        lib             code for various client-side libraries
        server          code for sample server
        util            utility programs for building and maintaining X11

You should be familiar especially with the documents in 'doc/Server'.  Also, two
entries in 'util' should be noted:  'imake' is a tool to create a consistent set
of makefiles from common templates; and 'makedepend' is a tool to construct or
reconstruct make file dependency lists.


HOW TO BUILD IT
---------------

    Unless you can come up with a C preprocessor which does not exhibit the bugs
that the Apollo one does, do not bother to make or run the 'imake' tool in the
'util/imake' directory.  In any case this is not strictly necessary; the
VAX-oriented makefiles that exist already will work pretty well.  If you can
come up with a good cpp, and you really wish to customize the makefiles, you can
take a stab at imake.

    Next, make the 'makedepend' tool in the 'util/makedepend' directory.

Doing makes
-----------

    Only if you have made an imake with a good cpp should you (at the top level)
do a 'make Makefiles'; this runs 'imake' on everything.

    Before running make on any part of the X11 code, do a 'make depend'.
This will update the dependencies part of the file to not spuriously
refer to some header files non-existent on DOMAIN/IX, and to refer to all
header files actually depended on.

    When everything is finally built, you will have to find a home in your
file system for the executables and other runtime files.  We suggest
not using '/usr/new' if you have X Version 10, to avoid confusion over
what version of X a program is for.  Version 10 and Version 11 are
completely incompatible.  The default homes for fonts and the RGB database
for X11 will be in '/usr/lib/X11'.

    The code falls into two categories, client side and server side.  The
top level directories 'lib' and 'clients' are client side code.  They should
be made in that order.  In parallel with this, you can make the server side
code, in the directories 'fonts' and 'server'.  More details on server side
building follow; client side notes follow them.

Making the server
-----------------

    There are Apollo-specific entries in 'server/include/servermd.h' which
specify bit order, byte order, and pad boundaries for characters in fonts.
The latter of these is set to 2 (i.e. character glyphs start on word
boundaries), but it can be changed to 1 or 4.  1 makes font files smaller
but prevents them from working on non-68020 systems, since the server will
get odd address errors.  4 makes them bigger; it may improve text drawing
performance somewhat (on monochrome only; color uses Apollo native text
primitives).  The font compiler and the server/ddx/mfb code must be compiled
with the same version of this header file!

    To make the fonts that the server will use, you must compile them from
their source forms.  First, make the font compiler in 'fonts/compiler'.  After
building the font compiler, run it on each of the font sources in 'fonts/bdf',
redirecting its output to the 'fonts/snf' directory.  All this is actually
controlled by 'fonts/Makefile'.

    The Apollo server itself uses code from the following directories:

    server/os/4.2bsd
    server/dix
    server/ddx/snf
    server/ddx/mi
    server/ddx/mfb
    server/ddx/apollo
    server/ddx/apollo/apc

    Only these directories need to be built.  (They depend on the include
files in 'include' and 'server/include', of course.  Also, there is a directory
server/ddx/apollo/include which contains specific versions of some Apollo system
include files.  DO NOT copy these to the node's /sys/ins directory, leave them
where they are!)

    By default, the switcher feature of the Apollo server (see the Xapollo(8)
man page) is included.  It is controlled by the symbol SWITCHER, whose
definition you can take out of the Imakefile or Makefile if you want to build a
server without this feature for some reason.

    In 'server/include/site.h' are definitions for pathnames for fonts and
the color database.  You may wish to decide where these things will live
now, so you can edit this file if necessary.  If you decide differently
later, you will need to re-edit this file and remake the server, or always
supply server command line options to override the defaults.

    Now you can go to the 'server' directory and type 'make Xapollo'.


Making the client side code
---------------------------

    The Xlib code, the basic subroutine library interface to the protocol for
clients written in C, resides in 'lib/X'.

    Xlib requires nothing special; you can just make it.  This takes a long
time, especially if you let it compile everything twice in order to make both
debuggable and non-debuggable versions.  You may want to change the Imakefile
or Makefile to make only one flavor of object file.

    Some routines to assist porting from X10 are in 'lib/oldX'; you may wish
to make this library as well.  Some code in 'demos' may use it.  Also,
'lib/oldXMenu' has a version of the X10 XMenu library which you may want.

    In the 'lib/Xtk' directory, there is a change.  'Load.c' cannot be made
to work on Apollos, since it relies on '/dev/kmem'; it's best to just remove
references to 'Load.[co]' from the Imakefile or Makefile.

    The toolkit code may or may not refer to /usr/include/string.h instead of
/usr/include/strings.h, which is what it really wants.  If you don't have
the former, you may wish to make a link of that name to the latter, or make
a version of the former which #include's the latter, or something.

    Now the toolkit can be made.

    Finally, you can make the client programs.  Note that 'xload' wants to use
the routines from 'lib/Xtk/Load.c', which is not available on Apollos as
explained above, so an Apollo version of 'xload' isn't useful.


HOW TO INSTALL IT
-----------------

    Copy the compiled font files in 'fonts/snf' to wherever you said they would
live in 'server/include/site.h'.  The server is in 'server/Xapollo'; it will now
run.  Client programs are in their respective subdirectories of 'clients',
'demos' or 'hacks'.  Put these executables wherever is convenient.


HOW TO RUN IT
-------------

    You must have TCP/IP installed and running.

    The server borrows the entire display.  Therefore, there are three
approaches to debugging and running it.  One is to get a dumb terminal and run
a shell to invoke the server from it.  Another is to /com/crp or rlogin to the
node that will run the server from a different node, preferably right next to
it.  The last is to make shell scripts that will run the server, sleep for long
enough to let it initialize itself, and then run some clients.  This last
approach requires the least hardware, but requires working more-or-less blind,
until you have a working server and xterm(1) running.  (Once the server is known
to work, the xinit(1) program is a more convenient way to get the server and
a login xterm(1) running.)

    There is a new feature in Release 2 called the switcher, which makes some
of the above awkwardness unnecessary.  See the Xapollo(8) man page for details.

    See the Xapollo(8) man page for options, keyboard information, etc.

    When running a client program, the environment variable DISPLAY should be
set, although some clients allow the display to be specified on the command line
as well.  In the case of the C shell, you should say:

    setenv DISPLAY <host-name-of-server-node>:0

    Since the selection of fonts is probably not identical to what it was for
V10, you might want to check any ~/.Xdefaults or ~/.uwmrc files left over from
V10 to be sure you are not trying to use non-existent fonts.

    In order to establish a connection from a remote client, the name of the
host running the client program must exist as an entry in the server's file
'/etc/X0.hosts'; this is the list of "trusted" hosts.  This pathname is
constructed in 'server/os/4.2bsd/access.c', routine ResetHosts.  The 'xhost'
client program will also add a host to the list of trusted hosts, until the
server resets itself.

    If you have the unofficial UDS support code (the uds type manager), a client
can use it to establish a connection to the local server via use of the display
named "unix:0".
