======================================================= CONTRIBUTOR: Engineering Staff, Atria Software, Inc. ======================================================= ********************************************************** ************** THIS IS UNSUPPORTED SOFTWARE ************** ********************************************************** ********************************************************** * Atria makes no representation that the descriptions * * and software code contained in this document will * * not infringe on existing or future patent rights, * * copyrights, trademarks, trade secrets or other * * proprietary rights of third parties. The * * descriptions contained herein do not imply the * * granting of licenses to make, use, sell, license or * * otherwise transfer Atria products described herein. * * Atria disclaims responsibility for errors which may * * appear in this document, and it reserves the right, * * in its sole discretion and without notice, to make * * substitutions and modifications in the products and * * practices described in this document. * ********************************************************** ------------------ T0005: IMAKE GUIDE ------------------ Imake is invaluable for maintaining Makefiles that build software for for a variety of platforms. Imake can be used to generate platform-specific Makefiles from machine-independent descriptions called Imakefiles. Imake makes very heavy use of the C preprocessor for both constants and macros. Because it is based on CPP, it is highly portable. It is used to build the X Window System, and is included with standard X distributions. This document describes the various parameters that can be used to configure Makefiles with Imake. This document is derived from the InterViews 2.5 Imake Configuration Guide, which was derived from the X Window System Imake Configuration Guide, Release 3. The Imake program was written by Todd Brunhoff while a guest engineer at Project Athena, MIT. It is copyrighted by MIT and is in the public domain. IMAKE BASICS ------------ Imakefiles usually contain definitions of make variables plus one or more CPP macro invocations to build the desired parts of the Makefile. Imake processes a template file (typically called "Imake.tmpl") which contains definitions that are common to all Makefiles. The template file includes an architecture definition file (arch.c), a platform-specific definitions file (*.cf), a local site-specific definitions file (local.def), and a project configuration file (proj.tmpl). The *.cf files predefine some platform-dependent build parameters in order to set special compiler flags, etc. local.def predefines some build parameters that you want to set across all platforms at your site. You should modify only these files if you need to change a parameter. Imake.tmpl then includes a rule definitions file (rules.def) and the Imakefile being processed (INCLUDE_IMAKEFILE). rules.def defines rules in the form of macros. The Imakefile defines make variables and uses some of the rules provided by rules.def. Finally, Imake.tmpl appends a set of common rules to the bottom of the Makefile. The best way to get going is to obtain samples of all the files mentioned above (Imake.tmpl, rules.def, local.def, proj.tmpl, and the *.cf's), then modify them for your own use. PLATFORM AND MACHINE ARCHITECTURE --------------------------------- The first file that Imake.tmpl includes, arch.c, contains a series of conditional blocks for identifying the platform and machine architecture. Each conditional block defines several symbols (i.e., macros) representing the machine being configured. The conditional blocks assume that cpp defines a unique preprocessor symbol which identifies the machine architecture. If you have a machine whose cpp does not define such a symbol or you have to add support for another platform, follow the instructions in arch.c. Example: for all Sun platforms, CPP defines the symbol "sun". Multiple machine architectures support the Sun platform, and CPP defines a different unique symbol for each of them. This is illustrated by an excerpt from arch.c: #ifdef sun #undef sun #define SunArchitecture #ifdef mc68020 #undef SUN3 #undef sun3 #define MachineDep SUN3 #define machinedep sun3 #endif #ifdef sparc #undef SUN4 #undef sun4 #define MachineDep SUN4 #define machinedep sun4 #endif #define MacroIncludeFile #define MacroFile sun.cf #endif When generating machine-dependent Makefiles, configuration parameters are determined by the value of "MachineDep". You can use "machinedep" (which defines a lower-case string) to generate file or directory names in your Imakefiles. For example, builds might be executed in subdirectories named "sun3" and "sun4". Imake.tmpl uses MacroIncludeFile to include the .cf file for the platform. You can use "#ifdef SunArchitecture" in Imakefiles to obtain platform-specific rules for the Sun platform. BUILD PARAMETERS ---------------- Imake handles differences between operating systems by using platform-specific .cf files to set various build parameters. The easiest way to create a new .cf file is to: * find a .cf file similar to yours or start with generic.cf. * set the SystemV parameter if your OS is based on SVR2. * set the OSName, OSMajorVersion, and OSMinorVersion parameters. * look at the other .cf files, Imake.tmpl, and proj.tmpl to see if there are any variables you'd like to set. Common ones include: HasSockets, HasVFork, HasVoidSignalReturn, HasBsearch, HasPutenv, etc. Even if you don't need to write a new .cf file, you should inspect the .cf file and correct the major and minor version numbers for your operating system if necessary. You can predefine any parameter by including an appropriate definition in the .cf file. You can also predefine parameters in local.def. If Imake.tmpl finds any undefined parameters after including the .cf file and local.def, it provides default values for them. You can predefine the following parameters: SystemV whether or not based on SVR2 OSMajorVersion major version number of OS OSMinorVersion minor version number of OS UnalignedReferencesAllowed whether or not arbitrary addresses may be deref ExecableScripts whether or not scripts with #! may be exec'ed BourneShell full pathname of Bourne shell ConstructMFLAGS whether or not to do MFLAGS with MAKEFLAGS HasLargeTmp whether or not /tmp has over 1meg of space HasSockets whether or not system has bsd sockets HasVFork whether or not libc has vfork() HasPutenv whether or not libc has putenv() HasVoidSignalReturn whether or not signal() proc is type void HasBsearch whether or not libc has bsearch() HasCfront whether or not system has cfront translator CompileInMachineDepSubdir whether or not to segregate .o files in subdirs StripInstalledPrograms whether or not to strip installed programs RemoveAfterInstall whether or not to remove a.out after install OptimizedCDebugFlags C compiler flags to turn on optimizer DebuggableCDebugFlags C compiler flags to turn on debugger NoOpCDebugFlags C compiler default flags DefaultCDebugFlags one of previous 3 for compiling programs LibraryCDebugFlags one of previous 3 for compiling libraries InstPgmFlags install options for stripping installed pgms InstBinFlags install modes for program binaries InstUidFlags install modes for setuid programs (xterm) InstLibFlags install modes for libraries InstIncFlags install modes for includes InstManFlags install modes for manual pages InstDatFlags install modes for data files InstKmemFlags install modes for setgid kmem programs (xload) AfterInstallCmd command to remove a.out after it's installed ArCmd command to create and add to libraries BootstrapCFlags initial -Dmacro for systems that don't have 'em BootstrapCpuCmd command to identify this machine's cpu type CcCmd command to run C compiler CplusplusCcCmd command to run C++ compiler CppCmd command to run C preprocessor PreProcessCmd command to run cpp with C default defines DependCmd command to run makedepend DependCFlags default makedepend options GenclassCmd command to run genclass ImakeCmd command to run imake ImakeOpts default imake options InstallCmd command to do bsd-style install LdCmd command to run loader CplusplusLdCmd command to run loader for C++ programs LintCmd command to run linter LintLibFlag flag to tell lint to create a library LintOpts default lint options CpCmd command to copy a file LnCmd command to soft link (if possible) a file MakeCmd command to make from Makefile MkdirhierCmd command to create directory hierarchies MvCmd command to rename a file RanlibCmd command to run after creating a library RanlibInstFlags special flags to ranlib for installed libs RmCmd command to remove a file TagsCmd command to generate C tags TroffCmd command to format a nroff/troff file on stdout StandardCppDefines defines for cpp'ing scripts StandardIncludes includes for C compiler StandardDefines defines and flags for C compiler ExtraLibraries special libraries at end of load line ExtraLoadFlags special flags for load lines SrcDir where C or C++ files are wrt .o files GenDir where template-generated files are wrt .o files WindowSystem window system to build InterViews for (X10/X11) InstallRelative whether or not to install in $(TOP)/installed DestDir path for parent dir of all following paths BinDir path for installed window sys-dep programs LocalBinDir path for installed window sys-indep programs IncRoot path for parent dir of InterViews includes dir IncDir path for installed InterViews includes UsrLibDir path for installed libraries XConfigDir path for installed platform .cf files ConfigDir path for installed config files ManSuffix suffix for program man pages LibManSuffix suffix for library man pages ManDir path for installed program man pages LibmanDir path for installed library man pages RelativeBinDir rel. path for installed window sys-dep programs RelativeLocalBinDir rel. path for installed window sys-ind programs RelativeIncDir rel. path for installed InterViews includes RelativeUsrLibDir rel. path for installed libraries RelativeConfigDir rel. path for installed config files RelativeManDir rel. path for installed man pages InstallPlatformCfFiles whether or not to install platform .cf files LOCAL SITE-SPECIFIC DEFINITIONS FILE ------------------------------------ You can use local.def to set build parameters across all platforms at your site. You should nest #defines inside #ifndef..#endif pairs so platform-specific .cf files can still override local.def. IMAKEFILES ---------- Individual Imakefiles may use any of the macros defined in rules.def. Some of these rules use make variables that the Imakefile sometimes must define itself. For example, many rules used for compiling source modules reference $(CC). These rules can be used for both C programs and C++ programs by changing the value of a make variable or two. An Imakefile for C programs might include: CC = CcCmd whereas an Imakefile for C++ programs might include: CC = CplusplusCcCmd When Imake is run, it substitutes the value of the relevant CPP macro, resulting in a "normal" make variable definition, for example: CC = /bin/cc or CC = /bin/CC Other such variables include: CDEBUGFLAGS Optimization? Debugging symbols? LOCAL_LIBRARIES Names of libraries to be linked with SYS_LIBRARIES system libraries to be linked; e.g. "-lm" SRCS files to be read by makedepend; $(SRC)//* OBJS .o files to be loaded together GENERATING MAKEFILES FROM IMAKEFILES ------------------------------------ You have to run Imake to make a Makefile from an Imakefile the very first time. (Along with the template and definitions files, a script which invokes imake is available to help with this step.) If you ever need to regenerate a particular Makefile again, say because you edited the Imakefile or you edited one of the configuration files, just type "make Makefile". If you want to regenerate the Makefiles in that directory's subdirectories as well, type "make Makefiles". (Generated Makefile have rules for regenerating themselves.) If you are using "make depend", note that regenerating a Makefile throws away its automatically generated dependencies, so you should always follow "make Makefile" or "make Makefiles" with "make depend".