![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv9 / X11 / src / X.V11R1 / server / ddx / apollo|
Return to README CVS log | Up to [Research Unix] / researchv9 / X11 / src / X.V11R1 / server / ddx / apollo |
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.