Fossil SCM

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

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button