cde/config/cf/README

   1 $TOG: README /main/76 1998/05/11 14:35:10 barstow $
   2
   3 The easiest way to write an Imakefile is to find another one that does
   4 something similar and copy/modify it!
   5
   6 To change any of these variables, edit the site.def file.
   7
   8 Imake.tmpl provides defaults for the following variables:
   9
  10         AlternateIncRoot        compiler needs -I to find project includes
  11         AlternateUsrLibDir      linker needs -L to find project libraries
  12         ArCmd                   command used to create libraries
  13         ArCmdBase               program name part of ArCmd
  14         ArAddCmd                flags to have ArCmdBase add files to a library
  15         ArExtCmd                flags to have ArCmdBase extract files
  16         AsCmd                   command used to run assembler
  17         BootstrapCFlags         missing cpp symbols needed to get started
  18         BourneShell             command used to run Bourne Shell
  19         CCsuf                   suffix that C++ source files have
  20         CURDIR                  current directory relative to top of sources
  21         CcCmd                   command to run C compiler
  22         CompressCmd             command to run compress program
  23         GzipCmd                 command to run gzip program
  24         ConstructMFLAGS         System V option to set MFLAGS make variable
  25         CpCmd                   command to copy one file to another
  26         CplusplusCmd            command to run C++ compiler
  27         CplusplusFilt           command to run C++ name demangler
  28         CplusplusYaccCmd        command to produce C++ source from yacc source
  29         CppCmd                  command to run C preprocessor
  30         CrossCompiling          cross compiling? (not fully supported)
  31         DebuggableCDebugFlags   C compiler -I's and -D's to turn on debug info
  32         DefaultCCOptions        default special C compiler options
  33         DefaultCDebugFlags      debug/optimize flags for programs
  34         DefaultUsrBin           program directory used even if PATH not set
  35         DependFlags             extra makedepend flags
  36         DoRanlibCmd             boolean for system uses ranlib
  37         EqnCmd                  command used for eqn
  38         ExecableScripts         boolean for systems that can exec() #!/bin/sh
  39         ExpandManNames          boolean to expand man pages names to long form
  40         ExtraFilesToClean       extra files to remove on make clean
  41         ExtraLibraries          system-specific libraries need to link
  42         ExtraLoadFlags          system-specific loader flags
  43         FileManSuffix           man suffix for file format pages
  44         FilesToClean            files to delete in make clean
  45         FortranCmd              command to run Fortran compiler
  46         FortranDebugFlags       flags for Fortran debug info
  47         FortranFlags            Fortran compiler flags
  48         HasBSD44Sockets         boolean for system has BSD4.4 sockets
  49         HasBsearch              boolean for libc has bsearch()
  50         HasBrokenCCForLink      boolean for brain damaged cc driver
  51         HasCenterLineC          boolean for system has CenterLine C compiler
  52         HasCenterLineCplusplus  boolean for system has CenterLine C++ compiler
  53         HasClearmake            use Clearcase's clearmake make program?
  54         HasCodeCenter           boolean for system has CodeCenter
  55         HasCplusplus            system has a C++ compiler?
  56         HasDECnet               system has DECnet?
  57         HasFortran              boolean for system has Fortran compiler
  58         HasGcc                  boolean for system has GNU gcc compiler
  59         HasGcc2                 boolean for system has GNU gcc 2.x compiler
  60         HasGcc2ForCplusplus     use gcc 2 for C++ programs?
  61         HasKrb5                 system has Kerberos version 5 support?
  62         HasLargeTmp             boolean for system has /tmp space
  63         HasLatex                system has LaTeX document preparation software
  64         HasLibCrypt             boolean for system has libcrypt
  65         HasNdbm                 boolean for system has ndbm routines
  66         HasPoll                 use poll() syscall?
  67         HasPurify               boolean for system has Purify
  68         HasPutenv               boolean for libc has putenv()
  69         HasSecureRPC            boolean for Sun Secure RPC
  70         HasSetUserContext       boolean for setusercontext()
  71         HasSentinel             boolean for system has Sentinel available
  72         HasSharedLibraries      boolean for system has shared libraries
  73         HasShm                  boolean for System V shared memory
  74         HasSockets              boolean for system has BSD sockets
  75         HasStrcasecmp           boolean for system implements str[n]casecmp
  76         HasStreams              use STREAMS I/O interface?
  77         HasSymLinks             boolean for system has symbolic links
  78         HasTestCenter           boolean for system has TestCenter
  79         HasVarDirectory         boolean for system has /var
  80         HasVFork                boolean for system has vfork()
  81         HasVoidSignalReturn     boolean for POSIX signal() procs
  82         HasZlib                 boolean for system has libz
  83         IncRoot                 parent of X11 include directory
  84         InstBinFlags            install flags for binaries
  85         InstDatFlags            install flags for data files
  86         InstIncFlags            install flags for header files
  87         InstKmemFlags           install flags for xload to get at /dev/kmem
  88         InstLibFlags            install flags for libraries
  89         InstManFlags            install flags for manual pages
  90         InstPgmFlags            install flags for normal programs
  91         InstUidFlags            install flags for xterm to chown /dev/ptys
  92         InstallCmd              command to install files
  93         KornShell               command used to run Korn Shell
  94         Krb5Includes            where to include Kerberos header files from
  95         Krb5Libraries           where to load Kerberos libraries from
  96         LdCmd                   command to run loader
  97         LdCombineFlags          flags for incremental loading
  98         LexCmd                  command to run lex
  99         LexLib                  library for programs using lex output
 100         LintCmd                 command to run lint
 101         LintLibFlag             flags to generate lint libraries
 102         LintOpts                lint options to control strictness
 103         LnCmd                   command to link two files
 104         LoaderLibPrefix         loader flags before libraries
 105         LocalRulesFile          site-specific file with additional imake rules
 106         LocalTmplFile           file with additional imake variables
 107         MacroFile               name of machine-dependent config params file
 108         MacroIncludeFile        <MacroFile>
 109         MakeCmd                 command to run make
 110         Malloc0ReturnsNull      boolean for malloc(0) == NULL
 111         Malloc0ReturnsNullDefines -D's to build libX11/libXt
 112         MathLibrary             library for programs using C math functions
 113         MsMacros                macro flag for TroffCmd, normally "-ms"
 114         MvCmd                   command to rename a file
 115         NdbmDefines             -D's to turn on use of ndbm routines
 116         NeedConstPrototoypes    whether const is supported
 117         NeedFunctionPrototypes  whether or not to force function prototypes
 118         NeedNestedPrototypes    whether nested prototypes are supported
 119         NeedVarargsPrototypes   whether varargs prototypes are supported
 120         NeedWidePrototypes      whether or not to widen function prototypes
 121         NoOpCDebugFlags         C compiler flags to not debug or optimize
 122         NoRConst                YES if const for structs of funcs is bad
 123         OSMajorVersion          major version number of operating system
 124         OSMinorVersion          minor version number of operating system
 125         OptimizedCDebugFlags    C compiler flags to turn on optimization
 126         XtPopdownConformance    XtPopdown conformans to the specification
 127         PreProcessCmd           command to run /lib/cpp on scripts
 128         RanlibCmd               command to clean up libraries
 129         RanlibInstFlags         flags to ranlib after copying
 130         ResourceConfigurationManagement boolean for Xt's Resource Configuration
 131                                         Management
 132         RmCmd                   command to delete files
 133         ShLibDir                directory in which to install shared libraries
 134         StandardCppDefines      -D's for running cpp
 135         StandardDefines         -D's for running C compiler
 136         StandardIncludes        -I's for running C compiler
 137         StripInstalledPrograms  boolean for sites that want to install -s
 138         SystemV                 boolean for systems that are at least SVR2
 139         SystemV4                boolean for SVR4 systems
 140         TOPDIR                  relative path to top of sources
 141         TagsCmd                 command to run tags
 142         TblCmd                  command to run tbl
 143         TroffCmd                command to run troff to get PostScript
 144         UNCOMPRESSPATH          command to run uncompress
 145         UnalignedReferencesAllowed      boolean for unaligned copies ok
 146         UsrLibDir               directory in which to install libraries
 147         YaccCmd                 command to run yacc
 148
 149 X11.tmpl provides defaults for the following variables:
 150
 151         AdmDir                  directory containing system log files
 152         AllocateLocalDefines    -D's to turn on alloca() (should be in Imake.tmpl)
 153         BDFTOSNFFILT            command to run bdftosnf
 154         BaseExtensionDefines    universal extensions to use
 155         BinDir                  directory in which to install programs
 156         BuildAppgroup           build AppGroup extension in server
 157         BuildCup                build Colormap Utilization extension in server
 158         BuildDBE                build DOUBLE-BUFFER extension
 159         BuildDIS                build Document Imaging Subset of XIE
 160         BuildDPMS               build Display Power Management Signaling extension
 161         BuildFontServer         build font server
 162         BuildFonts              build pcf fonts
 163         BuildIncRoot            relative path to location of headers in build
 164         BuildIncTop             path from build includes directory to top
 165         BuildEVI                build EVI server extension
 166         BuildLBX                build LBX (aka X.fast) server extension
 167         BuildMultibuffer        build Multibuffer extension (obsolete)
 168         BuildPlugin             build xrx plug-in for web browsers
 169         BuildRECORD             Build RECORD extension
 170         BuildPexExt             build PEX server extension and fonts
 171         BuildPhigs              build Phigs (obsolete)
 172         BuildServer             build X server
 173         BuildXAudio             build Audio
 174         BuildXAServer           build Audio server
 175         BuildXCSecurity         Build Security Extension
 176         BuildXIE                build X Image Extension
 177         BuildXInputExt          build X Input extension (requires ddx support,
 178                                         which exists only in Xhp and XFree86)
 179         BuildXInputLib          build X Input library
 180         BuildXKB                build X Keyboard Extension?
 181         BuildXKBlib             build X Keyboard Extension into Xlib?
 182         UseXKBInClients         Use XKB functions in normal clients?
 183         ConfigDir               install directory for config files
 184         ConnectionFlags         -D's for supported transports
 185         ContribDir              location of user-contributed sources
 186         DebugLibFS              build libFS_d.a
 187         DebugLibICE             build libICE_d.a
 188         DebugLibPex             build libPEX5_d.a
 189         DebugLibSM              build libSM_d.a
 190         DebugLibX11             build libX11_d.a
 191         DebugLibXau             build libXau_d.a
 192         DebugLibXaw             build libXaw_d.a
 193         DebugLibXdmcp           build libXdmcp_d.a
 194         DebugLibXext            build libXext_d.a
 195         DebugLibXi              build libXi_d.a
 196         DebugLibXie             build libXie_d.a
 197         DebugLibXmu             build libXmu_d.a
 198         DebugLibXt              build libXt_d.a
 199         DebugLibXtst            build libXtst_d.a
 200         DebugLibXag             build libXag_d.a
 201         DebugOldX               build liboldX_d.a
 202         DefaultFSConfigFile     default font server config file
 203         DefaultFontPath         default server font path
 204         DefaultRGBDatabase      default server rgb color database
 205         DefaultSystemPath       default system xdm PATH environment variable
 206         DefaultSystemShell      default /bin/sh
 207         DefaultUserPath         default user xdm PATH environment variable
 208         DependCmd               command to run makedepend
 209         DependDir               build directory containing makedepend program
 210         ExtensionDefines        -D's for universal extensions
 211         ExtensionOSDefines      -D's for additional extensions
 212         FontCompilerFlags       flags for bdftosnf
 213         FontDefines             -D's to turn on font options
 214         FontDir                 directory in which to install fonts
 215         FontFilters             -D's to specify font conversion filters
 216         FontOSDefines           -D's for which fonts to support
 217         ForceNormalLib          force building of .a in addition to shared lib
 218         GzipFontCompression     boolean for using gzip instead of compress
 219         HasXdmAuth              boolean for using XDM-AUTHORIZATION-1;
 220                                         needs Wraphelp.c, see Release Notes
 221         InstallAppDefFiles      install new app defaults files over old?
 222         InstallFSConfig         install fs config file over old?
 223         InstallLibManPages      boolean for installing library man pages
 224         InstallSecurityConfig   install server security policy file over old?
 225         InstallXdmConfig        install xdm config files over old?
 226         InstallXinitConfig      install xinit config files over old?
 227         LibDir                  directory in which to install X11 support files
 228         LibManSuffix            man suffix for library pages
 229         LibmanDir               directory in which to install library man pages
 230         LintlibDir              directory in which to install lint libs
 231         ManDir                  directory in which to install program man pages
 232         ManDirectoryRoot        parent of man directories relative to root
 233         ManPath                 full path of parent directory
 234         ManSourcePath           common prefix of man page directories
 235         ManSuffix               man suffix for programs
 236         MiscManSuffix           man suffix for miscellaneous pages
 237         NeedDefaultDepLibs      boolean for enabling default DEPLIBS
 238         NlsDir                  directory in which to install nls files
 239         NormalLibFS             build libFS.a
 240         NormalLibICE            build libICE.a
 241         NormalLibPex            build libPEX5.a
 242         NormalLibPhigs          build libphigs.a
 243         NormalLibSM             build libSM.a
 244         NormalLibX11            build libX11.a
 245         NormalLibXau            build libXau.a
 246         NormalLibXaw            build libXaw.a
 247         NormalLibXdmcp          build libXdmcp.a
 248         NormalLibXext           build libXext.a
 249         NormalLibXi             build libXi.a
 250         NormalLibXie            build libXie.a
 251         NormalLibXmu            build libXmu.a
 252         NormalLibXt             build libXt.a
 253         NormalLibXtst           build libXtst.a
 254         NormalLibXag            build libXag.a
 255         NormalOldX              build liboldX.a
 256         OsNameDefines           beats me
 257         PexApiDir               PEX include file location
 258         PexCCOptions            special options for building PEX library
 259         PexCDebugFlags          special flags for building PEX library
 260         PexClientDefines        special -D's for building PEX clients
 261         PexDipexDefines         special -D's for building PEX di files
 262         PexPhigsDefines         special -D's for building PEX library
 263         PexShmIPC               boolean for using shared memory in phigsmon
 264         PhigsInclude            include directory for phigs clients
 265         PrimaryScreenResolution resolution of default server screen
 266         ProfileLibFS            build libFS_p.a
 267         ProfileLibICE           build libICE_p.a
 268         ProfileLibPex           build libPEX5_p.a
 269         ProfileLibSM            build libSM_p.a
 270         ProfileLibX11           build libX11_p.a
 271         ProfileLibXau           build libXau_p.a
 272         ProfileLibXaw           build libXaw_p.a
 273         ProfileLibXdmcp         build libXdmcp_p.a
 274         ProfileLibXext          build libXext_p.a
 275         ProfileLibXi            build libXi_p.a
 276         ProfileLibXie           build libXie_p.a
 277         ProfileLibXmu           build libXmu_p.a
 278         ProfileLibXt            build libXt_p.a
 279         ProfileLibXtst          build libXtst_p.a
 280         ProfileLibXag           build libXag_p.a
 281         ProfileOldX             build liboldX_p.a
 282         ProjectX                version indicating this is the X Window System
 283         RemoveTargetProgramByMoving     boolean for rm -f that doesn't
 284         SHELLPATH               -D for /bin/sh
 285         ServerConfigDir         directory for server security config files
 286         ServerDefines           complete -D's for server
 287         ServerExtraDefines      special -D's for server
 288         ServerOSDefines         OS -D's for server
 289         ServerAssertDefines     -DNDEBUG for no assertions, /**/ for assertions
 290         SharedLibFS             boolean for making sharable libFS.so
 291         SharedLibICE            boolean for making sharable libICE.so
 292         SharedLibPex            boolean for making sharable libPEX5.so
 293         SharedLibPhigs          boolean for making sharable libphigs.so
 294         SharedLibSM             boolean for making sharable libSM.so
 295         SharedLibX11            boolean for making sharable libX11.so
 296         SharedLibXau            boolean for making sharable libXau.so
 297         SharedLibXaw            boolean for making sharable libXaw.so
 298         SharedLibXdmcp          boolean for making sharable libXdmcp.so
 299         SharedLibXext           boolean for making sharable libXext.so
 300         SharedLibXi             boolean for making sharable libXi.so
 301         SharedLibXie            boolean for making sharable libXie.so
 302         SharedLibXmu            boolean for making sharable libXmu.so
 303         SharedLibXt             boolean for making sharable libXt.so
 304         SharedLibXtst           boolean for making sharable libXtst.so
 305         SharedLibXag            boolean for making sharable libXag.so
 306         SharedOldX              boolean for making sharable liboldX.so
 307         ShmDefines              MIT-SHM define
 308         TwmDir                  directory in which to install twm config files
 309         UseCCMakeDepend         boolean for using alternate makedepend script
 310         UseRgbTxt               use rgb.txt file as is instead of DBM-compiled
 311         VarDirectory            directory in /var for logs, etc., and config
 312         VendorHasX11R6_3libXext don't need Security & AppGroup in xrx plug-in
 313         XAppLoadDir             directory in which to install app defaults
 314         XFileSearchPathBase     base file search path
 315         XFileSearchPathDefault  default path to search for app defaults files
 316         XInputDefines           XINPUT define
 317         XMalloc0ReturnsNullDefines -D's specifically for libX11
 318         XawClientDepLibs        DEPLIBS for clients that use Xaw
 319         XawClientLibs           LOCAL_LIBRARIES for clients that use Xaw
 320         XdmConfigurationSubdirectory    name of default xdm configuration
 321         XdmDir                  directory in which to install xdm files
 322         XdmServersType          type of xdm Xservers file to install
 323         XinitDir                directory in which to install xinit files
 324         XPrintDir               parent of X Print server config directory
 325         XprtServer              build the X Print server
 326         XmanLocalSearchPath     non-standard path for man pages
 327         XtErrorPrefix           leading text in XtError() msg; eg. 'X Toolkit '
 328         XtWarningPrefix         leading text in XtWarning()msg, same as above
 329         XtMalloc0ReturnsNullDefines -D's specifically for libXt
 330         ZBDFTOSNFFILT           -D to run uncompress and bdftosnf
 331
 332
 333 Library.tmpl provides defaults for the following variables:
 334
 335         AvoidNullMakeCommand    for makes that spout about $(_NULLCMD_)
 336         LibraryCCOptions        special C compiler options for libraries
 337         LibraryCDebugFlags      library debug/optimize flags to override defs
 338         LibraryCcCmd            command to run C compiler in libraries
 339         LibraryCplusplusOptions special C++ options for libraries
 340         LibraryCplusplusDebugFlags  library debug/optimize flags for C++
 341         LibraryCplusplusCmd     command to run C++ compiler in libraries
 342         LibraryDefines          -D's for libraries
 343         SeparateSharedCompile   shared and unshared libs use same binaries?
 344
 345
 346 Server.tmpl provides defaults for the following variables:
 347
 348         ServerCCOptions         server C compiler options to override defaults
 349         ServerCcCmd             command to run C compiler in server
 350         ServerCDebugFlags       server debug/opt compiler flags
 351         ServerDefines           server standard -D's
 352         InstallServerSetUID     does this system need X server suid to root?
 353
 354
 355 Threads.tmpl provides defaults for the following variables:
 356
 357         LocalThreads            whether to enable multi-threading support
 358         LocalThreadsDefines     -D flags needed in this directory
 359
 360
 361 An <os>Lib.rules file provides defaults for the following variables:
 362
 363         HasSharedLibraries      boolean for using shared libraries
 364         SharedDataSeparation    boolean indicating separate data/code
 365         SharedCodeDef           -D's for compiling shared library files
 366         SharedLibraryDef        -D's for defining which kind of shared lib
 367         ShLibIncludeFile        location of the <os>Lib.tmpl file
 368         SharedLibraryLoadFlags  loader flags when making the library
 369         UseExportLists          boolean for using an export list
 370         PositionIndependentCFlags               PIC compiler flags for C
 371         PositionIndependentCplusplusFlags       PIC compiler flags for C++
 372
 373           Note: PositionIndependentCplusplusFlags is only required if the
 374           C and C++ compilers use different flags to build PIC code.  The
 375           default configuration will try to use PositionIndependentCFlags
 376           for both C and C++ compiles.
 377
 378 An <os>Lib.tmpl file provides defaults for the following variables:
 379
 380         SharedFSReqs            required libs for libFS.so
 381         SharedFSRev             version number for libFS.so
 382         SharedICEReqs           required libs for libICE.so
 383         SharedICERev            version number for libICE.so
 384         SharedOldXReqs          required libs for liboldX.so
 385         SharedOldXRev           version number for liboldX.so
 386         SharedPexReqs           required libs for libPEX5.so
 387         SharedPexRev            version number for libPEX5.so
 388         SharedSMReqs            required libs for libSM.so
 389         SharedSMRev             version number for libSM.so
 390         SharedX11Reqs           required libs for libX11.so
 391         SharedX11Rev            version number for libX11.so
 392         SharedXauReqs           required libs for libXau.so
 393         SharedXauRev            version number for libXau.so
 394         SharedXawReqs           required libs for libXaw.so
 395         SharedXawRev            version number for libXaw.so
 396         SharedXdmcpReqs         required libs for libXdmcp.so
 397         SharedXdmcpRev          version number for libXdmcp.so
 398         SharedXextReqs          required libs for libXext.so
 399         SharedXextRev           version number for libXext.so
 400         SharedXiReqs            required libs for libXi.so
 401         SharedXiRev             version number for libXi.so
 402         SharedXieReqs           required libs for libXie.so
 403         SharedXieRev            version number for libXie.so
 404         SharedXmuReqs           required libs for libXmu.so
 405         SharedXmuRev            version number for libXmu.so
 406         SharedXtReqs            required libs for libXt.so
 407         SharedXtRev             version number for libXt.so
 408         SharedXtstReqs          required libs for libXtst.so
 409         SharedXtstRev           version number for libXtst.so
 410         SharedXmReqs            required libs for libXm.so
 411         SharedXmRev             version number for libXm.so
 412         SharedMrmReqs           required libs for libMrm.so
 413         SharedMrmRev            version number for libMrm.so
 414         SharedUilReqs           required libs for libUil.so
 415         SharedUilRev            version number for libUil.so
 416         SharedTtReqs            required libs for libtt.so
 417         SharedTtRev             version number for libtt.so
 418         SharedPamReqs           required libs for libpam.so
 419         SharedPamRev            version number for libpam.so
 420         SharedDtSvcReqs         required libs for libDtSvc.so
 421         SharedDtSvcRev          version number for libDtSvc.so
 422         SharedDtSearchReqs      required libs for libDtSearch.so
 423         SharedDtSearchRev       version number for libDtSearch.so
 424         SharedDtWidgetReqs      required libs for libDtWidget.so
 425         SharedDtWidgetRev       version number for libDtWidget.so
 426         SharedDtHelpReqs        required libs for libDtHelp.so
 427         SharedDtHelpRev         version number for libDtHelp.so
 428         SharedDtPrintReqs       required libs for libDtPrint.so
 429         SharedDtPrintRev        version number for libDtPrint.so
 430         SharedDtTermReqs        required libs for libDtTerm.so
 431         SharedDtTermRev         version number for libDtTerm.so
 432         SharedDtMrmReqs         required libs for libDtMrm.so
 433         SharedDtMrmRev          version number for libDtMrm.so
 434
 435 The following variables are used by some part of the tree:
 436
 437         AckToolset              programs/Xserver/hw/xfree86
 438         BuildChooser            build the xdm chooser program?
 439         SharedLibXdmGreet       use xdm shared dynamic greeter library?
 440         LatexCmd                command to run LaTeX on a document
 441         DvipsCmd                command to turn .dvi file into PostScript
 442         MotifBC                 using Motif 1.1.1, 1.1.2, or 1.1.3?
 443         GetValuesBC             compat GetValues behavior for broken apps?
 444         NeedBerklib             application needs libXbsd?
 445         SvgaConfig              default SVGA configuration
 446         HasGetReturnAddress     util/memleak
 447         HasShadowPasswd         system has getspnam() function
 448         XnestServer             build X server with Xlib-based ddx
 449         XVirtualFramebufferServer       build X server with virtual memory framebuffer
 450         XpRasterDDX             include the raster print ddx driver
 451         XpColorPclDDX           include the color PCL print ddx driver
 452         XpMonoPclDDX            include the monochrome PCL print ddx driver
 453         XpPostScriptDDX         include the PostScript print ddx driver
 454         WebServer               host:port of your Web server (see programs/xrx)
 455         HtmlDir                 path used by Web server for HTML and RX docs
 456         CgiBinDir               path used by Web server for CGI programs
 457         ProxyManager            ICE network ID to contact a running proxymngr
 458
 459
 460 Make Variables
 461
 462 The following make variables are used by imake rules and may be set in
 463 an individual Imakefile.
 464
 465 DEFINES                 program-specific -D flags and other arguments
 466                         to pass to the C compiler, lint, and makedepend.
 467 DEPEND_DEFINES          program-specific flags in addition to
 468                         $(DEFINES) to pass to lint and makedepend.
 469                         This is usually used when there are special
 470                         compilation rules for individual files, and
 471                         the defines passed to those files affect
 472                         makedepend results.  If they can be passed to
 473                         all files during the makedepend step without
 474                         affecting the results for other files,
 475                         DEPEND_DEFINES is used to do that.  Example is
 476                         the Xlib Imakefile.
 477 INCLUDES                program-specific -I flags.
 478 HEADERS                 .h files to install with "make includes" and
 479                         "make install".  If this Imakefile includes
 480                         Library.tmpl there are no headers, include
 481                         this line instead of a HEADERS definition:
 482                         #define LibHeaders NO
 483 REQUIREDLIBS            when building a shared library, other libraries used
 484                         by this library that should be referenced at
 485                         link time.
 486 LINTLIBS                program-specific libraries for lint.
 487 LOCAL_LDFLAGS           program-specific flags for the linker.
 488 LOCAL_LIBRARIES         project libraries (usually specified
 489                         as -lname) needed by this program.
 490                         For example, "-lXt -lXext -lX11".
 491                         Used by SimpleProgramTarget and
 492                         ComplexProgramTarget* rules.
 493                         Do not include any system-specific libraries here.
 494 SYS_LIBRARIES           system libraries (usually specified
 495                         as -lname) needed by this program.
 496                         For example "MathLibrary".
 497                         Do not include any system-specific libraries
 498                         such as "-lnsl" here; they are automatically
 499                         added to the link command by the
 500                         vendor-specific .cf file.
 501 SUBDIRS                 for an Imakefile in a directory containing
 502                         subdirectories, this names the subdirectories.
 503                         Such an Imakefile also needs to #define IHaveSubdirs
 504                         and call MakeSubdirs() and DependSubdirs().
 505 MANSUFFIX               suffix used by InstallManPage* rules.
 506                         May be set to $(LIBMANSUFFIX), $(FILEMANSUFFIX), or
 507                         $(MISCMANSUFFIX) in directories for libraries or data
 508                         files.
 509
 510
 511 Rule-specific variables that may be set in an individual Imakefile.
 512 If you aren't using these rules, you may need variables with a similar
 513 function, but you need not use these names.  However, following these
 514 conventions may make your Imakefile easier to read and maintain.
 515
 516 DEPLIBS                 library dependencies for ComplexProgramTarget
 517 SRCS                    source files used by ComplexProgramTarget and
 518                         DependTarget.
 519 OBJS                    object files used by ComplexProgramTarget
 520 PROGRAMS                default target used with ComplexProgramTarget_(n)
 521 SRCS1                   source files used by ComplexProgramTarget_1
 522 OBJS1                   object files used by ComplexProgramTarget_1
 523 DEPLIBS1                library dependencies for ComplexProgramTarget_1
 524 SRCS2                   source files used by ComplexProgramTarget_2
 525 OBJS2                   object files used by ComplexProgramTarget_2
 526 DEPLIBS2                library dependencies for ComplexProgramTarget_2
 527 SRCS3                   source files used by ComplexProgramTarget_3
 528 OBJS3                   object files used by ComplexProgramTarget_3
 529 DEPLIBS3                library dependencies for ComplexProgramTarget_3
 530
 531 Variables that can be set on the make command line:
 532
 533 DESTDIR                 directory under which "make install" should
 534                         install instead of "/"; used only for testing
 535                         "make install" rules.
 536 FILE                    file for "lint1" target to run lint on.
 537 CDEBUGFLAGS             -g and/or -O flag to control C compiler optimization.
 538 CXXDEBUGFLAGS           -g and/or -O flag to control C++ optimization.
 539 LDSTRIPFLAGS            flag to have linker strip objects (typically -x).
 540                         Typically set to the empty string to prevent
 541                         the linker from stripping objects; use this
 542                         way when setting CDEBUGFLAGS to "-g".
 543
 544 These variables are set in project-specific files such as X11.tmpl.
 545 They should NOT be set in an Imakefile.  These variables are sometimes
 546 misused; they are included here to remind Imakefile writers NOT to use
 547 them:
 548
 549 EXTRA_DEFINES           project-specific -D flags
 550 EXTRA_INCLUDES          project-specific -I flags
 551 EXTRA_ICONFIGFILES      Additional project-specific imake config files
 552                         to add to ICONFIGFILES.
 553                         This is a list of files that define variables
 554                         that might affect compilation of some files.
 555
 556 Many other make variables are set up by the imake config files and can
 557 be used in an Imakefile.  The easiest way to discover them is to look
 558 at the Makefile generated by an empty Imakefile.
 559
 560
 561 Comments
 562
 563 Use C comment syntax in an Imakefile for comments that should not
 564 appear in the resulting Makefile.
 565 Use "XCOMM" at the start of each
 566 line to produce a comment that will appear in the Makefile.
 567 (The "XCOMM" will
 568 be translated into the Makefile comment character "#" by imake.)
 569 Do NOT use "#" as a comment character in Imakefiles; it confuses the C
 570 preprocessor used by imake on some systems.
 571
 572
 573 Imake variables
 574
 575 Don't abuse the variables in X11.tmpl that describe
 576 particular pieces of X by using them to describe your own subsystems.
 577 Instead, create new variables that are defaulted using
 578 Imake.tmpl variables.
 579
 580
 581 Examples
 582
 583 Since the easiest way to write an Imakefile is to start with one that
 584 works, here are some short, easy-to-read Imakefile examples in the X
 585 distribution:
 586
 587 with subdirs:   config/Imakefile
 588 library:        lib/Xau/Imakefile
 589 simple program: programs/xdpyinfo/Imakefile
 590 complex progs:  programs/xclipboard/Imakefile
 591 complex prog:   programs/xmodmap/Imakefile
 592
 593 Common Rules
 594
 595 Here are some of the common rules for building programs.  How to use
 596 them is described in Imake.rules and in the O'Reilly book "Software
 597 Portability with imake."
 598
 599 Basic program-building rules
 600
 601 All of these except NormalProgramTarget also generate rules to install
 602 the program and its manual page, and to generate dependencies.
 603
 604 SimpleProgramTarget     Use if there is only one program to be made
 605                         and it has only one source file.
 606
 607 ComplexProgramTarget    Use if there is only one program to be made
 608                         and it has multiple source files.  Set SRCS to
 609                         the names of the source files, set OBJS to
 610                         the names of the object files, and set DEPLIBS
 611                         to the libraries that this program depends on.
 612
 613 ComplexProgramTarget_1  Like ComplexProgramTarget, but uses SRCS1,
 614                         OBJS1, and DEPLIBS1 and can be used with
 615                         ComplexProgramTarget_2 and ComplexProgramTarget_3
 616                         to build up to three programs in the same directory.
 617                         Set PROGRAMS to the programs built by all of
 618                         these rules.  For more than 3 programs, use
 619                         NormalProgramTarget for each.
 620 ComplexProgramTarget_2  Use after ComplexProgramTarget_1 for the
 621                         second program in a directory.  Uses SRCS2,
 622                         OBJS2, and DEPLIBS2.
 623 ComplexProgramTarget_3  Use after ComplexProgramTarget_2 for the
 624                         third program in a directory.  Uses SRCS3,
 625                         OBJS3, and DEPLIBS3.
 626
 627 NormalProgramTarget     Build a program.  Can be used multiple times
 628                         with different arguments in the same Imakefile.
 629
 630 Lower level rules, often used with NormalProgramTarget
 631
 632 InstallProgram          install a program.
 633
 634 InstallManPage          install a manual page.
 635
 636 DependTarget()          include once at end of Imakefile with
 637                         NormalProgramTarget rules or that uses Library.tmpl.
 638                         Generates dependencies for files named in SRCS.
 639
 640 Manual page rules, commonly used only in special documentation directories:
 641
 642 InstallManPage
 643 InstallManPageLong
 644 InstallManPageAliases
 645
 646 Other rules:
 647
 648 SpecialCObjectRule      Compile a C file with special flags.
 649 AllTarget               Declare additional targets to build.
 650 InstallAppDefaults      Install X application defaults file.
 651
 652 Imakefile for directory with subdirectories
 653
 654 XCOMM this is a sample Imakefile for a directory containing subdirectories
 655 #define IHaveSubdirs
 656 #define PassCDebugFlags CDEBUGFLAGS="$(CDEBUGFLAGS)"
 657 SUBDIRS = list of subdirs ...
 658 MakeSubdirs($(SUBDIRS))
 659 DependSubdirs($(SUBDIRS))
 660
 661
 662 Common Targets
 663
 664 These targets are typically NOT defined explicitly by the Imakefile
 665 writer; rather they are generated automatically by imake rules.
 666 They are listed here for the convenience of people using the resulting
 667 Makefile, not people writing the original Imakefile.
 668
 669 all                     Default rule; builds whatever is in this directory.
 670 Makefile                Remake the Makefile (use after changing Imakefile).
 671                         Run "make depend" after.
 672 Makefiles               Remake all Makefiles in subdirectories.  (Does
 673                         nothing if no subdirectories.)
 674                         Run "make depend" after.
 675 includes                Generate and install in the tree any necessary
 676                         header files.
 677 depend                  Update dependencies in the Makefile calculated
 678                         by examining the source files.
 679 install                 Install what "make all" built on the system.
 680 install.man             Install manual pages.
 681 clean                   Remove built objects and other derived files.
 682 lint                    Run lint.
 683 tags                    Create a tags file.