home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / RELNOTES.ms < prev    next >
Encoding:
Text File  |  1991-08-28  |  79.5 KB  |  2,108 lines
  1. .\" $XConsortium: RELNOTES.ms,v 1.23 91/08/29 09:45:58 rws Exp $
  2. .\" use ms macros
  3. .if n \{
  4. .nr LL 79n
  5. .ll 79n
  6. .nr FL 79n
  7. .nr LT 79n
  8. .\}
  9. .nr PS 11
  10. .de Ds
  11. .LP
  12. .in +.5i
  13. .nf
  14. ..
  15. .de De
  16. .fi
  17. .in -.5i
  18. ..
  19. .de Ip
  20. .LP
  21. .ne 3
  22. \fB\\$1\fP
  23. .br
  24. .IP
  25. ..
  26. .ds LF \fBX Window System Release Notes\fP
  27. .ds RF \fBX Version 11, Release 5\fP
  28. .ce 4
  29. \s+2\fBX Window System, Version 11, Release 5\fP\s-2
  30.  
  31. \s+1\fBRelease Notes\fP\s-1
  32.  
  33. \fIMIT X Consortium staff\fP
  34.  
  35. MIT Laboratory for Computer Science
  36. .sp 3
  37. Copyright \(co\ 1991 by the Massachusetts Institute of Technology.
  38. .nr PS 9
  39. .LP
  40. Permission to use, copy, modify, and distribute this document 
  41. for any purpose and without fee is hereby granted, provided 
  42. that the above copyright notice and this permission notice
  43. appear in all copies, and that the name of MIT not be used 
  44. in advertising or publicity pertaining to this document without 
  45. specific, written prior permission.
  46. MIT makes no representations about the suitability of this
  47. document for any purpose.
  48. It is provided ``as is'' without express or implied warranty.
  49. .nr PS 11
  50. .LP
  51. \fIX Window System\fP is a trademark of MIT.
  52. .sp 3
  53. This document describes how to build, install, and get started with
  54. Release 5 of the X Window System from MIT
  55. and gives a brief overview of the contents of the release.
  56. .NH 1
  57. For the Impatient Explorer
  58. .LP
  59. For those of you who will try to build the distribution without reading the
  60. entire release notes first, here is a quick summary of what to do.
  61. .LP
  62. If you want to build with \fBgcc\fP, edit \fBmit/config/site.def\fP by
  63. uncommenting the \fBHasGcc\fP line.
  64. .LP
  65. If you want to install into somewhere other than \fB/usr/bin/X11\fP,
  66. \fB/usr/include/X11\fP, etc., edit \fBmit/config/site.def\fP by uncommenting
  67. the \fBProjectRoot\fP lines and changing "/usr/X11R5" to whatever directory
  68. you want to install into.  (Do \fInot\fP use \fBDESTDIR\fP.)
  69. .LP
  70. Check the appropriate \fBmit/config/\fP\fIvendor\fP\fB.cf\fP file to
  71. make sure that \fBOSMajorVersion\fP and \fBOSMinorVersion\fP are
  72. set correctly (change them if necessary).
  73. .LP
  74. Find the \fBBootstrapCFlags\fP line, if any, in the \fIvendor\fP\fB.cf\fP file.
  75. If there isn't one, \fBcd\fP to the \fBmit\fP directory and type:
  76. .Ds
  77. make World >& world.log
  78. .De
  79. .LP
  80. If there is a \fBBootstrapCFlags\fP, take its value\s-2\u1\d\s0
  81. .FS
  82. \s+2\&1.  If you are using the \fBx386.cf\fP file, you will have to compute the
  83. correct value.\s-2
  84. .FE
  85. and type:
  86. .Ds
  87. make World BOOTSTRAPCFLAGS="\fIvalue\fP" >& world.log
  88. .De
  89. .LP
  90. Do not call the output file ``make.log'', or it will be deleted.
  91. If the build is successful, you can install most of it with:
  92. .Ds
  93. make install >& install.log
  94. .De
  95. .LP
  96. You can install man pages with:
  97. .Ds
  98. make install.man >& man.log
  99. .De
  100. .LP
  101. You can install lint libraries (if desired) with:
  102. .Ds
  103. make install.ln >& lintlib.log
  104. .De
  105. .LP
  106. If things fail, read the rest of the release notes.
  107. .NH 1
  108. Brief Overview of the Distribution
  109. .LP
  110. (If you want, you can skip to the next chapter first, and get your
  111. build started.  While it is compiling you will have plenty of time
  112. to read the rest of the release notes.)
  113. .LP
  114. There are two parts to the Release 5 distribution: MIT software and
  115. documentation, and user-contributed software and documentation.
  116. The MIT part contains:
  117. .Ip "X Consortium Standards"
  118. The MIT X Consortium produces standards:  documents which define
  119. network protocols, programming interfaces, and other aspects of
  120. the X environment.  See the \fBXStandards\fP man page for a
  121. list of standards.  See the \fBXConsortium\fP man page for
  122. information about the X Consortium.
  123. .Ip "Sample Implementations"
  124. For most of our standards, we provide \fIsample\fP implementations
  125. to demonstrate proof of concept.  These are not \fIreference\fP
  126. implementations; the written specifications define the standards.
  127. .Ip "Fonts"
  128. A collection of bitmap and outline fonts are included in the
  129. distribution, contributed by various individuals and companies.
  130. .Ip "Utility Libraries"
  131. A number of libraries, such as the \fIAthena Widget Set\fP, are
  132. included.  These are not standards, but are used in building
  133. MIT applications and may be useful in building other applications.
  134. .Ip "Sample Programs"
  135. We also provide a number of application programs.
  136. A few of these programs, such as \fBxdm\fP,
  137. should be considered essential in almost all environments.
  138. The rest of the applications carry no special status, they
  139. are simply programs that have been developed and/or maintained
  140. by MIT X Consortium staff.
  141. In some cases, you will find better substitutes for these
  142. programs in the user-contributed software.
  143. .LP
  144. The user-contributed part contains whatever people contribute.
  145. You find a variety of software and documentation here:
  146. application programs, demos, examples, libraries, Asian input methods,
  147. X server extensions, etc.
  148. .NH 2
  149. Structure of the MIT Sources
  150. .LP
  151. All of the MIT sources are under a single directory, \fBmit\fP.
  152. Sources are organized into the following subdirectories:
  153. .Ip "clients"
  154. This directory contains most of the sample applications.
  155. See the program man pages for details.
  156. .Ip "config"
  157. This directory contains configuration files and the \fBimake\fP
  158. program used to build the release.
  159. Details are covered in other sections below.
  160. .Ip "demos"
  161. This directory contains a small collection of graphics demonstration programs,
  162. a few utility/test programs, and some performance demonstration programs.
  163. These are by no means the ``best'' demo programs around, they just happen
  164. to be ones we try to maintain.
  165. .Ip "doc"
  166. This directory contains \fBtroff\fP sources to X Consortium standards,
  167. server internals documentation,
  168. documentation for various utility libraries,
  169. some useful tutorial material.
  170. .Ip "extensions"
  171. This directory contains implementations of X server extensions,
  172. both the server internals and the application programming libraries,
  173. and some test programs.  Of particular note here, new in Release 5,
  174. is PEX, the PHIGS Extension to X used for 3D graphics, and the PHIGS
  175. programming library which interfaces to the PEX protocol.
  176. .Ip "fonts"
  177. This directory contains bitmap fonts in source form,
  178. some outline fonts,
  179. a sample font server,
  180. a utility font library used by the X server and font server,
  181. a client font library for interacting with the font server,
  182. and programs for building fonts and querying the font server.
  183. .Ip "hardcopy"
  184. This directory contains pre-generated PostScript files for
  185. the client man pages and for
  186. most of the documentation found in the \fBdoc\fP directory.
  187. The files are compressed with \fBcompress\fP to save disk space.
  188. If you do not have \fBcompress\fP on your system, you will
  189. find a version in the \fBmit/util/compress\fP directory.
  190. .Ip "include"
  191. This directory contains various library-independent C header files
  192. and a collection of bitmap files.
  193. .Ip "lib"
  194. This directory contains programming libraries and support files.
  195. Of note are Xlib (the lowest-level C programming interface to X),
  196. Xt (the X Toolkit Intrinsics), Xmu (an eclectic set of utility functions),
  197. Xaw (the Athena Widget Set), and CLX (a Common Lisp interface to X).
  198. .Ip "man"
  199. This directory contains a few top-level man pages about the release
  200. (general information, server access control mechanisms, the X Consortium,
  201. and X Consortium standards), and man pages for some of the programming
  202. libraries.
  203. .Ip "rgb"
  204. This directory contains a program to generate the color database used
  205. by the X server and sample databases.
  206. .Ip "server"
  207. This directory contains the X server sources, both device-independent
  208. (\fBdix\fP) and device-dependent (\fBddx\fP).  In this release, there
  209. is support for building the following servers:
  210. .Ds
  211. DECstation 2100/3100 monochrome and color displays
  212. DECstation 5000 CX and MX displays
  213. IBM RS/6000 skyway adapter
  214. Apple Macintosh monochrome and color displays
  215. MIPS monochrome and color displays
  216. OMRON LUNA monochrome displays (color displays operate in monochrome)
  217. Tektronix 4319 color display
  218. VAXstation QVSS and QDSS displays
  219. Sun monochrome and 8-bit color displays (with GX support)
  220. Various VGA displays under System V/386
  221. .De
  222. .IP
  223. If your favorite hardware is not listed above, please do not blame us at MIT,
  224. we ship what Consortium members provide.  Only in a few cases do we try to
  225. maintain device-specific software for our own development needs.
  226. .\".Ip "util"
  227. .LP
  228. \fButil\fP
  229. .br
  230. .IP
  231. This directory contains miscellaneous utility programs and shell scripts
  232. used to build, maintain, and install the release.
  233. .NH 1
  234. Building the Release
  235. .LP
  236. The core distribution (code under the \fBmit\fP directory) has been
  237. built and tested at MIT on the following systems:
  238. .Ds
  239. AIX 3.1.5, on IBM RS/6000
  240. Apollo SR10.3 (very minimal testing, bsd4.3 only)
  241. AT&T Unix System V Release 4 V2, on AT&T WGS6386
  242. A/UX 2.0.1
  243. HP-UX 7.0, on HP9000/s300
  244. IRIX 4.0
  245. Mach 2.5 Version 1.13, on OMRON Luna 88k
  246. NEWS-OS 4.1, on Sony NWS-1850
  247. NEWS-OS 5.0U, on Sony NWS-3710
  248. SunOS 4.1.1, on Sun 3, Sparc 1, and Sparc 2
  249. Ultrix-32 4.2, VAX and RISC
  250. UNICOS 5.1
  251. UTek 4.0
  252. VAX 4.3bsd (with unknown local changes)
  253. .De
  254. .LP
  255. In somes cases, we have not used the most recent version of the operating
  256. system (sorry).  Support for earlier versions of the operating systems
  257. listed is not claimed, and not guaranteed.
  258. .LP
  259. In addition to the systems above, support has been provided by vendors for:
  260. .Ds
  261. AIX 2.2 and AOS 4.3, on IBM RT
  262. AIX 1.2.1, on IBM PS/2
  263. ConvexOS V9.0
  264. DG/UX 4.32
  265. INTERACTIVE UNIX Version 2.2.1
  266. Mach 2.5 Version 1.40, on OMRON Luna 68k
  267. Motorola R32V2/R3V6.2 and R40V1
  268. RISCOS 4.50
  269. UNIOS-B 4.3BSD UNIX: 2.00
  270. Unix System V/386 Release 3.2, on ESIX, SCO, and AT&T (``work in progress'')
  271. Unix System V/386 Release 4.0, on DELL
  272. .De
  273. .NH 2
  274. Unpacking the Distribution
  275. .LP
  276. The distribution normally comes as multiple tar files, either on
  277. tape or across a network.  Create a directory to hold the distribution,
  278. \fBcd\fP to it, and untar everything from that directory.  For example:
  279. .Ds
  280. mkdir \fIsourcedir\fP
  281. cd \fIsourcedir\fP
  282. tar xfp \fItar-file-or-tape-device\fP
  283. .De
  284. .LP
  285. If you have obtained compressed and split tar files over the network,
  286. then the sequence for each part of the \fBmit\fP directory might be:
  287. .Ds
  288. cd \fIftp-dir\fP/mit-\fIN\fP
  289. cat mit-\fIN\fP.?? | uncompress | (cd \fIsourcedir\fP; tar xfp -)
  290. .De
  291. .LP
  292. The sequence for each part of the \fBcontrib\fP directory might be:
  293. .Ds
  294. cd \fIftp-dir\fP/contrib-\fIN\fP
  295. cat contrib-\fIN\fP.?? | uncompress | (cd \fIsourcedir\fP; tar xfp -)
  296. .De
  297. .LP
  298. The \fIsourcedir\fP directory you choose can be anywhere in any of your
  299. filesystems that is
  300. convenient to you.  After extracting the release, you should end up with an
  301. \fBmit\fP subdirectory, and a \fBcontrib\fP subdirectory if you unpack
  302. user-contributed software.  You will need about 100 megabytes of disk space
  303. to unpack the \fBmit\fP directory contents; building it will of course
  304. require more disk space.
  305. .NH 2
  306. Symbolic Link Trees
  307. .LP
  308. If you expect to build the distribution on more than one machine using
  309. a shared source tree, or you just want to keep the source tree pure,
  310. you may want to use the shell script \fBmit/util/scripts/lndir.sh\fP to create
  311. a symbolic link tree on each build machine.  This is fairly expensive in
  312. disk space, however.  To do this, create a directory for the build, \fBcd\fP
  313. to it, and type:
  314. .Ds
  315. \fIsourcedir\fP/mit/util/scripts/lndir.sh \fIsourcedir\fP
  316. .De
  317. .LP
  318. where \fIsourcedir\fP is the pathname of the
  319. directory where you stored the sources.  All of the build instructions
  320. given below should then be done in the build directory on each machine,
  321. rather than in the source directory.
  322. .LP
  323. The shell script is reasonably portable but quite slow to execute.
  324. If you want you can instead try compiling a similar C program, but
  325. it is slightly tricky to do before the distribution is built;
  326. \fBcd\fP to the directory \fBmit/util/progs\fP and try typing:
  327. .Ds
  328. ln -s ../../include X11
  329. cc -o lndir -I. lndir.c
  330. .De
  331. .LP
  332. If it compiles and links, it will probably work; otherwise you can
  333. try typing:
  334. .Ds
  335. cc -o lndir -I. -DNOSTDHDRS lndir.c
  336. .De
  337. .LP
  338. If it still fails, use the shell script.
  339. .NH 2
  340. Setting Configuration Parameters
  341. .LP
  342. You will notice that few if any of the subdirectories under \fBmit\fP
  343. contain a \fBMakefile\fP, but they do contain an \fBImakefile\fP.
  344. The \fBImakefile\fP is a template file used to create a \fBMakefile\fP
  345. containing build rules and variables appropriate for the target machine.
  346. The \fBMakefile\fP is generated by the program \fBimake\fP.
  347. Most of the configuration work prior to building the release is to
  348. set parameters so that \fBimake\fP will generate correct files.
  349. .LP
  350. The directory \fBmit/config\fP contains configuration
  351. files that control how the distribution is built.  On systems directly
  352. supported by this distribution, only minimal editing of these files
  353. should be necessary.  If your system is not supported by the
  354. distribution but conforms to ANSI C and POSIX.1 and has socket-style
  355. networking, then you should be able to build a new configuration
  356. file relatively easily.  Otherwise, edits to many files throughout
  357. the system may be necessary.  We only deal with minor editing for
  358. supported systems here.
  359. .LP
  360. The main files to be concerned with in the \fBmit/config\fP directory
  361. are \fBsite.def\fP and one of the \fIvendor\fP\fB.cf\fP files.  The
  362. \fBsite.def\fP file should be used for most site-specific configuration
  363. customizations.  The \fB.cf\fP file should normally only need to be edited
  364. if you are using a different release of the operating system.
  365. .NH 3
  366. The vendor.cf File
  367. .LP
  368. Find the appropriate \fB.cf\fP file from this table:
  369. .Ds
  370. .ta 2.5i
  371. AIX    ibm.cf
  372. AOS    ibm.cf
  373. Apollo    apollo.cf
  374. AT&T Unix SVR4    att.cf
  375. A/UX    macII.cf
  376. BSD    bsd.cf
  377. ConvexOS    convex.cf
  378. DG/UX    DGUX.cf
  379. HP-UX    hp.cf
  380. INTERACTIVE    x386.cf
  381. IRIX    sgi.cf
  382. Mach (Luna)    luna.cf
  383. Motorola    moto.cf
  384. NEWS-OS    sony.cf
  385. RISCOS    Mips.cf
  386. SunOS    sun.cf
  387. Ultrix    ultrix.cf
  388. UNICOS    cray.cf
  389. UTek    pegasus.cf
  390. UNIOS-B    luna.cf
  391. Unix System V/386    x386.cf
  392. .De
  393. .LP
  394. Look through this file, and check the \fBOSMajorVersion\fP and
  395. \fBOSMinorVersion\fP values.  The numbers have been preset
  396. to what was tested at MIT or what was supplied by the vendor.
  397. If the version numbers match the operating system you are
  398. currently running, all is well.  If they do not, you
  399. will need to edit to file to make them correct.  In a few cases
  400. (specifically
  401. changing UNICOS from 5.1 to 6.0) there should not be a problem
  402. in moving the version numbers forward to a newer release.
  403. However, if you are moving the version numbers backwards,
  404. or moving forward to a version that hasn't been pre-tested,
  405. you may have problems, and you have have to edit other parts
  406. of the file (and possibly other files) to get things to work.
  407. .LP
  408. You can browse through the rest of the items in the \fB.cf\fP file,
  409. but most of them you should not need to edit.
  410. .NH 3
  411. The site.def File
  412. .LP
  413. There are two main variables to set in the \fBsite.def\fP file:
  414. \fBHasGcc\fP and \fBProjectRoot\fP.  If you are going to compile
  415. the distribution with \fBgcc\fP, find the line that looks like
  416. .Ds
  417. /* #define HasGcc YES */
  418. .De
  419. .LP
  420. and remove the comment markers, turning it into
  421. .Ds
  422. #define HasGcc YES
  423. .De
  424. .LP
  425. If you are sharing a single \fBsite.def\fP across multiple systems,
  426. you can do something more complicated.
  427. For example, if you only want to use \fBgcc\fP on a Sun 3 (but not
  428. on Sparcs) you might use this:
  429. .Ds
  430. #ifdef SunArchitecture
  431. #define HasGcc mc68000
  432. #endif
  433. .De
  434. .LP
  435. The most common error when using \fBgcc\fP is to fail to run
  436. the \fBfixincludes\fP script (from the \fBgcc\fP distribution)
  437. when installing \fBgcc\fP.  Make sure you have done this before
  438. compiling the release.  Another common error is likely to be
  439. using \fBgcc\fP ANSI C include files when the vendor operating system
  440. supplies correct ones.  The \fBgcc\fP include files \fBassert.h\fP,
  441. \fBlimits.h\fP, and \fBstddef.h\fP are prime candidates for not installing.
  442. .LP
  443. The \fBProjectRoot\fP variable controls where the software will
  444. eventually be installed.  The default as distributed for most
  445. systems is to install into ``system'' directories: \fB/usr/bin/X11\fP,
  446. \fB/usr/include/X11\fP, \fB/usr/lib\fP, and \fB/usr/man\fP (this
  447. is the behaviour when \fBProjectRoot\fP is not defined).
  448. If you prefer to install into alternate directories, the simplest
  449. thing to do is to set \fBProjectRoot\fP.  Find the four \fBProjectRoot\fP
  450. lines in the \fBsite.def\fP file, and again remove the ``/*'' and ``*/''
  451. comment markers that surround them.  You will see a default choice
  452. for \fBProjectRoot\fP of \fB/usr/X11R5\fP; if you don't like that one,
  453. replace it with another.  Assuming you have set the variable to some
  454. value /\fIpath\fP, files will be installed into
  455. /\fIpath\fP/bin, /\fIpath\fP/include/X11, /\fIpath\fP/lib, and
  456. /\fIpath\fP/man.
  457. .LP
  458. Note that in a few cases (\fBibm.cf\fP and \fBx386.cf\fP) the
  459. vendor-supplied \fB.cf\fP file supplies a \fBProjectRoot\fP by default.
  460. If you want to accept this one, do not uncomment the one in \fBsite.def\fP;
  461. otherwise the one you place in \fBsite.def\fP will
  462. override the default setting.
  463. .LP
  464. The directories where the software will be installed are compiled in
  465. to various programs and files during the build process, so it is
  466. important that you get the configuration correct at the outset.
  467. If you change your mind later, you will want to do a ``make Everything''
  468. to rebuild correctly.
  469. .LP
  470. Notice that the \fBsite.def\fP file was two parts, one protected with
  471. ``#ifdef BeforeVendorCF'' and one with ``#ifdef AfterVendorCF''.
  472. The file is actually processed twice, once before the \fB.cf\fP file
  473. and once after.  About the only thing you need to set in the ``before''
  474. section is \fBHasGcc\fP; just about everything else can be set in the
  475. ``after'' section.
  476. .LP
  477. There are a large number of parameters that you can modify to change
  478. what gets built and how it gets built.  An exhaustive list and explanation
  479. will not be given here; you can browse through \fBmit/config/README\fP
  480. to see a list of parameters.  However, here are some notable parameters
  481. that you can set in the ``after'' section:
  482. .Ip "BuildXsi\fP and \fBBuildXimp"
  483. New in this release, Xlib contains support for internationalized
  484. input methods, using library- or network-based implementation methods.
  485. The implementation details internal to Xlib can vary considerably
  486. depending on the types of input methods supported.  In this release,
  487. two different implementations are supported, named \fBXsi\fP and
  488. \fBXimp\fP.  As distributed, the default on all systems except Sony
  489. is \fBXsi\fP.  If you want to use \fBXimp\fP instead, add this:
  490. .Ds
  491. #define BuildXimp YES
  492. .De
  493. .Ip "BuildServer"
  494. This controls whether or not an X server is built.  If the variable
  495. is not set to \fBNO\fP in the \fB.cf\fP file, then the default is
  496. to build a server.  If you want to disable the server, add this:
  497. .Ds
  498. #define BuildServer NO
  499. .De
  500. .Ip "BuildFonts"
  501. Compiled fonts take up a lot of disk space.  In this release, the
  502. compiled form (called ``pcf'') can be shared across all machines
  503. of all architectures, so you may only want to build the fonts on
  504. one machine.  To disable font building, add this:
  505. .Ds
  506. #define BuildFonts NO
  507. .De
  508. .Ip "BuildPex"
  509. PEX is an X extension supporting 3-D graphics and the PHIGS programming
  510. interface.  The PEX sources are known to cause some compilers to
  511. exceed their static symbol table sizes.  If this happens to you, you
  512. can disable PEX by adding this:
  513. .Ds
  514. #define BuildPex NO
  515. .De
  516. .Ip "ManSuffix"
  517. User program man pages are installed by default in subdirectory
  518. ``mann'' with suffix ``.n''.
  519. You can change this to ``man1'' and ``.1'', for example, by adding this:
  520. .Ds
  521. #define ManSuffix 1
  522. .De
  523. .Ip "InstallLibManPages"
  524. By default, the programming library man pages (Xlib, Xt, various
  525. extensions) are installed along with all of the other man pages.
  526. The library pages constitute a considerable number of files.
  527. If you do not expect to be programming with X, or prefer
  528. using other forms of documentation, you can disable installation of
  529. the library pages by adding this:
  530. .Ds
  531. #define InstallLibManPages NO
  532. .De
  533. .Ip "InstallXdmConfig\fP and \fBInstallXinitConfig"
  534. The \fBxdm\fP and \fBxinit\fP programs are the normal ways to run X servers.
  535. By default, the configuration files for these programs are not installed,
  536. to avoid inadvertently destroying existing configuration files.
  537. If you are not yet using \fBxdm\fP or \fBxinit\fP, or will be installing
  538. into a new destination, or do not wish to retain your old configuration
  539. files, add these:
  540. .Ds
  541. #define InstallXdmConfig YES
  542. #define InstallXinitConfig YES
  543. .De
  544. .Ip "XdmServersType"
  545. Some of the \fBxdm\fP config files are generated based on configuration
  546. parameters.  One of the files controls whether an X server is started
  547. by default.  By default the choice is made based on whether an X server
  548. is built as part of this distribution (the \fBBuildServer\fP parameter).
  549. If you are not building a server, but you will be running a product server
  550. on the workstation under \fBxdm\fP, you should add this:
  551. .Ds
  552. #define XdmServersType ws
  553. .De
  554. .Ip "HasXdmAuth"
  555. This release supports a DES-based form of authorization called
  556. XDM-AUTHORIZATION-1.  The source file \fBmit/lib/Xdmcp/Wraphelp.c\fP,
  557. which is necessary for this to compile, might not be included in your
  558. distribution due to possible export regulations; if it is not
  559. included and you are a US citizen, you should be able to obtain the
  560. file over the network.  To enable building of this mechanism, add this:
  561. .Ds
  562. #define HasXdmAuth YES
  563. .De
  564. .Ip "InstallFSConfig"
  565. New to this release is a network font server, \fBfs\fP.  By default,
  566. the configuration files for the font server are not installed.  To
  567. have them installed, add this:
  568. .Ds
  569. #define InstallFSConfig YES
  570. .De
  571. .Ip "MotifBC"
  572. If you want to use the Release 5 Xlib and Xt with Motif 1.1, you
  573. will need to enable a backward compatibility flag, by adding this:
  574. .Ds
  575. #define MotifBC YES
  576. .De
  577. .NH 2
  578. System Pitfalls
  579. .LP
  580. On a few systems, you are likely to have build problems unless you make some
  581. minor changes to the system.  Naturally, you should exercise caution
  582. before making changes to system files, but these are our recommendations
  583. based on our experience.
  584. .LP
  585. On VAX Ultrix systems, you may find that \fB<stdlib.h>\fP
  586. contains declarations of \fBmalloc\fP, \fBcalloc\fP, and \fBrealloc\fP
  587. with a return value of ``void *''.  You may find this causes problems
  588. when compiling with a non-ANSI-C compiler, in which case a workaround
  589. is to change the return values to ``char\&*'' in the ``#else'' section.
  590. .LP
  591. Ultrix may not provide \fB<locale.h>\fP unless you load the
  592. Internationalization subset.  You will need this file to compile
  593. the distribution (or else you will need to reset a configuration
  594. parameter, see below).
  595. .LP
  596. On SunOS systems, you may find that statically linking (when debugging)
  597. against both Xlib and the \fBlibc\fP will result in unresolved symbols to
  598. dynamic linker functions, because Xlib contains calls to \fBwcstombs\fP.
  599. Either link dynamically against \fBlibc\fP, or compile and link
  600. the stub routines in \fBmit/util/misc/dlsym.c\fP.
  601. .LP
  602. On Sun 3s, the default is to compile library files with no special floating
  603. point assumptions.  If all of your Sun 3s have floating point hardware, you
  604. may want to change this, for better performance of Xlib color functions.
  605. For example, in the ``after'' section of your \fBsite.def\fP file,
  606. you might add:
  607. .Ds
  608. #if defined(SunArchitecture) && defined(mc68000)
  609. #undef LibraryCCOptions
  610. #define SharedLibraryCCOptions -f68881 -pipe
  611. #endif
  612. .De
  613. .LP
  614. On AOS, you may find that \fB<stdarg.h>\fP is missing.
  615. In that case, you should be able to copy \fBmit/util/misc/rt.stdarg.h\fP
  616. to create the file.
  617. .LP
  618. On some System V/386 systems, you may find when using \fBgcc\fP in
  619. ANSI mode that there are inconsistent declarations between \fB<memory.h>\fP
  620. and \fB<string.h>\fP.  In that case, you may find it convenient to
  621. remove \fB<memory.h>\fP and make it a link to \fB<string.h>\fP.
  622. .LP
  623. On some System V/386 systems, you may need to build and install a
  624. \fBdbm\fP library before building the X server and RGB database.
  625. One can be found in \fBcontrib/util/sdbm\fP.
  626. .NH 3
  627. Internationalization
  628. .LP
  629. This release has support for internationalization, based on the
  630. ANSI C and POSIX locale model.  On some systems, you may discover
  631. that while the locale interface is supported, only the ``C'' locale
  632. is actually provided in the base operating system.  If you have
  633. such a system, and would like to experiment with a broader set
  634. of locales, the Xlib implementation contains support you can use,
  635. although use of this override has not really be tested.  You
  636. need to add the following defines to the \fBStandardDefines\fP
  637. parameter:
  638. .Ds
  639. -DX_WCHAR -DX_LOCALE
  640. .De
  641. .LP
  642. In most cases you will have to directly edit the \fB.cf\fP file to do this,
  643. or else you will have to know what the rest of the values are supposed to
  644. be, and add this to \fBsite.def\fP:
  645. .Ds
  646. #undef StandardDefines
  647. #define StandardDefines \fIprevious-values\fP -DX_WCHAR -DX_LOCALE
  648. .De
  649. .LP
  650. It is also possible to directly edit the file \fBmit/include/Xosdefs.h\fP,
  651. but this is not recommended.
  652. .LP
  653. With this setup, you will have to be careful that the system's
  654. declaration of \fBwchar_t\fP (in \fB<stddef.h>\fP) never gets used;
  655. this might be tricky.
  656. .NH 2
  657. Typing ``make World''
  658. .LP
  659. One more piece of information is required before building, at least
  660. on some systems: bootstrap flags.  Look in your \fB.cf\fP file for
  661. a line of the form
  662. .Ds
  663. #define BootstrapCFlags \fIvalue\fP
  664. .De
  665. .LP
  666. If there isn't one things are simple, otherwise things
  667. are only slightly more complicated.  If there is more than one
  668. (for example, in \fBibm.cf\fP, \fBmoto.cf\fP, and \fBsony.cf\fP),
  669. then you need to select the right one; it should be pretty obvious by the
  670. grouping according to operating system type.  Note that on
  671. A/UX you only need this value if you are using \fBgcc\fP,
  672. and that on a Sun you only need this value if you are using
  673. an earlier version of the operating system.
  674. .LP
  675. If you are using \fBx386.cf\fP, you will have to ``compute'' the value
  676. from the information given in the file.  You may also need to do other
  677. preparatory work; please read \fBmit/server/ddx/x386/README\fP.
  678. .LP
  679. If no value is required on your system, you can \fBcd\fP to the \fBmit\fP
  680. directory and start the build with:
  681. .Ds
  682. make World >& world.log
  683. .De
  684. .LP
  685. If a value is required, start the build with:
  686. .Ds
  687. make World BOOTSTRAPCFLAGS="\fIvalue\fP" >& world.log
  688. .De
  689. .LP
  690. You can call the output file something other than ``world.log'', but
  691. do not call it ``make.log'' because files with this name are
  692. automatically deleted during the ``cleaning'' stage of the build.
  693. .LP
  694. Because the build can take several hours to complete, you will probably
  695. want to run it in the background, and keep a watch on the output.
  696. For example:
  697. .Ds
  698. make World >& world.log &
  699. tail -f world.log
  700. .De
  701. .LP
  702. If something goes wrong, the easiest thing is to just start over
  703. (typing ``make World'' again) once you have corrected the problem.
  704. It is possible that a failure will corrupt the top-level \fBMakefile\fP.
  705. If that happens, simply delete the file and recreate a workable
  706. substitute with:
  707. .Ds
  708. cp Makefile.ini Makefile
  709. .De
  710. .LP
  711. When the build completes, examine the \fBworld.log\fP file for
  712. errors.  If you search for `:' (colon) characters, and skip
  713. the obvious compile lines, it is usually pretty easy to spot
  714. any errors.\s-2\u2\d\s0
  715. .FS
  716. \s+2\&2.  Searching for colon does not work particularly well on the RS/6000
  717. because it appears in command lines when building shared libraries.
  718. Try searching for colon followed by space.\s-2
  719. .FE
  720. .NH 1
  721. Installing the Release
  722. .LP
  723. Although it is possible to test the release before installing it,
  724. it is a lot easier to test after it has been installed.
  725. If everything is built successfully, you can install the software
  726. by typing the following as root, from the \fBmit\fP directory:
  727. .Ds
  728. make install >& install.log
  729. .De
  730. .LP
  731. Again, you might want to run this in the background and use \fBtail\fP
  732. to watch the progress.
  733. .LP
  734. You can install the man pages by typing the following as root,
  735. from the \fBmit\fP directory:
  736. .Ds
  737. make install.man >& man.log
  738. .De
  739. .LP
  740. You can install lint libraries (useful if your systems does does not have
  741. an ANSI C compiler) by typing the following as root,
  742. from the \fBmit\fP directory:
  743. .Ds
  744. make install.ln >& lintlib.log
  745. .De
  746. .NH 2
  747. Setting Up xterm
  748. .LP
  749. If your \fB/etc/termcap\fP and \fB/usr/lib/terminfo\fP databases do not have 
  750. correct entries for \fBxterm\fP, sample entries are provided in the directory
  751. \fBmit/clients/xterm/\fP.  System V users may need to compile and install the 
  752. \fBterminfo\fP entry with the \fBtic\fP utility.
  753. .LP
  754. Since each \fBxterm\fP will need a separate pseudoterminal,
  755. you need a reasonable number of them for normal execution.
  756. You probably will want at least 32 on a small, multiuser system.
  757. On most systems, each pty has two devices, a master and a slave,
  758. which are usually named /dev/tty[pqrstu][0-f] and /dev/pty[pqrstu][0-f].
  759. If you don't have at least the ``p'' and ``q'' sets configured
  760. (try typing ``ls /dev/?ty??''), you should have your system administrator
  761. add them.  This is commonly done by running the \fBMAKEDEV\fP script in
  762. the \fB/dev\fP directory with appropriate arguments.
  763. .NH 2
  764. Starting Servers at System Boot
  765. .LP
  766. The \fBxdm\fP program is designed to be run automatically at system startup.
  767. Please read the \fBxdm\fP man page for details on setting up configuration
  768. files; reasonable sample files are in \fBmit/clients/xdm/config\fP.
  769. If your system uses an \fB/etc/rc\fP file at boot time, you can
  770. usually enable \fBxdm\fP by placing the following at or near the end of
  771. the file:
  772. .Ds
  773. if [ -f /usr/bin/X11/xdm ]; then
  774.         /usr/bin/X11/xdm; echo -n ' xdm'
  775. fi
  776. .De
  777. .LP
  778. The example here uses \fB/usr/bin/X11\fP, but if you have installed into
  779. a different directory (for example by setting \fBProjectRoot\fP) then you
  780. need to substitute the correct directory.
  781. .LP
  782. If you are going to use the font server, you can also start it at boot time
  783. by adding this:
  784. .Ds
  785. if [ -f /usr/bin/X11/fs ]; then
  786.         /usr/bin/X11/fs &; echo -n ' fs'
  787. fi
  788. .De
  789. .LP
  790. If you are unsure about how system boot works, or if your system does
  791. not use \fB/etc/rc\fP, consult your system administrator for help.
  792. .NH 1
  793. Rebuilding the Release
  794. .LP
  795. You shouldn't need this right away, but eventually you are probably
  796. going to make changes to the sources, for example by applying
  797. public patches distributed by MIT.  If only C source files are
  798. changed, you should be able to rebuild just by going to the \fBmit\fP
  799. directory and typing:
  800. .Ds
  801. make >& make.log
  802. .De
  803. .LP
  804. If configuration files are changed, the safest thing to do is type:
  805. .Ds
  806. make Everything >& every.log
  807. .De
  808. .LP
  809. ``Everything'' is similar to ``World'' in that it rebuilds every
  810. \fBMakefile\fP, but unlike ``World'' it does not delete the
  811. existing objects, libraries, and executables, and only rebuilds
  812. what is out of date.
  813. .LP
  814. Note that in both kinds of rebuilds you do not need to supply the
  815. \fBBootstrapCFlags\fP value any more, the information is already recorded.
  816. .NH 1
  817. Building Contributed Software
  818. .LP
  819. The software in \fBcontrib\fP is not set up to have everything
  820. built automatically.  It is assumed that you will build individual
  821. pieces as you find the desire, time, and/or disk space.  You need
  822. to have the MIT software built and installed before building the
  823. contributed software.  To build a program or library in \fBcontrib\fP,
  824. look in its directory for any special build instructions (for example,
  825. a \fBREADME\fP file).  If there are none, and there is an \fBImakefile\fP,
  826. \fBcd\fP to the directory and type:
  827. .Ds
  828. xmkmf -a
  829. make >& make.log
  830. .De
  831. .LP
  832. This will build a \fBMakefile\fP in the directory and all subdirectories,
  833. and then build the software.  If the build is successful, you should be
  834. able to install it using the same commands used for the \fBmit\fP
  835. software:
  836. .Ds
  837. make install >& install.log
  838. make install.man >& man.log
  839. .De
  840. .NH 1
  841. Filing Bug Reports
  842. .LP
  843. If you find a reproducible bug in software in the \fBmit\fP directory,
  844. or find bugs in the \fBmit\fP documentation, please send a bug report
  845. to MIT using the form in the file \fBmit/bug-report\fP and the
  846. destination address:
  847. .Ds
  848. xbugs@expo.lcs.mit.edu
  849. .De
  850. .LP
  851. Please try to provide all of the information requested on the form if it is
  852. applicable; the little extra time you spend on the report will make it
  853. much easier for us to reproduce, find, and fix the bug.  Receipt of bug
  854. reports is generally acknowledged, but sometimes it can be delayed by a
  855. few weeks.
  856. .LP
  857. Bugs in \fBcontrib\fP software should not be reported to MIT.  Consult
  858. the documentation for the individual software to see where (if anywhere)
  859. to report the bug.
  860. .NH 1
  861. Public Fixes
  862. .LP
  863. We occasionally put out patches to the MIT software, to fix any
  864. serious problems that are discovered.  Such fixes (if any) can be found
  865. on \fBexport.lcs.mit.edu\fP, in the directory \fBpub/R5/fixes\fP,
  866. using anonymous \fBftp\fP.  Fixes are applied using the \fBpatch\fP
  867. program; a copy of it is included in the directory \fBmit/util/patch\fP.
  868. .LP
  869. For those without \fBftp\fP access, individual fixes can be obtained by
  870. electronic mail by sending a message to
  871. .Ds
  872. xstuff@expo.lcs.mit.edu
  873. .De
  874. .LP
  875. (Note that the host here is ``expo'', not ``export''.)  In the usual case,
  876. the message should have a subject line and no body, or a single-line body and
  877. no subject, in either case the line looking like:
  878. .Ds
  879. send fixes \fInumber\fP
  880. .De
  881. .LP
  882. where \fInumber\fP is a decimal number, starting from one.  To get a
  883. summary of available fixes, make the line:
  884. .Ds
  885. index fixes
  886. .De
  887. .LP
  888. If you need help, make the line:
  889. .Ds
  890. help
  891. .De
  892. .LP
  893. Some mailers produce mail headers that are unusable for extracting return
  894. addresses.  If you use such a mailer, you won't get any response.  If you
  895. happen to know an explicit return path, you can include include one in the
  896. body of your message, and the daemon will use it.  For example:
  897. .Ds
  898. path \fIuser\fP%\fIhost\fP.bitnet@mitvma.mit.edu
  899.     or
  900. path \fIhost1\fP!\fIhost2\fP!\fIuser\fP@uunet.uu.net
  901. .De
  902. .NH 1
  903. Configuring for a New Architecture
  904. .LP
  905. Here is a very brief overview of the files that \fBimake\fP reads.
  906. All the files are in the \fBmit/config\fP directory, except
  907. for the \fBImakefile\fP in the directory for which the \fBMakefile\fP
  908. is being created.  The processing order is:
  909. .Ds
  910. .ta 2.5i
  911. Imake.tmpl    variables not related specifically to X
  912.     site.def    site-specific BeforeVendorCF part
  913.     *.cf    machine-specific
  914.         *Lib.rules    shared library rules
  915.     site.def    site-specific AfterVendorCF part
  916.     Project.tmpl    X-specific variables
  917.         *Lib.tmpl    shared library variables
  918.     Imake.rules        rules
  919. Imakefile        specific to the program or library
  920.     Library.tmpl    library rules
  921.     Server.tmpl    server rules
  922. .De
  923. The indentation levels indicate what files include other files.
  924. .NH 2
  925. Imake.tmpl
  926. .LP
  927. The first part of \fBImake.tmpl\fP determines which \fB.cf\fP
  928. file to include.  If your \fBcpp\fP defines a unique symbol,
  929. that should be used to select the file.
  930. Otherwise, you should place a -D symbol definition
  931. in \fBBootstrapCFlags\fP in your \fB.cf\fP file and use that.
  932. The canonical code to add to \fBImake.tmpl\fP is:
  933. .Ds
  934. #ifdef \fIsymbol\fP
  935. #define MacroIncludeFile <\fIsymbol\fP.cf>
  936. #define MacroFile \fIsymbol\fP.cf
  937. #undef \fIsymbol\fP
  938. #define \fISymbol\fPArchitecture
  939. #endif /* \fIsymbol\fP */
  940. .De
  941. .NH 2
  942. imakemdep.h
  943. .LP
  944. You also need to edit the file \fBimakemdep.h\fP.  There are
  945. three parts to this file.  The first contains defines (beyond
  946. \fBBootstrapCFlags\fP) or compiler options that are required to get
  947. \fBimake\fP itself built the first time.
  948. .LP
  949. The next section is for \fBimake\fP itself.
  950. There is a hook in case your \fBcpp\fP collapses tabs down to single spaces.
  951. There is also a way to override the \fBcpp\fP to use.
  952. Finally, add specific defines to pass to \fBcpp\fP
  953. when processing configuration files.
  954. .LP
  955. The last section is for \fBmakedepend\fP, to tell it about
  956. predefined symbols that will be used to control inclusion of header files.
  957. .LP
  958. .NH 2
  959. vendor.cf
  960. .LP
  961. Most of the rest of your vendor-specific configuration information goes here.
  962. We won't try to tell you everything you need; study the other \fB.cf\fP
  963. files and copy from systems that are similar.  One good rule to follow
  964. is to not define anything that will get the correct default value from
  965. somewhere else; this will make it easier to see what is special, and will
  966. make it easier for sites to customize in their \fBsite.def\fP.
  967. .LP
  968. If you have shared libraries, the convention is to place the
  969. configuration rules and standard parameters in a file named
  970. \fIos\fP\fBLib.rules\fP, and to place version number parameters
  971. and \fBmake\fP variables in a file named \fIos\fP\fBLib.tmpl\fP.
  972. Look at the existing files and mimic them.
  973. .NH 2
  974. Other Files
  975. .LP
  976. Unfortunately, for a new system there are a potentially large number of files
  977. that you may have to modify.  Only the most prominent ones are listed here.
  978. .Ds
  979. mit/include/Xfuncs.h
  980. mit/include/Xmd.h
  981. mit/include/Xos.h
  982. mit/include/Xosdefs.h
  983. mit/clients/xload/get_load.c
  984. mit/clients/xman/vendor.c
  985. mit/clients/xman/vendor.h
  986. mit/clients/xterm/main.c
  987. mit/lib/X/Xlibnet.h
  988. mit/server/include/servermd.h
  989. .De
  990. .NH 1
  991. Writing Portable Code
  992. .LP
  993. In this section we give a brief introduction to using various header
  994. files to aid in writing portable code.
  995. .NH 2
  996. <X11/Xosdefs.h>
  997. .LP
  998. The file \fB<X11/Xosdefs.h>\fP defines symbols that describe the system
  999. environment for ANSI C and POSIX.  We likely will extend it to other
  1000. standards in the future.  We have found these symbols useful in
  1001. writing portable code, and hope that other writers of X software will
  1002. use them as well.
  1003. This file is not part of any X Consortium standard,
  1004. it is simply part of our software distribution.
  1005. .LP
  1006. \fB<X11/Xosdefs.h>\fP can be included directly by a file, or it
  1007. will be automatically included when you include \fB<X11/Xos.h>\fP.
  1008. .LP
  1009. The symbols in \fB<X11/Xosdefs.h>\fP tell when you can, for example, do
  1010. .Ds
  1011. #include <stdlib.h>
  1012. .De
  1013. .LP
  1014. without getting a ``no such header file'' error from the compiler.
  1015. If the system provides a declaration for a function or value for a
  1016. constant, it is important to use the system's definition rather than
  1017. providing your own, particularly because you might not use function
  1018. prototypes and the system might, or vice versa.
  1019. .LP
  1020. \fB<X11/Xosdefs.h>\fP currently controls two symbols:
  1021. \fBX_NOT_STDC_ENV\fP and \fBX_NOT_POSIX\fP.
  1022. .LP
  1023. \fBX_NOT_STDC_ENV\fP means the system does not have ANSI C header files.
  1024. Thus, for example, if \fBX_NOT_STDC_ENV\fP is not defined, it is safe to
  1025. include \fB<stdlib.h>\fP.  Do not confuse this symbol with \fB_\^_STDC_\^_\fP,
  1026. which says whether the compiler itself supports ANSI C semantics.
  1027. \fBX_NOT_STDC_ENV\fP is independent, and tells what header files it
  1028. is safe to include.
  1029. .LP
  1030. Lack of the symbol \fBX_NOT_STDC_ENV\fP does \fInot\fP mean that the
  1031. system has \fB<stdarg.h>\fP.  This header file is part of ANSI C,
  1032. but we have found it more useful to check for it separately because
  1033. many systems have all the ANSI C files we need except this one.
  1034. \fB_\^_STDC_\^_\fP is used to control inclusion of this file.
  1035. .LP
  1036. An example of using \fBX_NOT_STDC_ENV\fP might be to know when the system
  1037. declares \fBgetenv\fP:
  1038. .Ds
  1039. #ifndef X_NOT_STDC_ENV
  1040. #include <stdlib.h>
  1041. #else
  1042. extern char *getenv();
  1043. #endif
  1044. .De
  1045. .LP
  1046. We usually put the standard case first in our code, using ``#ifndef''.
  1047. .LP
  1048. \fBX_NOT_POSIX\fP means the system does not have POSIX.1 header files.
  1049. Lack of this symbol does \fInot\fP mean that the POSIX environment is
  1050. the default.  You may still have to define \fB_POSIX_SOURCE\fP before
  1051. including the header file to get POSIX definitions.\s-2\u3\d\s0
  1052. .FS
  1053. \s+2\&3.  We have found it very unfortunate that POSIX did not define
  1054. a standard symbol that means ``give me POSIX, plus any non-conflicting
  1055. vendor-specific definitions''.\s-2
  1056. .FE
  1057. .LP
  1058. An example of using \fBX_NOT_POSIX\fP might be to determine the type that
  1059. \fBgetuid\fP would be declared by in \fB<pwd.h>\fP:
  1060. .Ds
  1061. #include <pwd.h>
  1062. #ifndef X_NOT_POSIX
  1063.     uid_t uid;
  1064. #else
  1065.     int uid;
  1066.     extern int getuid();
  1067. #endif
  1068.     uid = getuid();
  1069. .De
  1070. .LP
  1071. Note that both of these symbols, when declared, state a
  1072. non-compliance.  This was chosen so that porting to a new, standard
  1073. platform would be easier.  Only non-standard platforms need to add
  1074. themselves to \fB<X11/Xosdefs.h>\fP to turn on the appropriate symbols.
  1075. .LP
  1076. Not all systems for which we leave these symbols undefined strictly
  1077. adhere to the relevant standards.  Thus you will sometimes see checks
  1078. for a specific O/S near a check for one of the Xosdefs.h symbols.
  1079. However, we have found it most useful to label systems as conforming
  1080. even if they have some holes in their compliance.  Presumably these
  1081. holes will become fewer as time goes on.
  1082. .NH 2
  1083. <X11/Xos.h>
  1084. .LP
  1085. In general, \fB<X11/Xos.h>\fP should be used instead of the
  1086. following header files:
  1087. .Ds
  1088. <string.h>
  1089. <strings.h>
  1090. <sys/types.h>
  1091. <sys/file.h>
  1092. <fcntl.h>
  1093. <sys/time.h>
  1094. <unistd.h>
  1095. .De
  1096. This file is not part of any X Consortium standard,
  1097. it is simply part of our software distribution.
  1098. .LP
  1099. Some common routines for which you need to include
  1100. \fB<X11/Xos.h>\fP before using are:
  1101. .Ds
  1102. index
  1103. rindex
  1104. strchr
  1105. strrchr
  1106. (all the other standard string routines)
  1107. gettimeofday
  1108. time
  1109. .De
  1110. .LP
  1111. Data types and constants that should be obtained with \fB<X11/Xos.h>\fP are:
  1112. .Ds
  1113. caddr_t
  1114. O_RDONLY
  1115. O_RDWR
  1116. (and other \fBopen\fP constants)
  1117. R_OK
  1118. W_OK
  1119. X_OK
  1120. (and other \fBfcntl\fP constants)
  1121. .De
  1122. .LP
  1123. Unfortunately, we did not create a header file for declaring \fBmalloc\fP
  1124. correctly, and it can be a bit tricky.  You can use what we currently
  1125. have by copying, for example, from \fBmit/lib/Xt/Alloc.c\fP:
  1126. .Ds
  1127. #ifndef X_NOT_STDC_ENV
  1128. #include <stdlib.h>
  1129. #else
  1130. char *malloc(), *realloc(), *calloc();
  1131. #endif
  1132. #if defined(macII) && !defined(__STDC__)  /* stdlib.h fails to define these */
  1133. char *malloc(), *realloc(), *calloc();
  1134. #endif /* macII */
  1135. .De
  1136. .NH 2
  1137. <X11/Xfuncs.h>
  1138. .LP
  1139. This file contains definitions of \fBbcopy\fP, \fBbzero\fP,
  1140. and \fBbcmp\fP.\s-2\u4\d\s0
  1141. .FS
  1142. \s+2\&4.  Yes, we should have used the ANSI C function names,
  1143. but we thought we had too much existing code using the BSD names.\s-2
  1144. .FE
  1145. You should include this header in any file that uses these functions.
  1146. This file is not part of any X Consortium standard,
  1147. it is simply part of our software distribution.
  1148. .NH 2
  1149. <X11/Xfuncproto.h>
  1150. .LP
  1151. This file contains definitions for writing function declarations
  1152. to get function prototypes to work right.
  1153. It deals with ANSI C compilers as well as pre-ANSI C compilers
  1154. that have parts of function prototypes implemented.
  1155. This file is not part of any X Consortium standard,
  1156. it is simply part of our software distribution.
  1157. .LP
  1158. For external header files that might get used from C++,
  1159. you should wrap all of your function declarations like this:
  1160. .Ds
  1161. _XFUNCPROTOBEGIN
  1162. \fIfunction declarations\fP
  1163. _XFUNCPROTOEND
  1164. .De
  1165. When in doubt, assume that the header file might get used from C++.
  1166. .LP
  1167. A typical function declaration uses \fBNeedFunctionPrototypes\fP, like this:
  1168. .Ds
  1169. extern Atom XInternAtom(
  1170. #if NeedFunctionPrototypes
  1171.     Display*        /* display */,
  1172.     _Xconst char*    /* atom_name */,
  1173.     Bool        /* only_if_exists */         
  1174. #endif
  1175. );
  1176. .De
  1177. .LP
  1178. If there are \fBconst\fP parameters, use the symbol \fB_Xconst\fP instead,
  1179. as above.
  1180. If it is plausible to pass a string literal to a char* parameter, then
  1181. it is a good idea to declare the parameter with \fB_Xconst\fP, so that
  1182. literals can be passed in C++.
  1183. .LP
  1184. If there are nested function prototypes, use \fBNeedNestedPrototypes\fP:
  1185. .Ds
  1186. extern Bool XCheckIfEvent(
  1187. #if NeedFunctionPrototypes
  1188.     Display*        /* display */,
  1189.     XEvent*        /* event_return */,
  1190.     Bool (*) (
  1191. #if NeedNestedPrototypes
  1192.            Display*            /* display */,
  1193.                XEvent*            /* event */,
  1194.                XPointer            /* arg */
  1195. #endif
  1196.              )        /* predicate */,
  1197.     XPointer        /* arg */
  1198. #endif
  1199. );
  1200. .De
  1201. .LP
  1202. If there is a variable argument list, use \fBNeedVarargsPrototypes\fP:
  1203. .Ds
  1204. extern char *XGetIMValues(
  1205. #if NeedVarargsPrototypes
  1206.     XIM /* im */, ...
  1207. #endif
  1208. );
  1209. .De
  1210. .LP
  1211. If you have parameter types that will widen in K&R C, then you should
  1212. use \fBNeedWidePrototypes\fP:
  1213. .Ds
  1214. extern XModifierKeymap *XDeleteModifiermapEntry(
  1215. #if NeedFunctionPrototypes
  1216.     XModifierKeymap*    /* modmap */,
  1217. #if NeedWidePrototypes
  1218.     unsigned int    /* keycode_entry */,
  1219. #else
  1220.     KeyCode        /* keycode_entry */,
  1221. #endif
  1222.     int            /* modifier */
  1223. #endif
  1224. );
  1225. .De
  1226. .LP
  1227. If you use \fB_Xconst\fP, \fBNeedNestedPrototypes\fP,
  1228. \fBNeedVarargsPrototypes\fP, or \fBNeedWidePrototypes\fP,
  1229. then your function implementation also has to have a
  1230. function prototype.  For example:
  1231. .Ds
  1232. #if NeedFunctionPrototypes
  1233. Atom XInternAtom (
  1234.     Display *dpy,
  1235.     _Xconst char *name,
  1236.     Bool onlyIfExists)
  1237. #else
  1238. Atom XInternAtom (dpy, name, onlyIfExists)
  1239.     Display *dpy;
  1240.     char *name;
  1241.     Bool onlyIfExists;
  1242. #endif
  1243. {
  1244.     ...
  1245. }
  1246. .De
  1247. .LP
  1248. Actually, anytime you use a function prototype in a header file,
  1249. you should use a function prototype in the implementation, as
  1250. required by ANSI C.  The MIT X sources do not follow this (we've
  1251. never had time to make all the changes), and there are almost
  1252. certainly compilers that will complain if the implementation
  1253. does not match the declaration.
  1254. .NH 2
  1255. Other Symbols
  1256. .LP
  1257. Do not use the names \fBclass\fP, \fBnew\fP, or \fBindex\fP as
  1258. variables or struct members.  The names \fBclass\fP and \fBnew\fP
  1259. are reserved words in C++, and you may find your header files
  1260. used by a C++ program someday.
  1261. Depending on your system, \fBindex\fP can be defined as \fBstrchr\fP
  1262. or a macro in \fB<X11/Xos.h>\fP; this may cause problems if you
  1263. include this header file.
  1264. .LP
  1265. The following system-specific symbols are commonly used in X sources
  1266. where OS dependencies intrude:\s-2\u5\d\s0
  1267. .FS
  1268. \s+2\&5.  At most \fIone\fP of these symbols should be defined
  1269. on a given system!\s-2
  1270. .FE
  1271. .Ds
  1272. .ta 1i
  1273. USG    based on System V Release 2
  1274. SYSV    based on System V Release 3
  1275. SVR4    System V Release 4
  1276. .De
  1277. .LP
  1278. For other system-specific symbols, look at the \fBStandardDefines\fP
  1279. parameters in the \fBmit/config/*.cf\fP files.
  1280. .NH 1
  1281. What's New, What's Changed
  1282. .LP
  1283. In this section we briefly describe some of the more significant
  1284. new features of Release 5.
  1285. .NH 2
  1286. New standards
  1287. .LP
  1288. The following standards are new in Release 5:
  1289. .Ip "X Font Service Protocol"
  1290. Instead of forcing each X server to read all fonts from the
  1291. filesystem, the X Font Server Protocol makes it
  1292. possible to manage fonts separately from the X server, directing the X
  1293. server to request fonts via this new Consortium standard network protocol from
  1294. a font server.
  1295. In addition, for fonts which take a long time to
  1296. open, this allows the X server to continue with other clients while
  1297. the font server services the font requests.
  1298. .Ip "XLFD changes for scalable fonts"
  1299. The X Logical Font Description standard has been compatibly enhanced
  1300. to allow clients to specify and use scalable fonts.
  1301. .Ip "X Input Device Extension"
  1302. This extension has been promoted from Draft Standard to full
  1303. Consortium Standard with this release.
  1304. .Ip "Inter-Client Communications Conventions"
  1305. This standard has been updated to cover the new X Device Color
  1306. Characterization Conventions for device-independent color support in Xlib.
  1307. .NH 2
  1308. General
  1309. .LP
  1310. We have tried hard with this release to make our code use standard
  1311. features from POSIX.1 and ANSI C when possible.  A new include file
  1312. \fB<X11/Xosdefs.h>\fP describes which systems comply or do not comply with
  1313. these standards.
  1314. .LP
  1315. Two new X authorization schemes are included, a DES based private-key system
  1316. which was described in the R4 XDMCP document - XDM-AUTHORIZATION-1 (along
  1317. with the associated XDMCP authentication system XDM-AUTHENTICATION-1) and
  1318. the Sun Secure RPC based SUN-DES-1 system, which uses the SunOS supplied
  1319. security system.
  1320. .NH 2
  1321. Clients
  1322. .LP
  1323. Most clients participate in the WM_DELETE_WINDOW protocol.
  1324. .LP
  1325. New clients: \fBeditres\fP, \fBviewres\fP, \fBxconsole\fP, \fBxcmsdb\fP.
  1326. New demos: \fBbeach_ball\fP, \fBauto_box\fP, \fBgpc\fP,
  1327. \fBxcmstest\fP, \fBxgas\fP, \fBx11perf\fP.
  1328. \fBXlswins\fP has been removed; it is replaced by \fBxwininfo -tree\fP.
  1329. Moved to contrib: \fBmuncher\fP, \fBplaid\fP.
  1330. Completely new implementation: \fBbitmap\fP and \fBxmag\fP.
  1331. Other changes of note:
  1332. .Ip editres
  1333. \fBEditres\fP is a tool that allows users and application developers to view
  1334. the full widget hierarchy of any X Toolkit client that speaks the
  1335. Editres protocol.  In addition \fBeditres\fP will help the user construct
  1336. resource specifications, allow the user to apply the resource to
  1337. the application and view the results dynamically.  Once the user is
  1338. happy with a resource specification, editres will append the resource
  1339. string to the user's resources file.
  1340. .Ip xdm
  1341. \fBXdm\fP can now display a menu of hosts for XDMCP-capable terminals using the
  1342. new \fIchooser\fP client.  This is useful for X terminals that
  1343. do not themselves offer such a menu.
  1344. XDMCP works with STREAMS.
  1345. A new setup program is invoked by \fBxdm\fP prior to putting up the
  1346. login window; this program can be used to run \fBxsetroot\fP, \fBxcmsdb\fP,
  1347. and do any other custom initialization required.
  1348. .Ip xterm
  1349. Cuts of wrapped lines are now treated as a single line.
  1350. Cuts of multi-page regions now work and highlight correctly.
  1351. Pasting large amounts of data into \fBxterm\fP now works (on systems with
  1352. properly-working pty implementations).
  1353. New arguments have been added to the send-signal action: quit, alarm.
  1354. The \fBtiteInibit\fP resource has been modified to also inhibit
  1355. the escape sequence
  1356. which switches to the alternate screen.
  1357. Two new items have been added to the VT Fonts menu: 
  1358. 5x7 (Tiny) and 10x20 (Huge).
  1359. The following resources have been added: \fBresizeGravity\fP,
  1360. \fBbellSuppressTime\fP,
  1361. \fBappcursorDefault\fP, \fBappkeypadDefault\fP,
  1362. \fBginTerminator\fP, \fBautoWrap\fP.
  1363. The \fIXterm Control Sequences\fP document is up to date.
  1364. \fBXterm\fP is installed securely when made setuid on SunOS 4.1.1
  1365. with shared libraries.
  1366. .Ip xmh
  1367. \fBXmh\fP now uses the \fBMH\fP environment variable, if set.
  1368. \fBXmh\fP now supports checking for mail in multiple maildrops.
  1369. Enhanced participation in WM_PROTOCOLS has been added.
  1370. New resources have been added, including:
  1371. \fBcheckpointInterval\fP,
  1372. \fBcheckpointNameFormat\fP,
  1373. \fBmailInterval\fP,
  1374. \fBrescanInterval\fP, \fBshowOnInc\fP, \fBnoMailBitmap\fP,
  1375. \fBnewMailBitmap\fP, \fBnewMailIconBitmap\fP, and \fBnoMailIconBitmap\fP.
  1376. New actions have been added:
  1377. XmhWMProtocols, XmhShellCommand, XmhCheckForNewMail,
  1378. XmhViewMarkDelete.
  1379. Better recovery from unexpected inconsistencies with the filesystem
  1380. has been implemented.
  1381. Better POP support has been added.
  1382. See the file \fBmit/clients/xmh/CHANGES\fP for more details.
  1383. .Ip oclock
  1384. \fBOclock\fP has a new \fB\-transparent\fP option.
  1385. .Ip xload
  1386. \fBXload\fP is secure on SunOS 4.1.1 with shared libraries.
  1387. .Ip xditview
  1388. \fBXditview\fP now supports \fBpic\fP, scalable fonts, settable
  1389. device resolution, and has a better user interface.
  1390. .NH 2
  1391. Libraries in General
  1392. .LP
  1393. All of the useful libraries now use function prototypes by default for
  1394. systems which support them.
  1395. SunOS shared libraries now use much less swap space than in R4.
  1396. In addition, System V Release 4 and AIX 3.1 shared libraries are also
  1397. supported now.  Configuring new shared library systems should be much
  1398. easier than before.
  1399. .NH 2
  1400. Xlib
  1401. .LP
  1402. Two new major pieces of functionality have been added to Xlib:
  1403. device independent color, and internationalization (i18n).
  1404. In addition, a few other additions and improvements have been made.
  1405. .NH 3
  1406. Xlib Manual
  1407. .LP
  1408. The Xlib manual has been reorganized for Release 5.
  1409. Unfortunately, this may cause considerable confusion for a while
  1410. when people quote section numbers without reference to the release.
  1411. However, we feel that the new organization is a considerable improvement.
  1412. .NH 3
  1413. Device-independent Color
  1414. .LP
  1415. The \fBXcms\fP (X Color Management System) functions in Xlib
  1416. support device-independent color spaces derivable from the CIE XYZ
  1417. color space.
  1418. This includes the CIE XYZ, xyY, L*u*v*, and L*a*b* color spaces as well as
  1419. the TekHVC color space.
  1420. In addition, linear RGB intensity value space has been added, as
  1421. well as gamma correction for device RGB values,
  1422. and a uniform syntax has been adopted for specifying colors in strings.
  1423. Xlib now supports client-side color name databases, and the
  1424. existing Xlib functions that use color names (e.g.,
  1425. \fBXLookupColor\fP and \fBXAllocNamedColor\fP) now handle all
  1426. color spaces, so that the contrivance of using \fBXParseColor\fP
  1427. followed by \fBXAllocColor\fP is no longer necessary.
  1428. Xlib provides direct programming interfaces for dealing with color
  1429. values in different spaces, and for converting between spaces.
  1430. New device-independent color spaces can also be added.
  1431. For details on the new color functionality, read Chapter 6 of
  1432. the new Xlib manual.
  1433. .LP
  1434. Monitors are characterized by data stored on root window properties;
  1435. the new \fBxcmsdb\fP program can be used to set these properties.
  1436. Unfortunately, you need a color analyzer instrument to generate
  1437. characterizations; choosing a random one will almost certainly
  1438. produce inaccurate colors.  However, you will find some sample
  1439. database files in \fBmit/clients/xcmsdb/datafiles\fP and in
  1440. \fBcontrib/clients/ca100/monitors\fP.
  1441. .NH 3
  1442. Internationalization
  1443. .LP
  1444. An internationalized application is one which is adaptable to the requirements
  1445. of different native languages, local customs, and character string encodings.
  1446. The process of adapting the operation to a particular native language,
  1447. local custom, or string encoding is called localizaton.
  1448. A goal of internationalization is to permit localization
  1449. without program source modifications or recompilation.
  1450. .LP
  1451. Internationalization in Xlib is based on the concept of a \fIlocale\fP.
  1452. A locale defines the ``localized'' behavior of a program at run-time.
  1453. Locales affect Xlib in its:
  1454. .IP \(bu 5
  1455. Encoding and processing of input method text
  1456. .IP \(bu 5
  1457. Encoding of resource files and values
  1458. .IP \(bu 5
  1459. Encoding and imaging of text strings
  1460. .IP \(bu 5
  1461. Encoding and decoding for inter-client text communication
  1462. .LP
  1463. Characters from various languages are represented in a computer
  1464. using an encoding.
  1465. Different languages have different encodings,
  1466. and there are even different encodings for the same characters
  1467. in the same language.
  1468. .LP
  1469. Xlib provides support for localized text imaging and text input.
  1470. Sets of functions are provided for multibyte (char\&*) text as well as
  1471. wide character (\fBwchar_t\fP) text in the form supported
  1472. by the host C language environment.
  1473. For details on the new internationalization functionality,
  1474. read Chapter 13 of the new Xlib manual.
  1475. .LP
  1476. Two sample implementations of the internationalization mechanisms
  1477. exist in this release, one called \fBXsi\fP and one called \fBXimp\fP.
  1478. You will find documentation for them in \fBmit/doc/I18N\fP and
  1479. \fBcontrib/im\fP, and locale definition files in \fBmit/lib/nls\fP.
  1480. In \fBcontrib/im\fP you will also find network-based
  1481. Input Method servers.
  1482. .LP
  1483. Unfortunately, none of the programs in the MIT software use the new
  1484. internationalization facilities.  However, you will find some sample
  1485. clients in \fBcontrib/im\fP, and internationalized versions of some
  1486. of the MIT clients in \fBcontrib/clients\fP.
  1487. .NH 3
  1488. Keysyms
  1489. .LP
  1490. By default a database of all registered vendor-private keysyms
  1491. gets installed, so that Xlib can map between keysym values and names.
  1492. .NH 3
  1493. Resource Databases
  1494. .LP
  1495. A new SCREEN_RESOURCES property has been defined, permitting
  1496. screen-specific resources to be set, so that (for example)
  1497. colors can be specified for a color screen and not effect
  1498. a monochrome screen on the same server.  The \fBxrdb\fP program
  1499. has been enhanced to ``do the right thing'' automatically
  1500. in most cases.
  1501. .LP
  1502. New functions have been defined to merge a resource database
  1503. directly from a file, and to combine two databases with either
  1504. ``augment'' or ``override'' semantics.
  1505. .LP
  1506. A ``#include'' syntax is now supported in resource files.
  1507. A specific example of using this is to have a customized
  1508. app-defaults file (in an Xt application) include the base
  1509. app-defaults file.
  1510. .LP
  1511. A new reserved component name, ``?'', has been defined
  1512. that matches a single level in the resource hierarchy.
  1513. This makes it easier to override resources specified in
  1514. app-defaults files.
  1515. .LP
  1516. A new function, \fBXrmEnumerateDatabase\fP, has been defined
  1517. to search for matching entries in a resource database.
  1518. The \fBappres\fP program has been enhanced in this release
  1519. to become a convenient interface to this function.
  1520. .LP
  1521. A new function, \fBXrmPermStringToQuark\fP, has been
  1522. introduced to avoid having Xlib allocate needless storage
  1523. for constant strings.
  1524. .NH 3
  1525. Extensions
  1526. .LP
  1527. A new function has been added to permit an extension to convert
  1528. errors with additional data into Xlib format, and one has been
  1529. added to permit an extension to print out the values in an
  1530. error handler.
  1531. .NH 3
  1532. Miscellaneous
  1533. .LP
  1534. A new type \fBXPointer\fP has been introduced, replacing
  1535. uses of the non-standard type \fBcaddr_t\fP.  Old programs
  1536. using \fBcaddr_t\fP will still work, of course.
  1537. .NH 3
  1538. Performance
  1539. .LP
  1540. The new color and internationalization facilities have the unfortunate
  1541. effect of making executables quite a bit larger on systems that do
  1542. not have shared libraries.
  1543. .LP
  1544. The resource database functions have been completely rewritten for
  1545. this release.  Databases should be significantly smaller in memory,
  1546. and loading and parsing resources should be faster.
  1547. .NH 2
  1548. Xt Intrinsics
  1549. .LP
  1550. At the data structure level, Release 5 retains complete binary
  1551. compatibility with Release 4.  The specification of the
  1552. \fBObjectPart\fP,
  1553. \fBRectObjPart\fP,
  1554. \fBCorePart\fP,
  1555. \fBCompositePart\fP,
  1556. \fBShellPart\fP,
  1557. \fBWMShellPart\fP,
  1558. \fBTopLevelShellPart\fP,
  1559. and
  1560. \fBApplicationShellPart\fP
  1561. instance records was made less strict to permit implementations to
  1562. add internal fields to these structures.  Any implementation that
  1563. chooses to do so would, of course, force a recompilation.
  1564. The Xlib specification for
  1565. \fBXrmValue\fP
  1566. and
  1567. \fBXrmOptionDescRec\fP
  1568. was updated to use a new type,
  1569. \fBXPointer\fP,
  1570. for the \fIaddr\fP and \fIvalue\fP fields respectively, to avoid
  1571. ANSI C conformance problems.  The definition of
  1572. \fBXPointer\fP
  1573. is binary compatible with the previous implementation.
  1574. .NH 3
  1575. baseTranslations Resource
  1576. .LP
  1577. A new pseudo-resource, \fBXtNbaseTranslations\fP, was defined to permit
  1578. application developers to specify translation tables in application
  1579. defaults files while still giving end users the ability to augment
  1580. or override individual event sequences.  This change will affect
  1581. only those applications that wish to take advantage of the new
  1582. functionality, or those widgets that may have previously defined
  1583. a resource named ``baseTranslations''.
  1584. .LP
  1585. Applications wishing to take advantage of the new functionality
  1586. would change their application defaults file, e.g., from
  1587. .Ds
  1588. app.widget.translations: \fIvalue\fP
  1589. .De
  1590. to
  1591. .Ds
  1592. app.widget.baseTranslations: \fIvalue\fP
  1593. .De
  1594. If it is important to the application to preserve complete
  1595. compatibility of the defaults file between different versions
  1596. of the application running under Release 4 and Release 5,
  1597. the full translations can be replicated in both the ``translations''
  1598. and the ``baseTranslations'' resource.
  1599. .NH 3
  1600. Resource File Search Path
  1601. .LP
  1602. The current specification allows implementations greater flexibility
  1603. in defining the directory structure used to hold the application class
  1604. and per-user application defaults files.  Previous specifications
  1605. required the substitution strings to appear in the default path in a
  1606. certain order, preventing sites from collecting all the files for
  1607. a specific application together in one directory.  The Release 5
  1608. specification allows the default path to specify the substitution
  1609. strings in any order within a single path entry.  Users will need to
  1610. pay close attention to the documentation for the specific
  1611. implementation to know where to find these files and how to specify
  1612. their own
  1613. \fBXFILESEARCHPATH\fP
  1614. and
  1615. \fBXUSERFILESEARCHPATH\fP
  1616. values when overriding the system defaults.
  1617. .NH 3
  1618. Customization Resource
  1619. .LP
  1620. \fBXtResolvePathname\fP
  1621. supports a new substitution string, %C, for specifying separate
  1622. application class resource files according to arbitrary user-specified
  1623. categories.  The primary motivation for this addition was separate
  1624. monochrome and color application class defaults files.  The
  1625. substitution value is obtained by querying the current resource
  1626. database for the application resource name ``customization'', class
  1627. ``Customization''.  Any application that previously used this
  1628. resource name and class will need to be aware of the possibly
  1629. conflicting semantics.
  1630. .NH 3
  1631. Per-Screen Resource Database
  1632. .LP
  1633. To allow a user to specify separate preferences for each screen of a
  1634. display, a per-screen resource specification string has been added and
  1635. multiple resource databases are created; one for each screen.  This
  1636. will affect any application that modified the (formerly unique)
  1637. resource database associated with the display subsequent to the Intrinsics
  1638. database initialization.  Such applications will need to be aware
  1639. of the particular screen on which each shell widget is to be created.
  1640. .LP
  1641. Although the wording of the specification changed substantially in the
  1642. description of the process by which the resource database(s) is
  1643. initialized, the net effect is the same as in prior releases with the
  1644. exception of the added per-screen resource specification and the new
  1645. customization substitution string in
  1646. \fBXtResolvePathname\fP.
  1647. .NH 3
  1648. Internationalization of Applications
  1649. .LP
  1650. Internationalization as defined by ANSI is a technology that
  1651. allows support of an application in a single locale.  In
  1652. adding support for internationalization to the Intrinsics
  1653. the restrictions of this model have been followed.
  1654. In particular, the new Intrinsics interfaces are designed to not
  1655. preclude an application from using other alternatives.
  1656. For this reason, no Intrinsics routine makes a call to establish the
  1657. locale.   However, a convenience routine to establish the
  1658. locale at initialize time has been provided, in the form
  1659. of a default procedure that must be explicitly installed
  1660. if the application desires ANSI C locale behavior.
  1661. .LP
  1662. As many objects in X, particularly resource databases, now inherit
  1663. the global locale when they are created, applications wishing to use
  1664. the ANSI C locale model should use the new function
  1665. \fBXtSetLanguageProc\fP
  1666. to do so.
  1667. .LP
  1668. The internationalization additions also define event filters
  1669. as a part of the Xlib Input Method specifications.  The
  1670. Intrinsics enable the use of event filters through additions to
  1671. \fBXtDispatchEvent\fP.
  1672. Applications that may not be dispatching all events through
  1673. \fBXtDispatchEvent\fP
  1674. should be reviewed in the context of this new input method mechanism.
  1675. .LP
  1676. In order to permit internationalization of error messages the name
  1677. and path of the error database file is now allowed to be implementation
  1678. dependent.  No adequate standard mechanism has yet been suggested to
  1679. allow the Intrinsics to locate the database from localization information
  1680. supplied by the client.
  1681. .LP
  1682. The previous specification for the syntax of the language string
  1683. specified by
  1684. \fBxnlLanguage\fP
  1685. has been dropped to avoid potential conflicts with other standards.
  1686. The language string syntax is now implementation-defined.
  1687. The example syntax cited is consistent with the previous
  1688. specification.
  1689. .NH 3
  1690. Permanently Allocated Strings
  1691. .LP
  1692. In order to permit additional memory savings, an Xlib interface was
  1693. added to allow the resource manager to avoid copying certain string
  1694. constants.  The Intrinsics specification was updated to explicitly require
  1695. the Object \fIclass_name\fP, \fIresource_name\fP, \fIresource_class\fP,
  1696. \fIresource_type\fP, \fIdefault_type\fP in resource tables, Core \fIactions\fP
  1697. \fIstring\fP field, and Constraint \fIresource_name\fP, \fIresource_class\fP,
  1698. \fIresource_type\fP, and \fIdefault_type\fP resource fields to be
  1699. permanently allocated.  This explicit requirement is expected to
  1700. affect only applications that may create and destroy classes
  1701. on the fly.
  1702. .NH 3
  1703. Arguments to Existing Functions
  1704. .LP
  1705. The \fIargs\fP argument to
  1706. \fBXtAppInitialize\fP,
  1707. \fBXtVaAppInitialize\fP,
  1708. \fBXtOpenDisplay\fP,
  1709. \fBXtDisplayInitialize\fP,
  1710. and
  1711. \fBXtInitialize\fP
  1712. were changed from
  1713. \fBCardinal\fP*
  1714. to int* to conform to pre-existing convention and avoid otherwise
  1715. annoying typecasting in ANSI C environments.
  1716. .NH 3
  1717. Implementation
  1718. .LP
  1719. Function prototypes are now fully supported in the header files.
  1720. .LP
  1721. \fB<X11/Intrinsic.h>\fP no longer includes \fB<X11/Xos.h>\fP by default.
  1722. Inclusion of this file was a bug in earlier releases.  If you have
  1723. old code that depends on this bug, you can define -DXT_BC when you compile
  1724. to get back the old behaviour.
  1725. .LP
  1726. String constants are now defined in a single array, saving memory and external
  1727. symbols.  Note that because the new implementation uses #defines, string
  1728. constants in widget header files which duplicate a constant defined by Xt
  1729. should either be removed or protected from a collision.
  1730. .LP
  1731. The translation manager facilities have been completely reimplemented
  1732. in this release, resulting in substantially less memory consumed by
  1733. some applications.
  1734. A number of other memory-saving changes have been implemented, and
  1735. in a few cases execution time should be faster.
  1736. .LP
  1737. The default keycode to keysym translator deals with all Latin keysyms.
  1738. .NH 3
  1739. Extension Events
  1740. .LP
  1741. Unfortunately, the Xt standard as of R5 still does not address the
  1742. issues of integrating events from protocol extensions into the
  1743. normal Xt dispatch mechanism.  The adventurous will find a set
  1744. of patches to Xt in \fBcontrib/lib/Xt\fP that attempt to address
  1745. this problem.  These patches are non-standard, experimental,
  1746. subject to change, not guaranteed, may adversely affect your ability to
  1747. apply public patches from MIT, and have not reviewed by the X Consortium.
  1748. .NH 2
  1749. PEX
  1750. .LP
  1751. The PEX Sample Implementation (SI) is composed of several parts. The
  1752. major components are the extension to the X Server, which implements
  1753. the PEX protocol, and the client side Application Protocol Interface (API),
  1754. which provides a mechanism by which clients can generate PEX protocol.
  1755. The API provided with the PEX-SI is the ISO IS PHIGS Binding and the
  1756. yet to be standardized PHIGS PLUS Binding.
  1757. .LP
  1758. In addition to these major components, several other minor components are
  1759. provided.  These include documentation, 3D fonts for PEX, demos, and
  1760. a verification suite called InsPEX.  Also provided in \fBcontrib\fP
  1761. are additional example programs and demos.
  1762. .LP
  1763. These elements are located in the following area:
  1764. .LP
  1765. The PEX server extension is located in the directories under
  1766. \fBmit/extensions/server/PEX\fP.  Device independent portions are located
  1767. in \fBmit/extensions/server/PEX/dipex\fP.  Device dependent functionality
  1768. appears in \fBmit/extensions/server/PEX/ddpex\fP.  Operating system font
  1769. dependent code appears in \fBmit/extensions/server/PEX/ospex\fP.  General
  1770. purpose server include files are in \fBmit/extensions/server/PEX/include\fP.
  1771. .LP
  1772. The API code is located under the directory \fBmit/extensions/lib/PEX\fP.
  1773. The PHIGS/PHIGS PLUS Binding routines are in the \fBc_binding\fP subdirectory.
  1774. The PHIGS Monitor (PM), a separate process started at client runtime
  1775. to handle PHIGS Input functionality, is in the \fBcp\fP subdirectory.
  1776. Other code located in the various subdirectories handles PHIGS archival,
  1777. error handling, and comprises the internal library level that PHIGS calls
  1778. to generate the PEX Protocol.
  1779. .LP
  1780. All PEX documentation is located in the directory \fBmit/doc/extensions/PEX\fP,
  1781. with pregenerated PostScript files in \fBmit/hardcopy/extensions/PEX\fP.
  1782. The PEX Protocol Specification itself is in the \fBProto\fP subdirectory.  All
  1783. SI documentation is in the \fBSI\fP subdirectory.  Three subdirectories there
  1784. contain an Architecture Specification, a Porting Guide (with implementation
  1785. details), and a User's Guide.  The sources and programs used to generate
  1786. these files are located in the \fBmit/doc/extensions/PEX/SI\fP directory.
  1787. Also located there is the \fBPHIGS\fP subdirectory which contains PHIGS man
  1788. pages and macros for printing these pages.
  1789. .LP
  1790. Font source for PEX and utilities to build them are located in the directory 
  1791. \fBmit/fonts/PEX\fP.  Two stroke fonts are supplied.
  1792. .LP
  1793. The PEX verification tool InsPEX can be found in the
  1794. \fBmit/extensions/test/InsPEX\fP directory.
  1795. Shell scripts are provided there to run InsPEX.
  1796. More information on InsPEX is available in the User's Guide.
  1797. .LP
  1798. Demos for PEX can be found in the \fBmit/demos\fP directory.
  1799. Two demos and the
  1800. NCGA Graphics Performance Characterization (GPC) Suite can be found
  1801. there.  The demos are in the \fBmit/demos/auto_box\fP and
  1802. \fBmit/demos/beach_ball\fP directories, and are named \fBauto_box\fP
  1803. and \fBbeach_ball\fP respectively.
  1804. The GPC suite is found in \fBmit/demos/gpc\fP.
  1805. This suite consists of demos (in the \fBobjects\fP subdirectory),
  1806. benchmarks (various directories below \fBbenchmarks\fP) and tests
  1807. (in \fBtests\fP).  For more information on how to run these demos see the
  1808. User's Guide.
  1809. .LP
  1810. There are also several unsupported demos and examples available in
  1811. \fBcontrib\fP.  In \fBcontrib/demos/beach_ball2\fP a newer version 
  1812. of the \fBbeach_ball\fP demo with enhanced functionality can be found.
  1813. In \fBcontrib/examples/PEX\fP various PHIGS based clients that
  1814. demonstrate how to use PEX via the PHIGS API are available.
  1815. .NH 3
  1816. Standards and Functionality
  1817. .LP
  1818. This release conforms to the PEX Protocol Specification V5.0P.
  1819. The release comes with 2 fonts, Roman and Roman_M (see the User's Guide for
  1820. more details).  It implements the minimum required HLHSR (Hidden Line/
  1821. Hidden Surface Removal) for PHIGS compliance (i.e., NONE).  The release
  1822. only supports 8-bit color.
  1823. .LP
  1824. The API binding has been updated to the ISO IS PHIGS binding.
  1825. The directory \fBmit/util/PEX\fP contains \fBsed\fP scripts for
  1826. converting programs
  1827. from the previous binding to the new binding.  These scripts do most of 
  1828. the work, but some manual editing is still needed.  There is a \fBREADME\fP
  1829. file in this directory with notes and information.
  1830. .LP
  1831. The PHIGS Binding provides most PHIGS/PHIGS PLUS functionality.  The full
  1832. PHIGS Input Model (Valuator, Locator, Stroke, Choice, String, Pick)
  1833. is implemented in a device independent manner using the Athena Widget Set.
  1834. PHIGS/PHIGS PLUS functionality includes, but is not limited to the following
  1835. graphical primitives:  Polylines, Polymarkers, Fill Areas, Triangle Strips,
  1836. NURBS Curves and Surfaces, 2D and 3D Text.  Other operations include
  1837. Depth Cueing, Modelling Clip, Backface removal, Lighting Models and
  1838. Surface Reflection.
  1839. .LP
  1840. Functionality not completed in this release is as follows: 
  1841. .LP
  1842. In the API:
  1843. .Ds
  1844. Mapping of PHIGS font ids to PEX fonts
  1845. .De
  1846. .LP
  1847. In the Server:
  1848. .Ds
  1849. Backface Attributes and Distinguish Flag
  1850. Font sharing between clients
  1851. Patterns, Hatches and associated attributes
  1852. Color Interpolation
  1853. Transparency
  1854. Depth Cueing for Markers
  1855. Z-buffering
  1856. Double Buffering
  1857. .De
  1858. .LP
  1859. In InsPEX:
  1860. .Ds
  1861. Completion of port to ISO IS PHIGS Binding
  1862. .De
  1863. .NH 3
  1864. PEX and PHIGS Documents
  1865. .LP
  1866. The following documents are provided with this release:
  1867. .Ds
  1868. PEX-SI User Guide
  1869. PEX-SI Graphics Library Manual Pages
  1870. PEX-SI Architecture Specification
  1871. PEX-SI Porting Guide
  1872. .De
  1873. .LP
  1874. They are located in subdirectories of \fBmit/doc/extensions/PEX\fP.
  1875. Please read the PEX-SI User's Guide for descriptions of the documents and
  1876. how to use them.  Instructions for printing the documents are provided
  1877. in a README file in each of the document directories.
  1878. .LP
  1879. The User's Guide is provided as a starting point in the documentation.
  1880. It describes the various documents provided with the release, and includes
  1881. instructions on using the clients, the API and the server code.
  1882. It also includes specifications for the server functionality and archive
  1883. format.
  1884. .LP
  1885. The Graphics Library Manual Pages are for the client-side library,
  1886. written to the ISO IS binding.
  1887. .LP
  1888. The Architecture Specification describes the PEX-SI architecture
  1889. at a high level.
  1890. .LP
  1891. The Porting Guide is intended as an extension to the Architecture
  1892. Specification.  There is a lot of good information in this document,
  1893. and it is organized fairly well, but it lacks some polish.  It is not a
  1894. complete document.
  1895. .NH 3
  1896. InsPEX
  1897. .LP
  1898. This release of InsPEX includes coverage of all the PHIGS PLUS graphics
  1899. primitives, such as fill area sets with data, quadrilateral meshes,
  1900. triangle strips, and NURBS.  PHIGS PLUS attributes such as direct color
  1901. specification, depth cuing, and lighting are also exercised.
  1902. .LP
  1903. The testing of input is somewhat limited by the problem of simulating
  1904. mouse and keyboard input in a reliable and portable fashion.  For the
  1905. pick, locator, and stroke devices, simulating the mouse events is
  1906. straightforward, but since the string, valuator, and choice devices
  1907. are built upon a toolkit (Athena Widgets in the PEX-SI's case), getting
  1908. window id's for the appropriate windows and sending mouse
  1909. clicks to the right place on those windows is more difficult,
  1910. and probably impossible to do in a way that could be quickly
  1911. ported to another toolkit along with these input devices.
  1912. The technology for automatic testing of software using
  1913. a graphical user interface under X has not progressed to the
  1914. point where this functionality could be tested in a way
  1915. that would be useful to all the potential users of InsPEX.
  1916. .LP
  1917. For nearly all of the tests that use image comparison
  1918. to verify graphical output, reference images have been supplied.
  1919. Due to outstanding bugs in the code, however, some tests are shipped without
  1920. reference images.  Also, since back-facing attributes are not implemented,
  1921. the images saved for these tests are actually incorrect.  These have been
  1922. shipped, however, because they still can be helpful to someone porting
  1923. the PEX-SI.  It should be expected that when backfacing attributes are
  1924. implemented, these tests will fail and image comparison will be required.
  1925. .LP
  1926. Along with the \fBREADME\fP in the main InsPEX directory, there is a sample
  1927. log file, sample.log, and an automatically-generated summary of all the
  1928. current tests, \fBtest_descrip\fP.  See the \fBREADME\fP for a description
  1929. of how that file was generated.
  1930. .NH 2
  1931. Athena Widget Set
  1932. .LP
  1933. Many minor bugs have been fixed.
  1934. The Xaw examples have been moved to \fBcontrib\fP.
  1935. However, please note that the Athena Widgets have been and continue
  1936. to be low on our priority list, so many bugs remain (particularly
  1937. in the Text widget) and many requests for enhancements have not
  1938. been implemented.  Because some incompatible
  1939. changes have been made, the shared library major version number on
  1940. Suns has been incremented.
  1941. .Ip "Header Files"
  1942. Function prototypes have been added to the public interfaces.
  1943. .Ip "AsciiSrc"
  1944. No warning message is printed when the file cannot be
  1945. written to; the return value should be enough info.
  1946. \fBGetValues\fP on the string resource was failing when
  1947. "useStringInPlace" was set to true; fixed.
  1948. A memory leak when freeing pieces in a source of type "ascii String"
  1949. has been plugged.
  1950. The buffer is now updated whenever the "string" resource is set using
  1951. \fBXtSetValues\fP.  If the type is file then the file is read in again.
  1952. .Ip "Box"
  1953. \fBBox.h\fP now includes \fB<X11/Xmu/Converters.h>\fP for the 
  1954. orientation resources.
  1955. .Ip "Clock"
  1956. Changed to be a subclass of \fBSimple\fP instead of \fBCore\fP.
  1957. .Ip "Command"
  1958. A bug in changing the shape style back to Rectangular has been fixed.
  1959. .Ip "Dialog"
  1960. The Icon resource type has changed from \fBPixmap\fP to \fBBitmap\fP.
  1961. .Ip "Form"
  1962. The geometry handler now will now disallow geometry management
  1963. requests that will force the child outside the \fBForm\fP's window.
  1964. EdgeType names have been changed to have prefix ``Xaw'' instead of ``Xt'', but
  1965. the old definitions are still around with a #define.
  1966. The string-to-widget converter no longer caches resources.
  1967. .Ip "Logo"
  1968. Changed to be a subclass of \fBSimple\fP instead of \fBCore\fP.
  1969. Reverse video now works correctly.
  1970. .Ip "Mailbox"
  1971. Changed to be a subclass of \fBSimple\fP instead of \fBCore\fP.
  1972. Reverse video now works correctly.
  1973. .Ip "MenuButton"
  1974. The \fBMenuButton\fP widget no longer places a server grab on itself.
  1975. Instead, \fBPopupMenu\fP is registered as a grab action.  As a result
  1976. of this, clients which popped up menus without using \fBXtMenuPopup\fP
  1977. or \fBMenuPopup\fP or \fBPopupMenu\fP in the menu button translations will
  1978. fail to have a grab active.  They should make a call to
  1979. \fBXtRegisterGrabAction\fP on the appropriate action in the application
  1980. initialization routine, or use a different translation.
  1981. .Ip "Paned"
  1982. \fBPaned.h\fP now includes \fB<X11/Xmu/Converters.h>\fP for the 
  1983. orientation resources.
  1984. .Ip "Panner"
  1985. This widget is new in R5, see the Xaw manual for details.
  1986. .Ip "Porthole"
  1987. This widget is new in R5, see the Xaw manual for details.
  1988. .Ip "Repeater"
  1989. This widget is new in R5, see the Xaw manual for details.
  1990. .Ip "Scrollbar"
  1991. Changed to be a subclass of \fBSimple\fP instead of \fBCore\fP.
  1992. The type of thumb resource has changes from \fBPixmap\fP to \fBBitmap\fP.
  1993. However, if applications provide the resource conversion, the 
  1994. \fBSetValues\fP method can still handle pixmaps of correct depth.
  1995. .Ip "Simple"
  1996. A color cursor converter has been added, as well as the new
  1997. new resource types: \fBXtNpointerColor\fP,
  1998. \fBXtNpointerColorBackground\fP, and \fBXtNcursorName\fP.
  1999. .Ip "SmeBSB"
  2000. The Right bitmaps are now painted in the correct location.
  2001. Right and Left Bitmaps can be specified in resource files, and
  2002. at startup time.
  2003. .Ip "Text"
  2004. If there is no current selection the the selection extends
  2005. from the insert point, rather than some random location.
  2006. Forward (Backward) Paragraph works at the paragraph boundaries now.
  2007. Selecting a word now transitions correctly at both end points.
  2008. An infinite loop when using fill paragraph in a read only text widget
  2009. has been found and fixed.
  2010. When the "resize" resource is set the text will start up with
  2011. exactly enough space to contain the text in the widget.
  2012. A bug that could cause an infinite loop when Meta-Q was used
  2013. to invoke the form-paragraph function on a read-only text widget has
  2014. been fixed.
  2015. Problems dealing with exposure events have been fixed.
  2016. In \fBTextP.h\fP, the names of the following symbolic constants
  2017. have each had the prefix Xaw added to them:
  2018. \fBXawLF\fP, \fBXawCR\fP, \fBXawTAB\fP, \fBXawBS\fP, \fBXawSP\fP,
  2019. \fBXawDEL\fP, and \fBXawBSLASH\fP.
  2020. .Ip "Toggle"
  2021. The widget state is preserved across changes in sensitivity.
  2022. A string-to-widget converter is registered for radio groups.
  2023. .Ip "Tree"
  2024. This widget is new in R5, see the Xaw manual for details.
  2025. .Ip "Paned"
  2026. A bug that caused \fBXtGeometryYes\fP returns to have bogus values,
  2027. and caused panes to get random sizes, has been fixed.
  2028. .Ip "Vendor"
  2029. Support has been added for the \fBeditres\fP protocol.
  2030. All applications using the Athena Widgets are automatically
  2031. editable with \fBeditres\fP.
  2032. A bug that cause \fBShell\fP to ignore all but first child has been fixed.
  2033. .Ip "Viewport"
  2034. \fBXawPannerReport\fP support has been added.
  2035. .NH 2
  2036. X Server
  2037. .LP
  2038. Considerably more work speeding up the server has been done,
  2039. particularly in the \fBcfb\fP and \fBmfb\fP code.
  2040. The font interfaces are completely new.
  2041. Compressed fonts are not supported in the release.
  2042. Other changes are documented in \fBmit/doc/Server/r5.tbl.ms\fP.
  2043. .NH 2
  2044. Fonts
  2045. .Ip "Font Server"
  2046. A sample implementation of the server side of the X Font Service Protocol
  2047. is provided in a new program, \fBfs\fP.
  2048. On the Macintosh, a special version of the server called \fBMacFS\fP
  2049. can be used to serve TrueType fonts.
  2050. .Ip "New Font Format"
  2051. Both the X server and the font server use a
  2052. new font format, \fIpcf\fP (portable compiled font).
  2053. Pcf is readable across different machines and contains more information
  2054. about a font than the old snf format.  Fonts in snf format can still
  2055. be used.
  2056. .Ip "Font Applications"
  2057. The following new utilities talk to the font server:
  2058. \fBfsinfo\fP, \fBfslsfonts\fP, \fBfstobdf\fP, and \fBshowfont\fP.
  2059. To build pcf fonts, \fBbdftosnf\fP has been replaced by \fBbdftopcf\fP.
  2060. .Ip "Scalable Fonts"
  2061. Bitstream, Inc. has donated an outline scaling engine along with
  2062. a set of sample fonts, matching the donated bitmap fonts included with
  2063. Release 4.  In addition, a usable (but not very pretty) bitmap scaling
  2064. engine has been implemented which
  2065. allows the use of all other fonts at arbitrary point sizes.
  2066. .Ip "Font Changes"
  2067. Many \fBmisc\fP fonts now have ISO Latin-1 upper half characters and
  2068. some tuning.
  2069. The following sets of fonts are new:
  2070. Latin/Hebrew in ISO8859-8 encoding,
  2071. Kanji in JISX0208.1983-0 encoding,\s-2\u6\d\s0
  2072. .FS
  2073. \s+2\&6.  The JIS Kanji fonts were purchased on behalf of the MIT X Consortium
  2074. from the Japanese Standards Association, 1-24, Akasaka 4,
  2075. Minato-ku, Tokyo 107, Japan.  They were converted to BDF format,
  2076. keeping within the JIS rules.  In keeping with
  2077. JIS rules, these fonts should not be transformed into other encodings, they
  2078. should only be used in the JISX0208.1983-0 encoding.  It is also strongly
  2079. recommended that companies wishing to use these fonts in commercial products
  2080. should purchase the original JIS font standards directly from JSA.  The
  2081. purchase price is nominal.\s-2
  2082. .FE
  2083. Hangul in KSC5601.1987-0 encoding.
  2084. .NH 1
  2085. Acknowledgements
  2086. .LP
  2087. The MIT Release 5 distribution is brought to you by the MIT X Consortium.
  2088. A cast of thousands, literally, have made this release possible.
  2089. We cannot possibly acknowledge them all here.
  2090. The names of all people who made it a reality will be found in the
  2091. individual documents and source files.
  2092. We greatly appreciate the work that everyone has put into this release.
  2093. .sp 1
  2094. .in +3i
  2095. .nf
  2096. Hoping you enjoy Release 5,
  2097.  
  2098. Donna Converse
  2099. Stephen Gildea
  2100. Susan Hardy
  2101. Jay Hersh
  2102. Keith Packard
  2103. David Sternlicht
  2104. Bob Scheifler
  2105. Ralph Swick
  2106.  
  2107. (R5 Survival Club)
  2108.