Return to README CVS log

Up to [Research Unix] / researchv9 / X11 / src / X.V11R1 / server / ddx / apollo

Annotation of researchv9/X11/src/X.V11R1/server/ddx/apollo/README, revision 1.1

1.1     ! root        1: 
        !             2: 
        !             3:     These notes are intended to help you get the X11 server running on your
        !             4: Apollo system.  They also contain some hints to help you with the other
        !             5: components of the X11 software.  We assume you are familiar with the structure
        !             6: of the X system; ideally you have experience with Version 10 of X, or prior beta
        !             7: versions of X11.
        !             8: 
        !             9: SYSTEM REQUIREMENTS
        !            10: -------------------
        !            11: 
        !            12:     Hardware requirements:  An Apollo node with keyboard 2 or 3, including a
        !            13: mouse.
        !            14: 
        !            15:     Software considerations:
        !            16: 
        !            17:     If you are running SR9.5.1, you may have trouble with the following software
        !            18: components.  However, X11 beta sites have succeeded in making a working Apollo
        !            19: server at SR9.5.1.
        !            20:         --  The C compiler, compiling some of the Apollo driver code.
        !            21:         --  The C preprocessor (/usr/lib/cpp), if you use the imake utility
        !            22:             program (this is not required).
        !            23:         --  /lib/streams, in using local TCP/IP connections.
        !            24: 
        !            25:     If you are running SR9.6, you may have trouble with the following software
        !            26: components.
        !            27:         --  The C preprocessor (/usr/lib/cpp), if you use the imake utility
        !            28:             program (this is not required).
        !            29:         --  /lib/streams, in using local TCP/IP connections.
        !            30: 
        !            31:     If you are running SR9.7, you may have trouble with the following software
        !            32: components.
        !            33:         --  The C preprocessor (/usr/lib/cpp), if you use the imake utility
        !            34:             program (this is not required).
        !            35: 
        !            36:     If you are having problems with any of the above, you can obtain a patch
        !            37: tape from Apollo with better versions.  Ask for the October 1987 or later patch
        !            38: tape from your local sales office.
        !            39: 
        !            40:     This implementation of the server is the typical "dumb monochrome" port.
        !            41: It will run on any Apollo display, color or monochrome, but it will only do
        !            42: 1-bit black-and-white graphics.
        !            43: 
        !            44: 
        !            45: GETTING ORIENTED
        !            46: ----------------
        !            47: 
        !            48:     Top level directories are:
        !            49: 
        !            50:         clients         client program sources
        !            51:         demos           demo client program sources
        !            52:         doc             documentation
        !            53:         extensions      code for portable extensions
        !            54:         fonts           sources and compiler sources for server fonts
        !            55:         hacks           client programs classified as hacks
        !            56:         include         include files needed by both client and server code
        !            57:         lib             code for various client-side libraries
        !            58:         server          code for sample server
        !            59:         util            utility programs for building and maintaining X11
        !            60: 
        !            61: You should be familiar especially with the documents in 'doc/Server'.  Also, two
        !            62: entries in 'util' should be noted:  'imake' is a tool to create a consistent set
        !            63: of makefiles from common templates; and 'makedepend' is a tool to construct or
        !            64: reconstruct make file dependency lists.
        !            65: 
        !            66: 
        !            67: HOW TO BUILD IT
        !            68: ---------------
        !            69: 
        !            70:     First, make the 'imake' tool in the 'util/imake' directory.
        !            71: 
        !            72:     Next, make the 'makedepend' tool in the 'util/makedepend' directory.
        !            73: You will have to change its Makefile if you do not have CPP source.
        !            74: 
        !            75: Doing makes
        !            76: -----------
        !            77: 
        !            78:     First, at the top level do a 'make Makefiles'; this runs 'imake' on
        !            79: everything.  This step is actually optional, as the delivered Makefiles
        !            80: are already adequate.  You will have to decide whether you are interested
        !            81: in the benefits of re-creating all your makefiles from a given template
        !            82: or not.
        !            83: 
        !            84:     Before running make on any part of the X11 code, do a 'make depend'.
        !            85: This will update the dependencies part of the file to not spuriously
        !            86: refer to some header files non-existent on DOMAIN/IX, and to refer to all
        !            87: header files actually depended on.
        !            88: 
        !            89:     When everything is finally built, you will have to find a home in your
        !            90: file system for the executables and other runtime files.  We suggest
        !            91: not using '/usr/new' if you have X Version 10, to avoid confusion over
        !            92: what version of X a program is for.  Version 10 and Version 11 are
        !            93: completely incompatible.  The default homes for fonts and the RGB database
        !            94: for X11 will be in '/usr/lib/X11'.
        !            95: 
        !            96:     The code falls into two categories, client side and server side.  The
        !            97: top level directories 'lib' and 'clients' are client side code.  They should
        !            98: be made in that order.  In parallel with this, you can make the server side
        !            99: code, in the directories 'fonts' and 'server'.  More details on server side
        !           100: building follow; client side notes follow them.
        !           101: 
        !           102: Making the server
        !           103: -----------------
        !           104: 
        !           105:     There are Apollo-specific entries in 'server/include/servermd.h' which
        !           106: specify bit order, byte order, and pad boundaries for characters in fonts.
        !           107: The latter of these is set to 2 (i.e. character glyphs start on word
        !           108: boundaries), but it can be changed to 1 or 4.  1 makes font files smaller
        !           109: but prevents them from working on non-68020 systems, since the server will
        !           110: get odd address errors.  4 makes them bigger; it may improve text drawing
        !           111: performance somewhat.  The font compiler and the server/ddx/mfb code must be
        !           112: compiled with the same version of this header file!
        !           113: 
        !           114:     To make the fonts that the server will use, you must compile them from
        !           115: their source forms.  First, make the font compiler in 'fonts/compiler'.  After
        !           116: building the font compiler, run it on each of the font sources in 'fonts/bdf',
        !           117: redirecting its output to the 'fonts/snf' directory.  All this is actually
        !           118: controlled by 'fonts/Makefile'.
        !           119: 
        !           120:     The Apollo server itself uses code from the following directories:
        !           121: 
        !           122:     server/os/4.2bsd
        !           123:     server/dix
        !           124:     server/ddx/mi
        !           125:     server/ddx/mfb
        !           126:     server/ddx/apollo
        !           127: 
        !           128:     Only these directories need to be built.  (They depend on the include
        !           129: files in 'include' and 'server/include', of course.)
        !           130: 
        !           131:     In 'server/include/site.h' are definitions for pathnames for fonts and
        !           132: the color database.  You may wish to decide where these things will live
        !           133: now, so you can edit this file if necessary.  If you decide differently
        !           134: later, you will need to re-edit this file and remake the server, or always
        !           135: supply server command line options to override the defaults.
        !           136: 
        !           137:     You may want to do the following for the benefit of the OS code:
        !           138: 
        !           139:       /com/crl /usr/include/machine/machparam.h /usr/include/machine/param.h
        !           140: 
        !           141:     Now you can go to the 'server' directory and type 'make Xapollo'.
        !           142: 
        !           143: 
        !           144: Making the client side code
        !           145: ---------------------------
        !           146: 
        !           147:     The Xlib code, the basic subroutine library interface to the protocol for
        !           148: clients written in C, resides in 'lib/X'.
        !           149: 
        !           150:     Xlib requires nothing special; you can just make it.  This takes a long
        !           151: time, especially if you let it compile everything twice in order to make both
        !           152: debuggable and non-debuggable versions.  You may want to change the Imakefile
        !           153: or Makefile to make only one flavor of object file.
        !           154: 
        !           155:     Some routines to assist porting from X10 are in 'lib/oldX'; you may wish
        !           156: to make this library as well.  Some code in 'demos' uses it.  Also,
        !           157: 'lib/oldXMenu' has a version of the X10 XMenu library which you may want.
        !           158: 
        !           159:     Two versions of the X toolkit, layered on Xlib, are in 'lib/Xtk' and
        !           160: 'lib/oldXtk'.  To our current knowledge, 'lib/oldXtk' is the one that will be
        !           161: used by any clients requiring the toolkit.
        !           162: 
        !           163:     In the 'lib/oldXtk' directory, there is a change.  'Load.c' cannot be made
        !           164: to work on Apollos, since it relies on '/dev/kmem'; it's best to just remove
        !           165: references to 'Load.[co]' from the Imakefile or Makefile.
        !           166: 
        !           167:     The toolkit code may or may not refer to /usr/include/string.h instead of
        !           168: /usr/include/strings.h, which is what it really wants.  If you don't have
        !           169: the former, you may wish to make a link of that name to the latter, or make
        !           170: a version of the former which #include's the latter, or something.
        !           171: 
        !           172:     Now the toolkit can be made.
        !           173: 
        !           174:     Finally, you can make the client programs.  Note that 'xload' wants to use
        !           175: the routines from 'lib/oldXtk/Load.c', which is not available on Apollos as
        !           176: explained above, so an Apollo version of 'xload' isn't useful.
        !           177: 
        !           178: 
        !           179: HOW TO INSTALL IT
        !           180: -----------------
        !           181: 
        !           182:     Copy the compiled font files in 'fonts/snf' to wherever you said they would
        !           183: live in 'server/include/site.h'.  The server is in 'server/Xapollo'; it will now
        !           184: run.  Client programs are in their respective subdirectories of 'clients',
        !           185: 'demos' or 'hacks'.  Put these executables wherever is convenient.
        !           186: 
        !           187: 
        !           188: HOW TO RUN IT
        !           189: -------------
        !           190: 
        !           191:     You must have TCP/IP installed and running.
        !           192: 
        !           193:     The server borrows the entire display.  Therefore, there are three
        !           194: approaches to debugging and running it.  One is to get a dumb terminal and run
        !           195: a shell to invoke the server from it.  Another is to /com/crp or rlogin to the
        !           196: node that will run the server from a different node, preferably right next to
        !           197: it.  The last is to make shell scripts that will run the server, sleep for long
        !           198: enough to let it initialize itself, and then run some clients.  This last
        !           199: approach requires the least hardware, but requires working more-or-less blind,
        !           200: until you have a working server and xterm running.
        !           201: 
        !           202:     As regards the keyboard, the following comment in 'server/ddx/apollo/
        !           203: apollo_io.c' tells the story.
        !           204: 
        !           205: /*
        !           206:  *  We assume Apollo keyboard number 2 (with mouse, without numeric keypad or lighted
        !           207:  *  CapsLock key).  (Keyboard number 1 is unsupported, since it can't have a mouse.  Keyboard
        !           208:  *  number 3 is a superset of keyboard number 2.  It has the ability to generate raw key up/down
        !           209:  *  transitions; this should be supported but isn't.  Keyboard number 2 cannot generate raw key
        !           210:  *  up/downs.)
        !           211:  *
        !           212:  *  Only the white keys, the four basic arrow keys and F1-F8 are implemented now.
        !           213:  *  Up transitions for the white keys are faked.
        !           214:  *  Positions of the real control and shift keys are inferred from the raw input character;
        !           215:  *      their transitions are faked if necessary.
        !           216:  *  "Mouse" Control, Shift and Meta keys are as for Apollo V10 driver:
        !           217:  *      Control:  KBD_$LD    Boxed up-arrow     Lower left corner of left-hand keypad
        !           218:  *      Shift:    KBD_$LF    Boxed down-arrow   Lower right corner of left-hand keypad
        !           219:  *      Meta:     KBD_$R1    "POP"              Lower right corner of main keyboard
        !           220:  *
        !           221:  *  You can bail out of the server by hitting the ABORT/EXIT key (KBD_$R5S/KBD_$R5).  Unshifted,
        !           222:  *  it will exit the server in an orderly fashion.  If this doesn't work (i.e. server is wedged),
        !           223:  *  the shifted version is the system quit character.
        !           224:  */
        !           225: 
        !           226:     When running a client program, the environment variable DISPLAY should be
        !           227: set, although some clients allow the display to be specified on the command line
        !           228: as well.  In the case of the C shell, you should say:
        !           229: 
        !           230:     setenv DISPLAY <host-name-of-server-node>:0
        !           231: 
        !           232:     Since the selection of fonts is probably not identical to what it was for
        !           233: V10, you might want to check any ~/.Xdefaults or ~/.uwmrc files left over from
        !           234: V10 to be sure you are not trying to use non-existent fonts.
        !           235: 
        !           236:     In order to establish a connection from a remote client, the name of the
        !           237: host running the client program must exist as an entry in the server's file
        !           238: '/etc/X0.hosts'; this is the list of "trusted" hosts.  This pathname is
        !           239: constructed in 'server/os/4.2bsd/access.c', routine ResetHosts.  The 'xhost'
        !           240: client program will also add a host to the list of trusted hosts, until the
        !           241: server resets itself.
        !           242: 
        !           243:     If you have the unofficial UDS support code (the uds type manager), a client
        !           244: can use it to establish a connection to the local server via use of the display
        !           245: named "unix:0".
        !           246: 
        !           247: 
        !           248: LIMITATIONS
        !           249: -----------
        !           250: 
        !           251:     As mentioned above, this is a monochrome-only port using the portable MFB
        !           252: code, therefore performance is not as good as it is for the Apollo X Version 10
        !           253: implementation.  Also, the keyboard support for keyboard 3 could allow more
        !           254: natural use of control and shift, and it could add more Apollo keys to the
        !           255: keymap.
        !           256: 
        !           257: 
        !           258: FIXED BUGS SINCE BETA
        !           259: ---------------------
        !           260: 
        !           261:     This version of the Apollo server has a working software cursor (to the
        !           262: best of our knowledge).
        !           263: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.