Fossil SCM

fossil-scm / tools / makeheaders.html

Source Blame History 1150 lines

b62f651…	stephan	1	<html>
b62f651…	stephan	2	<head><title>The Makeheaders Program</title></head>
b62f651…	stephan	3	<body bgcolor=white>
b62f651…	stephan	4	<h1 align=center>The Makeheaders Program</h1>
b62f651…	stephan	5
b62f651…	stephan	6
b62f651…	stephan	7	<p>
b62f651…	stephan	8	This document describes <em>makeheaders</em>,
b62f651…	stephan	9	a tool that automatically generates “<code>.h</code>”
b62f651…	stephan	10	files for a C or C++ programming project.
b62f651…	stephan	11	</p>
b62f651…	stephan	12
b62f651…	stephan	13
b62f651…	stephan	14	<h2>Table Of Contents</h2>
b62f651…	stephan	15
b62f651…	stephan	16	<ul>
b62f651…	stephan	17	<li><a href="#H0002">1,0 Background</a>
b62f651…	stephan	18	<ul>
b62f651…	stephan	19	<li><a href="#H0003">1.1 Problems With The Traditional Approach</a>
b62f651…	stephan	20
b62f651…	stephan	21	<li><a href="#H0004">1.2 The Makeheaders Solution</a>
b62f651…	stephan	22	</ul>
b62f651…	stephan	23	<li><a href="#H0005">2.0 Running The Makeheaders Program</a>
b62f651…	stephan	24
b62f651…	stephan	25	<li><a href="#H0006">3.0 Preparing Source Files For Use With Makeheaders</a>
b62f651…	stephan	26	<ul>
b62f651…	stephan	27	<li><a href="#H0007">3.1 The Basic Setup</a>
b62f651…	stephan	28
b62f651…	stephan	29	<li><a href="#H0008">3.2 What Declarations Get Copied</a>
b62f651…	stephan	30
b62f651…	stephan	31	<li><a href="#H0009">3.3 How To Avoid Having To Write Any Header Files</a>
b62f651…	stephan	32
b62f651…	stephan	33	<li><a href="#H0010">3.4 Designating Declarations For Export</a>
b62f651…	stephan	34
b62f651…	stephan	35	<li><a href="#H0011">3.5 Local declarations processed by makeheaders</a>
b62f651…	stephan	36
b62f651…	stephan	37	<li><a href="#H0012">3.6 Using Makeheaders With C++ Code</a>
b62f651…	stephan	38
b62f651…	stephan	39	<li><a href="#H0013">3.7 Conditional Compilation</a>
b62f651…	stephan	40
b62f651…	stephan	41	<li><a href="#H0014">3.8 Caveats</a>
b62f651…	stephan	42	</ul>
b62f651…	stephan	43	<li><a href="#H0015">4.0 Using Makeheaders To Generate Documentation</a>
b62f651…	stephan	44
b62f651…	stephan	45	<li><a href="#H0016">5.0 Compiling The Makeheaders Program</a>
b62f651…	stephan	46
b62f651…	stephan	47	<li><a href="#H0017">6.0 History</a>
b62f651…	stephan	48
b62f651…	stephan	49	<li><a href="#H0018">7.0 Summary And Conclusion</a>
b62f651…	stephan	50	</ul><a name="H0002"></a>
b62f651…	stephan	51	<h2>1.0 Background</h2>
b62f651…	stephan	52
b62f651…	stephan	53	<p>
b62f651…	stephan	54	A piece of C source code can be one of two things:
b62f651…	stephan	55	a <em>declaration</em> or a <em>definition</em>.
b62f651…	stephan	56	A declaration is source text that gives information to the
b62f651…	stephan	57	compiler but doesn't directly result in any code being generated.
b62f651…	stephan	58	A definition is source text that results in executable machine
b62f651…	stephan	59	instructions or initialization data.
b62f651…	stephan	60	(These two terms are sometimes used inconsistently by other authors.
b62f651…	stephan	61	In particular, many people reverse the meanings of these words when
b62f651…	stephan	62	discussing Pascal or Ada code.
b62f651…	stephan	63	The meanings described here are the same as used in the ANSI-C
b62f651…	stephan	64	standards document.)
b62f651…	stephan	65	</p>
b62f651…	stephan	66
b62f651…	stephan	67	<p>
b62f651…	stephan	68	Declarations in C include things such as the following:
b62f651…	stephan	69	<ul>
b62f651…	stephan	70	<li> Typedefs.
b62f651…	stephan	71	<li> Structure, union and enumeration declarations.
b62f651…	stephan	72	<li> Function and procedure prototypes.
b62f651…	stephan	73	<li> Preprocessor macros and #defines.
b62f651…	stephan	74	<li> “<code>extern</code>” variable declarations.
b62f651…	stephan	75	</ul>
b62f651…	stephan	76	</p>
b62f651…	stephan	77
b62f651…	stephan	78	<p>
b62f651…	stephan	79	Definitions in C, on the other hand, include these kinds of things:
b62f651…	stephan	80	<ul>
b62f651…	stephan	81	<li> Variable definitions.
b62f651…	stephan	82	<li> The bodies of functions and procedures.
b62f651…	stephan	83	<li> Initialization data.
b62f651…	stephan	84	</ul>
b62f651…	stephan	85	</p>
b62f651…	stephan	86
b62f651…	stephan	87	<p>
b62f651…	stephan	88	The distinction between a declaration and a definition is common in
b62f651…	stephan	89	modern software engineering.
b62f651…	stephan	90	Another way of looking at the difference is that the declaration
b62f651…	stephan	91	is the <em>interface</em> and the definition is the <em>implementation</em>.
b62f651…	stephan	92	</p>
b62f651…	stephan	93
b62f651…	stephan	94	<p>
b62f651…	stephan	95	In C programs, it has always been the tradition that declarations are
b62f651…	stephan	96	put in files with the “<code>.h</code>” suffix and definitions are
b62f651…	stephan	97	placed in “<code>.c</code>” files.
b62f651…	stephan	98	The .c files contain “<code>#include</code>” preprocessor statements
b62f651…	stephan	99	that cause the contents of .h files to be included as part of the
b62f651…	stephan	100	source code when the .c file is compiled.
b62f651…	stephan	101	In this way, the .h files define the interface to a subsystem and
b62f651…	stephan	102	the .c files define how the subsystem is implemented.
b62f651…	stephan	103	</p>
b62f651…	stephan	104
b62f651…	stephan	105	<a name="H0003"></a>
b62f651…	stephan	106	<h3>1.1 Problems With The Traditional Approach</h3>
b62f651…	stephan	107
b62f651…	stephan	108	<p>
b62f651…	stephan	109	As the art of computer programming continues to advance, and the size
b62f651…	stephan	110	and complexity of programs continues to swell, the traditional C
b62f651…	stephan	111	approach of placing declarations and definitions in separate files begins
b62f651…	stephan	112	to present the programmer with logistics and
b62f651…	stephan	113	maintenance problems.
b62f651…	stephan	114	To wit:
b62f651…	stephan	115	</p>
b62f651…	stephan	116
b62f651…	stephan	117	<p>
b62f651…	stephan	118	<ol>
b62f651…	stephan	119	<p><li>
b62f651…	stephan	120	In large codes with many source files, it becomes difficult to determine
b62f651…	stephan	121	which .h files should be included in which .c files.
b62f651…	stephan	122	<p><li>
b62f651…	stephan	123	It is typically the case that a .h file will be forced to include
b62f651…	stephan	124	another .h files, which in turn might include other .h files,
b62f651…	stephan	125	and so forth.
b62f651…	stephan	126	The .c file must be recompiled when any of the .h files in this chain
b62f651…	stephan	127	are altered, but it can be difficult to determine what .h files are found
b62f651…	stephan	128	in the include chain.
b62f651…	stephan	129	A frequent Makefile error is to omit some .h files from a dependency
b62f651…	stephan	130	list even though those files are on the include file chain.
b62f651…	stephan	131	<p><li>
b62f651…	stephan	132	Some information is common to both the declaration and the definition of
b62f651…	stephan	133	an object in C, and so must be repeated in both the .h and the .c files
b62f651…	stephan	134	for that object.
b62f651…	stephan	135	In a large project, it can become increasingly difficult to keep the two
b62f651…	stephan	136	files in sync.
b62f651…	stephan	137	<p><li>
b62f651…	stephan	138	When a .c file includes a .h file and the .h files changes, the .c file
b62f651…	stephan	139	must be recompiled, even if the part of the .h file that changed is not
b62f651…	stephan	140	actually used by the .c file.
b62f651…	stephan	141	In a large program, it is generally the case that almost every .c file ends up
b62f651…	stephan	142	depending on one or two of the more important .h files, and so when those .h
b62f651…	stephan	143	files change, the entire program must be recompiled.
b62f651…	stephan	144	It also happens that those important .h files tend to be the ones that
b62f651…	stephan	145	change most frequently.
b62f651…	stephan	146	This means that the entire program must be recompiled frequently,
b62f651…	stephan	147	leading to a lengthy modify-compile-test cycle and a corresponding
b62f651…	stephan	148	decrease in programmer productivity.
b62f651…	stephan	149	<p><li>
b62f651…	stephan	150	The C programming language requires that declarations depending upon
b62f651…	stephan	151	each other must occur in a particular order.
b62f651…	stephan	152	In a program with complex, interwoven data structures, the correct
b62f651…	stephan	153	declaration order can become very difficult to determine manually,
b62f651…	stephan	154	especially when the declarations involved are spread out over several
b62f651…	stephan	155	files.
b62f651…	stephan	156	</ol>
b62f651…	stephan	157	</p>
b62f651…	stephan	158
b62f651…	stephan	159	<a name="H0004"></a>
b62f651…	stephan	160	<h3>1.2 The Makeheaders Solution</h3>
b62f651…	stephan	161
b62f651…	stephan	162	<p>
b62f651…	stephan	163	The makeheaders program is designed to ameliorate the problems associated
b62f651…	stephan	164	with the traditional C programming model by automatically generating
b62f651…	stephan	165	the interface information in the .h files from
b62f651…	stephan	166	interface information contained in other .h files and
b62f651…	stephan	167	from implementation information in the .c files.
b62f651…	stephan	168	When the makeheaders program is run, it scans the source
b62f651…	stephan	169	files for a project,
b62f651…	stephan	170	then generates a series of new .h files, one for each .c file.
b62f651…	stephan	171	The generated .h files contain exactly those declarations required by the
b62f651…	stephan	172	corresponding .c files, no more and no less.
b62f651…	stephan	173	</p>
b62f651…	stephan	174
b62f651…	stephan	175	<p>
b62f651…	stephan	176	The makeheaders programming model overcomes all of the objections to the
b62f651…	stephan	177	traditional C programming model.
b62f651…	stephan	178	<ol>
b62f651…	stephan	179	<p><li>
b62f651…	stephan	180	Because all declarations needed by a .c file are contained in a
b62f651…	stephan	181	single .h file, there is never any question about what .h files
b62f651…	stephan	182	a .c will need to include. If the .c file is named
b62f651…	stephan	183	<code>alpha.c</code> then it must include only the single .h file
b62f651…	stephan	184	named <code>alpha.h</code>.
b62f651…	stephan	185	(The .c file might also use some include files from the standard
b62f651…	stephan	186	library, such as <code><stdio.h&gt</code>, but that is another matter.)
b62f651…	stephan	187	<p><li>
b62f651…	stephan	188	The generated .h files do not include other .h files, and so there
b62f651…	stephan	189	are no include chains to worry about.
b62f651…	stephan	190	The file <code>alpha.c</code> depends on <code>alpha.h</code> and
b62f651…	stephan	191	nothing more.
b62f651…	stephan	192	<p><li>
b62f651…	stephan	193	There is still duplication in the .h and the .c file, but because
b62f651…	stephan	194	the duplicate information is automatically generated, it is no longer
b62f651…	stephan	195	a problem.
b62f651…	stephan	196	Simply rerun makeheaders to resynchronize everything.
b62f651…	stephan	197	<p><li>
b62f651…	stephan	198	The generated .h file contains the minimal set of declarations needed
b62f651…	stephan	199	by the .c file.
b62f651…	stephan	200	This means that when something changes, a minimal amount of recompilation
b62f651…	stephan	201	is required to produce an updated executable.
b62f651…	stephan	202	Experience has shown that this gives a dramatic improvement
b62f651…	stephan	203	in programmer productivity by facilitating a rapid modify-compile-test
b62f651…	stephan	204	cycle during development.
b62f651…	stephan	205	<p><li>
b62f651…	stephan	206	The makeheaders program automatically sorts declarations into the
b62f651…	stephan	207	correct order, completely eliminating the wearisome and error-prone
b62f651…	stephan	208	task of sorting declarations by hand.
b62f651…	stephan	209	</ol>
b62f651…	stephan	210	<p>
b62f651…	stephan	211
b62f651…	stephan	212	<p>
b62f651…	stephan	213	In addition, the makeheaders program is fast and unintrusive.
b62f651…	stephan	214	It is a simple matter to incorporate makeheaders into a Makefile
b62f651…	stephan	215	so that makeheaders will be run automatically whenever the project
b62f651…	stephan	216	is rebuilt.
b62f651…	stephan	217	And the burden of running makeheaders is light.
b62f651…	stephan	218	It will easily process tens of thousands of lines of source
b62f651…	stephan	219	code per second.
b62f651…	stephan	220	</p>
b62f651…	stephan	221
b62f651…	stephan	222	<a name="H0005"></a>
b62f651…	stephan	223	<h2>2.0 Running The Makeheaders Program</h2>
b62f651…	stephan	224
b62f651…	stephan	225	<p>
b62f651…	stephan	226	The makeheaders program is very easy to run.
b62f651…	stephan	227	If you have a collection of C source code and include files in the working
b62f651…	stephan	228	directory, then you can run makeheaders to generate appropriate .h
b62f651…	stephan	229	files using the following command:
b62f651…	stephan	230	<pre>
b62f651…	stephan	231	makeheaders *.[ch]
b62f651…	stephan	232	</pre>
b62f651…	stephan	233	That's really all there is to it!
b62f651…	stephan	234	This command will generate one .h file for every .c file.
b62f651…	stephan	235	Any .h files that were generated by a prior run of makeheaders
b62f651…	stephan	236	are ignored,
b62f651…	stephan	237	but manually entered .h files
b62f651…	stephan	238	that contain structure declarations and so forth will be scanned and
b62f651…	stephan	239	the declarations will be copied into the generated .h files as
b62f651…	stephan	240	appropriate.
b62f651…	stephan	241	But if makeheaders sees that the .h file that it has generated is no
b62f651…	stephan	242	different from the .h file it generated last time, it doesn't update
b62f651…	stephan	243	the file.
b62f651…	stephan	244	This prevents the corresponding .c files from having to
b62f651…	stephan	245	be needlessly recompiled.
b62f651…	stephan	246	</p>
b62f651…	stephan	247
b62f651…	stephan	248	<p>
b62f651…	stephan	249	There are several options to the makeheaders program that can
b62f651…	stephan	250	be used to alter its behavior.
b62f651…	stephan	251	The default behavior is to write a single .h file for each .c file and
b62f651…	stephan	252	to give the .h file the same base name as the .c file.
b62f651…	stephan	253	Instead of generating a whole mess of .h files, you can, if you choose,
b62f651…	stephan	254	generate a single big .h file that contains all declarations needed
b62f651…	stephan	255	by all the .c files. Do this using the -h option to makeheaders.
b62f651…	stephan	256	As follows:
b62f651…	stephan	257	<pre>
b62f651…	stephan	258	makeheaders -h *.[ch] >common.h
b62f651…	stephan	259	</pre>
b62f651…	stephan	260	With the -h option, the .h file is not actually written to a disk file but
b62f651…	stephan	261	instead appears on standard output, where you are free to redirect it
b62f651…	stephan	262	into the file of your choice.
b62f651…	stephan	263	</p>
b62f651…	stephan	264
b62f651…	stephan	265	<p>
b62f651…	stephan	266	A similar option is -H. Like the lower-case -h option, big -H
b62f651…	stephan	267	generates a single include file on standard output. But unlike
b62f651…	stephan	268	small -h, the big -H only emits prototypes and declarations that
b62f651…	stephan	269	have been designated as “exportable”.
b62f651…	stephan	270	The idea is that -H will generate an include file that defines
b62f651…	stephan	271	the interface to a library.
b62f651…	stephan	272	More will be said about this in section 3.4.
b62f651…	stephan	273	</p>
b62f651…	stephan	274
b62f651…	stephan	275	<p>
b62f651…	stephan	276	Sometimes you want the base name of the .c file and the .h file to
b62f651…	stephan	277	be different.
b62f651…	stephan	278	For example, suppose you want the include file for <code>alpha.c</code>
b62f651…	stephan	279	to be called <code>beta.h</code>.
b62f651…	stephan	280	In this case, you would invoke makeheaders as follows:
b62f651…	stephan	281	<pre>
b62f651…	stephan	282	makeheaders alpha.c:beta.h
b62f651…	stephan	283	</pre>
b62f651…	stephan	284	Any time a filename argument contains a colon, the name before the
b62f651…	stephan	285	colon is taken to be the name of the .c file and the name after the
b62f651…	stephan	286	colon is taken to be the name of the .h file.
b62f651…	stephan	287	You can't use the shell's wildcard mechanism with this approach, but that
b62f651…	stephan	288	normally isn't a problem in Makefiles, which is where this stuff
b62f651…	stephan	289	comes in handy.
b62f651…	stephan	290	</p>
b62f651…	stephan	291
b62f651…	stephan	292	<p>
b62f651…	stephan	293	If you want a particular file to be scanned by makeheaders but you
b62f651…	stephan	294	don't want makeheaders to generate a header file for that file,
b62f651…	stephan	295	then you can supply an empty header filename, like this:
b62f651…	stephan	296	<pre>
b62f651…	stephan	297	makeheaders alpha.c beta.c gamma.c:
b62f651…	stephan	298	</pre>
b62f651…	stephan	299	In this example, makeheaders will scan the three files named
b62f651…	stephan	300	“<code>alpha.c</code>”,
b62f651…	stephan	301	“<code>beta.c</code>” and
b62f651…	stephan	302	“<code>gamma.c</code>”
b62f651…	stephan	303	but because of the colon on the end of third filename
b62f651…	stephan	304	it will only generate headers for the first two files.
b62f651…	stephan	305	Unfortunately,
b62f651…	stephan	306	it is not possible to get makeheaders to process any file whose
b62f651…	stephan	307	name contains a colon.
b62f651…	stephan	308	</p>
b62f651…	stephan	309
b62f651…	stephan	310	<p>
b62f651…	stephan	311	In a large project, the length of the command line for makeheaders
b62f651…	stephan	312	can become very long.
b62f651…	stephan	313	If the operating system doesn't support long command lines
b62f651…	stephan	314	(example: DOS and Win32) you may not be able to list all of the
b62f651…	stephan	315	input files in the space available.
b62f651…	stephan	316	In that case, you can use the “<code>-f</code>” option followed
b62f651…	stephan	317	by the name of a file to cause makeheaders to read command line
b62f651…	stephan	318	options and filename from the file instead of from the command line.
b62f651…	stephan	319	For example, you might prepare a file named “<code>mkhdr.dat</code>”
b62f651…	stephan	320	that contains text like this:
b62f651…	stephan	321	<pre>
b62f651…	stephan	322	src/alpha.c:hdr/alpha.h
b62f651…	stephan	323	src/beta.c:hdr/beta.h
b62f651…	stephan	324	src/gamma.c:hdr/gamma.h
b62f651…	stephan	325	...
b62f651…	stephan	326	</pre>
b62f651…	stephan	327	Then invoke makeheaders as follows:
b62f651…	stephan	328	<pre>
b62f651…	stephan	329	makeheaders -f mkhdr.dat
b62f651…	stephan	330	</pre>
b62f651…	stephan	331	</p>
b62f651…	stephan	332
b62f651…	stephan	333	<p>
b62f651…	stephan	334	The “<code>-local</code>” option causes makeheaders to
b62f651…	stephan	335	generate of prototypes for “<code>static</code>” functions and
b62f651…	stephan	336	procedures.
b62f651…	stephan	337	Such prototypes are normally omitted.
b62f651…	stephan	338	</p>
b62f651…	stephan	339
b62f651…	stephan	340	<p>
b62f651…	stephan	341	Finally, makeheaders also includes a “<code>-doc</code>” option.
b62f651…	stephan	342	This command line option prevents makeheaders from generating any
b62f651…	stephan	343	headers at all.
b62f651…	stephan	344	Instead, makeheaders will write to standard output
b62f651…	stephan	345	information about every definition and declaration that it encounters
b62f651…	stephan	346	in its scan of source files.
b62f651…	stephan	347	The information output includes the type of the definition or
b62f651…	stephan	348	declaration and any comment that precedes the definition or
b62f651…	stephan	349	declaration.
b62f651…	stephan	350	The output is in a format that can be easily parsed, and is
b62f651…	stephan	351	intended to be read by another program that will generate
b62f651…	stephan	352	documentation about the program.
b62f651…	stephan	353	We'll talk more about this feature later.
b62f651…	stephan	354	</p>
b62f651…	stephan	355
b62f651…	stephan	356	<p>
b62f651…	stephan	357	If you forget what command line options are available, or forget
b62f651…	stephan	358	their exact name, you can invoke makeheaders using an unknown
b62f651…	stephan	359	command line option (like “<code>--help</code>” or
b62f651…	stephan	360	“<code>-?</code>”)
b62f651…	stephan	361	and it will print a summary of the available options on standard
b62f651…	stephan	362	error.
b62f651…	stephan	363	If you need to process a file whose name begins with
b62f651…	stephan	364	“<code>-</code>”,
b62f651…	stephan	365	you can prepend a “<code>./</code>” to its name in order to get it
b62f651…	stephan	366	accepted by the command line parser.
b62f651…	stephan	367	Or, you can insert the special option “<code>--</code>” on the
b62f651…	stephan	368	command line to cause all subsequent command line arguments to be treated as
b62f651…	stephan	369	filenames even if their names begin with “<code>-</code>”.
b62f651…	stephan	370	</p>
b62f651…	stephan	371
b62f651…	stephan	372	<a name="H0006"></a>
b62f651…	stephan	373	<h2>3.0 Preparing Source Files For Use With Makeheaders</h2>
b62f651…	stephan	374
b62f651…	stephan	375	<p>
b62f651…	stephan	376	Very little has to be done to prepare source files for use with
b62f651…	stephan	377	makeheaders since makeheaders will read and understand ordinary
b62f651…	stephan	378	C code.
b62f651…	stephan	379	But it is important that you structure your files in a way that
b62f651…	stephan	380	makes sense in the makeheaders context.
b62f651…	stephan	381	This section will describe several typical uses of makeheaders.
b62f651…	stephan	382	</p>
b62f651…	stephan	383
b62f651…	stephan	384	<a name="H0007"></a>
b62f651…	stephan	385	<h3>3.1 The Basic Setup</h3>
b62f651…	stephan	386
b62f651…	stephan	387	<p>
b62f651…	stephan	388	The simplest way to use makeheaders is to put all definitions in
b62f651…	stephan	389	one or more .c files and all structure and type declarations in
b62f651…	stephan	390	separate .h files.
b62f651…	stephan	391	The only restriction is that you should take care to chose basenames
b62f651…	stephan	392	for your .h files that are different from the basenames for your
b62f651…	stephan	393	.c files.
b62f651…	stephan	394	Recall that if your .c file is named (for example)
b62f651…	stephan	395	“<code>alpha.c</code>”
b62f651…	stephan	396	makeheaders will attempt to generate a corresponding header file
b62f651…	stephan	397	named “<code>alpha.h</code>”.
b62f651…	stephan	398	For that reason, you don't want to use that name for
b62f651…	stephan	399	any of the .h files you write since that will prevent makeheaders
b62f651…	stephan	400	from generating the .h file automatically.
b62f651…	stephan	401	</p>
b62f651…	stephan	402
b62f651…	stephan	403	<p>
b62f651…	stephan	404	The structure of a .c file intended for use with makeheaders is very
b62f651…	stephan	405	simple.
b62f651…	stephan	406	All you have to do is add a single “<code>#include</code>” to the
b62f651…	stephan	407	top of the file that sources the header file that makeheaders will generate.
b62f651…	stephan	408	Hence, the beginning of a source file named “<code>alpha.c</code>”
b62f651…	stephan	409	might look something like this:
b62f651…	stephan	410	</p>
b62f651…	stephan	411
b62f651…	stephan	412	<pre>
b62f651…	stephan	413	/*
b62f651…	stephan	414	* Introductory comment...
b62f651…	stephan	415	*/
b62f651…	stephan	416	#include "alpha.h"
b62f651…	stephan	417
b62f651…	stephan	418	/* The rest of your code... */
b62f651…	stephan	419	</pre>
b62f651…	stephan	420
b62f651…	stephan	421	<p>
b62f651…	stephan	422	Your manually generated header files require no special attention at all.
b62f651…	stephan	423	Code them as you normally would.
b62f651…	stephan	424	However, makeheaders will work better if you omit the
b62f651…	stephan	425	“<code>#if</code>” statements people often put around the outside of
b62f651…	stephan	426	header files that prevent the files from being included more than once.
b62f651…	stephan	427	For example, to create a header file named “<code>beta.h</code>”,
b62f651…	stephan	428	many people will habitually write the following:
b62f651…	stephan	429
b62f651…	stephan	430	<pre>
b62f651…	stephan	431	#ifndef BETA_H
b62f651…	stephan	432	#define BETA_H
b62f651…	stephan	433
b62f651…	stephan	434	/* declarations for beta.h go here */
b62f651…	stephan	435
b62f651…	stephan	436	#endif
b62f651…	stephan	437	</pre>
b62f651…	stephan	438
b62f651…	stephan	439	You can forego this cleverness with makeheaders.
b62f651…	stephan	440	Remember that the header files you write will never really be
b62f651…	stephan	441	included by any C code.
b62f651…	stephan	442	Instead, makeheaders will scan your header files to extract only
b62f651…	stephan	443	those declarations that are needed by individual .c files and then
b62f651…	stephan	444	copy those declarations to the .h files corresponding to the .c files.
b62f651…	stephan	445	Hence, the “<code>#if</code>” wrapper serves no useful purpose.
b62f651…	stephan	446	But it does make makeheaders work harder, forcing it to put
b62f651…	stephan	447	the statements
b62f651…	stephan	448
b62f651…	stephan	449	<pre>
b62f651…	stephan	450	#if !defined(BETA_H)
b62f651…	stephan	451	#endif
b62f651…	stephan	452	</pre>
b62f651…	stephan	453
b62f651…	stephan	454	around every declaration that it copies out of your header file.
b62f651…	stephan	455	No ill effect should come of this, but neither is there any benefit.
b62f651…	stephan	456	</p>
b62f651…	stephan	457
b62f651…	stephan	458	<p>
b62f651…	stephan	459	Having prepared your .c and .h files as described above, you can
b62f651…	stephan	460	cause makeheaders to generate its .h files using the following simple
b62f651…	stephan	461	command:
b62f651…	stephan	462
b62f651…	stephan	463	<pre>
b62f651…	stephan	464	makeheaders *.[ch]
b62f651…	stephan	465	</pre>
b62f651…	stephan	466
b62f651…	stephan	467	The makeheaders program will scan all of the .c files and all of the
b62f651…	stephan	468	manually written .h files and then automatically generate .h files
b62f651…	stephan	469	corresponding to all .c files.
b62f651…	stephan	470	</p>
b62f651…	stephan	471
b62f651…	stephan	472	<p>
b62f651…	stephan	473	Note that
b62f651…	stephan	474	the wildcard expression used in the above example,
b62f651…	stephan	475	“<code>*.[ch]</code>”,
b62f651…	stephan	476	will expand to include all .h files in the current directory, both
b62f651…	stephan	477	those entered manually be the programmer and others generated automatically
b62f651…	stephan	478	by a prior run of makeheaders.
b62f651…	stephan	479	But that is not a problem.
b62f651…	stephan	480	The makeheaders program will recognize and ignore any files it
b62f651…	stephan	481	has previously generated that show up on its input list.
b62f651…	stephan	482	</p>
b62f651…	stephan	483
b62f651…	stephan	484	<a name="H0008"></a>
b62f651…	stephan	485	<h3>3.2 What Declarations Get Copied</h3>
b62f651…	stephan	486
b62f651…	stephan	487	<p>
b62f651…	stephan	488	The following list details all of the code constructs that makeheaders
b62f651…	stephan	489	will extract and place in
b62f651…	stephan	490	the automatically generated .h files:
b62f651…	stephan	491	</p>
b62f651…	stephan	492
b62f651…	stephan	493	<ul>
b62f651…	stephan	494	<p><li>
b62f651…	stephan	495	When a function is defined in any .c file, a prototype of that function
b62f651…	stephan	496	is placed in the generated .h file of every .c file that
b62f651…	stephan	497	calls the function.</p>
b62f651…	stephan	498
b62f651…	stephan	499	<P>If the “<code>static</code>” keyword of C appears at the
b62f651…	stephan	500	beginning of the function definition, the prototype is suppressed.
b62f651…	stephan	501	If you use the “<code>LOCAL</code>” keyword where you would normally
b62f651…	stephan	502	say “<code>static</code>”, then a prototype is generated, but it
b62f651…	stephan	503	will only appear in the single header file that corresponds to the
b62f651…	stephan	504	source file containing the function. For example, if the file
b62f651…	stephan	505	<code>alpha.c</code> contains the following:
b62f651…	stephan	506	<pre>
b62f651…	stephan	507	LOCAL int testFunc(void){
b62f651…	stephan	508	return 0;
b62f651…	stephan	509	}
b62f651…	stephan	510	</pre>
b62f651…	stephan	511	Then the header file <code>alpha.h</code> will contain
b62f651…	stephan	512	<pre>
b62f651…	stephan	513	#define LOCAL static
b62f651…	stephan	514	LOCAL int testFunc(void);
b62f651…	stephan	515	</pre>
b62f651…	stephan	516	However, no other generated header files will contain a prototype for
b62f651…	stephan	517	<code>testFunc()</code> since the function has only file scope.</p>
b62f651…	stephan	518
b62f651…	stephan	519	<p>When the “<code>LOCAL</code>” keyword is used, makeheaders will
b62f651…	stephan	520	also generate a #define for LOCAL, like this:
b62f651…	stephan	521	<pre>
b62f651…	stephan	522	#define LOCAL static
b62f651…	stephan	523	</pre>
b62f651…	stephan	524	so that the C compiler will know what it means.</p>
b62f651…	stephan	525
b62f651…	stephan	526	<p>If you invoke makeheaders with a “<code>-local</code>”
b62f651…	stephan	527	command-line option, then it treats the “<code>static</code>”
b62f651…	stephan	528	keyword like “<code>LOCAL</code>” and generates prototypes in the
b62f651…	stephan	529	header file that corresponds to the source file containing the function
b62f651…	stephan	530	definition.</p>
b62f651…	stephan	531
b62f651…	stephan	532	<p><li>
b62f651…	stephan	533	When a global variable is defined in a .c file, an
b62f651…	stephan	534	“<code>extern</code>”
b62f651…	stephan	535	declaration of that variable is placed in the header of every
b62f651…	stephan	536	.c file that uses the variable.
b62f651…	stephan	537	</p>
b62f651…	stephan	538
b62f651…	stephan	539	<p><li>
b62f651…	stephan	540	When a structure, union or enumeration declaration or a
b62f651…	stephan	541	function prototype or a C++ class declaration appears in a
b62f651…	stephan	542	manually produced .h file, that declaration is copied into the
b62f651…	stephan	543	automatically generated
b62f651…	stephan	544	.h files of all .c files that use the structure, union, enumeration,
b62f651…	stephan	545	function or class.
b62f651…	stephan	546	But declarations that appear in a
b62f651…	stephan	547	.c file are considered private to that .c file and are not copied into
b62f651…	stephan	548	any automatically generated files.
b62f651…	stephan	549	</p>
b62f651…	stephan	550
b62f651…	stephan	551	<p><li>
b62f651…	stephan	552	All #defines and typedefs that appear in manually produced .h files
b62f651…	stephan	553	are copied into automatically generated .h files as needed.
b62f651…	stephan	554	Similar constructs that appear in .c files are considered private to
b62f651…	stephan	555	those files and are not copied.
b62f651…	stephan	556	</p>
b62f651…	stephan	557
b62f651…	stephan	558	<p><li>
b62f651…	stephan	559	When a structure, union or enumeration declaration appears in a .h
b62f651…	stephan	560	file, makeheaders will automatically
b62f651…	stephan	561	generate a typedef that allows the declaration to be referenced without
b62f651…	stephan	562	the “<code>struct</code>”, “<code>union</code>” or
b62f651…	stephan	563	“<code>enum</code>” qualifier.
b62f651…	stephan	564	In other words, if makeheaders sees the code:
b62f651…	stephan	565	<pre>
b62f651…	stephan	566	struct Examp { /* ... */ };
b62f651…	stephan	567	</pre>
b62f651…	stephan	568	it will automatically generate a corresponding typedef like this:
b62f651…	stephan	569	<pre>
b62f651…	stephan	570	typedef struct Examp Examp;
b62f651…	stephan	571	</pre>
b62f651…	stephan	572	</p>
b62f651…	stephan	573
b62f651…	stephan	574	<p><li>
b62f651…	stephan	575	Makeheaders generates an error message if it encounters a function or
b62f651…	stephan	576	variable definition within a .h file.
c3d321f…	stephan	577	The .h files are supposed to contain only interface, not implementation.
b62f651…	stephan	578	C compilers will not enforce this convention, but makeheaders does.
b62f651…	stephan	579	</ul>
b62f651…	stephan	580
b62f651…	stephan	581	<p>
b62f651…	stephan	582	As a final note, we observe that automatically generated declarations
b62f651…	stephan	583	are ordered as required by the ANSI-C programming language.
b62f651…	stephan	584	If the declaration of some structure “<code>X</code>” requires a
b62f651…	stephan	585	prior declaration of another structure “<code>Y</code>”, then Y will
b62f651…	stephan	586	appear first in the generated headers.
b62f651…	stephan	587	</p>
b62f651…	stephan	588
b62f651…	stephan	589	<a name="H0009"></a>
b62f651…	stephan	590	<h3>3.3 How To Avoid Having To Write Any Header Files</h3>
b62f651…	stephan	591
b62f651…	stephan	592	<p>
b62f651…	stephan	593	In my experience, large projects work better if all of the manually
b62f651…	stephan	594	written code is placed in .c files and all .h files are generated
b62f651…	stephan	595	automatically.
b62f651…	stephan	596	This is slightly different from the traditional C method of placing
b62f651…	stephan	597	the interface in .h files and the implementation in .c files, but
b62f651…	stephan	598	it is a refreshing change that brings a noticeable improvement to the
b62f651…	stephan	599	coding experience.
b62f651…	stephan	600	Others, I believe, share this view since I've
b62f651…	stephan	601	noticed recent languages (ex: java, tcl, perl, awk) tend to
b62f651…	stephan	602	support the one-file approach to coding as the only option.
b62f651…	stephan	603	</p>
b62f651…	stephan	604
b62f651…	stephan	605	<p>
b62f651…	stephan	606	The makeheaders program supports putting both
b62f651…	stephan	607	interface and implementation into the same source file.
b62f651…	stephan	608	But you do have to tell makeheaders which part of the source file is the
b62f651…	stephan	609	interface and which part is the implementation.
b62f651…	stephan	610	Makeheaders has to know this in order to be able to figure out whether or
b62f651…	stephan	611	not structures declarations, typedefs, #defines and so forth should
b62f651…	stephan	612	be copied into the generated headers of other source files.
b62f651…	stephan	613	</p>
b62f651…	stephan	614
b62f651…	stephan	615	<p>
b62f651…	stephan	616	You can instruct makeheaders to treat any part of a .c file as if
b62f651…	stephan	617	it were a .h file by enclosing that part of the .c file within:
b62f651…	stephan	618	<pre>
b62f651…	stephan	619	#if INTERFACE
b62f651…	stephan	620	#endif
b62f651…	stephan	621	</pre>
b62f651…	stephan	622	Thus any structure definitions that appear after the
b62f651…	stephan	623	“<code>#if INTERFACE</code>” but before the corresponding
b62f651…	stephan	624	“<code>#endif</code>” are eligible to be copied into the
b62f651…	stephan	625	automatically generated
b62f651…	stephan	626	.h files of other .c files.
b62f651…	stephan	627	</p>
b62f651…	stephan	628
b62f651…	stephan	629	<p>
b62f651…	stephan	630	If you use the “<code>#if INTERFACE</code>” mechanism in a .c file,
b62f651…	stephan	631	then the generated header for that .c file will contain a line
b62f651…	stephan	632	like this:
b62f651…	stephan	633	<pre>
b62f651…	stephan	634	#define INTERFACE 0
b62f651…	stephan	635	</pre>
b62f651…	stephan	636	In other words, the C compiler will never see any of the text that
b62f651…	stephan	637	defines the interface.
b62f651…	stephan	638	But makeheaders will copy all necessary definitions and declarations
b62f651…	stephan	639	into the .h file it generates, so .c files will compile as if the
b62f651…	stephan	640	declarations were really there.
b62f651…	stephan	641	This approach has the advantage that you don't have to worry with
b62f651…	stephan	642	putting the declarations in the correct ANSI-C order -- makeheaders
b62f651…	stephan	643	will do that for you automatically.
b62f651…	stephan	644	</p>
b62f651…	stephan	645
b62f651…	stephan	646	<p>
b62f651…	stephan	647	Note that you don't have to use this approach exclusively.
b62f651…	stephan	648	You can put some declarations in .h files and others within the
b62f651…	stephan	649	“<code>#if INTERFACE</code>” regions of .c files.
b62f651…	stephan	650	Makeheaders treats all declarations alike, no matter where they
b62f651…	stephan	651	come from.
b62f651…	stephan	652	You should also note that a single .c file can contain as many
b62f651…	stephan	653	“<code>#if INTERFACE</code>” regions as desired.
b62f651…	stephan	654	</p>
b62f651…	stephan	655
b62f651…	stephan	656	<a name="H0010"></a>
b62f651…	stephan	657	<h3>3.4 Designating Declarations For Export</h3>
b62f651…	stephan	658
b62f651…	stephan	659	<p>
b62f651…	stephan	660	In a large project, one will often construct a hierarchy of
b62f651…	stephan	661	interfaces.
b62f651…	stephan	662	For example, you may have a group of 20 or so files that form
b62f651…	stephan	663	a library used in several other parts of the system.
b62f651…	stephan	664	Each file in this library will present two interfaces.
b62f651…	stephan	665	One interface will be the routines and data structures it is
b62f651…	stephan	666	willing to share with other files in the same library, and the
b62f651…	stephan	667	second interface is those routines and data structures it wishes
b62f651…	stephan	668	to make available to other subsystems.
b62f651…	stephan	669	(The second interface is normally a subset of the first.)
b62f651…	stephan	670	Ordinary C does not provide support for a tiered interface
b62f651…	stephan	671	like this, but makeheaders does.
b62f651…	stephan	672	</p>
b62f651…	stephan	673
b62f651…	stephan	674	<p>
b62f651…	stephan	675	Using makeheaders, it is possible to designate routines and data
b62f651…	stephan	676	structures as being for “<code>export</code>”.
b62f651…	stephan	677	Exported objects are visible not only to other files within the
b62f651…	stephan	678	same library or subassembly but also to other
b62f651…	stephan	679	libraries and subassemblies in the larger program.
b62f651…	stephan	680	By default, makeheaders only makes objects visible to other members
b62f651…	stephan	681	of the same library.
b62f651…	stephan	682	</p>
b62f651…	stephan	683
b62f651…	stephan	684	<p>
b62f651…	stephan	685	That isn't the complete truth, actually.
b62f651…	stephan	686	The semantics of C are such that once an object becomes visible
b62f651…	stephan	687	outside of a single source file, it is also visible to any user
b62f651…	stephan	688	of the library that is made from the source file.
b62f651…	stephan	689	Makeheaders can not prevent outsiders from using non-exported resources,
b62f651…	stephan	690	but it can discourage the practice by refusing to provide prototypes
b62f651…	stephan	691	and declarations for the services it does not want to export.
b62f651…	stephan	692	Thus the only real effect of the making an object exportable is
b62f651…	stephan	693	to include it in the output makeheaders generates when it is run
b62f651…	stephan	694	using the -H command line option.
b62f651…	stephan	695	This is not a perfect solution, but it works well in practice.
b62f651…	stephan	696	</p>
b62f651…	stephan	697
b62f651…	stephan	698	<p>
b62f651…	stephan	699	But trouble quickly arises when we attempt to devise a mechanism for
b62f651…	stephan	700	telling makeheaders which prototypes it should export and which it should
b62f651…	stephan	701	keep local.
b62f651…	stephan	702	The built-in “<code>static</code>” keyword of C works well for
b62f651…	stephan	703	prohibiting prototypes from leaving a single source file, but because C doesn't
b62f651…	stephan	704	support a linkage hierarchy, there is nothing in the C language to help us.
b62f651…	stephan	705	We'll have to invite our own keyword: “<code>EXPORT</code>”
b62f651…	stephan	706	</p>
b62f651…	stephan	707
b62f651…	stephan	708	<p>
b62f651…	stephan	709	Makeheaders allows the EXPORT keyword to precede any function or
b62f651…	stephan	710	procedure definition.
b62f651…	stephan	711	The routine following the EXPORT keyword is then eligable to appear
b62f651…	stephan	712	in the header file generated using the -H command line option.
b62f651…	stephan	713	Note that if a .c file contains the EXPORT keyword, makeheaders will
b62f651…	stephan	714	put the macro
b62f651…	stephan	715	<pre>
b62f651…	stephan	716	#define EXPORT
b62f651…	stephan	717	</pre>
b62f651…	stephan	718	in the header file it generates for the .c file so that the EXPORT keyword
b62f651…	stephan	719	will never be seen by the C compiler.
b62f651…	stephan	720	</p>
b62f651…	stephan	721
b62f651…	stephan	722	<p>
b62f651…	stephan	723	But the EXPORT keyword only works for function and procedure definitions.
b62f651…	stephan	724	For structure, union and enum definitions, typedefs, #defines and
b62f651…	stephan	725	class declarations, a second mechanism is used.
b62f651…	stephan	726	Just as any declarations or definition contained within
b62f651…	stephan	727	<pre>
b62f651…	stephan	728	#if INTERFACE
b62f651…	stephan	729	#endif
b62f651…	stephan	730	</pre>
b62f651…	stephan	731	are visible to all files within the library, any declarations
b62f651…	stephan	732	or definitions within
b62f651…	stephan	733	<pre>
b62f651…	stephan	734	#if EXPORT_INTERFACE
b62f651…	stephan	735	#endif
b62f651…	stephan	736	</pre>
b62f651…	stephan	737	will become part of the exported interface.
b62f651…	stephan	738	The “<code>#if EXPORT_INTERFACE</code>” mechanism can be used in
b62f651…	stephan	739	either .c or .h files.
b62f651…	stephan	740	(The “<code>#if INTERFACE</code>” can also be used in both .h and
b62f651…	stephan	741	.c files, but since it's use in a .h file would be redundant, we haven't
b62f651…	stephan	742	mentioned it before.)
b62f651…	stephan	743	</p>
b62f651…	stephan	744
b62f651…	stephan	745	<a name="H0011"></a>
b62f651…	stephan	746	<h3>3.5 Local declarations processed by makeheaders</h3>
b62f651…	stephan	747
b62f651…	stephan	748	<p>
b62f651…	stephan	749	Structure declarations and typedefs that appear in .c files are normally
b62f651…	stephan	750	ignored by makeheaders.
b62f651…	stephan	751	Such declarations are only intended for use by the source file in which
b62f651…	stephan	752	they appear and so makeheaders doesn't need to copy them into any
b62f651…	stephan	753	generated header files.
b62f651…	stephan	754	We call such declarations “<code>private</code>”.
b62f651…	stephan	755	</p>
b62f651…	stephan	756
b62f651…	stephan	757	<p>
b62f651…	stephan	758	Sometimes it is convenient to have makeheaders sort a sequence
b62f651…	stephan	759	of private declarations into the correct order for us automatically.
b62f651…	stephan	760	Or, we could have static functions and procedures for which we would like
b62f651…	stephan	761	makeheaders to generate prototypes, but the arguments to these
b62f651…	stephan	762	functions and procedures uses private declarations.
b62f651…	stephan	763	In both of these cases, we want makeheaders to be aware of the
b62f651…	stephan	764	private declarations and copy them into the local header file,
b62f651…	stephan	765	but we don't want makeheaders to propagate the
b62f651…	stephan	766	declarations outside of the file in which they are declared.
b62f651…	stephan	767	</p>
b62f651…	stephan	768
b62f651…	stephan	769	<p>
b62f651…	stephan	770	When this situation arises, enclose the private declarations
b62f651…	stephan	771	within
b62f651…	stephan	772	<pre>
b62f651…	stephan	773	#if LOCAL_INTERFACE
b62f651…	stephan	774	#endif
b62f651…	stephan	775	</pre>
b62f651…	stephan	776	A “<code>LOCAL_INTERFACE</code>” block works very much like the
b62f651…	stephan	777	“<code>INTERFACE</code>” and
b62f651…	stephan	778	“<code>EXPORT_INTERFACE</code>”
b62f651…	stephan	779	blocks described above, except that makeheaders insures that the
b62f651…	stephan	780	objects declared in a LOCAL_INTERFACE are only visible to the
b62f651…	stephan	781	file containing the LOCAL_INTERFACE.
b62f651…	stephan	782	</p>
b62f651…	stephan	783
b62f651…	stephan	784	<a name="H0012"></a>
b62f651…	stephan	785	<h3>3.6 Using Makeheaders With C++ Code</h3>
b62f651…	stephan	786
b62f651…	stephan	787	<p>
b62f651…	stephan	788	You can use makeheaders to generate header files for C++ code, in
b62f651…	stephan	789	addition to C.
b62f651…	stephan	790	Makeheaders will recognize and copy both “<code>class</code>”
b62f651…	stephan	791	declarations
b62f651…	stephan	792	and inline function definitions, and it knows not to try to generate
b62f651…	stephan	793	prototypes for methods.
b62f651…	stephan	794	</p>
b62f651…	stephan	795
b62f651…	stephan	796	<p>
b62f651…	stephan	797	In fact, makeheaders is smart enough to be used in projects that employ
b62f651…	stephan	798	a mixture of C and C++.
b62f651…	stephan	799	For example, if a C function is called from within a C++ code module,
b62f651…	stephan	800	makeheaders will know to prepend the text
b62f651…	stephan	801	<pre>
b62f651…	stephan	802	extern "C"
b62f651…	stephan	803	</pre>
b62f651…	stephan	804	to the prototype for that function in the C++ header file.
b62f651…	stephan	805	Going the other way,
b62f651…	stephan	806	if you try to call a C++ function from within C, an
b62f651…	stephan	807	appropriate error message is issued, since C++ routines can not
b62f651…	stephan	808	normally be called by C code (due to fact that most C++ compilers
b62f651…	stephan	809	use name mangling to facilitate type-safe linkage.)
b62f651…	stephan	810	</p>
b62f651…	stephan	811
b62f651…	stephan	812	<p>
b62f651…	stephan	813	No special command-line options are required to use makeheaders with
b62f651…	stephan	814	C++ input. Makeheaders will recognize that its source code is C++
b62f651…	stephan	815	by the suffix on the source code filename. Simple ".c" or ".h" suffixes
b62f651…	stephan	816	are assumed to be ANSI-C. Anything else, including ".cc", ".C" and
b62f651…	stephan	817	".cpp" is assumed to be C++.
b62f651…	stephan	818	The name of the header file generated by makeheaders is derived from
b62f651…	stephan	819	the name of the source file by converting every "c" to "h" and
b62f651…	stephan	820	every "C" to "H" in the suffix of the filename.
b62f651…	stephan	821	Thus the C++ source
b62f651…	stephan	822	file “<code>alpha.cpp</code>” will induce makeheaders to
b62f651…	stephan	823	generate a header file named “<code>alpha.hpp</code>”.
b62f651…	stephan	824	</p>
b62f651…	stephan	825
b62f651…	stephan	826	<p>
b62f651…	stephan	827	Makeheaders augments class definitions by inserting prototypes to
b62f651…	stephan	828	methods where appropriate. If a method definition begins with one
b62f651…	stephan	829	of the special keywords <b>PUBLIC</b>, <b>PROTECTED</b>, or
b62f651…	stephan	830	<b>PRIVATE</b> (in upper-case to distinguish them from the regular
b62f651…	stephan	831	C++ keywords with the same meaning) then a prototype for that
b62f651…	stephan	832	method will be inserted into the class definition. If none of
b62f651…	stephan	833	these keywords appear, then the prototype is not inserted. For
b62f651…	stephan	834	example, in the following code, the constructor is not explicitly
b62f651…	stephan	835	declared in the class definition but makeheaders will add it there
b62f651…	stephan	836	because of the PUBLIC keyword that appears before the constructor
b62f651…	stephan	837	definition.
b62f651…	stephan	838	</p>
b62f651…	stephan	839
b62f651…	stephan	840	<blockquote><pre>
b62f651…	stephan	841	#if INTERFACE
b62f651…	stephan	842	class Example1 {
b62f651…	stephan	843	private:
b62f651…	stephan	844	int v1;
b62f651…	stephan	845	};
b62f651…	stephan	846	#endif
b62f651…	stephan	847	PUBLIC Example1::Example1(){
b62f651…	stephan	848	v1 = 0;
b62f651…	stephan	849	}
b62f651…	stephan	850	</pre></blockquote>
b62f651…	stephan	851
b62f651…	stephan	852	<p>
b62f651…	stephan	853	The code above is equivalent to the following:
b62f651…	stephan	854	</p>
b62f651…	stephan	855
b62f651…	stephan	856	<blockquote><pre>
b62f651…	stephan	857	#if INTERFACE
b62f651…	stephan	858	class Example1 {
b62f651…	stephan	859	private:
b62f651…	stephan	860	int v1;
b62f651…	stephan	861	public:
b62f651…	stephan	862	Example1();
b62f651…	stephan	863	};
b62f651…	stephan	864	#endif
b62f651…	stephan	865	Example1::Example1(){
b62f651…	stephan	866	v1 = 0;
b62f651…	stephan	867	}
b62f651…	stephan	868	</pre></blockquote>
b62f651…	stephan	869
b62f651…	stephan	870	<p>
b62f651…	stephan	871	The first form is preferred because only a single declaration of
b62f651…	stephan	872	the constructor is required. The second form requires two declarations,
b62f651…	stephan	873	one in the class definition and one on the definition of the constructor.
b62f651…	stephan	874	</p>
b62f651…	stephan	875
b62f651…	stephan	876	<h4>3.6.1 C++ Limitations</h4>
b62f651…	stephan	877
b62f651…	stephan	878	<p>
b62f651…	stephan	879	Makeheaders does not understand more recent
b62f651…	stephan	880	C++ syntax such as templates and namespaces.
b62f651…	stephan	881	Perhaps these issues will be addressed in future revisions.
b62f651…	stephan	882	</p>
b62f651…	stephan	883
b62f651…	stephan	884	<a name="H0013"></a>
b62f651…	stephan	885	<h3>3.7 Conditional Compilation</h3>
b62f651…	stephan	886
b62f651…	stephan	887	<p>
b62f651…	stephan	888	The makeheaders program understands and tracks the conditional
b62f651…	stephan	889	compilation constructs in the source code files it scans.
b62f651…	stephan	890	Hence, if the following code appears in a source file
b62f651…	stephan	891	<pre>
b62f651…	stephan	892	#ifdef UNIX
b62f651…	stephan	893	# define WORKS_WELL 1
b62f651…	stephan	894	#else
b62f651…	stephan	895	# define WORKS_WELL 0
b62f651…	stephan	896	#endif
b62f651…	stephan	897	</pre>
b62f651…	stephan	898	then the next patch of code will appear in the generated header for
b62f651…	stephan	899	every .c file that uses the WORKS_WELL constant:
b62f651…	stephan	900	<pre>
b62f651…	stephan	901	#if defined(UNIX)
b62f651…	stephan	902	# define WORKS_WELL 1
b62f651…	stephan	903	#endif
b62f651…	stephan	904	#if !defined(UNIX)
b62f651…	stephan	905	# define WORKS_WELL 0
b62f651…	stephan	906	#endif
b62f651…	stephan	907	</pre>
b62f651…	stephan	908	The conditional compilation constructs can be nested to any depth.
b62f651…	stephan	909	Makeheaders also recognizes the special case of
b62f651…	stephan	910	<pre>
b62f651…	stephan	911	#if 0
b62f651…	stephan	912	#endif
b62f651…	stephan	913	</pre>
b62f651…	stephan	914	and treats the enclosed text as a comment.
b62f651…	stephan	915	</p>
b62f651…	stephan	916
b62f651…	stephan	917	<a name="H0014"></a>
b62f651…	stephan	918	<h3>3.8 Caveats</h3>
b62f651…	stephan	919
b62f651…	stephan	920	<p>
b62f651…	stephan	921	The makeheaders system is designed to be robust
b62f651…	stephan	922	but it is possible for a devious programmer to fool the system,
b62f651…	stephan	923	usually with unhelpful consequences.
b62f651…	stephan	924	This subsection is a guide to helping you avoid trouble.
b62f651…	stephan	925	</p>
b62f651…	stephan	926
b62f651…	stephan	927	<p>
b62f651…	stephan	928	Makeheaders does not understand the old K&R style of function
b62f651…	stephan	929	and procedure definitions.
b62f651…	stephan	930	It only understands the modern ANSI-C style, and will probably
b62f651…	stephan	931	become very confused if it encounters an old K&R function.
b62f651…	stephan	932	Therefore you should take care to avoid putting K&R function definitions
b62f651…	stephan	933	in your code.
b62f651…	stephan	934	</p>
b62f651…	stephan	935
b62f651…	stephan	936	<p>
b62f651…	stephan	937	Makeheaders does not understand when you define more than one
b62f651…	stephan	938	global variable with the same type separated by a comma.
b62f651…	stephan	939	In other words, makeheaders does not understand this:
b62f651…	stephan	940	<pre>
b62f651…	stephan	941	int a = 4, b = 5;
b62f651…	stephan	942	</pre>
b62f651…	stephan	943	The makeheaders program wants every variable to have its own
b62f651…	stephan	944	definition. Like this:
b62f651…	stephan	945	<pre>
b62f651…	stephan	946	int a = 4;
b62f651…	stephan	947	int b = 5;
b62f651…	stephan	948	</pre>
b62f651…	stephan	949	Notice that this applies to global variables only, not to variables
b62f651…	stephan	950	you declare inside your functions.
b62f651…	stephan	951	Since global variables ought to be exceedingly rare, and since it is
b62f651…	stephan	952	good style to declare them separately anyhow, this restriction is
b62f651…	stephan	953	not seen as a terrible hardship.
b62f651…	stephan	954	</p>
b62f651…	stephan	955
b62f651…	stephan	956	<p>
b62f651…	stephan	957	Makeheaders does not support defining an enumerated or aggregate type in
b62f651…	stephan	958	the same statement as a variable declaration. None of the following
b62f651…	stephan	959	statements work completely:
b62f651…	stephan	960	<pre>
b62f651…	stephan	961	struct {int field;} a;
b62f651…	stephan	962	struct Tag {int field;} b;
b62f651…	stephan	963	struct Tag c;
b62f651…	stephan	964	</pre>
b62f651…	stephan	965	Instead, define types separately from variables:
b62f651…	stephan	966	<pre>
b62f651…	stephan	967	#if INTERFACE
b62f651…	stephan	968	struct Tag {int field;};
b62f651…	stephan	969	#endif
b62f651…	stephan	970	Tag a;
b62f651…	stephan	971	Tag b; /* No more than one variable per declaration. */
b62f651…	stephan	972	Tag c; /* So must put each on its own line. */
b62f651…	stephan	973	</pre>
b62f651…	stephan	974	See <a href="#H0008">3.2 What Declarations Get Copied</a> for details,
b62f651…	stephan	975	including on the automatic typedef.
b62f651…	stephan	976	</p>
b62f651…	stephan	977
b62f651…	stephan	978	<p>
b62f651…	stephan	979	The makeheaders program processes its source file prior to sending
b62f651…	stephan	980	those files through the C preprocessor.
b62f651…	stephan	981	Hence, if you hide important structure information in preprocessor defines,
b62f651…	stephan	982	makeheaders might not be able to successfully extract the information
b62f651…	stephan	983	it needs from variables, functions and procedure definitions.
b62f651…	stephan	984	For example, if you write this:
b62f651…	stephan	985	<pre>
b62f651…	stephan	986	#define BEGIN {
b62f651…	stephan	987	#define END }
b62f651…	stephan	988	</pre>
b62f651…	stephan	989	at the beginning of your source file, and then try to create a function
b62f651…	stephan	990	definition like this:
b62f651…	stephan	991	<pre>
b62f651…	stephan	992	char StrDup(const char zSrc)
b62f651…	stephan	993	BEGIN
b62f651…	stephan	994	/* Code here */
b62f651…	stephan	995	END
b62f651…	stephan	996	</pre>
b62f651…	stephan	997	then makeheaders won't be able to find the end of the function definition
b62f651…	stephan	998	and bad things are likely to happen.
b62f651…	stephan	999	</p>
b62f651…	stephan	1000
b62f651…	stephan	1001	<p>
b62f651…	stephan	1002	For most projects the code constructs that makeheaders cannot
b62f651…	stephan	1003	handle are very rare.
b62f651…	stephan	1004	As long as you avoid excessive cleverness, makeheaders will
b62f651…	stephan	1005	probably be able to figure out what you want and will do the right
b62f651…	stephan	1006	thing.
b62f651…	stephan	1007	</p>
b62f651…	stephan	1008
b62f651…	stephan	1009	<p>
b62f651…	stephan	1010	Makeheaders has limited understanding of enums. In particular, it does
b62f651…	stephan	1011	not realize the significance of enumerated values, so the enum is not
b62f651…	stephan	1012	emitted in the header files when its enumerated values are used unless
b62f651…	stephan	1013	the name associated with the enum is also used. Moreover, enums can be
b62f651…	stephan	1014	completely anonymous, e.g. “<code>enum {X, Y, Z};</code>”.
b62f651…	stephan	1015	Makeheaders ignores such enums so they can at least be used within a
b62f651…	stephan	1016	single source file. Makeheaders expects you to use #define constants
b62f651…	stephan	1017	instead. If you want enum features that #define lacks, and you need the
b62f651…	stephan	1018	enum in the interface, bypass makeheaders and write a header file by
b62f651…	stephan	1019	hand, or teach makeheaders to emit the enum definition when any of the
b62f651…	stephan	1020	enumerated values are used, rather than only when the top-level name (if
b62f651…	stephan	1021	any) is used.
b62f651…	stephan	1022	</p>
b62f651…	stephan	1023
b62f651…	stephan	1024	<a name="H0015"></a>
b62f651…	stephan	1025	<h2>4.0 Using Makeheaders To Generate Documentation</h2>
b62f651…	stephan	1026
b62f651…	stephan	1027	<p>
b62f651…	stephan	1028	Many people have observed the advantages of generating program
b62f651…	stephan	1029	documentation directly from the source code:
b62f651…	stephan	1030	<ul>
b62f651…	stephan	1031	<li> Less effort is involved. It is easier to write a program than
b62f651…	stephan	1032	it is to write a program and a document.
b62f651…	stephan	1033	<li> The documentation is more likely to agree with the code.
b62f651…	stephan	1034	When documentation is derived directly from the code, or is
b62f651…	stephan	1035	contained in comments immediately adjacent to the code, it is much
b62f651…	stephan	1036	more likely to be correct than if it is contained in a separate
b62f651…	stephan	1037	unrelated file in a different part of the source tree.
b62f651…	stephan	1038	<li> Information is kept in only one place. When a change occurs
b62f651…	stephan	1039	in the code, it is not necessary to make a corresponding change
b62f651…	stephan	1040	in a separate document. Just rerun the documentation generator.
b62f651…	stephan	1041	</ul>
b62f651…	stephan	1042	The makeheaders program does not generate program documentation itself.
b62f651…	stephan	1043	But you can use makeheaders to parse the program source code, extract
b62f651…	stephan	1044	the information that is relevant to the documentation and to pass this
b62f651…	stephan	1045	information to another tool to do the actual documentation preparation.
b62f651…	stephan	1046	</p>
b62f651…	stephan	1047
b62f651…	stephan	1048	<p>
b62f651…	stephan	1049	When makeheaders is run with the “<code>-doc</code>” option, it
b62f651…	stephan	1050	emits no header files at all.
b62f651…	stephan	1051	Instead, it does a complete dump of its internal tables to standard
b62f651…	stephan	1052	output in a form that is easily parsed.
b62f651…	stephan	1053	This output can then be used by another program (the implementation
b62f651…	stephan	1054	of which is left as an exercise to the reader) that will use the
b62f651…	stephan	1055	information to prepare suitable documentation.
b62f651…	stephan	1056	</p>
b62f651…	stephan	1057
b62f651…	stephan	1058	<p>
b62f651…	stephan	1059	The “<code>-doc</code>” option causes makeheaders to print
b62f651…	stephan	1060	information to standard output about all of the following objects:
b62f651…	stephan	1061	<ul>
b62f651…	stephan	1062	<li> C++ class declarations
b62f651…	stephan	1063	<li> Structure and union declarations
b62f651…	stephan	1064	<li> Enumerations
b62f651…	stephan	1065	<li> Typedefs
b62f651…	stephan	1066	<li> Procedure and function definitions
b62f651…	stephan	1067	<li> Global variables
b62f651…	stephan	1068	<li> Preprocessor macros (ex: “<code>#define</code>”)
b62f651…	stephan	1069	</ul>
b62f651…	stephan	1070	For each of these objects, the following information is output:
b62f651…	stephan	1071	<ul>
b62f651…	stephan	1072	<li> The name of the object.
b62f651…	stephan	1073	<li> The type of the object. (Structure, typedef, macro, etc.)
b62f651…	stephan	1074	<li> Flags to indicate if the declaration is exported (contained within
b62f651…	stephan	1075	an EXPORT_INTERFACE block) or local (contained with LOCAL_INTERFACE).
b62f651…	stephan	1076	<li> A flag to indicate if the object is declared in a C++ file.
b62f651…	stephan	1077	<li> The name of the file in which the object was declared.
b62f651…	stephan	1078	<li> The complete text of any block comment that precedes the declarations.
b62f651…	stephan	1079	<li> If the declaration occurred inside a preprocessor conditional
b62f651…	stephan	1080	(“<code>#if</code>”) then the text of that conditional is
b62f651…	stephan	1081	provided.
b62f651…	stephan	1082	<li> The complete text of a declaration for the object.
b62f651…	stephan	1083	</ul>
b62f651…	stephan	1084	The exact output format will not be described here.
b62f651…	stephan	1085	It is simple to understand and parse and should be obvious to
b62f651…	stephan	1086	anyone who inspects some sample output.
b62f651…	stephan	1087	</p>
b62f651…	stephan	1088
b62f651…	stephan	1089	<a name="H0016"></a>
b62f651…	stephan	1090	<h2>5.0 Compiling The Makeheaders Program</h2>
b62f651…	stephan	1091
b62f651…	stephan	1092	<p>
b62f651…	stephan	1093	The source code for makeheaders is a single file of ANSI-C code,
b62f651…	stephan	1094	approximately 3000 lines in length.
b62f651…	stephan	1095	The program makes only modest demands of the system and C library
b62f651…	stephan	1096	and should compile without alteration on most ANSI C compilers
b62f651…	stephan	1097	and on most operating systems.
b62f651…	stephan	1098	It is known to compile using several variations of GCC for Unix
b62f651…	stephan	1099	as well as Cygwin32 and MSVC 5.0 for Win32.
b62f651…	stephan	1100	</p>
b62f651…	stephan	1101
b62f651…	stephan	1102	<a name="H0017"></a>
b62f651…	stephan	1103	<h2>6.0 History</h2>
b62f651…	stephan	1104
b62f651…	stephan	1105	<p>
b62f651…	stephan	1106	The makeheaders program was first written by D. Richard Hipp
b62f651…	stephan	1107	(also the original author of
b62f651…	stephan	1108	<a href="https://sqlite.org/">SQLite</a> and
b62f651…	stephan	1109	<a href="https://fossil-scm.org/">Fossil</a>) in 1993.
b62f651…	stephan	1110	Hipp open-sourced the project immediately, but it never caught
b62f651…	stephan	1111	on with any other developers and it continued to be used mostly
b62f651…	stephan	1112	by Hipp himself for over a decade. When Hipp was first writing
b62f651…	stephan	1113	the Fossil version control system in 2006 and 2007, he used
b62f651…	stephan	1114	makeheaders on that project to help simplify the source code.
b62f651…	stephan	1115	As the popularity of Fossil increased, the makeheaders
b62f651…	stephan	1116	that was incorporated into the Fossil source tree became the
b62f651…	stephan	1117	"official" makeheaders implementation.
b62f651…	stephan	1118	</p>
b62f651…	stephan	1119
b62f651…	stephan	1120	<p>
b62f651…	stephan	1121	As this paragraph is being composed (2016-11-05), Fossil is the
b62f651…	stephan	1122	only project known to Hipp that is still using makeheaders. On
b62f651…	stephan	1123	the other hand, makeheaders has served the Fossil project well and
b62f651…	stephan	1124	there are no plans remove it.
b62f651…	stephan	1125	</p>
b62f651…	stephan	1126
b62f651…	stephan	1127	<a name="H0018"></a>
b62f651…	stephan	1128	<h2>7.0 Summary And Conclusion</h2>
b62f651…	stephan	1129
b62f651…	stephan	1130	<p>
b62f651…	stephan	1131	The makeheaders program will automatically generate a minimal header file
b62f651…	stephan	1132	for each of a set of C source and header files, and will
b62f651…	stephan	1133	generate a composite header file for the entire source file suite,
b62f651…	stephan	1134	for either internal or external use.
b62f651…	stephan	1135	It can also be used as the parser in an automated program
b62f651…	stephan	1136	documentation system.
b62f651…	stephan	1137	</p>
b62f651…	stephan	1138
b62f651…	stephan	1139	<p>
b62f651…	stephan	1140	The makeheaders program has been in use since 1994,
b62f651…	stephan	1141	in a wide variety of projects under both UNIX and Win32.
b62f651…	stephan	1142	In every project where it has been used, makeheaders has proven
b62f651…	stephan	1143	to be a very helpful aid
b62f651…	stephan	1144	in the construction and maintenance of large C codes.
b62f651…	stephan	1145	In at least two cases, makeheaders has facilitated development
b62f651…	stephan	1146	of programs that would have otherwise been all but impossible
b62f651…	stephan	1147	due to their size and complexity.
b62f651…	stephan	1148	</p>
b62f651…	stephan	1149	</body>
b62f651…	stephan	1150	</html>

Fossil SCM

Keyboard Shortcuts