Import sendmail 8.13.8
[dragonfly.git] / contrib / sendmail-8.13.8 / devtools / README
1 This directory contains tools.  Do not attempt to actually build
2 anything in this directory.
3
4 The Build script allows you to specify a base location for the object
5 files by using the -O flag:
6
7         Build -O /tmp
8
9 will put the object files in /tmp/obj.*/.  Also, if the SENDMAIL_SUFFIX
10 environment variable is set, its value will be used in the obj.* directory
11 name.
12
13 The Build script allows you to specify a site configuration file by using
14 the -f flag:
15
16         Build -f siteconfig.m4
17
18 You can put such site configuration files in the Site sub-directory;
19 see Site/README for details.
20
21 If you need to support multiple build configurations from the same tree,
22 you can use prefixes to differentiate your configurations.  Use the -Q
23 flag to Build:
24
25         Build -Q prefix
26
27 Build will select a prefix.*.m4 file instead of the site.*.m4 file according
28 to the conventions in Site/README, and use it to modify the build
29 configuration.  The object directory used will be obj.prefix.*/.  Your
30 prefix.*.m4 files should reside in the Site directory.  You may not use
31 -Q and -f simultaneously.
32
33 While building a site configuration file, beyond using define() to set
34 variables, you can also add to a definition using the APPENDDEF() and
35 PREPENDDEF() macros.  For example:
36
37         APPENDDEF(`confINCDIRS', `-I/usr/local/bind/include')
38
39 will add -I/usr/local/bind/include to the already existing confINCDIRS.
40 Note: There must be no trailing spaces after the last quote mark and
41 before the closing parenthesis.  Also you may need to properly quote
42 m4 reserved words as specified by your vendor's m4 command.
43
44 By default, sendmail will search your system for include and library
45 directories as well as certain libraries (libdb.* for Berkeley DB and
46 libbind.a or libresolv.* for name resolution).  You can turn off this
47 configuration step by specifying the -S flag with the Build command.
48
49 The OS subtree contains definitions for variations on a standard
50 model for system installation.  The M4 variables that can be defined
51 and their defaults before referencing the appropriate OS definitions
52 are listed below.  Note that variables preceded by an asterisk (*)
53 are currently not used in the open source distribution.
54
55 confBEFORE          [empty]             Files to create before sendmail is
56                                         compiled.  The methods must be defined
57                                         in the Makefile using PUSHDIVERT(3).
58 confBLDVARIANT      OPTIMIZED           This controls which object variant will
59                                         be built and is controlled with the
60                                         -v flag to the Build
61                                         script. Internally, this macro is
62                                         used to select compiler options in
63                                         the devtools/OS/*.m4 files.  Valid
64                                         arguments for the Build -v flag are
65                                         "optimized", "debug", and "purify"
66                                         which map to confBLDVARIANT values
67                                         of "OPTIMIZED", "DEBUG", and
68                                         "PURIFY".  This is a work in
69                                         progress, and as such not all
70                                         devtools/OS/*.m4 have been updated
71                                         yet. (See Linux for an example of
72                                         one that has.)  Also, in the future
73                                         it may be desirable to append a
74                                         variant identifier to the object
75                                         directory name to allow different
76                                         variants to independently co-exist
77                                         on a given target platform.  Note:
78                                         the PURIFY variant has not been
79                                         fully implemented on any platforms
80                                         yet. Other variants can be added as
81                                         needed in the future. Changing this
82                                         macro from its default will affect
83                                         other default values.
84 confBUILDBIN        ../../devtools/bin  The location of the build support
85                                         binaries, relative to the obj.*
86                                         directory.
87 confCC              cc                  The C compiler to use.
88 confCCOPTS          [empty]             Additional options to pass to confCC.
89 *confCCOPTS_SO      -fPIC               Additional options for compiling
90                                         shared object libraries.
91 confCOPY            cp                  A program that copies files.
92 confDEPEND_TYPE     generic             How to build dependencies.  This should
93                                         be the name of a file in
94                                         devtools/M4/depend
95 confDEPLIBS         [empty]             Dependent libraries when building 
96                                         shared objects. 
97 confDONT_INSTALL_CATMAN  [undefined]    Don't install the formatted manual
98                                         pages.
99 confEBINDIR         /usr/libexec        The location for binaries executed
100                                         from other binaries, e.g., mail.local
101                                         or smrsh.
102 confENVDEF          [empty]             -D flags passed to C compiler.
103 confFORCE_RMAIL     [undefined]         If defined, install the rmail program
104                                         without question.
105 confGBINGRP         smmsp               The group for set-group-ID binaries.
106 confGBINMODE        2555                The mode for set-group-ID binaries.
107 confGBINOWN         root                The owner for set-group-ID binaries.
108 confMSPQOWN         smmsp               The owner of the MSP queue.
109 confMSP_QUEUE_DIR   /var/spool/clientmqueue   The MSP queue directory.
110 confMSP_STFILE      sm-client.st        Name of the MSP statistics file.
111 confHFDIR           /etc/mail           Location of the sendmail helpfile.
112 confHFFILE          helpfile            Name of the installed helpfile.
113 confINCDIRS         [empty]             -I flags passed to C compiler.
114 confINCGRP          bin                 The group for include files.
115 confINCMODE         444                 The mode of installed include files.
116 confINCOWN          root                The owner for include files.
117 confINCLUDEDIR      /usr/include        Where to install include files.
118 confINSTALL         install             The BSD-compatible install program.
119                                         Use ${BUILDBIN}/install.sh if none
120                                         is available on your system.
121 confINSTALL_RAWMAN  [undefined]         Install the unformatted manual pages.
122 *confLD             confCC              Linker to use.
123 confLDOPTS          [empty]             Linker options passed to ld.
124 *confLDOPTS_SO      -shared -Wl         Additional linker options for
125                                         linking shared object libraries.
126 confLIBDIR          /usr/lib            Where to install library files.
127 confLIBDIRS         [empty]             -L flags passed to ld.
128 confLIBGRP          bin                 The group for libraries.
129 confLIBMODE         444                 The mode of installed libraries.
130 confLIBOWN          root                The owner for libraries.
131 confLIBS            [varies]            -l flags passed to ld.
132 confLIBSEARCH       db bind resolv 44bsd
133                                         Search for these libraries for
134                                         linking with programs.
135 confLIBSEARCHPATH   /lib /usr/lib /usr/shlib
136                                         Locations to search for the
137                                         libraries specified by confLIBSEARCH.
138 confLINKS           ${UBINDIR}/newaliases ${UBINDIR}/mailq \
139                     ${UBINDIR}/hoststat ${UBINDIR}/purgestat
140                                         Names of links to sendmail.
141 confLN              ln                  The command used to create links.
142 confLNOPTS          -f -s               The parameters for confLN.
143 confMAN1            confMANROOT 1       The location of man1 files.
144 confMAN1EXT         1                   The extension on files in confMAN1.
145 confMAN1SRC         0                   The source for man pages installed
146                                         in confMAN1.
147 confMAN3            confMANROOT 3       The location of man3 files.
148 confMAN3EXT         3                   The extension on files in confMAN3.
149 confMAN3SRC         0                   The source for man pages installed
150                                         in confMAN3.
151 confMAN4            confMANROOT 4       The location of man4 files.
152 confMAN4EXT         4                   The extension on files in confMAN4.
153 confMAN4SRC         0                   The source for man pages installed
154                                         in confMAN4.
155 confMAN5            confMANROOT 5       The location of man5 files.
156 confMAN5EXT         5                   The extension on files in confMAN5.
157 confMAN5SRC         0                   The source for man pages installed
158                                         in confMAN5.
159 confMAN8            confMANROOT 8       The location of man8 files.
160 confMAN8EXT         8                   The extension on files in confMAN8.
161 confMAN8SRC         0                   The source for man pages installed
162                                         in confMAN8.
163 confMANDOC          -man                The macros used to format man pages.
164 confMANGRP          bin                 The group of installed man pages.
165 confMANMODE         444                 The mode of installed man pages.
166 confMANOWN          bin                 The owner of installed man pages.
167 confMANROOT         /usr/share/man/cat  The root of the man subtree.
168 confMANROOTMAN      /usr/share/man/man  The root of the man subtree, for
169                                         unformatted manual pages.
170 confMAPDEF          [varies]            The map definitions, e.g.,
171                                         -DNDBM -DNEWDB.  -DNEWDB is always
172                                         added if libdb.* can be found.
173 confMBINDIR         /usr/sbin           The location of the MTA (sm-mta,
174                                         sendmail) binary.
175 confMBINGRP         bin                 The group of the MTA binary (sm-mta).
176 confMBINMODE        550                 The mode of the MTA binary (sm-mta).
177 confMBINOWN         root                The owner of the MTA binary (sm-mta).
178 confMTCCOPTS        [empty]             Additional options for compiling
179                                         multi-threaded object files.
180 confMTLDOPTS        [empty]             Additional linker options for
181                                         linking multithreaded binaries.
182 confNO_HELPFILE_INSTALL  [undefined]    If defined, don't install the sendmail
183                                         helpfile by default.
184 confNO_MAN_BUILD    [undefined]         If defined, don't build the man
185                                         pages.
186 confNO_MAN_INSTALL  [undefined]         If defined, don't install the man
187                                         pages by default.
188 confNO_STATISTICS_INSTALL  [undefined]  If defined, don't install the sendmail
189                                         statistics file by default.
190 confNROFF           groff -Tascii       The command to format man pages.
191 confOBJADD          [empty]             Objects that should be included in
192                                         when linking sendmail and the
193                                         associated utilities.  See also
194                                         confSRCADD.
195 confOPTIMIZE        -O                  Flags passed to C compiler as ${O}.
196 confRANLIB          echo                The path to the program to use
197                                         as ranlib.
198 confRANLIBOPTS      [empty]             Options to pass to ranlib.
199 confREQUIRE_LIBSM   [empty]             Define if libsm is required.
200 confSBINDIR         /usr/sbin           The location of root-oriented
201                                         commands, such as makemap.
202 confSBINGRP         bin                 The group for set-user-ID binaries.
203 confSBINMODE        4555                The mode for set-user-ID binaries.
204 confSBINOWN         root                The owner for set-user-ID binaries.
205 confSETUSERID_INSTALL   [undefined]     Needs to be defined to enable the
206                                         install-set-user-id target for
207                                         sendmail.  See sendmail/SECURITY.
208 confSHAREDLIB_EXT   .so                 Shared library file extenion name.
209 confSHAREDLIB_SUFFIX [empty]            Shared object version suffix.   
210 confSHAREDLIBDIR    /usr/lib            Directory for installing shared 
211                                         library. 
212 confSHELL           /bin/sh             The shell to use inside make.
213 confSM_OS_HEADER    [varies]            The name of the platform specific
214                                         include file.  Undefine this if
215                                         libsm is not used.
216 confSMOBJADD        [empty]             Objects that should be included in
217                                         when linking sendmail.  See also
218                                         confSMSRCADD.
219 confSMSRCADD        [empty]             C source files which correspond to
220                                         objects listed in confSMOBJADD.
221 confSMSRCDIR        [varies]            The sendmail source directory
222                                         relative to support program obj.*
223                                         directories.  If not set, the
224                                         Makefile will use a path set by the
225                                         Build script.
226 confSRCADD          [empty]             C source files which correspond to
227                                         objects listed in confOBJADD.
228 confSRCDIR          [varies]            The root of the source directories
229                                         relative to support program obj.*
230                                         directories.  If not set, the
231                                         Makefile will use a path set by the
232                                         Build script.
233 confSONAME          [empty]             ld flag for recording the shared object
234                                         name into shared object.
235 confSTDIR           /etc/mail           The directory in which to store the
236                                         sendmail statistics file.
237 confSTFILE          statistics          Name of the installed statistics file.
238 confSTMODE          0600                Mode of the installed statistics file.
239 confSTRIP           strip               What program to use for stripping
240                                         executables.
241 confSTRIPOPTS       [empty]             Options to pass to the strip program.
242 confUBINDIR         /usr/bin            The directory for user-executable
243                                         binaries.
244 confUBINGRP         bin                 The group for user-executable binaries.
245 confUBINMODE        555                 The mode for user-executable binaries.
246 confUBINOWN         bin                 The owner for user-executable binaries.
247
248 There are also program specific variables for each of the programs
249 in the sendmail distribution.  Each has the form `conf_prog_ENVDEF',
250 for example, `conf_sendmail_ENVDEF'.  If the program name contains
251 a '.' it must be replaced by '_' first, e.g., use `conf_mail_local_LIBS'
252 instead of `conf_mail.local_LIBS'.  The variables are:
253
254 conf_prog_ENVDEF    [empty]             -D flags passed to C compiler when
255                                         compiling prog.
256 conf_prog_LIB_POST  [empty]             -l flags passed to ld when linking
257                                         prog (after other libraries).
258 conf_prog_LIBS      [varies]            -l flags passed to ld when linking
259                                         prog (before other libraries).
260 conf_prog_OBJADD    [empty]             Additional object files given to ld
261                                         when linking prog.
262 conf_prog_SRCADD    [empty]             C source files to compile and link
263                                         for prog.
264
265 The order of the different conf*LIBS* is as follows:
266 conf_prog_LIBS confLIBS conf_prog_LIB_POST
267
268 ----------------------------------------------------------------
269
270 ----------------
271 New build system
272 ----------------
273
274 Sendmail's build system has undergone some rearrangement to accommodate
275 future development.  To the end user building sendmail from a distribution,
276 this should have little effect.  All the same configuration files and macros
277 should still behave the same.
278
279 If you need to make some radical changes to a Makefile.m4 or are adding new
280 libraries or utilities, you may want to read the rest of this document on
281 how to work with the new system.
282
283
284 --------
285 Overview
286 --------
287
288 The purpose of the redesign is twofold.  First, it cuts down massively on
289 replicated information.  Second, the new design should lend itself better to
290 working on platforms with somewhat different build tools than on standard
291 unix.
292
293 The main idea is to have the Makefile.m4 in each subdirectory contain the
294 minimum amount of information needed to describe the elements needed for
295 the build process and the products produced.
296
297 Each product has a type and each type has a template that provides a basic
298 makefile for that type.  Right now the templates are organized by the broad
299 type of the operating system. The two existing types are UNIX and NT.
300
301
302 ------------------
303 Makefile.m4 basics
304 ------------------
305
306 Each Makefile.m4 is split into separate products.  For the most part, the
307 products are considered totally separate from other products in the
308 Makefile.m4.  Each products is delineated by two macros: bldPRODUCT_START and
309 bldPRODUCT_END.
310
311 The form for bldPRODUCT_START is:
312 bldPRODUCT_START(<product_type>, <product_name>)
313 where <product_type> is the type of product to be produced (e.g., executable,
314 library, manpage) and <product_name> is a unique identifier within the
315 product_type name space for this Makefile.m4
316
317 The form for bldPRODUCT_END is:
318 bldPRODUCT_END
319
320 This is marks the end of all the information for the current product.
321
322 There is one other macro required in any Makefile.m4 and that is bldFINISH
323 which takes no arguments and must appear after all the products have been
324 defined.
325
326 When the actual makefile is generated each product appears in two sections.
327 The first is where makefile variables are set (e.g., CFLAGS=-O).  The second
328 is where the targets appear (e.g., foo.o: foo.c).  Anything diverted to
329 bldTARGETS_SECTION ends up in the second part of the makefile.  Anything
330 else turns up in the header part where variables are defined.
331
332 As always, any straight text put into Makefile.m4 will just show up as is
333 in the finished makefile.
334
335
336 -------------
337 Product Types
338 -------------
339
340 executable
341 ----------
342
343 This means an executable created from C sources.  The name of the executable
344 is derived from the product_name in the bldPRODUCT_START macro.
345
346 bldSOURCES - This should be defined to a space separated list of source
347 files that make up the executable.
348
349 bldBIN_TYPE - This determines where the binaries will be installed and what
350 permissions they will have.  Available types are `M', `U', `K', `S', and `E'.
351 See M4/UNIX/make/executable.m4 for what the different types mean.
352
353 bldTARGET_LINKS - This determines where additional symbolic links to the
354 executable are placed.  These should be full pathnames, separated by
355 spaces.
356
357
358 test
359 ----
360
361 This is just like 'executable', but is used for test programs.
362 The program cannot be installed.  Each time it is built, it is executed
363 by make with no arguments.
364
365
366 manpage
367 -------
368
369 This builds manpages from source using *roff.
370
371 bldSOURCES - This should be defined to a space separated list of man source
372 files.
373
374 bldINSTALLABLE - This should be set if the library should be installed in
375 confLIBDIR.
376
377 library
378 -------
379
380 This builds a static library from C sources.
381
382 bldSOURCES - This should be defined to a space separated list of C source
383 files that make up the library.
384
385
386 $Revision: 8.94 $, Last updated $Date: 2002/09/23 21:29:17 $