Import X server from vnc-3.3.7.
[rdpsrv] / Xserver / INSTALL.TXT
1
2
3
4
5
6
7
8
9
10               Building and Installing the X Window System
11
12
13
14
15
16
17
18
19                              Stephen Gildea
20
21                               X Consortium
22
23
24
25
26
27
28                              March 5, 1996
29
30                         Updated For Release 6.3
31
32
33
34
35
36
37
38
39
40
41 Copyright c 1995, 1996 X Consortium
42
43 Permission is hereby granted, free of charge, to any person obtaining a
44 copy of this software and associated documentation files (the
45 "Software"), to deal in the Software without restriction, including
46 without limitation the rights to use, copy, modify, merge, publish, dis-
47 tribute, sublicense, and/or sell copies of the Software, and to permit
48 persons to whom the Software is furnished to do so, subject to the fol-
49 lowing conditions:
50
51 The above copyright notice and this permission notice shall be included
52 in all copies or substantial portions of the Software.
53
54 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
55 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABIL-
56 ITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT
57 SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABIL-
58 ITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
59 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
60 IN THE SOFTWARE.
61
62 Except as contained in this notice, the name of the X Consortium shall
63 not be used in advertising or otherwise to promote the sale, use or
64 other dealings in this Software without prior written authorization from
65 the X Consortium.
66
67 X Window System is a trademark of X Consortium, Inc.
68
69
70 1.  Easy Build Instructions
71
72 This quick summary is no substitute for reading the full build instruc-
73 tions later in this document.
74
75 Edit xc/config/cf/site.def for local preferences.  If you want to build
76 with gcc uncomment the HasGcc2 line.  If you want to install somewhere
77 other than /usr/X11R6.3, change ProjectRoot.  (Do not use DESTDIR.)
78
79 If any fixes have been released by the X Consortium, stop here and fol-
80 low the instructions at the top of each patch, but don't do any of the
81 make commands suggested in the patches.  Then continue here.
82
83 Check the appropriate vendor-specific .cf file in xc/config/cf/ to make
84 sure that OSMajorVersion and OSMinorVersion are set correctly for your
85 system.  Override them in site.def if necessary.
86
87 See if there is a BootstrapCFlags mentioned in the comments in the
88 vendor-specific .cf file.  If there isn't one, cd to the xc directory
89 and type:
90
91         % make World >& world.log
92
93
94 If there is a BootstrapCFlags, take its value and type:
95
96         % make World BOOTSTRAPCFLAGS="value" >& world.log
97
98
99 Do not call the output file "make.log" when doing "make World".  After a
100 successful build, you can install with:
101
102         % make install >& install.log
103
104
105 You can install manual pages with:
106
107         % make install.man >& man.log
108
109
110 While the system is building (or if things fail), read the rest of these
111 installation instructions.
112
113
114
115 2.  Building X
116
117
118 This document gives detailed instructions for building Release 6:  get-
119 ting it off the distribution medium, configuring, compiling, installing,
120 running, and updating.
121
122 Release Notes are in xc/RELNOTES.* (various formats) in the distribu-
123 tion.
124
125 More recent information about newly-discovered problems may be found in
126 the Frequently Asked Questions posting appearing monthly on the
127 comp.windows.x newsgroup and xpert mailing list.  It is also available
128 via anonymous FTP on ftp.x.org in the file contrib/faqs/FAQ.Z, or on
129 your local X mirror site.
130
131
132 2.1.  Preparing the Site
133
134
135 If you are unpacking tar files, you will need about 130 Mb to hold the
136 xc/ part.  To install requires 30-50 Mb assuming you have shared
137 libraries (80-100 Mb without).  You will need an equivalent amount of
138 extra space to build, since you also need room for all the object files.
139
140 Distributed as tar files, Release 6.3 core is divided into parts as fol-
141 lows:
142
143
144         xc-1.tar       contains everything in xc/ that isn't in the other tar files
145         xc-2.tar       contains xc/fonts, xc/doc/specs, xc/util
146         xc-3.tar       contains xc/doc/hardcopy
147
148
149 If you define BuildFonts to NO, you only need to unpack xc-1.tar to
150 build.  If you build fonts, then you will also need xc-2.tar to build.
151
152
153 2.2.  Unpacking the Distribution
154
155
156 The distribution normally comes as multiple tar files, either on tape or
157 across a network, or as a CD-ROM.
158
159
160 2.2.1.  Unpacking a Compressed FTP Distribution
161
162
163 If you have obtained compressed tar files over the network, create a
164 directory to hold the sources and cd into it:
165
166         mkdir sourcedir
167         cd sourcedir
168
169 Then for each tar file xc-*.tar.Z, execute this:
170
171         zcat ftp-dir/xc-N.tar.Z | tar xf -
172
173
174
175 2.2.2.  Unpacking a gzipped FTP Distribution
176
177
178 If you have obtained gzipped tar files over the network, create a direc-
179 tory to hold the sources and cd into it:
180
181         mkdir sourcedir
182         cd sourcedir
183
184 Then for each tar file xc-*.tar.gz, execute this:
185
186         gunzip -c ftp-dir/xc-N.tar.gz | tar xf -
187
188
189
190 2.2.3.  Unpacking a Split Compressed FTP Distribution
191
192
193 If you have obtained compressed and split tar files over the network,
194 create a directory to hold the sources:
195
196         mkdir sourcedir
197
198 Then for each directory xc-*:
199
200         cd ftp-dir/xc-N
201         cat xc-N.?? | uncompress | (cd sourcedir; tar xf -)
202
203
204
205 2.2.4.  Unpacking the Tape Distribution
206
207
208 If you have obtained a tape, create a directory to hold the sources and
209 untar everything into that directory:
210
211         mkdir sourcedir
212         cd sourcedir
213         tar xf tape-device
214
215
216
217 2.2.5.  Using the CD-ROM
218
219
220 If you have obtained a CD-ROM, you don't have to do anything to unpack
221 it.  However, you will have to create a symbolic link tree to build X.
222 See the next section.
223
224 To mount the CD-ROM, see the mount(8) manual page on your system or the
225 liner notes that came with the CD-ROM.  Some systems, e.g., Solaris 2,
226 can automatically mount the CD-ROM for you.
227
228
229 2.3.  Apply Patches
230
231
232 If there are fixes released that are more recent than your distribution,
233 apply them now.  Follow the instructions at the top of each patch, but
234 don't do any make commands.  See the section "Public Patches" later in
235 this document.  Then continue here.
236
237
238 2.4.  Symbolic Link Trees
239
240
241 If you expect to build the distribution on more than one machine using a
242 shared source tree, or you are building from CD-ROM, or you just want to
243 keep the source tree pure, you may want to use the program
244 xc/config/util/lndir.c to create a symbolic link tree on each build
245 machine.  The links may use an additional 10 megabytes, but it is
246 cheaper than having multiple copies of the source tree.
247
248 It may be tricky to compile lndir before the distribution is built.  If
249 you have a copy from a previous release, use that.  Makefile.ini can be
250 used for building lndir the first time.  You may have to specify
251 OSFLAGS=-Dsomething to get it to compile.  What you would pass as
252 BOOTSTRAPCFLAGS might work.  The command line looks something like this:
253
254         make -f Makefile.ini OSFLAGS=-Dflag
255
256
257 To use a symbolic link tree, create a directory for the build, cd to it,
258 and type this:
259
260         lndir sourcedir
261
262
263 where sourcedir is the pathname of the directory where you stored the
264 sources.  All of the build instructions given below should then be done
265 in the build directory on each machine, rather than in the source direc-
266 tory.
267
268 xc/config/util/mkshadow/ contains mkshadow, an alternative program to
269 lndir.
270
271
272 2.5.  Configuration Parameters
273
274
275 Build information for each source directory is in files called
276 Imakefile.  An Imakefile, along with local configuration information in
277 xc/config/cf/, is used by the program imake to generate a Makefile.
278
279 Most of the configuration work prior to building the release is to set
280 parameters so that imake will generate correct files.  Most of those
281 parameters are set in xc/config/cf/site.def.  You will also need to
282 check the appropriate vendor-specific .cf file in xc/config/cf/ to make
283 sure that OSMajorVersion, OSMinorVersion, and OsTeenyVersion are set
284 correctly for your system.  Override them in site.def if necessary.
285
286 The site.def file has two parts, one protected with "#ifdef BeforeVen-
287 dorCF" and one with "#ifdef AfterVendorCF".  The file is actually pro-
288 cessed twice, once before the .cf file and once after.  About the only
289 thing you need to set in the "before" section is HasGcc2; just about
290 everything else can be set in the "after" section.
291
292 The sample site.def also has commented out support to include another
293 file, host.def.  This scheme may be useful if you want to set most
294 parameters site-wide, but some parameters vary from machine to machine.
295 If you use a symbolic link tree, you can share site.def across all
296 machines, and give each machine its own copy of host.def.
297
298 The config parameters are listed in xc/config/cf/README, but here are
299 some of the more common parameters that you may wish to set in site.def.
300
301 ProjectRoot
302      The destination where X will be installed.  This variable needs to
303      be set before you build, as some programs that read files at run-
304      time have the installation directory compiled in to them.  Assuming
305      you have set the variable to some value /path, files will be
306      installed into /path/bin, /path/include/X11, /path/lib, and
307      /path/man.
308
309 HasGccSet to YES to build with gcc version 1.
310
311 HasGcc2
312      Set to YES to build with gcc version 2.  Both this option and
313      HasGcc look for a compiler named gcc, but HasGcc2 will cause the
314      build to use more features of gcc 2, such as the ability to compile
315      shared libraries.
316
317 BuildXInputExt
318      Set to YES to build the X Input Extension.  This extension requires
319      device-dependent support in the X server, which exists only in Xhp
320      in our implementation.
321
322 BuildPexExt
323      Set to NO to not build the PEX server extension and fonts.
324
325 DefaultUsrBin
326      This is a directory where programs will be found even if PATH is
327      not set in the environment.  It is independent of ProjectRoot and
328      defaults to /usr/bin.  It is used, for example, when connecting
329      from a remote system via rsh.  The rstart program installs its
330      server in this directory.
331
332 InstallServerSetUID
333      Some systems require the X server to run as root to access the dev-
334      ices it needs.  If you are on such a system and will not be using
335      xdm, you can set this variable to YES to install the X server
336      setuid to root.  Note that the X server has not been analyzed by
337      the X Consortium for security in such an installation; talk to your
338      system manager before setting this variable.
339
340 InstallXdmConfig
341      By default set to NO, which suppresses installing xdm config files
342      over existing ones.  Leave it set to NO if your site has customized
343      the files in /usr/X11R6.3/lib/X11/xdm, as many sites do.  If you
344      don't install the new files, merge any changes present in the new
345      files.
346
347 MotifBC
348      Causes Xlib and Xt to work around some bugs in older versions of
349      Motif.  Set to YES only if you will be linking with Motif version
350      1.1.1, 1.1.2, or 1.1.3.
351
352 GetValuesBC
353      Setting this variable to YES allows illegal XtGetValues requests
354      with NULL ArgVal to usually succeed, as R5 did.  Some applications
355      erroneously rely on this behavior.  Support for this will be
356      removed in a future release.
357
358 The following vendor-specific .cf files are in the release but have not
359 been tested recently and hence probably need changes to work:
360 apollo.cf, bsd.cf, convex.cf, DGUX.cf, luna.cf, macII.cf, Mips.cf,
361 moto.cf, Oki.cf, pegasus.cf, x386.cf.  Amoeba.cf is known to require
362 additional patches.
363
364 The file xc/lib/Xdmcp/Wraphelp.c, for XDM-AUTHORIZATION-1, is not
365 included in this release.
366
367
368 2.6.  System Build Notes
369
370
371 This section contains hints on building X with specific compilers and
372 operating systems.
373
374 If the build isn't finding things right, make sure you are using a com-
375 piler for your operating system.  For example, a pre-compiled gcc for a
376 different OS will not have right symbols defined, so imake will not work
377 correctly.
378
379
380 2.6.1.  gcc
381
382 gcc version 2 is in regular use at the X Consortium on Sparc platforms.
383 Set the variable HasGcc2.  X will not compile on some systems with gcc
384 version 2.5, 2.5.1, or 2.5.2 because of an incorrect declaration of mem-
385 move() in a gcc include file.
386
387 If you are using a gcc version older than 2.7 on Solaris x86, you need
388 to specify BOOTSTRAPCFLAGS="-Dsun" in the "make World" command.
389
390
391 2.6.2.  Other GNU tools
392
393 Use of the GNU assembler, as, or linker, ld, is not supported.  GNU make
394 is not supported.
395
396
397 2.6.3.  SparcWorks 2.0
398
399
400 If you have a non-threaded program and want to debug it with the old
401 SparcWorks 2.0 dbx, you will need to use the thread stubs library in
402 xc/util/misc/thr_stubs.c.  Compile it as follows:
403
404         cc -c thr_stubs.c
405         ar cq libthr_stubs.a thr_stubs.o
406         ranlib libthr_stubs.a
407
408 Install libthr_stubs.a in the same directory with your X libraries
409 (e.g., /usr/X11R6.3/lib/libthr_stubs.a).  Add the following line to
410 site.def:
411
412         #define ExtraLibraries -lsocket -lnsl $(CDEBUGFLAGS:-g=-lthr_stubs)
413
414 This example uses a make macro substitution; not all make implementa-
415 tions support this feature.
416
417
418 2.6.4.  CenterLine C under Solaris 2
419
420
421 If you are using the CenterLine C compiler to compile the distribution
422 under Solaris 2, place the following line in your site.def:
423
424         #define HasCenterLineC YES
425
426 If clcc is not in your default search path, add this line to site.def:
427
428         #define CcCmd /path/to/your/clcc
429
430
431 If you are using CodeCenter 4.0.4 or earlier, the following files
432 trigger bugs in the clcc optimizer:
433
434         xc/programs/Xserver/cfb16/cfbgetsp.c
435         xc/programs/Xserver/cfb16/cfbfillsp.c
436         xc/programs/Xserver/cfb/cfbgetsp.c
437
438
439 Thus to build the server, you will have to compile these files by hand
440 with the -g flag:
441
442         % cd xc/programs/Xserver/cfb16
443         % make CDEBUGFLAGS="-g" cfbgetsp.o cfbfillsp.o
444         % cd ../cfb
445         % make CDEBUGFLAGS="-g" cfbgetsp.o
446
447 This optimizer bug appears to be fixed in CodeCenter 4.0.6.
448
449
450 2.6.5.  IBM AIX 4.1.4
451
452
453 On AIX 4.1.4, the file lib/font/Type1/objects.c must be compiled without
454 optimization (-O) else the X server will exit when Type 1 fonts are
455 used.
456
457
458 2.6.6.  SunOS 4
459
460
461 SunOS 4.0 and earlier need BOOTSTRAPCFLAGS=-DNOSTDHDRS because they do
462 not have unistd.h nor stdlib.h.  Do not supply a BOOTSTRAPCFLAGS when
463 building any SunOS 4.1 version.
464
465
466 2.6.7.  Microsoft Windows NT
467
468
469 All of the base libraries are supported, including multi-threading in
470 Xlib and Xt, but some of the more complicated applications, specifically
471 xterm and xdm, are not supported.
472
473 There are also some other rough edges in the implementation, such as
474 lack of support for non-socket file descriptors as Xt alternate inputs
475 and not using the registry for configurable parameters like the system
476 filenames and search paths.
477
478 The Xnest server has been made to run on NT.  It requires a real X
479 server for output still.
480
481
482 2.6.8.  Omron Luna
483
484
485 The Omron Luna platform is no longer supported.  The Luna version of the
486 make program doesn't define the standard macro MAKE, so you must run it
487 as "make MAKE=make" at top level, e.g., "make MAKE=make World".
488
489
490 2.7.  The Build
491
492
493 On NT, type
494
495         nmake World.Win32 > world.log
496
497 On other systems, find the BootstrapCFlags line, if any, in the vendor-
498 specific .cf file.  If there isn't one, type
499
500         % make World >& world.log
501
502 otherwise type
503
504         % make World BOOTSTRAPCFLAGS="value" >& world.log
505
506
507 You can call the output file something other than "world.log", but do
508 not call it "make.log" because files with this name are automatically
509 deleted during the "cleaning" stage of the build.
510
511 Because the build can take several hours to complete, you will probably
512 want to run it in the background and keep a watch on the output.  For
513 example:
514
515         % make World >& world.log &
516         % tail -f world.log
517
518
519 If something goes wrong, the easiest thing is to just start over (typing
520 "make World" again) once you have corrected the problem.
521
522
523 2.8.  Installing X
524
525
526 If everything is built successfully, you can install the software by
527 typing the following as root:
528
529         % make install >& install.log
530
531
532 Again, you might want to run this in the background and use tail to
533 watch the progress.
534
535 You can install the manual pages by typing the following as root:
536
537         % make install.man >& man.log
538
539
540
541 2.8.1.  System Installation Notes
542
543
544 This section contains hints on installing and using X with specific com-
545 pilers and operating systems.
546
547
548 2.8.1.1.  The X Server on AIX 4
549
550
551 For IBM's AIX 4, you need to make sure the LFT device is associated with
552 the correct graphics adapter.  It's a one-time setup that does not hap-
553 pen automatically, even if there's only one graphics adapter in the sys-
554 tem.  To configure the LFT device properly, become root and start SMIT.
555 Go to the "Devices" category, choose "LFT", then "Displays", then "Move
556 the LFT to Another Display".
557
558 Select "Both" for when the change should take effect, then select the
559 display adapter where you want to run the X server.  Confirm the changes
560 and exit SMIT; from now on, you should be able to run the server just
561 fine.
562
563 To run Xibm from xdm, you must provide the "-force" flag on the server
564 command line in the Xservers file.
565
566
567 2.9.  Shared Libraries
568
569
570 The version number of some of the the shared libraries has been changed.
571 On SunOS 4, which supports minor version numbers for shared libraries,
572 programs linked with the R6 libraries will use the new libraries with no
573 special action required.  On other platforms you have the following
574 choices:
575
576 1.   Keep the old versions of the libraries around.
577
578 2.   Relink all applications with the new libraries.
579
580 3.   Create a link from the old name to the new name.
581
582      For example, to have programs that were linked against
583      libX11.so.6.0 use libX11.so.6.3, make this link:
584
585              ln -s libX11.so.6.3 libX11.so.6.0
586
587
588
589 2.10.  Setting Up xterm
590
591
592 If your /etc/termcap and /usr/lib/terminfo databases do not have correct
593 entries for xterm, use the sample entries provided in the directory
594 xc/programs/xterm/.  System V users may need to compile and install the
595 terminfo entry with the tic utility.
596
597 Since each xterm will need a separate pseudoterminal, you need a reason-
598 able number of them for normal execution.  You probably will want at
599 least 32 on a small, multiuser system.  On most systems, each pty has
600 two devices, a master and a slave, which are usually named
601 /dev/tty[pqrstu][0-f] and /dev/pty[pqrstu][0-f].  If you don't have at
602 least the "p" and "q" sets configured (try typing "ls /dev/?ty??"), you
603 should have your system administrator add them.  This is commonly done
604 by running the MAKEDEV script in the /dev directory with appropriate ar-
605 guments.
606
607
608 2.11.  Starting Servers at System Boot
609
610
611 The xfs and xdm programs are designed to be run automatically at system
612 startup.  Please read the manual pages for details on setting up confi-
613 guration files; reasonable sample files are in xc/programs/xdm/config/
614 and xc/programs/xfs/.
615
616
617 2.11.1.  On BSD-based systems using /etc/rc
618
619
620 If your system uses an /etc/rc file at boot time, you can usually enable
621 these programs by placing the following at or near the end of the file:
622
623         if [ -f /usr/X11R6.3/bin/xfs ]; then
624                 /usr/X11R6.3/bin/xfs & echo -n ' xfs'
625         fi
626
627         if [ -f /usr/X11R6.3/bin/xdm ]; then
628                 /usr/X11R6.3/bin/xdm; echo -n ' xdm'
629         fi
630
631
632 Since xfs can serve fonts over the network, you do not need to run a
633 font server on every machine with an X display.  You should start xfs
634 before xdm, since xdm may start an X server which is a client of the
635 font server.
636
637 The examples here use /usr/X11R6.3/bin, but if you have installed into a
638 different directory by setting (or unsetting) ProjectRoot then you need
639 to substitute the correct directory.
640
641 If you are unsure about how system boot works, or if your system does
642 not use /etc/rc, consult your system administrator for help.
643
644
645 2.11.2.  On SystemV-based systems
646
647
648 There are two ways you can get On systems with a /etc/inittab file, you
649 can edit this file to add the lines
650
651         xfs:3:once:/usr/X11R6.3/bin/xfs
652         xdm:3:once:/usr/X11R6.3/bin/xdm
653
654
655 On some systems, you can edit a file in /etc/init.d to run the X Consor-
656 tium xdm instead of the vendor's product xdm.  On Sony this file is
657 /etc/init.d/consxdm.  On IRIX edit /etc/init.d/xdm.
658
659
660 2.12.  Using OPEN LOOK applications
661
662
663 You can use the X11R6 Xsun server with OPEN LOOK applications, but you
664 must pass the -swapLkeys flag to the server on startup, or the OPEN LOOK
665 Undo, Copy, Paste, Find, and Cut keys may not work correctly.  For exam-
666 ple, to run Sun's OpenWindows 3.3 desktop environment with an X11R6
667 server, use the command:
668
669         % openwin -server /usr/X11R6.3/bin/Xsun -swapLkeys
670
671
672 The keysyms reported by keys on the numeric keypad have also changed
673 since X11R5; if you find that OpenWindows applications do not respond to
674 keypad keys and cursor control keys when using the R6 server, you can
675 remap the keypad to generate R5 style keysyms using the following xmod-
676 map commands:
677
678         keysym Pause = F21
679         keysym Print = F22
680         keysym Break = F23
681         keysym KP_Equal = F24
682         keysym KP_Divide = F25
683         keysym KP_Multiply = F26
684         keysym KP_Home = F27
685         keysym KP_Up = Up
686         keysym KP_Prior = F29
687         keysym KP_Left = Left
688         keycode 100 = F31
689         keysym KP_Right = Right
690         keysym KP_End = F33
691         keysym KP_Down = Down
692         keysym KP_Next = F35
693         keysym KP_Insert = Insert
694         keysym KP_Delete = Delete
695
696
697
698 2.13.  Rebuilding after Patches
699
700
701 You shouldn't need this right away, but eventually you are probably go-
702 ing to make changes to the sources, for example by applying any public
703 patches that may be released.
704
705 Each patch comes with explicit instructions at the top of it saying what
706 to do.  Thus the procedure here is only an overview of the types of com-
707 mands that might be necessary to rebuild X after changing it.
708
709 If you are building from CD-ROM, apply the patches to the symbolic link
710 tree.  The links to changed files will be replaced with local files con-
711 taining the new contents.
712
713 If only source files are changed, you should be able to rebuild just by
714 going to the xc directory in your build tree and typing:
715
716         % make >& make.log
717
718
719 If configuration files are changed, the safest thing to do is type:
720
721         % make Everything >& every.log
722
723
724 "Everything" is similar to "World" in that it rebuilds every Makefile,
725 but unlike "World" it does not delete the existing objects, libraries,
726 and executables, and only rebuilds what is out of date.
727
728
729 2.14.  Formatting the Documentation
730
731
732 The PostScript files in xc/doc/hardcopy can be generated from the
733 sources in xc/doc/specs.  Most of the documentation is in troff using
734 the -ms macros.  The easiest way to format it is to use the Imakefiles
735 provided.
736
737 Set the name of your local troff program by setting the variable
738 TroffCmd in xc/config/cf/site.def.  Then build the Makefiles:
739
740         cd xc/doc
741         make SUBDIRS=specs Makefiles
742
743
744 Finally, go to the directory you are interested in and type "make"
745 there.  This command will generate .PS files.  You can also generate
746 text files by specifying the document name with a .txt extension as a
747 make target, e.g., "make icccm.txt".
748
749