summaryrefslogtreecommitdiff
path: root/Build/source/texk/kpathsea/doc/install.texi
blob: b3eaa203455154881ce51509173361f776919b0f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
@ifclear version
@defcodeindex cm
@defcodeindex fl
@defcodeindex op
@end ifclear

@node Installation
@chapter Installation

@cindex installation
@cindex configuration
@cindex compilation

@ifset version
(A copy of this chapter is in the distribution file @file{kpathsea/INSTALL}.)
@end ifset

The procedure for Kpathsea (and Web2c, etc.) configuration and
installation follows.  If you encounter trouble, see @ref{Common
problems}, a copy of which is in the file @file{kpathsea/BUGS}.

@menu
* Simple installation::      If you just want to do it.
* Custom installation::      If you want to change things around.
* Security::                 Who can write what files, etc.
* TeX directory structure::  Managing the horde of TeX input files.
* unixtex.ftp::              Getting software via FTP, on CD-ROM, or on tape.
* Reporting bugs::           Where and how to report bugs.
@end menu


@node Simple installation
@section Simple installation

@cindex simple installation
@cindex installation, simple

@cindex precompiled executables, instead of installation
@cindex installation, getting executables instead of
Installing @TeX{} and friends for the first time can be a daunting
experience.  Thus, you may prefer to skip this whole thing and just get
precompiled executables: see @ref{unixtex.ftp}.

This section explains what to do if you wish to take the defaults for
everything, and generally to install in the simplest possible way.  Most
steps here refer to corresponding subsection in the next section which
explains how to override defaults and generally gives more details.

By default everything will be installed under @file{/usr/local} and the
following discussion assumes this.  However, if you already have @TeX{}
installed, its location is used to derive the directory under which
everything is to be installed.

@enumerate
@item
Be sure you have enough disk space: approximately 8 megabytes for the
compressed archives, 15MB for sources, 50MB for compilation, 40MB for
the (initial) installed system (including library files).  @xref{Disk
space}.

@item
Retrieve these distribution archives:
@table @url
@item ftp://ftp.tug.org/tex/texk.tar.gz
These are the sources, which you will be compiling. 

@item ftp://ftp.tug.org/tex/texklib.tar.gz
This is a basic set of input files.  You should unpack it in the
directory @file{/usr/local/share}; doing so will create a @file{texmf}
subdirectory there.
@end table

These archives are mirrored on the CTAN hosts, in the
@file{systems/web2c} directory.

@noindent @xref{Kpathsea application distributions}.

@item
When using the default search paths, there is no need to edit any
distribution files. @xref{Changing search paths}.

@item
At the top level of the distribution, run @samp{sh configure}.  (If you
have the GNU Bash shell installed, run @samp{bash configure}.)
@xref{Running configure}.

@item
@samp{make}. @xref{Running make}.  If you are using a BSD 4.4 system
such as FreeBSD or NetBSD, you may have to use GNU make (often installed
in @file{/usr/local/bin}), not the BSD make.

@item 
@samp{make install}. @xref{Installing files}.

@item
@samp{make distclean}. @xref{Cleaning up}.

@item
Set up a cron job to rebuild the filename database that makes searching
faster.  This line will rebuild it every midnight:
@example
0 0 * * * cd /usr/local/share/texmf && @var{/bindir}/mktexlsr
@end example
@xref{Filename database generation}, and @ref{Filename database}.

@item
@cindex printer configuration files
@cindex PostScript fonts, additional
@cindex color printers, configuring
If you're installing Dvips, you also need to set up configuration files
for your printers and make any additional PostScript fonts available.
@xref{Installation,,, dvips, Dvips}.  If you have any color printers,
see @ref{Color device configuration,,, dvips, Dvips}.

@item
The first time you run a DVI driver, a bunch of PK fonts will be built
by Metafont via @code{mktexpk} (and added to the filename database).
This will take some time.  Don't be alarmed; they will created only this
first time (unless something is wrong with your path definitions).

By default, @code{mktexpk} will create these fonts in a hierarchy
under @file{/var/tmp/texfonts}; it simply assumes that @file{/var/tmp}
exists and is globally writable.  If you need a different arrangement,
see @ref{mktex configuration}.

@xref{mktex scripts}.

@item
@cindex fonts, being created
@pindex mktexpk @r{, initial runs}
@cindex tests, simple
For some simple tests, try @samp{tex story \\bye} and @samp{latex
sample2e}.  Then run @file{xdvi story} or @file{dvips sample2e} on the
resulting DVI files to preview/print the documents.  @xref{Installation
testing}.
@end enumerate


@node Custom installation
@section Custom installation

@cindex custom installation
@cindex installation, customized

Most sites need to modify the default installation procedure in some
way, perhaps merely changing the prefix from @samp{/usr/local}, perhaps
adding extra compiler or loader options to work around @code{configure}
bugs.  This section explains how to override default choices.  For
additional distribution-specific information:
@itemize @bullet
@item @file{dviljk/INSTALL}.
@item @xref{Installation,,,dvips,Dvips}.
@item @xref{Installation,,,web2c,Web2c}.
@item @file{xdvik/INSTALL}.
@end itemize

@cindex non-Unix operating systems
@cindex Amiga support
@cindex DOS support
@cindex OS/2 support
@cindex VMS support
These instructions are for Unix systems.  Other operating-system
specific distributions have their own instructions.  The code base
itself supports Amiga, DOS, OS/2, and VMS.


Following are the same steps as in the previous section (which describes
the simplest installation), but with much more detail.

@menu
* Disk space::                          
* Kpathsea application distributions::  
* Changing search paths::               
* Running configure::                   
* Running make::                        
* Installing files::                    
* Cleaning up::                         
* Filename database generation::        
* mktex scripts::                     
* Installation testing::               
@end menu


@node Disk space
@subsection Disk space

@cindex disk space, needed
@cindex total disk space
@cindex size of distribution archives
Here is a table showing the disk space needed for each distribution
(described in the next section).  The `(totals)' line reflects the
@samp{texk} source distribution and @samp{texklib}; the individual
distributions don't enter into it.  Sizes are in megabytes.  All numbers
are approximate.

@multitable {distribution} {.tar.gz} {unpacked} {compiled} {installed}
@item Distribution @tab .tar.gz @tab Unpacked @tab Compiled @tab Installed
@item dviljk   @tab   .9 @tab  3.8 @tab
@item dvipsk   @tab   .9 @tab  3.2 @tab
@item xdvik    @tab   .7 @tab  2.5 @tab
@item web2c    @tab  1.3 @tab  5.0 @tab
@item web      @tab  1.9 @tab  6.5 @tab    - @tab -
@item texk     @tab  7.5 @tab 32.1 @tab 95.3 @tab 33.5
@item texklib  @tab  6.3 @tab 15.0 @tab    - @tab 15.0
@item (totals) @tab 14.6 @tab 47.1 @tab 95.3 @tab 48.5
@end multitable


@node Kpathsea application distributions
@subsection Kpathsea application distributions

@cindex distributions, compiling simultaneously
@cindex version number, of Kpathsea
@cindex Kpathsea version number

@cindex distributions, not compiling
@cindex NeXT, lacking X11
@cindex X11, lacking on NeXT
The archive @url{ftp://ftp.tug.org/tex/texk.tar.gz} contains all of the
Kpathsea applications I maintain, and the library itself.  For example,
since NeXT does not generally support X11, you'd probably want to skip
@samp{xdvik} (or simply remove it after unpacking @file{texk.tar.gz}.
If you are not interested in all of them, you can also retrieve them
separately:

@cindex DVI drivers
@table @file
@item dviljk.tar.gz
@cindex PCL driver
@cindex LaserJet drive
DVI to PCL, for LaserJet printers.

@item dvipsk.tar.gz
@cindex PDF generation
@cindex PostScript driver
DVI to PostScript, for previewers, printers, or PDF generation.

@item web2c.tar.gz
The software needed to compile @TeX{} and friends.

@item web.tar.gz
The original WEB source files, also used in compilation.

@item xdvik.tar.gz
@cindex X11 previewer
DVI previewing under the X window system.

@end table

@cindex Babel
@cindex non-English typesetting
If you want to use the Babel La@TeX{} package for support of non-English
typesetting, you may need to retrieve additional files.  See the file
@file{install.txt} in the Babel distribution.


@node Changing search paths
@subsection Changing search paths

@cindex search paths, changing default
@cindex paths, changing default
@flindex texmf.in@r{, editing}
If the search paths for your installation differ from the standard
@TeX{} directory structure (@pxref{Top,, Introduction, tds, A Directory
Structure for @TeX{} files}), edit the file @file{kpathsea/texmf.in}
as desired, before running @code{configure}.  For example, if you have
all your fonts or macros in one big directory.

You may also wish to edit the file @file{mktex.cnf}, either before or
after installation, to control various aspects of @code{mktexpk} and
friends.  @xref{mktex configuration}.

You do not need to edit @file{texmf.in} to change the default
top-level or other installation @emph{directories} (only the paths).
You can and should do that when you run @code{configure} (next step).

You also do not need to edit @file{texmf.in} if you are willing to
rely on @file{texmf.cnf} at runtime to define the paths, and let the
compile-time default paths be incorrect.  Usually there is no harm in
doing this.

The section below explains default generation in more detail.

@menu
* Default path features::       
* Default path generation::     
@end menu


@node Default path features
@subsubsection Default path features

@cindex default path features
@cindex features, of default paths

The purpose of having all the different files described in the section
above is to avoid having the same information in more than one place. If
you change the installation directories or top-level prefix at
@code{configure}-time, those changes will propagate through the whole
sequence.  And if you change the default paths in @file{texmf.in},
those changes are propagated to the compile-time defaults.

The Make definitions are all repeated in several @t{Makefile}'s; but
changing the top-level @file{Makefile} should suffice, as it passes down
all the variable definitions, thus overriding the submakes.  (The
definitions are repeated so you can run Make in the subdirectories, if
you should have occasion to.)

@vindex MAKETEX_MODE
@cindex paths, device name included in
By default, the bitmap font paths end with @samp{/$MAKETEX_MODE}, thus
including the device name (usually a Metafont mode name such as
@samp{ljfour}).  This distinguishes two different devices with the same
resolution---a write/white from a write/black 300@dmn{dpi} printer, for
example.

@findex kpse_init_prog@r{, and @code{MAKETEX_MODE}}
@flindex proginit.c
However, since most sites don't have this complication, Kpathsea
(specifically, the @code{kpse_init_prog} function in
@file{kpathsea/proginit.c}) has a special case: if the mode has not been
explicitly set by the user (or in a configuration file), it sets
@code{MAKETEX_MODE} to @code{/}.  This makes the default PK path, for
example, expand into @code{@dots{}/pk//}, so fonts will be found even if
there is no subdirectory for the mode (if you arranged things that way
because your site has only one printer, for example) or if the program
is mode-independent (e.g., @code{pktype}).

To make the paths independent of the mode, simply edit
@file{texmf.in} before installation, or the installed
@file{texmf.cnf}, and remove the @samp{$MAKETEX_MODE}.

@xref{mktex script arguments}, for how this interacts with @code{mktexpk}.

@cindex TDS
@cindex @TeX{} directory structure
@xref{TeX directory structure,, @TeX{} directory structure}, for a
description of the default arrangement of the input files that comprise
the @TeX{} system. 


@node Default path generation
@subsubsection Default path generation

@cindex default paths, changing
@cindex paths, changing default
@cindex installation, changing default directories
@cindex directories, changing default installation

This section describes how the default paths are constructed.

You may wish to ignore the whole mess and simply edit @file{texmf.cnf}
after it is installed, perhaps even copying it into place beforehand so
you can complete the installation, if it seems necessary.

@cindex default paths, how they're made
To summarize the chain of events that go into defining the default paths:

@enumerate
@item
@samp{configure} creates a @file{Makefile} from each @file{Makefile.in}.

@item
@flindex texmf.sed
When Make runs in the @file{kpathsea} directory, it creates a file
@file{texmf.sed} that substitutes the Make value of @code{$(var)} for a
string @code{@@var@@}.  The variables in question are the one that
define the installation directories.

@item
@flindex texmf.in
@flindex texmf.cnf@r{, generated}
@file{texmf.sed} (together with a little extra magic---see
@file{kpathsea/Makefile}) is applied to @file{texmf.in} to generate
@file{texmf.cnf}.  This is the file that will eventually be installed
and used.

@item
@flindex paths.h
The definitions in @file{texmf.cnf} are recast as C @code{#define}'s in
@file{paths.h}.  These values will be the compile-time defaults; they
are not used at runtime unless no @file{texmf.cnf} file can be found.

(That's a lie: the compile-time defaults are what any extra @t{:}'s in
@file{texmf.cnf} expand into; but the paths as distributed have no extra
@t{:}'s, and there's no particular reason for them to.)
@end enumerate


@node Running configure
@subsection Running @code{configure}

@flindex configure@r{, running}
@flindex c-auto.in
@flindex Makefile.in
@findex ac_include@r{, Autoconf extension}
@cindex @@@var{var}@@ substitutions
@cindex system dependencies
Run @code{sh configure @var{options}} (in the top-level directory, the
one containing @file{kpathsea/}), possibly using a shell other than
@code{sh} (@pxref{configure shells}).

@code{configure} adapts the source distribution to the present system
via @code{#define}'s in @file{*/c-auto.h}, which are created from the
corresponding @file{c-auto.in}.  It also creates a @file{Makefile} from
the corresponding @file{Makefile.in}, doing @samp{@@@var{var}@@} and
@samp{ac_include} substitutions).

@flindex README.CONFIGURE
@flindex kpathsea/README.CONFIGURE
@code{configure} is the best place to control the configuration,
compilation, and installed location of the software, either via
command-line options, or by setting environment variables before
invoking it.  For example, you can disable @code{mktexpk} by default
with the option @samp{--disable-mktexpk}.
@xref{configure options}.

@menu
* configure shells::            
* configure options::           
* configure environment::
* configure scenarios::         
* Shared library::
@end menu


@node configure shells
@subsubsection @code{configure} shells

@cindex shells and @code{configure}
@pindex bash@r{, recommended for running @code{configure}}

Considerable effort has gone into trying to ensure that the
@code{configure} scripts can be run by most Bourne shell variants.
If @code{sh} runs into trouble, your best bet is to use Bash, the GNU
Bourne-again shell (@pxref{Top,,,bash,Bash Reference Manual}).

Bourne shell variants for which problems have been reported in the past
are:
@table @code
@item ksh
@pindex ksh@r{, losing with @code{configure}}
@pindex bsh@r{, ok with @code{configure}}
@cindex Korn shell@r{, losing with @code{configure}}
@cindex AIX shells and @code{configure}
Old versions of the Korn shell may fail to handle the scripts.  The Korn
shell may be installed as @file{/bin/sh} on AIX, in which case
@file{/bin/bsh} may serve instead.

@item ash
@pindex ash@r{, losing with @code{configure}}
@cindex NetBSD shells and @code{configure}
@cindex FreeBSD shells and @code{configure}
@cindex Linux shells and @code{configure}
Old versions of ash are unable to handle the scripts.  Ash is sometimes
installed as @file{/bin/sh} on NetBSD, FreeBSD, and Linux systems.
@file{/bin/bash} should be available for those systems, but might not be
part of a default installation.

@item @r{Ultrix} /bin/sh
@cindex DEC shells and @code{configure}
@cindex Ultrix shells and @code{configure}
@pindex sh5@r{, ok with @code{configure}}
@file{/bin/sh} under Ultrix is a DEC-grown shell that is notably
deficient in many ways.  @file{/bin/sh5} may be necessary.
@end table


@node configure options
@subsubsection @code{configure} options

@cindex @code{configure} options

For a complete list of all @code{configure} options, run @samp{configure
--help} or see @ref{Invoking configure,, Running @code{configure} scripts,
autoconf, Autoconf}, (a copy is in the file @file{kpathsea/README.CONFIGURE}).
The generic options are listed first in the @samp{--help} output, and
the package-specific options come last.  The environment variables
@code{configure} pays attention to are listed below.

Options particularly likely to be useful are @samp{--prefix},
@samp{--datadir}, and the like; see @ref{configure scenarios}.

@opindex --with @r{options}
@opindex --enable @r{options}
@cindex configuration of optional features
@cindex options to @code{configure}
This section gives pointers to descriptions of the @samp{--with} and
@samp{--enable} options to @code{configure} that Kpathsea-using programs
accept.

@table @samp
@item --without-mktexmf-default
@itemx --without-mktexpk-default
@itemx --without-mktextfm-default
@itemx --with-mktextex-default
Enable or disable the dynamic generation programs.  @xref{mktex
configuration}.

@item --enable-shared
@opindex --enable-shared
Build Kpathsea as a shared library, and link against it.  Also build the
usual static library.  @xref{Shared library}.

@item --disable-static
@opindex --disable-static
Build only the shared library.   Implies @samp{--enable-shared}.

@item --enable-maintainer-mode
@opindex --enable-maintainer-mode
Enables make targets that are useful for the maintainer and likely to be
a pain for anyone else; the makefiles created when this option is
enabled may not work at all for you.  You have been warned.
@end table

@node configure environment                           
@subsubsection @code{configure} environment

@code{configure} uses the value of the following environment variables in
determining your system's characteristics, and substitutes for them in
@t{Makefile}'s:

@vtable @samp
@item CC
@pindex gcc@r{, compiling with}
@pindex cc@r{, compiling with}
The compiler to use: default is @code{gcc} if it's installed, otherwise
@code{cc}.

@item CFLAGS
@cindex compiler options, specifying
Options to give the compiler: default is @samp{-g -O2} for @code{gcc},
@samp{-g} otherwise.  @code{CFLAGS} comes after any other options.  You
may need to include @code{-w} here if your compilations commonly have
useless warnings (e.g., @code{NULL redefined}), or @code{configure} may
fail to detect the presence of header files (it takes the messages on
standard error to mean the header file doesn't exist).

@item CPPFLAGS
@cindex configuration compiler options
Options to pass to the compiler preprocessor; this matters most for
configuration, not the actual source compilation.  The @code{configure}
script often does only preprocessing (e.g., to check for the existence
of @t{#include} files), and @code{CFLAGS} is not used for this.  You may
need to set this to something like
@samp{-I/usr/local/include/wwwhatever} if you have the libwww library
installed for hyper-xdvik (see @file{xdvik/INSTALL}).

@item DEFS
@cindex preprocessor options
Additional preprocessor options, but not used by @code{configure}.
Provided for enabling or disabling program features, as documented in
the various program-specific installation instructions.  @code{DEFS}
comes before any compiler options included by the distribution
@file{Makefile}s or by @code{configure}.

@item LDFLAGS
@cindex loader options
Additional options to give to the loader.  @code{LDFLAGS} comes before
any other linker options.

@item LIBS
@cindex libraries, specifying additional
Additional libraries to link with.
@end vtable


@node configure scenarios
@subsubsection @code{configure} scenarios

Here are some common installation scenarios:

@itemize @bullet
@item
Including X support in Metafont.  This is disabled by default, since
many sites have no use for it, and it's a leading cause of configuration
problems.
@example
configure --with-x
@end example

@item
@cindex @TeX{} hierarchy, one
Putting the binaries, @TeX{} files, GNU info files, etc.@: into a single
@TeX{} hierarchy, say @file{/here/texmf}, requires overriding defaults in
@code{configure}:
@example
configure --prefix=/here/texmf --datadir=/here
@end example

@item
@cindex multiple architectures, compiling on
@cindex architectures, compiling multiple
@cindex symbolic link trees, for multiple architectures
@opindex --srcdir@r{, for building multiple architectures}
@pindex lndir @r{for building symlink trees}
You can compile on multiple architectures simultaneously either by
building symbolic link trees with the @code{lndir} script from the X11
distribution, or with the @samp{--srcdir} option:
@example
configure --srcdir=@var{srcdir}
@end example

@item
@cindex multiple architectures, directories for
If you are installing binaries for multiple architectures into a single
hierarchy, you will probably want to override the default @file{bin} and
@file{lib} directories, something like this:
@example
configure --prefix=@var{texmf} --datadir=@var{texmf} \
  --bindir=@var{texmf}/@var{arch}/bin --libdir=@var{texmf}/@var{arch}/lib
make texmf=@var{texmf}
@end example
@pindex depot
@cindex automounter, and configuration
@noindent (Unless you make provisions for architecture-specific files in
other ways, e.g., with Depot or an automounter.)

@item
@opindex -O@r{, compiling with}
@opindex -g@r{, compiling without}
@cindex optimization, enabling
@cindex debugging with @samp{-g}, disabling
To compile with optimization (to compile without debugging, remove the
@samp{-g}):
@example
env CFLAGS="-g -O" sh configure @dots{}
@end example
@noindent For a potential problem if you optimize, see @ref{TeX or
Metafont failing,, @TeX{} or Metafont failing}.
@end itemize
  

@node Shared library
@subsubsection Shared library

@cindex shared library, making

@opindex --enable-shared
You can compile Kpathsea as a shared library on a few systems, by
specifying the option @samp{--enable-shared} when you run
@samp{configure}.

@cindex code sharing
The main advantage in doing this is that the executables can then share
the code, thus decreasing memory and disk space requirements.

On some systems, you can record the location of shared libraries in a
binary, usually by giving certain options to the linker.  Then
individual users do not need to set their system's environment variable
(e.g., @code{LD_LIBRARY_PATH}) to find shared libraries.  If you want to
do this, you will need to add the necessary options to @code{LDFLAGS}
yourself; for example, on Solaris, include something like
@samp{-R$@{prefix@}/lib}, on IRIX or Linux, use
@samp{-rpath$@{prefix@}/lib}.  (Unfortunately, making this happen by
default is very difficult, because of interactions with an existing
installed shared library.)


@node Running make
@subsection Running @code{make}

@pindex make@r{, running}

@flindex texmf.cnf@r{, creating}
@flindex paths.h@r{, creating}
@code{make} (still in the top-level directory).  This also creates the
@file{texmf.cnf} and @file{paths.h} files that define the default search
paths, and (by default) the @samp{plain} and @samp{latex} @TeX{} formats.

@cindex fallback resolutions, overriding
You can override directory names and other values at @code{make}-time.
@file{make/paths.make} lists the variables most commonly reset.  For
example, @samp{make default_texsizes=600} changes the list of fallback
resolutions.

You can also override each of @code{configure}'s environment variables
(@pxref{configure environment}).  The Make variables have the same names.

Finally, you can supply additional options via the following variables.
(@code{configure} does not use these.)

@vtable @samp
@item XCPPFLAGS
@itemx XDEFS
@cindex preprocessor options, additional
Preprocessor options.

@item XCFLAGS
@cindex compiler options, additional
Compiler options.

@item XLDFLAGS
@cindex loader options, initial
Loader options (included at beginning of link commands).

@item XLOADLIBES
@cindex loader options, final
More loader options (included at end of link commands).

@item XMAKEARGS
@cindex Make arguments, additional
Additional Make arguments passed to all sub-@code{make}'s. You may need
to include assignments to the other variables here via @code{XMAKEARGS};
for example: @samp{make XMAKEARGS="CFLAGS=-O XDEFS=-DA4"}.
@end vtable

@cindex compiler, changing
@cindex libraries, changing
It's generally a bad idea to use a different compiler (@samp{CC}) or
libraries (@code{LIBS}) for compilation than you did for configuration,
since the values @code{configure} determined may then be incorrect.

@cindex universe, BSD vs.@: system V
@cindex BSD universe
@cindex system V universe
@cindex Solaris BSD compatibility, not
@flindex libucb@r{, avoiding}
@flindex ucbinclude@r{, avoiding}
Adding compiler options to change the ``universe'' you are using
(typically BSD vs.@: system V) is generally a cause of trouble.  It's
best to use the native environment, whatever that is; @code{configure}
and the software usually adapt best to that.  In particular, under
Solaris 2.x, you should not use the BSD-compatibility library
(@file{libucb}) or include files (@file{ucbinclude}).

@cindex Babel
If you want to use the Babel La@TeX{} package for support of non-English
typesetting, you need to modify some files before making the La@TeX{}
format.  See the file @file{install.txt} in the Babel distribution.


@node Installing files
@subsection Installing files

@cindex installing files

The basic command is the usual @code{make install}.  For security
issues, @pxref{Security}.

The first time you install any manual in the GNU Info system, you should
add a line (you choose where) to the file @file{dir} in your
@samp{$(infodir)} directory.  Sample text for this is given near the top
of the Texinfo source files (@file{kpathsea/kpathsea.texi},
@file{dvipsk/dvips.texi}, and @file{web2c/doc/web2c.texi}).
If you have a recent version of the GNU Texinfo distribution installed
(@url{ftp://prep.ai.mit.edu/pub/gnu/texinfo-3.9.tar.gz} or later), this
should happen automatically.

On the offchance that this is your first Info installation, the
@file{dir} file I use is included in the distribution as
@file{etc/dir-example}.

@cindex multiple architectures, installing on
@cindex architecture-(in)dependent files, installing only
@cindex installation, architecture-(in)dependent files only
You may wish to use one of the following targets, especially if you are
installing on multiple architectures:
@itemize @bullet
@item
@findex install-exec @r{Make target}
@code{make install-exec} to install in architecture-dependent
directories, i.e., ones that depend on the @code{$(exec_prefix)} Make
variable.  This includes links to binaries, libraries, etc., not just
``executables''.

@item
@findex install-data @r{Make target}
@code{make install-data} to install in architecture-independent
directories, such as documentation, configuration files, pool files, etc.
@end itemize

@cindex AFS
@cindex Andrew File System, installing with
@flindex /afs/@dots{} @r{, installing into}
If you use the Andrew File System, the normal path (e.g.,
@var{prefix}/bin) only gets you to a read-only copy of the files, and
you must specify a different path for installation.  The best way to do this
is by setting the @samp{prefix} variable on the @code{make} command
line.  The sequence becomes something like this:
@example
configure --prefix=/whatever
make
make install prefix=/afs/.@var{system.name}/system/1.3/@@sys/whatever
@end example
@flindex ls-R @r{and AFS}
@cindex relative filenames in @file{ls-R}
@noindent With AFS, you will definitely want to use relative filenames in 
@file{ls-R} (@pxref{Filename database}), not absolute filenames.  This
is done by default, but check anyway.


@node Cleaning up
@subsection Cleaning up

@findex distclean @r{Make target}
The basic command is @code{make distclean}.  This removes all files
created by the build.

Alternatively,
@itemize @bullet
@item
@findex mostlyclean @r{Make target}
@code{make mostlyclean} if you intend to compile on another
architecture.  For Web2C, since the generated C files are portable,
they are not removed.  If the @code{lex} vs.@: @code{flex} situation
is going to be different on the next machine, @code{rm
web2c/lex.yy.c}.

@item
@findex clean @r{Make target}
@code{make clean} to remove files created by compiling, but leave
configuration files and Makefiles.

@item
@findex maintainer-clean @r{Make target}
@code{make maintainer-clean} to remove everything that the Makefiles can
rebuild.  This is more than @samp{distclean} removes, and you should
only use it if you are thoroughly conversant with (and have the necessary
versions of) Autoconf.

@item
@findex extraclean @r{Make target}
@code{make extraclean} to remove other junk, e.g., core files, log
files, patch rejects.  This is independent of the other @samp{clean}
targets.
@end itemize


@node Filename database generation
@subsection Filename database generation

@cindex filename database generation
@cindex generation of filename database

You will probably want to set up a @code{cron} entry on the appropriate
machine(s) to rebuild the filename database nightly or so, as in:
@example
0 0 * * * cd @var{texmf} && @var{/bindir}/mktexlsr
@end example
@noindent @xref{Filename database}.

Although the @code{mktex@dots{}} scripts make every effort to add
newly-created files on the fly, it can't hurt to make sure you get a
fresh version every so often.


@node mktex scripts
@subsection @file{mktex} scripts

@cindex @file{mktex} scripts
@cindex scripts for file creation

@cindex font set, infinite
@cindex dynamic creation of files
@cindex Sauter fonts, and dynamic source creation
@cindex EC fonts, and dynamic source creation
If Kpathsea cannot otherwise find a file, for some file types it is
configured by default to invoke an external program to create it
dynamically (@pxref{mktex configuration}).  These are collectively
known as @dfn{@code{mktex} scripts}, since most of them are named
@code{mktex...}.

For example, this is useful for fonts (bitmaps, TFM's, and
arbitrarily-sizable Metafont sources such as the Sauter and EC fonts),
since any given document can use fonts never before referenced.
Building all fonts in advance is therefore impractical, if not
impossible.

It is also useful for the @TeX{} @samp{.fmt} (and Metafont
@samp{.base} and Metapost @samp{.mem} files, @pxref{Memory
dumps,,,Web2c,web2c}), where pre-generating every format consumes a
lot of both time and space.

The script is passed the name of the file to create and possibly other
arguments, as explained below.  It must echo the full pathname of the
file it created (and nothing else) to standard output; it can write
diagnostics to standard error.

@menu
* config: mktex configuration.
* names: mktex script names.
* args: mktex script arguments.
@end menu


@node mktex configuration
@subsubsection @file{mktex} configuration

@cindex @file{mktex} script configuration
@cindex configuration of @file{mktex} scripts
@cindex enabling @file{mktex} scripts
@cindex disabling @file{mktex} scripts

The list of file types and program names that can run an external
program to create missing files is listed in the next section.  In the
absence of @code{configure} options specifying otherwise, everything
but @file{mktextex} will be enabled by default.  The @code{configure}
options to change the defaults are:

@cindex @code{configure} options for @file{mktex} scripts
@opindex --without-mktexfmt-default
@opindex --without-mktexmf-default
@opindex --without-mktexocp-default
@opindex --without-mktexofm-default
@opindex --without-mktexpk-default
@opindex --without-mktextfm-default
@opindex --with-mktextex-default
@example
--without-mktexfmt-default
--without-mktexmf-default
--without-mktexocp-default
--without-mktexofm-default
--without-mktexpk-default
--without-mktextfm-default
--with-mktextex-default
@end example

The @code{configure} setting is overridden if the environment variable
or configuration file value named for the script is set; e.g.,
@file{MKTEXPK} (@pxref{mktex script arguments}).

@flindex fmtutils.cnf
@code{mktexfmt} reads a file @file{fmtutil.cnf}, typically located in
@file{texmf/web2c/} to glean its configuration information.  The rest
of the files and features in this section are primarily intended for
the font generation scripts.

@flindex mktex.cnf
@flindex mktex.opt
@cindex site overrides for @code{mktex@dots{}}
As distributed, all the scripts source a file
@file{texmf/web2c/mktex.cnf} if it exists, so you can override various
defaults.  
See @file{mktex.opt}, for instance, which defines the default mode,
resolution, some special directory names, etc.  If you prefer not to
change the distributed scripts, you can simply create @file{mktex.cnf}
with the appropriate definitions (you do not need to create it if you
have nothing to put in it).  @file{mktex.cnf} has no special syntax;
it's an arbitrary Bourne shell script.  The distribution contains a
sample @file{mktex.cnf} for you to copy and modify as you please (it
is not installed anywhere).

@flindex mktex.opt
@vindex MT_FEATURES
In addition, you can configure a number of features with the
@code{MT_FEATURES} variable, which you can define:

@itemize @bullet
@item
in @file{mktex.opt}, as just mentioned;

@item
by editing the file @file{mktex.opt}, either before @samp{make
install} (in the source hierarchy) or after (in the installed
hierarchy);

@item
or in the environment.
@end itemize

If none of the options below are enabled, @code{mktexpk},
@code{mktextfm}, and @code{mktexmf} follow the following procedure to
decide where fonts should be installed.  Find the tree where the font's
sources are, and test the permissions of the @samp{fonts} directory of
that tree to determine whether it is writable.  If it is, put the files
in the tree in appropriate locations.  If it isn't writable, see whether
the tree is a system tree (named in @code{SYSTEXMF}).  If so, the
@code{VARTEXFONTS} tree is used.  In all other cases the working
directory is used.

The @samp{appendonlydir} option is enabled by default.

@vtable @samp
@item appendonlydir
@cindex directories, making append-only
@flindex mktexdir
Tell @code{mktexdir} to create directories append-only, i.e., set
their sticky bit (@pxref{Mode Structure,,, coreutils, GNU Core
Utilities}).  This feature is silently ignored on non-Unix platforms
(e.g. Windows/NT and MS-DOS) which don't support similar functionality.
This feature is enabled by default.

@item dosnames
@cindex 8.3 filenames, using
@cindex DOS compatible names
@flindex dpi@var{nnn} directories
Use 8.3 names; e.g., @file{dpi600/cmr10.pk} instead of
@file{cmr10.600pk}.  Note that this feature only affects filenames that
would otherwise clash with other TeX-related filenames; @file{mktex}
scripts do nothing about filenames which exceed the 8+3 MS-DOS limits
but remain unique when truncated (by the OS) to these limits, and nether
do the scripts care about possible clashes with files which aren't
related with TeX.  For example, @file{cmr10.600pk} would clash with
@file{cmr10.600gf} and is therefore changed when @samp{dosnames} is in
effect, but @file{mf.pool} and @file{mp.base} don't clash with any
TeX-related files and are therefore unchanged.

This feature is turned on by default on MS-DOS.  If you do not wish
@samp{dosnames} to be set on an MS-DOS platform, you need to set the
@code{MT_FEATURES} environment variable to a value that doesn't include
@samp{dosnames}.  You can also change the default setting by editing
@file{mktex.opt}, but only if you use the @file{mktex} shell scripts;
the emulation programs don't consult @file{mktex.opt}.

@item fontmaps
@cindex fontmaps
@cindex fontname
Instead of deriving the location of a font in the destination tree from
the location of the sources, the aliases and directory names from the
Fontname distribution are used. (@pxref{Top,, Introduction, fontname,
Fontname}).

@item nomfdrivers
@cindex metafont driver files
Let mktexpk and mktextfm create metafont driver files in a temporary
directory.  These will be used for just one metafont run and not
installed permanently.

@item nomode
@cindex mode directory, omitting
Omit the directory level for the mode name; this is fine as long as
you generate fonts for only one mode.

@item stripsupplier
@cindex supplier directory, omitting
Omit the font supplier name directory level.

@item striptypeface
@cindex typeface directory, omitting
Omit the font typeface name directory level.

@item strip
@cindex supplier directory, omitting
@cindex typeface directory, omitting
Omit the font supplier and typeface name directory levels.  This feature
is deprecated in favour of @samp{stripsupplier} and @samp{striptypeface}.

@item varfonts
@flindex /var/tmp/texfonts
@vindex VARTEXFONTS
@cindex Linux File System Standard
When this option is enabled, fonts that would otherwise be written in
system texmf tree go to the @code{VARTEXFONTS} tree instead.  The
default value in @file{kpathsea/Makefile.in} is
@file{/var/tmp/texfonts}.  The @cite{Linux File System Standard}
recommends @file{/var/tex/fonts}.

@vindex USE_VARTEXFONTS
The @samp{varfonts} setting in @code{MT_FEATURES} is overridden by the
@code{USE_VARTEXFONTS} environment variable: if set to @samp{1}, the
feature is enabled, and if set to @samp{0}, the feature is disabled.

@item texmfvar
@vindex TEXMFVAR
Force generated files that would go into a system tree (as defined by
@code{SYSTEXMF}) into @code{TEXMFVAR}. Starting with te@TeX{}-3.0, the
variable @code{TEXMFVAR} is always set.  The @samp{varfonts} feature takes
precedence if also set.

@vindex USE_TEXMFVAR
The @samp{texmfvar} setting in @code{MT_FEATURES} is overridden by the
@code{USE_TEXMFVAR} environment variable: if set to @samp{1}, the
feature is enabled, and if set to @samp{0}, the feature is disabled.
@end vtable


@node mktex script names
@subsubsection @file{mktex} script names

@cindex @file{mktex} script names
@cindex names for @file{mktex} scripts

The following table shows the default name of the script for each
of the file types which support runtime generation.

@table @file
@item mktexfmt
@pindex mktexfmt
@pindex fmtutil
(@samp{.fmt}, @samp{.base}, @samp{.mem}) @TeX{}/Metafont/MetaPost
formats.  This script is also named @command{fmtutil}, and reads
@file{fmtutil.cnf} for configuration information.

@item mktexmf
@pindex mktexmf
(@samp{.mf}) Metafont input files.

@item mkocp
@pindex mkocp
(@samp{.ocp}) Omega compiled process files.

@item mkofm
@pindex mkofm
(@samp{.ofm}) Omega font metric files.

@item mktexpk
@pindex mktexpk
(@samp{pk}) Glyph fonts.

@item mktextex
@pindex mktextex
(@samp{.tex}) @TeX{} input files (disabled by default).

@item mktextfm
@pindex mktextfm
(@samp{.tfm}) TFM files.
@end table

@vindex DVIPSMAKEPK
@vindex XDVIMAKEPK
@vindex DVILJMAKEPK
@noindent These names can be overridden by an environment variable specific
to the program---for example, @code{DVIPSMAKEPK} for Dvipsk.

@comment next two paragraphs are repeated in dvips.texi
@flindex missfont.log
@cindex failed @code{mktex@dots{}} script invocation
If a @code{mktex@dots{}} script fails, the invocation is appended to a
file @file{missfont.log} (by default) in the current directory.  You can
then execute the log file to create the missing files after fixing the
problem.

@vindex TEXMFOUTPUT
@vindex MISSFONT_LOG
If the current directory is not writable and the environment variable or
configuration file value @code{TEXMFOUTPUT} is set, its value is
used.  Otherwise, nothing is written.  The name @samp{missfont.log} is
overridden by the @code{MISSFONT_LOG} environment variable or
configuration file value.


@node mktex script arguments
@subsubsection @file{mktex} script arguments

@cindex arguments to @file{mktex}

The first argument to a @file{mktex} script is always the name
of the file to be created.

In the default @file{mktexpk} implementation, additional arguments may
also be passed:

@table @samp
@item --dpi @var{num}
Sets the resolution of the generated font to @var{num}.
@item --mfmode @var{name}
Sets the Metafont mode to @var{name}.
@item --bdpi @var{num}
Sets the ``base dpi'' for the font.  This must match the mode being
used.
@item --mag @var{string}
A ``magstep'' string suitable for the Metafont @code{mag} variable.
This must match the combination of @var{bdpi} and @var{dpi} being used.
@item --destdir @var{string}
A directory name. If the directory is absolute, it is used as-is.
Otherwise, it is appended to the root destination directory set in the
script.
@end table


@node Installation testing 
@subsection Installation testing

@cindex testing, post-installation
@cindex installation testing

Besides the tests listed in @ref{Simple installation}, you can try
running @samp{make check}.  This includes the torture tests (trip, trap,
and mptrap) that come with Web2c (@pxref{Triptrap,,, web2c, Web2c}).


@node Security
@section Security

@cindex security considerations

None of the programs in the @TeX{} system require any special system
privileges, so there's no first-level security concern of people gaining
illegitimate root access.

@cindex trojan horse attack
@flindex .rhosts@r{, writable by @TeX{}}
A @TeX{} document, however, can write to arbitrary files, e.g.,
@file{~/.rhosts}, and thus an unwitting user who runs @TeX{} on a random
document is vulnerable to a trojan horse attack.  This loophole is
closed by default, but you can be permissive if you so desire in
@file{texmf.cnf}.  @xref{tex invocation,,, web2c, Web2c}.  MetaPost has
the same issue.

Dvips, Xdvi, and @TeX{} can also execute shell commands under some
circumstances.  To disable this, see the @samp{-R} option in @ref{Option
details,,, dvips, Dvips}, the xdvi man page, and @ref{tex
invocation,,, web2c, Web2c}, respectively.

@cindex local cache of fonts
@cindex cache of fonts, local
Another security issue arises because it's very useful---almost
necessary---to make arbitrary fonts on user demand with @code{mktexpk}
and friends.  Where do these files get installed?  By default, the
@code{mktexpk} distributed with Kpathsea assumes a world-writable
@file{/var/tmp} directory; this is a simple and convenient approach, but
it may not suit your situation because it means that a local cache of
fonts is created on every machine.

@cindex globally writable directories
To avoid this duplication, many people consider a shared, globally
writable font tree desirable, in spite of the potential security
problems.  To do this you should change the value of @code{VARTEXFONTS}
in @file{texmf.cnf} to refer to some globally known directory.
@xref{mktex configuration}.

@cindex append-only directories and @code{mktexpk}
The first restriction you can apply is to make newly-created directories
under @file{texmf} be append-only with an option in @file{mktex.cnf}.
@xref{mktex configuration}.

@cindex group-writable directories
@cindex setgid scripts
Another approach is to establish a group (or user) for @TeX{} files,
make the @file{texmf} tree writable only to that group (or user), and
make @code{mktexpk} et al.@: setgid to that group (or setuid to that
user).  Then users must invoke the scripts to install things.  (If
you're worried about the inevitable security holes in scripts, then you
could write a C wrapper to exec the script.)

@cindex file permissions
@cindex permissions, file
The @file{mktex@dots{}} scripts install files with the same read and
write permissions as the directory they are installed in.  The
executable, sgid, suid, and sticky bits are always cleared.

@cindex directory permissions
@cindex permissions, directory
Any directories created by the @file{mktex@dots{}} scripts have the
same permissions as their parent directory, unless the
@code{appendonlydir} feature is used, in which case the sticky bit is
always set.