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      [empty]             Additional options for compiling
  90                                         shared object libraries.
  91 confCCLINK          confCC              Linker to use (for executables).
  92 confCOPY            cp                  A program that copies files.
  93 confMKDIR           [empty]             A program that creates directories
  94                                         (mkdir) and takes the -p parameter
  95                                         to create also intermediate directories
  96                                         as required.  If this macro is set,
  97                                         then it used by "make install" to
  98                                         create the required installation
  99                                         directories.
 100 confDEPEND_TYPE     generic             How to build dependencies.  This should
 101                                         be the name of a file in
 102                                         devtools/M4/depend
 103 confDEPLIBS         [empty]             Dependent libraries when building
 104                                         shared objects.
 105 confDONT_INSTALL_CATMAN  [undefined]    Don't install the formatted manual
 106                                         pages.
 107 confEBINDIR         /usr/libexec        The location for binaries executed
 108                                         from other binaries, e.g., mail.local
 109                                         or smrsh.
 110 confENVDEF          [empty]             -D flags passed to C compiler.
 111 confFORCE_RMAIL     [undefined]         If defined, install the rmail program
 112                                         without question.
 113 confGBINGRP         smmsp               The group for set-group-ID binaries.
 114 confGBINMODE        2555                The mode for set-group-ID binaries.
 115 confGBINOWN         root                The owner for set-group-ID binaries.
 116 confMSPQOWN         smmsp               The owner of the MSP queue.
 117 confMSP_QUEUE_DIR   /var/spool/clientmqueue   The MSP queue directory.
 118 confMSP_STFILE      sm-client.st        Name of the MSP statistics file.
 119 confHFDIR           /etc/mail           Location of the sendmail helpfile.
 120 confHFFILE          helpfile            Name of the installed helpfile.
 121 confINCDIRS         [empty]             -I flags passed to C compiler.
 122 confINCGRP          bin                 The group for include files.
 123 confINCMODE         444                 The mode of installed include files.
 124 confINCOWN          root                The owner for include files.
 125 confINCLUDEDIR      /usr/include        Where to install include files.
 126 confINSTALL         install             The BSD-compatible install program.
 127                                         Use ${BUILDBIN}/install.sh if none
 128                                         is available on your system.
 129 confINSTALL_RAWMAN  [undefined]         Install the unformatted manual pages.
 130 *confLD             confCC              Linker to use (for libraries).
 131 confLDOPTS          [empty]             Linker options.
 132 *confLDOPTS_SO      [empty]             Additional linker options for
 133                                         linking shared object libraries.
 134 confLIBDIR          /usr/lib            Where to install library files.
 135 confLIBDIRS         [empty]             -L flags passed to ld.
 136 confLIBGRP          bin                 The group for libraries.
 137 confLIBMODE         444                 The mode of installed libraries.
 138 confLIBOWN          root                The owner for libraries.
 139 confLIBS            [varies]            -l flags passed to ld.
 140 confLIBSEARCH       db bind resolv 44bsd cdb
 141                                         Search for these libraries for
 142                                         linking with programs.
 143 confLIBSEARCHPATH   /lib /usr/lib /usr/shlib
 144                                         Locations to search for the
 145                                         libraries specified by confLIBSEARCH.
 146 confLINKS           ${UBINDIR}/newaliases ${UBINDIR}/mailq \
 147                     ${UBINDIR}/hoststat ${UBINDIR}/purgestat
 148                                         Names of links to sendmail.
 149 confLN              ln                  The command used to create links.
 150 confLNOPTS          -f -s               The parameters for confLN.
 151 confMAN1            confMANROOT 1       The location of man1 files.
 152 confMAN1EXT         1                   The extension on files in confMAN1.
 153 confMAN1SRC         0                   The source for man pages installed
 154                                         in confMAN1.
 155 confMAN3            confMANROOT 3       The location of man3 files.
 156 confMAN3EXT         3                   The extension on files in confMAN3.
 157 confMAN3SRC         0                   The source for man pages installed
 158                                         in confMAN3.
 159 confMAN4            confMANROOT 4       The location of man4 files.
 160 confMAN4EXT         4                   The extension on files in confMAN4.
 161 confMAN4SRC         0                   The source for man pages installed
 162                                         in confMAN4.
 163 confMAN5            confMANROOT 5       The location of man5 files.
 164 confMAN5EXT         5                   The extension on files in confMAN5.
 165 confMAN5SRC         0                   The source for man pages installed
 166                                         in confMAN5.
 167 confMAN8            confMANROOT 8       The location of man8 files.
 168 confMAN8EXT         8                   The extension on files in confMAN8.
 169 confMAN8SRC         0                   The source for man pages installed
 170                                         in confMAN8.
 171 confMANDOC          -man                The macros used to format man pages.
 172 confMANGRP          bin                 The group of installed man pages.
 173 confMANMODE         444                 The mode of installed man pages.
 174 confMANOWN          bin                 The owner of installed man pages.
 175 confMANROOT         /usr/share/man/cat  The root of the man subtree.
 176 confMANROOTMAN      /usr/share/man/man  The root of the man subtree, for
 177                                         unformatted manual pages.
 178 confMAPDEF          [varies]            The map definitions, e.g.,
 179                                         -DNDBM -DNEWDB.  -DNEWDB is always
 180                                         added if libdb.* can be found,
 181                                         -DCDB is added if libcdb.* is found.
 182 confMBINDIR         /usr/sbin           The location of the MTA (sm-mta,
 183                                         sendmail) binary.
 184 confMBINGRP         bin                 The group of the MTA binary (sm-mta).
 185 confMBINMODE        550                 The mode of the MTA binary (sm-mta).
 186 confMBINOWN         root                The owner of the MTA binary (sm-mta).
 187 confMTCCOPTS        [empty]             Additional options for compiling
 188                                         multi-threaded object files.
 189 confMTLDOPTS        [empty]             Additional linker options for
 190                                         linking multithreaded binaries.
 191 confNO_HELPFILE_INSTALL  [undefined]    If defined, don't install the sendmail
 192                                         helpfile by default.
 193 confNO_MAN_BUILD    [undefined]         If defined, don't build the man
 194                                         pages.
 195 confNO_MAN_INSTALL  [undefined]         If defined, don't install the man
 196                                         pages by default.
 197 confNO_STATISTICS_INSTALL  [undefined]  If defined, don't install the sendmail
 198                                         statistics file by default.
 199 confNROFF           groff -Tascii       The command to format man pages.
 200 confOBJADD          [empty]             Objects that should be included in
 201                                         when linking sendmail and the
 202                                         associated utilities.  See also
 203                                         confSRCADD.
 204 confOPTIMIZE        -O                  Flags passed to C compiler as ${O}.
 205 confRANLIB          echo                The path to the program to use
 206                                         as ranlib.
 207 confRANLIBOPTS      [empty]             Options to pass to ranlib.
 208 confREQUIRE_LIBSM   [empty]             Define if libsm is required.
 209 confSBINDIR         /usr/sbin           The location of root-oriented
 210                                         commands, such as makemap.
 211 confSBINGRP         bin                 The group for set-user-ID binaries.
 212 confSBINMODE        4555                The mode for set-user-ID binaries.
 213 confSBINOWN         root                The owner for set-user-ID binaries.
 214 confSETUSERID_INSTALL   [undefined]     Needs to be defined to enable the
 215                                         install-set-user-id target for
 216                                         sendmail.  See sendmail/SECURITY.
 217 confSHAREDLIB_EXT   .so                 Shared library file extenion name.
 218 confSHAREDLIB_SUFFIX [empty]            Shared object version suffix.
 219 confSHAREDLIBDIR    /usr/lib/           Directory for installing shared
 220                                         library.  Note: if the value is
 221                                         not empty, it must end with a
 222                                         slash ('/') otherwise it will not
 223                                         be taken as a directory (but as
 224                                         the beginning of a path).
 225 confSHELL           /bin/sh             The shell to use inside make.
 226 confSM_OS_HEADER    [varies]            The name of the platform specific
 227                                         include file.  Undefine this if
 228                                         libsm is not used.
 229 confSMOBJADD        [empty]             Objects that should be included in
 230                                         when linking sendmail.  See also
 231                                         confSMSRCADD.
 232 confSMSRCADD        [empty]             C source files which correspond to
 233                                         objects listed in confSMOBJADD.
 234 confSMSRCDIR        [varies]            The sendmail source directory
 235                                         relative to support program obj.*
 236                                         directories.  If not set, the
 237                                         Makefile will use a path set by the
 238                                         Build script.
 239 confSRCADD          [empty]             C source files which correspond to
 240                                         objects listed in confOBJADD.
 241 confSRCDIR          [varies]            The root of the source directories
 242                                         relative to support program obj.*
 243                                         directories.  If not set, the
 244                                         Makefile will use a path set by the
 245                                         Build script.
 246 confSONAME          [empty]             ld flag for recording the shared object
 247                                         name into shared object.
 248 confSTDIR           /etc/mail           The directory in which to store the
 249                                         sendmail statistics file.
 250 confSTFILE          statistics          Name of the installed statistics file.
 251 confSTMODE          0600                Mode of the installed statistics file.
 252 confSTRIP           strip               What program to use for stripping
 253                                         executables.
 254 confSTRIPOPTS       [empty]             Options to pass to the strip program.
 255 confUBINDIR         /usr/bin            The directory for user-executable
 256                                         binaries.
 257 confUBINGRP         bin                 The group for user-executable binaries.
 258 confUBINMODE        555                 The mode for user-executable binaries.
 259 confUBINOWN         bin                 The owner for user-executable binaries.
 260
 261 There are also program specific variables for each of the programs
 262 in the sendmail distribution.  Each has the form `conf_prog_ENVDEF',
 263 for example, `conf_sendmail_ENVDEF'.  If the program name contains
 264 a '.' it must be replaced by '_' first, e.g., use `conf_mail_local_LIBS'
 265 instead of `conf_mail.local_LIBS'.  The variables are:
 266
 267 conf_prog_ENVDEF    [empty]             -D flags passed to C compiler when
 268                                         compiling prog.
 269 conf_prog_LIB_POST  [empty]             -l flags passed to ld when linking
 270                                         prog (after other libraries).
 271 conf_prog_LIBS      [varies]            -l flags passed to ld when linking
 272                                         prog (before other libraries).
 273 conf_prog_OBJADD    [empty]             Additional object files given to ld
 274                                         when linking prog.
 275 conf_prog_SRCADD    [empty]             C source files to compile and link
 276                                         for prog.
 277
 278 The order of the different conf*LIBS* is as follows:
 279 conf_prog_LIBS confLIBS conf_prog_LIB_POST
 280
 281 ----------------------------------------------------------------
 282
 283 ----------------
 284 New build system
 285 ----------------
 286
 287 Sendmail's build system has undergone some rearrangement to accommodate
 288 future development.  To the end user building sendmail from a distribution,
 289 this should have little effect.  All the same configuration files and macros
 290 should still behave the same.
 291
 292 If you need to make some radical changes to a Makefile.m4 or are adding new
 293 libraries or utilities, you may want to read the rest of this document on
 294 how to work with the new system.
 295
 296
 297 --------
 298 Overview
 299 --------
 300
 301 The purpose of the redesign is twofold.  First, it cuts down massively on
 302 replicated information.  Second, the new design should lend itself better to
 303 working on platforms with somewhat different build tools than on standard
 304 unix.
 305
 306 The main idea is to have the Makefile.m4 in each subdirectory contain the
 307 minimum amount of information needed to describe the elements needed for
 308 the build process and the products produced.
 309
 310 Each product has a type and each type has a template that provides a basic
 311 makefile for that type.  Right now the templates are organized by the broad
 312 type of the operating system. The two existing types are UNIX and NT.
 313
 314
 315 ------------------
 316 Makefile.m4 basics
 317 ------------------
 318
 319 Each Makefile.m4 is split into separate products.  For the most part, the
 320 products are considered totally separate from other products in the
 321 Makefile.m4.  Each products is delineated by two macros: bldPRODUCT_START and
 322 bldPRODUCT_END.
 323
 324 The form for bldPRODUCT_START is:
 325 bldPRODUCT_START(<product_type>, <product_name>)
 326 where <product_type> is the type of product to be produced (e.g., executable,
 327 library, manpage) and <product_name> is a unique identifier within the
 328 product_type name space for this Makefile.m4
 329
 330 The form for bldPRODUCT_END is:
 331 bldPRODUCT_END
 332
 333 This is marks the end of all the information for the current product.
 334
 335 There is one other macro required in any Makefile.m4 and that is bldFINISH
 336 which takes no arguments and must appear after all the products have been
 337 defined.
 338
 339 When the actual makefile is generated each product appears in two sections.
 340 The first is where makefile variables are set (e.g., CFLAGS=-O).  The second
 341 is where the targets appear (e.g., foo.o: foo.c).  Anything diverted to
 342 bldTARGETS_SECTION ends up in the second part of the makefile.  Anything
 343 else turns up in the header part where variables are defined.
 344
 345 As always, any straight text put into Makefile.m4 will just show up as is
 346 in the finished makefile.
 347
 348
 349 -------------
 350 Product Types
 351 -------------
 352
 353 executable
 354 ----------
 355
 356 This means an executable created from C sources.  The name of the executable
 357 is derived from the product_name in the bldPRODUCT_START macro.
 358
 359 bldSOURCES - This should be defined to a space separated list of source
 360 files that make up the executable.
 361
 362 bldBIN_TYPE - This determines where the binaries will be installed and what
 363 permissions they will have.  Available types are `M', `U', `K', `S', and `E'.
 364 See M4/UNIX/make/executable.m4 for what the different types mean.
 365
 366 bldTARGET_LINKS - This determines where additional symbolic links to the
 367 executable are placed.  These should be full pathnames, separated by
 368 spaces.
 369
 370
 371 test
 372 ----
 373
 374 This is just like 'executable', but is used for test programs.
 375 The program cannot be installed.  Each time it is built, it is executed
 376 by make with no arguments.
 377
 378
 379 manpage
 380 -------
 381
 382 This builds manpages from source using *roff.
 383
 384 bldSOURCES - This should be defined to a space separated list of man source
 385 files.
 386
 387
 388 library
 389 -------
 390
 391 This builds a static library from C sources.
 392
 393 bldSOURCES - This should be defined to a space separated list of C source
 394 files that make up the library.
 395
 396 bldINSTALLABLE - This should be set if the library should be installed in
 397 confLIBDIR.
 398
 399 $Revision: 8.104 $, Last updated $Date: 2012-01-21 00:07:06 $