add information about make variables that can be set in an Imakefile

and add lots of general advice about writing an Imakefile.

1 files changed, 227 insertions, 1 deletions

diff --git a/xc/config/cf/README b/xc/config/cf/README
index 91ff6b62f..a7fc87f8f 100644
--- a/xc/config/cf/README
+++ b/xc/config/cf/README
@@ -1,4 +1,4 @@
-$XConsortium: README,v 1.40 95/02/09 22:53:12 gildea Exp matt $
+$XConsortium: README,v 1.41 95/05/23 21:38:11 matt Exp gildea $
 
 The easiest way to write an Imakefile is to find another one that does
 something similar and copy/modify it!
@@ -376,3 +376,229 @@ The following variables are used by some part of the tree:
 	HasShadowPasswd		system has getspnam() function
 	XnestServer		build X server with Xlib-based ddx
 	XVirtualFramebufferServer	build X server with virtual memory framebuffer
+
+
+Make Variables
+
+The following make variables are used by imake rules and may be set in
+an individual Imakefile.
+
+DEFINES			program-specific -D flags and other arguments
+			to pass to the C compiler, lint, and makedepend.
+DEPEND_DEFINES		program-specific flags in addition to
+			$(DEFINES) to pass to lint and makedepend.
+			This is usually used when there are special
+			compilation rules for individual files, and
+			the defines passed to those files affect
+			makedepend results.  If they can be passed to
+			all files during the makedepend step without
+			affecting the results for other files,
+			DEPEND_DEFINES is used to do that.  Example is
+			the Xlib Imakefile.
+INCLUDES		program-specific -I flags.
+HEADERS			.h files to install with "make includes" and
+			"make install".  If this Imakefile includes
+			Library.tmpl there are no headers, include
+			this line instead of a HEADERS definition:
+			#define LibHeaders NO
+REQUIREDLIBS		when building a shared library, other libraries used
+			by this library that should be referenced at
+			link time.
+LINTLIBS		program-specific libraries for lint.
+LOCAL_LDFLAGS		program-specific flags for the linker.
+LOCAL_LIBRARIES		project libraries (usually specified
+			as -lname) needed by this program.
+			For example, "-lXt -lXext -lX11".
+			Used by SimpleProgramTarget and
+			ComplexProgramTarget* rules.
+			Do not include any system-specific libraries here.
+SYS_LIBRARIES		system libraries (usually specified
+			as -lname) needed by this program.
+			For example "MathLibrary".
+			Do not include any system-specific libraries
+			such as "-lnsl" here; they are automatically
+			added to the link command by the
+			vendor-specific .cf file.
+SUBDIRS			for an Imakefile in a directory containing
+			subdirectories, this names the subdirectories.
+			Such an Imakefile also needs to #define IHaveSubdirs
+			and call MakeSubdirs() and DependSubdirs().
+MANSUFFIX		suffix used by InstallManPage* rules.
+			May be set to $(LIBMANSUFFIX) or $(FILEMANSUFFIX) in
+			directories for libraries or data files.
+
+
+Rule-specific variables that may be set in an individual Imakefile.
+If you aren't using these rules, you may need variables with a similar
+function, but you need not use these names.  However, following these
+conventions may make your Imakefile easier to read and maintain.
+
+DEPLIBS			library dependencies for ComplexProgramTarget
+SRCS			source files used by ComplexProgramTarget and
+			DependTarget.
+OBJS			object files used by ComplexProgramTarget
+PROGRAMS		default target used with ComplexProgramTarget_(n)
+SRCS1			source files used by ComplexProgramTarget_1
+OBJS1			object files used by ComplexProgramTarget_1
+DEPLIBS1		library dependencies for ComplexProgramTarget_1
+SRCS2			source files used by ComplexProgramTarget_2
+OBJS2			object files used by ComplexProgramTarget_2
+DEPLIBS2		library dependencies for ComplexProgramTarget_2
+SRCS3			source files used by ComplexProgramTarget_3
+OBJS3			object files used by ComplexProgramTarget_3
+DEPLIBS3		library dependencies for ComplexProgramTarget_3
+
+Variables that can be set on the make command line:
+
+DESTDIR			directory under which "make install" should
+			install instead of "/"; used only for testing
+			"make install" rules.
+FILE			file for "lint1" target to run lint on.
+CDEBUGFLAGS		-g and/or -O flag to control C compiler optimization.
+CXXDEBUGFLAGS		-g and/or -O flag to control C++ optimization.
+LDSTRIPFLAGS		flag to have linker strip objects (typically -x).
+			Typically set to the empty string to prevent
+			the linker from stripping objects; use this
+			way when setting CDEBUGFLAGS to "-g".
+
+These variables are set in project-specific files such as Project.tmpl.
+They should NOT be set in an Imakefile.  These variables are sometimes
+misused; they are included here to remind Imakefile writers NOT to use
+them:
+
+EXTRA_DEFINES		project-specific -D flags
+EXTRA_INCLUDES		project-specific -I flags
+EXTRA_IXFLAGS		project-specific flags for ixx interface translator
+EXTRA_ICONFIGFILES	Additional project-specific imake config files
+			to add to ICONFIGFILES.
+			This is a list of files that define variables
+			that might affect compilation of some files.
+
+Many other make variables are set up by the imake config files and can
+be used in an Imakefile.  The easiest way to discover them is to look
+at the Makefile generated by an empty Imakefile.
+
+
+Comments
+
+Use C comment syntax in an Imakefile for comments that should not
+appear in the resulting Makefile.
+Use "XCOMM" at the start of each
+line to produce a comment that will appear in the Makefile.
+(The "XCOMM" will
+be translated into the Makefile comment character "#" by imake.)
+Do NOT use "#" as a comment character in Imakefiles; it confuses the C
+preprocessor used by imake on some systems.
+
+
+Imake variables
+
+Don't abuse the variables in Project.tmpl that describe
+particular pieces of X by using them to describe your own subsystems.
+Instead, create new variables that are defaulted using
+Imake.tmpl variables.
+
+
+Examples
+
+Since the easiest way to write an Imakefile is to start with one that
+works, here are some short, easy-to-read Imakefile examples in the X
+distribution:
+
+with subdirs:	config/Imakefile
+library:	lib/Xau/Imakefile
+simple program: programs/xdpyinfo/Imakefile
+complex progs:  programs/xclipboard/Imakefile
+complex prog:	programs/xmodmap/Imakefile
+
+Common Rules
+
+Here are some of the common rules for building programs.  How to use
+them is described in Imake.rules and in the O'Reilly book "Software
+Portability with imake."
+
+Basic program-building rules
+
+All of these except NormalProgramTarget also generate rules to install
+the program and its manual page, and to generate dependencies.
+
+SimpleProgramTarget	Use if there is only one program to be made
+			and it has only one source file.
+
+ComplexProgramTarget	Use if there is only one program to be made
+			and it has multiple source files.  Set SRCS to
+			the names of the source files, set OBJS to
+			the names of the object files, and set DEPLIBS
+			to the libraries that this program depends on.
+
+ComplexProgramTarget_1	Like ComplexProgramTarget, but uses SRCS1,
+			OBJS1, and DEPLIBS1 and can be used with
+			ComplexProgramTarget_2 and ComplexProgramTarget_3
+			to build up to three programs in the same directory.
+			Set PROGRAMS to the programs built by all of
+			these rules.  For more than 3 programs, use
+			NormalProgramTarget for each.
+ComplexProgramTarget_2	Use after ComplexProgramTarget_1 for the
+			second program in a directory.  Uses SRCS2,
+			OBJS2, and DEPLIBS2.
+ComplexProgramTarget_3	Use after ComplexProgramTarget_2 for the
+			third program in a directory.  Uses SRCS3,
+			OBJS3, and DEPLIBS3.
+
+NormalProgramTarget	Build a program.  Can be used multiple times
+			with different arguments in the same Imakefile.
+
+Lower level rules, often used with NormalProgramTarget
+
+InstallProgram		install a program.
+
+InstallManPage		install a manual page.
+
+DependTarget()		include once at end of Imakefile with
+			NormalProgramTarget rules.  Generates
+			dependencies for files named in SRCS.
+
+Manual page rules, commonly used only in special documentation directories:
+
+InstallManPage
+InstallManPageLong
+InstallManPageAliases
+
+Other rules:
+
+SpecialCObjectRule	Compile a C file with special flags.
+AllTarget		Declare additional targets to build.
+InstallAppDefaults	Install X application defaults file.
+
+Imakefile for directory with subdirectories
+
+XCOMM this is a sample Imakefile for a directory containing subdirectories
+#define IHaveSubdirs
+#define PassCDebugFlags CDEBUGFLAGS="$(CDEBUGFLAGS)"
+SUBDIRS = list of subdirs ...
+MakeSubdirs($(SUBDIRS))
+DependSubdirs($(SUBDIRS))
+
+
+Common Targets
+
+These targets are typically NOT defined explicitly by the Imakefile
+writer; rather they are generated automatically by imake rules.
+They are listed here for the convenience of people using the resulting
+Makefile, not people writing the original Imakefile.
+
+all			Default rule; builds whatever is in this directory.
+Makefile		Remake the Makefile (use after changing Imakefile).
+			Run "make depend" after.
+Makefiles		Remake all Makefiles in subdirectories.  (Does
+			nothing if no subdirectories.
+			Run "make depend" after.
+includes		Generate and install in the tree any necessary
+			header files.
+depend			Update dependencies in the Makefile calculated
+			by examining the source files.
+install			Install what "make all" built on the system.
+install.man		Install manual pages.
+clean			Remove built objects and other derived files.
+lint			Run lint.
+tags			Create a tags file.