config_maintain.html

Revision 415, 33.4 kB (checked in by patrick, 10 years ago)
Get this file in sync with reality. This includes describing the files in the juggler/mk directory, the use of GNU make and the overhaul of the build system I did a few months ago.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`

Line
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
2
3	<!-- $Id$ -->
4
5	<HEAD>
6	<TITLE>Maintaining and updating configure.in and Makefile.in</TITLE>
7	</HEAD>
8
9	<BODY BGCOLOR="#ffffff">
10
11	<DIV ALIGN="CENTER">
12	<H1>Working with <TT>configure.in</TT> and <TT>Makefile.in</TT></H1>
13	</DIV>
14
15	<HR WIDTH="80%" NOSHADE>
16
17	<H2>Basics</H2>
18
19	<DL>
20	<DT><B>Comments in <TT>configure.in</TT></B>
21	<DD>
22	<P>
23
24	Two types of comments can be used in <TT>configure.in</TT>. The first
25	is the relatively standard ``<TT>#</TT>'' comment. Lines beginning
26	with this character are copied into the final <I>configure</I> script
27	generated by <I>autoconf</I>(1). The other type is the <I>m4</I>(1)
28	comment. Lines commented in this way begin with ``<TT>dnl</TT>'' and
29	are <I>not</I> copied into the <I>configure</I> script.
30
31	<P>
32	<DT><B>Language used in <TT>configure.in</TT></B>
33	<DD>
34	<P>
35
36	The scripting language used in <TT>configure.in</TT> is <I>sh</I>(1).
37	All conditional statements must use the form:
38
39	<PRE>
40	if test "$some_var" = "some_val" ; then
41	...
42	fi
43	</PRE>
44
45	rather than:
46
47	<PRE>
48	if [ "$some_var" = "some_val" ] ; then
49	...
50	fi
51	</PRE>
52
53	The brackets are recognized as special characters by <I>m4</I>(1) and
54	may not be copied into <I>configure</I> properly.
55
56	<P>
57	<DT><B>Variable naming</B>
58	<DD>
59	<P>
60
61	When naming variables in <TT>configure.in</TT>, be sure to follow the
62	following conventions:
63
64	<P>
65
66	<UL>
67	<LI>Names for variables that will be set externally (primarily by
68	command-line options such as <TT>--enable-debug</TT>) and not
69	substituted into generated files at the end of execution are
70	named in all lower-case letters. All other variables are named
71	in all upper-case letters.
72	<LI>Variables that are not substituted into generated files at the
73	end of the <TT>configure</TT> script's execution begin with an
74	underscore (`<TT>_</TT>') to imply that they are internal to the
75	script. When referring to these variables, enclose the name in
76	curly braces to fully clarify it. For example:
77
78	<PRE>
79	_SOME_INTERNAL_VAR='Some value'
80
81	[...]
82
83	if test [ "${_SOME_INTERNAL_VAR}" = "Some value" ; then
84	[...]
85	fi
86	</PRE>
87	<LI>Variables used to preserve an existing variable's value in case
88	it should need to be reset are named and used as follows:
89
90	<PRE>
91	_vjsave_<I>VARIABLE</I>="$<I>VARIABLE</I>"
92
93	[...]
94
95	if test <B>Old value needs to be restored</B> ; then
96	$<I>VARIABLE</I>="$_vjsave_<I>VARIABLE</I>"
97	fi
98	</PRE>
99	</UL>
100
101	<P>
102	<DT><B>Multi-line parameters to Autoconf macros</B>
103	<DD>
104	<P>
105
106	Parameters spanning multiple lines may be passed to Autoconf macros
107	without using backslashes through a special block recognized by
108	<I>m4</I>(1). Simply enclose the parameter in <TT>[]</TT>'s and it
109	will be parsed as one parameter. Remember to be careful about the use
110	of semi-colons for separating <I>sh</I>(1) statements within these
111	blocks.
112
113	<P>
114	<DT><B>Custom preprocessor information</B>
115	<DD>
116	<P>
117
118	Anything that defines preprocessor macros other than those generated
119	by the Autoconf macros must be defined in <TT>acconfig.h</TT>. If they
120	are not defined in this file, <I>autoheader</I>(1) will complain as it
121	parses <TT>configure.in</TT> and finds these customizations. Follow
122	the existing syntax and layout of <TT>acconfig.h</TT> when making
123	additions to it. In general, additions only have to be made when a new
124	<I>AC_DEFINE</I>, <I>AC_CHECK_TYPE</I>, etc. line is added to
125	<TT>configure.in</TT>.
126
127	<P>
128	<DT><B>Including a common, external <TT>Makefile</TT></B>
129	<DD>
130	<P>
131
132	Due to inconsistencies in the way various operating systems implement
133	some sort of ``include'' directive in their <I>make</I>(1), there is no
134	easy method for including a common, external <TT>Makefile</TT>
135	containing variable assignments common to all <TT>Makefile</TT>s in the
136	source tree such that it would be platform independent. To solve this
137	problem, GNU's version of <I>make</I>(1) is used for compiling VR
138	Juggler.
139	</DL>
140
141	<HR WIDTH="80%" NOSHADE>
142	<P>
143
144	<H2>Layout of <TT>configure.in</TT></H2>
145
146	<DL>
147	<DT><B>Initialization</B>
148	<DD>
149	<P>
150
151	The first short block of <TT>configure.in</TT> performs some very basic
152	initialization tasks. The RCS revision number of the script is
153	maintained here so that the user can verify that s/he has the most
154	recent version of the actual <I>configure</I> script. A check for one
155	file in the source tree is also made to perform a very general, inexact
156	verification that things are where they are supposed to be. Currently,
157	<I>configure</I> will check for the existence of
158	<TT>Config/vjChunkDesc.cpp</TT>. Finally, the header file created when
159	done with the configuration process is named. This file is called
160	<TT>vjDefines.h</TT>.
161
162	<P>
163	<DT><B>Custom arguments</B>
164	<DD>
165	<P>
166
167	In this block, the custom arguments for the <I>configure</I> script are
168	defined. The first set defines the
169	<TT>--with-<I>package</I>[=<I>arg</I>]</TT> and
170	<TT>--without-<I>package</I></TT> arguments. These are intended to be
171	used for choosing some external software package to use at compile
172	time. They are also used for providing a small level of customization
173	to how the external software is found and/or used.
174
175	<P>
176
177	The second set define the <TT>--enable-<I>feature</I>[=<I>arg</I>]</TT>
178	and <TT>--disable-<I>feature</I></TT> arguments that allow the user
179	to choose which optional features can be built. From the
180	<A HREF="http://www.icemt.iastate.edu/~patrick/autoconf/">Autoconf 2.12
181	documentation</A>, ``These options should never make a feature behave
182	differently or cause one feature to replace another.''
183
184	<P>
185
186	For both sets of options, the <I>AC_ARG_WITH</I> and
187	<I>AC_ARG_ENABLE</I> macros behave the same way. The first argument is
188	the package/feature, the second is the description printed when the
189	user runs <I>configure</I> with the ``<TT>--help</TT>'' option. The
190	third argument sets a user-defined variable in the script to the
191	contents of <TT>$withval</TT> or <TT>$enableval</TT> respectively. If
192	no argument is given (e.g., the user specified
193	``<TT>--enable-opengl</TT>''), the variable will get either ``yes'' or
194	``no'' as its value depending upon whether the user used the positive
195	or negative form of the argument.
196
197	<P>
198
199	After the custom arguments are defined, some of the values that may be
200	read are processed. In particular, the application binary interface
201	(ABI) under which VR Juggler will be compiled is defined. This is
202	done prior to the system-dependent section to reduce duplicated code
203	even though the ABI is highly dependent upon the operating system and
204	underlying computer architecture.
205
206	<P>
207	<DT><B>System-dependent setup</B>
208	<DD>
209	<P>
210
211	Here, a common set of script variables are given values that are
212	usually dependent upon the system on which the script is being run.
213	The new variables used are all set to have no value before the
214	conditional <TT>case</TT> block begins. The subsequent conditional
215	block compares the value in <TT>$host</TT> (obtained from the
216	<I>AC_CANONICAL_HOST</I> macro) with known systems and sets values for
217	the variables appropriately.
218
219	<P>
220
221	Some existing variables are modified here as well. These include
222	<TT>$CFLAGS</TT>, <TT>$CXXFLAGS</TT> and <TT>$INCLUDES</TT>. Each of
223	these could have been set as part of the user's environment variables
224	or previously in the script as part of executing a macro. Thus, they
225	should be treated carefully so as not to destroy any existing values
226	that may be stored in them.
227
228	<P>
229
230	Besides setting values in variables, custom pre-processor macros are
231	defined here using the <I>AC_DEFINE</I> macro. This macro takes two
232	parameters:
233
234	<P>
235
236	<OL>
237	<LI>The name of the macro to define.
238	<LI>The value to which the macro is set by the pre-processor.
239	</OL>
240
241	<P>
242
243	To do something similar to:
244
245	<PRE>
246	#define VJ_DEF
247	</PRE>
248
249	use the following syntax:
250
251	<PRE>
252	AC_DEFINE(VJ_DEF,)
253	</PRE>
254
255	Defining macros that take parameters cannot be done with
256	<I>AC_DEFINE</I>. However, based on a check made for something (such
257	as <I>sginap</I>(2)), such a macro can be defined at the bottom of
258	<TT>acconfig.h</TT>. Refer to this file to see how a macro for
259	<I>sginap</I>() is defined using <I>usleep</I>(2) in this manner.
260
261	<P>
262	<DT><B>External program checks</B>
263	<DD>
264	<P>
265
266	This block is for standard program checks that <I>configure</I> does
267	to ensure that software needed for compiling the package works. Using
268	the values in several preset variables (including <TT>$CC</TT> for the
269	C compiler and <TT>$CXX</TT> for the C++ compiler), it runs tests on
270	the software and reports any problems it finds.
271
272	<P>
273	<DT><B>External library checks</B>
274	<DD>
275	<P>
276
277	Checks for needed external libraries are made here. In this
278	<I>configure</I> script, a great deal of processing is done in order
279	to ensure that the source can be properly compiled and linked using
280	certain external libraries. The basic process of checking for a
281	library (say, the OpenGL library) involves first checking to see if
282	the library can be linked, and if so, a check is then made for a
283	standard header file associated with the library (in this case,
284	<TT>GL/gl.h</TT>). In some cases, if a library cannot be found, a
285	fallback check is provided. In the case of the POSIX threads library,
286	an attempt to link against <TT>libpthread</TT> is made. If that fails
287	(as it will on HP-UX 10.20), a check is made to link against
288	<TT>libcma</TT>.
289
290	<P>
291
292	Upon successfully finding a library and a needed header file, several
293	variables are usually set that are used later in the Makefile
294	generation phase. If a library is not found, the script may simply
295	issue a warning about the problem or it may exit altogether if the
296	library's existence is crucial to the compiling process.
297
298	<P>
299
300	Adding new library checks can be complicated. The best method is to
301	refer to the
302	<A HREF="http://www.icemt.iastate.edu/~patrick/autoconf/">Autoconf 2.12
303	documentation</A> and the existing checks. All follow basically the
304	same structure.
305
306	<P>
307	<DT><B>Header file checks</B>
308	<DD>
309	<P>
310
311	Checks for standard header files and user-specified header files are
312	made here. The user-specified list is a space-separated list of
313	header files that may not exist on all systems. If a header file is
314	found, <TT>HAVE_<I>FILENAME</I>_H</TT> is defined in
315	<TT>vjDefines.h</TT> when it is generated.
316
317	<P>
318	<DT><B><TT>typedef</TT>, <TT>struct</TT> and compiler characteristic
319	checks</B>
320	<DD>
321	<P>
322
323	Here, checks are made to determine if the host system has various
324	types and structures defined or not. There are a few existing macros
325	that check for specific examples of these, and it is possible to have
326	user-defined checks. Currently, little is done in this block, and in
327	fact the only user-specified check is to see if the host system has
328	<TT>u_int</TT> defined. If not, it defines it (via the preprocessor,
329	not <TT><B>typedef</B></TT>) to be <TT>unsigned int</TT> through the
330	<I>AC_CHECK_TYPE</I> macro. To check for <TT>struct</TT>s, use
331	<I>AC_TRY_COMPILE</I> or <I>AC_EGREP_CPP</I>. Refer to the Autoconf
332	2.12 documentation section titled
333	``<A HREF="http://www.icemt.iastate.edu/~patrick/autoconf/autoconf_4.html#SEC21">Existing
334	Tests</A>'' for more detailed information.
335
336	<P>
337	<DT><B>Library function checks</B>
338	<DD>
339	<P>
340
341	Here, checks are made for any library and system functions (e.g.,
342	<I>gettimeofday</I>(2), <I>socket</I>(2), <I>sginap</I>(2)) that may
343	not exist on all systems. As with other sections, the user-specified
344	list of functions to check is the space-separated parameter passed to
345	the <I>AC_CHECK_FUNCS</I> macro. If found, <TT>HAVE_<I>FUNCNAME</I></TT>
346	will be defined in <TT>vjDefines.h</TT>.
347
348	<P>
349	<DT><B>Makefile substitution</B>
350	<DD>
351	<P>
352
353	Within this block of <TT>configure.in</TT>, special symbols in the
354	<TT>Makefile.in</TT> files are slated for replacement with variable
355	values. This is done through the <I>AC_SUBST</I> macro, and it simply
356	replaces a ``tag'' in a <TT>Makefile.in</TT> with the value stored in
357	the corresponding <I>configure</I> script variable. The following
358	example illustrates what happens during the file generation phase
359	(discussed next).
360
361	Say that some <TT>Makefile.in</TT> contains the following line:
362
363	<PRE>
364	CUSTOM_VAR = @CUSTOM_VAR@
365	</PRE>
366
367	The string enclosed by <TT>@</TT>'s is the tag that will be replaced
368	when <TT>Makefile</TT> is generated. In <TT>configure.in</TT>, there
369	following line must be present:
370
371	<PRE>
372	AC_SUBST(CUSTOM_VAR)
373	</PRE>
374
375	Note that the variable is not prepended by a `<TT>$</TT>' because
376	variable interpolation should not be done here. Of course,
377	<TT>$CUSTOM_VAR</TT> will generally have had some value set prior to
378	this point. That is not required however.
379
380	<P>
381
382	It is in this phase of configuration that most of the system-dependent
383	build work is done. This is similar to what Imake template files do.
384	Virtually everything preceding this point set variables to have values
385	appropriate to the host machine, and now they are put into the
386	<TT>Makefile</TT>s to be used for compiling the code. There are
387	several pre-defined variables that <I>configure</I> will substitute in
388	the input template files. Refer to the section titled
389	``<A HREF="http://www.icemt.iastate.edu/~patrick/autoconf/autoconf_3.html#SEC12">Preset
390	Output Variables</A>'' in the Autuconf 2.12 documentation for a list
391	of these.
392
393	<P>
394	<DT><B>File generation</B>
395	<DD>
396	<P>
397
398	In this last block, file generation is performed using the
399	<I>AC_OUTPUT</I> macro. It iterates through its space-separated list
400	of files and finds the associated <TT>.in</TT> template file. In
401	general, this step is only used for generating Makefiles
402	(<TT>vjDefines.h</TT> is defined automatically due to the
403	<I>AC_CONFIG_HEADER</I> call at the top of <TT>configure.in</TT>).
404	When a new directory and corresponding <TT>Makefile.in</TT> are added
405	to the source tree, an entry for it must be added to this list.
406	</DL>
407
408	<HR WIDTH="80%" NOSHADE>
409	<P>
410
411	<H2>Global Files for <I>make</I>(1)</H2>
412
413	<DL>
414	<DT><B><TT>mk/*.mk</TT> files</B>
415	<DD>
416	<P>
417
418	These files provide (typically) simple targets that may be included
419	by other <TT>Makefile</TT>s. The available files are:
420
421	<P>
422
423	<UL>
424	<LI><B><TT>vj.clean.mk</TT></B>: This provides a `<TT>clean</TT>'
425	target. The including file should add files to the variable
426	<TT>${CLEAN_FILES}</TT> using the <TT>+=</TT> assignment
427	operator. For example,
428
429	<PRE>
430	CLEAN_FILES += file1.o file2.o
431	</PRE>
432
433	The <TT>+=</TT> operator is used because a default value for
434	<TT>${CLEAN_FILES}</TT> is defined in this file, and thus the
435	addition of files to the list should be done <I>after</I>
436	including <TT>vj.clean.mk</TT>.
437
438	<P>
439
440	The including file may also have a local target for doing
441	specialized cleanup. To do this, set the variable
442	<TT>${_LOCAL_CLEAN}</TT> to some dummy value <I>before</I>
443	including <TT>vj.clean.mk</TT>. Then make a target in the
444	including <TT>Makefile</TT> called `<TT>_clean</TT>' that suits
445	the meets the given requirements for cleaning up.
446
447	<P>
448
449	<B>NOTE</B>: This file is included by the top-level file
450	<TT>Makefile.base</TT> and thus should not be directly included
451	by any files that include <TT>Makefile.base</TT>.
452	<LI><B><TT>vj.compile.mk</TT></B>: Suffix rules for compiling source
453	code are defined here. Currently, rules are given for building
454	object files from <TT>.c</TT>, <TT>.cpp</TT> and <TT>.C</TT>
455	source files. The file that includes this file must define
456	values for the following variables:
457
458	<UL>
459	<LI><TT>${OBJDIR}</TT>: Where the object file is to be built).
460	<LI><TT>${C_COMPILE}</TT>: The C compiler command line without
461	the <TT>-c</TT> or <TT>-o</TT> options.
462	<LI><TT>${CXX_COMPILE}</TT>: The C++ compiler command line again
463	without the <TT>-c</TT> or <TT>-o</TT> options).
464	</UL>
465
466	These variables are defined in the top-level file
467	<TT>Makefile.base</TT>.
468	<LI><B><TT>vj.dep.mk</TT></B>: Targets for building source file
469	dependencies are defined here. The targets are `<TT>depend</TT>'
470	for building the dependencies and `<TT>newdepend</TT>' for
471	rebuilding the dependencies. Those files including this one
472	must define the following variables:
473
474	<UL>
475	<LI><TT>${srcdir}</TT>: The directory where the source file(s)
476	is/are located.
477	<LI><TT>${DEPENDFLAGS}</TT>: Flags to pass to
478	<I>makedepend</I>(1), the program used to generate the
479	dependencies.
480	<LI><TT>${DEPEND_EXTRAS}</TT>: Extra flags that may not be
481	recognized by <I>makedepend</I>(1) because they may be
482	specific to a given compiler. Any recognized options will
483	be processed normally while any unrecognized options will
484	be silently ignored. Thus, this variable could be set to
485	<TT>${CLFAGS}</TT> to allow compiler options necessary for
486	the source to compile to be passed to <I>makedepend</I>(1).
487	<LI><TT>${DEPEND_SRCS}</TT>: The list of source files to be
488	processed.
489	<LI><TT>${OBJDIR}</TT>: The directory to which the compiled
490	object file(s) will be written.
491	<LI><TT>${WORKDIR}</TT>: The working directory (not necessarily
492	where the source files are found).
493	</UL>
494
495	Optionally, the following variables may also be defined:
496
497	<UL>
498	<LI><TT>${DEPEND_DEPS}</TT>: Dependencies for the
499	`<TT>depend</TT>' target.
500	<LI><TT>${NEWDEPEND_DEPS}</TT>: Dependencies for the
501	`<TT>newdepend</TT>' target.
502	</UL>
503	<LI><B><TT>vj.install.mk</TT></B>: This file adds an `<TT>install</TT>'
504	target to the including <TT>Makefile</TT>. The file including
505	this must define the <TT>${INSTALL}</TT> variable (the path to a
506	BSD-compatible <I>install</I>(1) program).
507
508	<P>
509
510	The including <TT>Makefile</TT> has the option to specifically
511	list what files should be installed or to use the default list
512	(<TT>${srcdir}/*.h</TT>). To provide a list, a value for the
513	variable <TT>${INSTALL_FILES}</TT> must be set. If choosing to
514	use the default list, a value for the <TT>${srcdir}</TT> variable
515	(the directory where the source file(s) is/are located) must be
516	defined.
517
518	<P>
519
520	The including <TT>Makefile</TT> also has the option to
521	specifically list where the files should be installed or to use
522	the default location. To specify a location, a value for the
523	variable <TT>${INSTALL_PATH}</TT> must be set. Otherwise, to
524	use the default, a value for the variable <TT>${includedir}</TT>
525	must be set.
526	<LI><B><TT>vj.lib.mk</TT></B>: Compiling of libraries, both static
527	and shared, is handled by this file. To compile a static library,
528	the target `<TT>static-lib</TT>' is provided; to compile a shared
529	library, the target `<TT>shared-lib</TT>' is provided. The
530	including <TT>Makefile</TT> must define the following variables:
531
532	<UL>
533	<LI><TT>${AR}</TT>: The path to <I>ar</I>(1) (or equivalent
534	program).
535	<LI><TT>${LD}</TT>: The path to <I>ld</I>(1) (or equivalent
536	program).
537	<LI><TT>${LDOPTS}</TT>: Extra, often platform-specific, options
538	for the linker (<TT>${LD}</TT>).
539	<LI><TT>${LIBDIR}</TT>: The directory where the library will
540	be made.
541	<LI><TT>${LIBNAME}</TT>: The name of the library to generate.
542	<LI><TT>${OBJS}</TT>: The object files to be compiled into the
543	library.
544	</UL>
545	<LI><B><TT>vj.rec.mk</TT></B>: This file provides a method for
546	building recursive targets through the `<TT>recursive</TT>'
547	target. The file including this should define the following
548	variables:
549
550	<UL>
551	<LI><TT>${BASE_OBJDIR}</TT>: The directory to which the object
552	file(s) is, are or will be located.
553	<LI><TT>${DIRPRFX}</TT>: The prefix directory (if any) of the
554	directories listed in <TT>${SUBDIRS}</TT>.
555	<LI><TT>${OPTIMIZER}</TT>: Optimizer flag(s) for the compiler.
556	<LI><TT>${RECTARGET}</TT>: The name of the recursive target to
557	build as it is named in the <TT>Makefile</TT>s over which
558	the recursion will be performed.
559	<LI><TT>${SUBDIRS}</TT>: The subdirectories over which the
560	recursion will be done.
561	</UL>
562
563	To build a recursive target, say `<TT>dbg</TT>', the following
564	call to this target will give the desired results:
565
566	<PRE>
567	SUBDIRS = Src1 Src2 Src3
568
569	dbg:
570	${MAKE} RECTARGET="$@" OPTIMIZER="-g" BASE_OBJDIR="obj/debug" recursive
571	</PRE>
572	</UL>
573
574	Be careful to define variables and targets at the right time with
575	regard to when the <TT>.mk</TT> file is included. Unless otherwise
576	specified, this should be done <I>before</I> including the <TT>.mk</TT>
577	file.
578
579	<P>
580	<DT><B><TT>Makefile.base</TT></B>
581	<DD>
582	<P>
583
584	Variables that are common to most, if not all, <TT>Makefile</TT>s in
585	the VR Juggler source tree are set in this file. These include the
586	installation path, paths to external programs and needed command-line
587	options used for compiling, installing, etc., and the names of the
588	final library binaries that will be built. Refer to the comments at
589	the head of this file for a full description of each variable defined
590	here.
591
592	<P>
593
594	<B>NOTE</B>: The file <TT>vj.clean.mk</TT> is included in this file
595	and thus any file that includes <TT>Makefile.base</TT> should set the
596	`<TT>default</TT>' target <I>before</I> including it. Also when
597	including this file, use the following directive:
598
599	<PRE>
600	include @topdir@/Makefile.base
601	</PRE>
602
603	This will ensure that there will be no problems with the path to the
604	file.
605
606	<P>
607	</DL>
608
609	<HR WIDTH="80%" NOSHADE>
610	<P>
611
612	<H2>General Layout of a <TT>Makefile.in</TT> File</H2>
613
614	<DL>
615	<DT><B>Default target to build</B>
616	<DD>
617	<P>
618
619	The default target for the <TT>Makefile</TT> to be generated should be
620	defined before doing anything else. This prevents any external files
621	that are included from inadvertently defining a target that would be
622	implicitly defined as the default target. In most cases, the default
623	target will be `<TT>all</TT>'.
624
625	<P>
626	<DT><B>Include <TT>Makefile.base</TT></B>
627	<DD>
628	<P>
629
630	The next step should be to include <TT>Makefile.base</TT> to get all of
631	its variable definitions. Some of these may be needed later in the
632	execution of the including file, so it should be included as early as
633	possible. It should <I>always</I> be included using the following
634	syntax for the path:
635
636	<PRE>
637	include @topdir@/Makefile.base
638	</PRE>
639
640	This will ensure that the path is specified correctly when the actual
641	<TT>Makefile</TT> is generated. Once <TT>Makefile.base</TT> is
642	included, <TT>${MKPATH}</TT> can be used for including files in the
643	<TT>juggler/mk</TT> directory of the source tree. Refer to the
644	previous section's information about <TT>Makefile.base</TT> for more
645	information about it.
646
647	<P>
648	<DT><B>Preset variables and variables local to the current file</B>
649	<DD>
650	<P>
651
652	The first set of assignments is for preset variables (that is, those
653	that are substituted by <I>configure</I> when the <TT>Makefile</TT> is
654	generated) and for variables that are closely related to the preset
655	variety. In general, many of these variables will have values that are
656	specific to the current <TT>Makefile</TT> being generated. In other
657	words, they cannot be shared via a common file that would be included
658	by the current <TT>Makefile</TT>.
659
660	<P>
661	<DT><B>Include any <TT>.mk</TT> files needed</B>
662	<DD>
663	<P>
664
665	Once all the variables are defined, this is a good time to include any
666	of the <TT>.mk</TT> files that this file will need. The path to these
667	files can be extracted from the variable <TT>${MKPATH}</TT> that is
668	defined in <TT>Makefile.base</TT>. Typically, these will be the files
669	needed for compiling, generating dependencies and installing. Refer
670	to the previous section's information about these files for detailed
671	information.
672
673	<P>
674	<DT><B>Finding source files using <TT>vpath</TT></B>
675	<DD>
676	<P>
677
678	<TT>vpath</TT> is a special directive that tells GNU <I>make</I>(1)
679	where to find dependencies for object files when the source is in
680	another directory. This allows easy compiling of common source for
681	multiple platforms independently. This should be initialized as
682	follows:
683
684	<PRE>
685	vpath
686	vpath %.c @srcdir@
687	vpath %.cpp @srcdir@
688	vpath %.o ${OBJDIR}
689	</PRE>
690
691	The above example is (obviously) for <TT>.c</TT>, <TT>.cpp</TT> and
692	<TT>.o</TT> files. For other extensions, change the settings
693	appropriately. The <TT>${OBJDIR}</TT> variable is set in
694	<TT>Makefile.base</TT>. Refer to the previous section's description
695	of <TT>Makefile.base</TT> for more information about that file.
696
697	<P>
698	<DT><B>Listing source files</B>
699	<DD>
700	<P>
701
702	The list of source files that <I>makedepend</I>(1) will parse and
703	what will actually be compiled are listed next. These file names
704	should not have any path prepended to them because this will interfere
705	with the output from <I>makedepend</I>(1). When the `<TT>depend</TT>'
706	target is built, it knows which directory contains the files to parse
707	from the <TT>${srcdir}</TT> variable.
708
709	<P>
710
711	The easiest way to handle listing the files is to use the
712	<TT>${DEPEND_SRCS}</TT> variable (required by <TT>vj.dep.mk</TT>) and
713	then use the following GNU <I>make</I>(1) macro to convert this list
714	into a list of object files to create:
715
716	<PRE>
717	DEPEND_SRCS := src1.cpp \
718	src2.cpp \
719	src3.cpp
720
721	OBJECTS := ${addprefix ${OBJDIR}/,${DEPEND_SRCS:.cpp=.o}}
722	</PRE>
723
724	In some cases, some files may be conditionally compiled depending on
725	the results of running the <I>configure</I> script. To add these source
726	files to <TT>${DEPEND_SRCS}</TT>, insert something similar to the
727	following before making the list of object files:
728
729	<PRE>
730	ifeq (@SOME_VAR@,