Fossil

Check-in [b6a4e859]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Add end-tags to the anchors in the /doc/trunk/src/makeheaders.html document.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:b6a4e8592d58ead7878f4a072fc6c4da71c7ea97
User & Date: drh 2011-01-28 19:09:04
Original Comment: Add end-tags to the anchors in the [doc/trunk/src/makeheaders.html] document.
Context
2011-01-29
03:56
Documentation updates. check-in: 20b2767f user: drh tags: trunk
2011-01-28
20:56
Add a new meta-data table named LEAF that holds a precomputed set of all leaves in the checkin DAG. Use this precomputed table rather than trying to compute the LEAFs on the fly, as a performance enhancement for repositories with many checkins. A rebuild is required. check-in: 69f43fc0 user: drh tags: experimental
19:09
Add end-tags to the anchors in the /doc/trunk/src/makeheaders.html document. check-in: b6a4e859 user: drh tags: trunk
14:09
Add hyperlinks to the "user:" and "tags:" marks in timelines. check-in: 13165785 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to src/makeheaders.html.

41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
..
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
...
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
...
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
...
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
...
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
...
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
...
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
...
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
...
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
...
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
...
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
...
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
....
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
<li><a href=makeheaders.html#H0014>3.8 Caveats</a>
</ul>
<li><a href=makeheaders.html#H0015>4.0 Using Makeheaders To Generate Documentation</a>

<li><a href=makeheaders.html#H0016>5.0 Compiling The Makeheaders Program</a>

<li><a href=makeheaders.html#H0017>6.0 Summary And Conclusion</a>
</ul><a name=H0002>
<h2>1.0 Background</h2>

<p>
A piece of C source code can be one of two things:
a <em>declaration</em> or a <em>definition</em>.
A declaration is source text that gives information to the
compiler but doesn't directly result in any code being generated.
................................................................................
The .c files contain ``<code>#include</code>'' preprocessor statements
that cause the contents of .h files to be included as part of the
source code when the .c file is compiled.
In this way, the .h files define the interface to a subsystem and
the .c files define how the subsystem is implemented.
</p>

<a name=H0003>
<h3>1.1 Problems With The Traditional Approach</h3>

<p>
As the art of computer programming continues to advance, and the size
and complexity of programs continues to swell, the traditional C
approach of placing declarations and definitions in separate files begins
to present the programmer with logistics and
................................................................................
In a program with complex, interwoven data structures, the correct
declaration order can become very difficult to determine manually, 
especially when the declarations involved are spread out over several
files.
</ol>
</p>

<a name=H0004>
<h3>1.2 The Makeheaders Solution</h3>

<p>
The makeheaders program is designed to ameliorate the problems associated
with the traditional C programming model by automatically generating
the interface information in the .h files from 
interface information contained in other .h files and
................................................................................
so that makeheaders will be run automatically whenever the project
is rebuilt.
And the burden of running makeheaders is light.
It will easily process tens of thousands of lines of source
code per second.
</p>

<a name=H0005>
<h2>2.0 Running The Makeheaders Program</h2>

<p>
The makeheaders program is very easy to run.
If you have a collection of C source code and include files in the working
directory, then you can run makeheaders to generate appropriate .h
files using the following command:
................................................................................
you can prepend a ``./'' to its name in order to get it
accepted by the command line parser.
Or, you can insert the special option ``--'' on the command
line to cause all subsequent command line arguments to be treated as
filenames even if their names beginn with ``-''.
</p>

<a name=H0006>
<h2>3.0 Preparing Source Files For Use With Makeheaders</h2>

<p>
Very little has to be done to prepare source files for use with
makeheaders since makeheaders will read and understand ordinary
C code.
But it is important that you structure your files in a way that
makes sense in the makeheaders context.
This section will describe several typical uses of makeheaders.
</p>

<a name=H0007>
<h3>3.1 The Basic Setup</h3>

<p>
The simpliest way to use makeheaders is to put all definitions in
one or more .c files and all structure and type declarations in
separate .h files.
The only restriction is that you should take care to chose basenames 
................................................................................
those entered manually be the programmer and others generated automatically
by a prior run of makeheaders.
But that is not a problem.
The makeheaders program will recognize and ignore any files it 
has previously generated that show up on its input list.
</p>

<a name=H0008>
<h3>3.2 What Declarations Get Copied</h3>

<p>
The following list details all of the code constructs that makeheaders
will extract and place in
the automatically generated .h files:
</p>
................................................................................
As a final note, we observe that automatically generated declarations
are ordered as required by the ANSI-C programming language.
If the declaration of some structure ``X'' requires a prior
declaration of another structure ``Y'', then Y will appear
first in the generated headers.
</p>

<a name=H0009>
<h3>3.3 How To Avoid Having To Write Any Header Files</h3>

<p>
In my experience, large projects work better if all of the manually
written code is placed in .c files and all .h files are generated
automatically.
This is slightly different for the traditional C method of placing
................................................................................
``#if INTERFACE'' regions of .c files.
Makeheaders treats all declarations alike, no matter where they
come from.
You should also note that a single .c file can contain as many
``#if INTERFACE'' regions as desired.
</p>

<a name=H0010>
<h3>3.4 Designating Declarations For Export</h3>

<p>
In a large project, one will often construct a hierarchy of
interfaces.
For example, you may have a group of 20 or so files that form
a library used in several other parts of the system.
................................................................................
The ``#if EXPORT_INTERFACE'' mechanism can be used in either
.c or .h files.
(The ``#if INTERFACE'' can also be used in both .h and .c files, 
but since it's use in a .h file would be redundant, we haven't mentioned
it before.)
</p>

<a name=H0011>
<h3>3.5 Local declarations processed by makeheaders</h3>

<p>
Structure declarations and typedefs that appear in .c files are normally
ignored by makeheaders.
Such declarations are only intended for use by the source file in which
they appear and so makeheaders doesn't need to copy them into any
................................................................................
A ``LOCAL_INTERFACE'' block works very much like the
``INTERFACE'' and ``EXPORT_INTERFACE''
blocks described above, except that makeheaders insures that the
objects declared in a LOCAL_INTERFACE are only visible to the
file containing the LOCAL_INTERFACE.
</p>

<a name=H0012>
<h3>3.6 Using Makeheaders With C++ Code</h3>

<p>
You can use makeheaders to generate header files for C++ code, in
addition to C.
Makeheaders will recognize and copy both ``class'' declarations
and inline function definitions, and it knows not to try to generate
................................................................................

<p>
Makeheaders does not understand more recent
C++ syntax such as templates and namespaces.
Perhaps these issued will be addressed in future revisions.
</p>

<a name=H0013>
<h3>3.7 Conditional Compilation</h3>

<p>
The makeheaders program understands and tracks the conditional 
compilation constructs in the source code files it scans.
Hence, if the following code appears in a source file
<pre>
................................................................................
<pre>
  #if 0
  #endif
</pre>
and treats the enclosed text as a comment.
</p>

<a name=H0014>
<h3>3.8 Caveats</h3>

<p>
The makeheaders system is designed to be robust
but it is possible for a devious programmer to fool the system,
usually with unhelpful consequences.
This subsection is a guide to helping you avoid trouble.
................................................................................
For most projects the code constructs that makeheaders cannot
handle are very rare.
As long as you avoid excessive cleverness, makeheaders will
probably be able to figure out what you want and will do the right
thing.
</p>

<a name=H0015>
<h2>4.0 Using Makeheaders To Generate Documentation</h2>

<p>
Many people have observed the advantages of generating program
documentation directly from the source code:
<ul>
<li> Less effort is involved.  It is easier to write a program than
................................................................................
<li> The complete text of a declaration for the object.
</ul>
The exact output format will not be described here.
It is simple to understand and parse and should be obvious to
anyone who inspects some sample output.
</p>

<a name=H0016>
<h2>5.0 Compiling The Makeheaders Program</h2>

<p>
The source code for makeheaders is a single file of ANSI-C code,
less than 3000 lines in length.
The program makes only modest demands of the system and C library
and should compile without alteration on most ANSI C compilers
and on most operating systems.
It is known to compile using several variations of GCC for Unix
as well as Cygwin32 and MSVC 5.0 for Win32.
</p>

<a name=H0017>
<h2>6.0 Summary And Conclusion</h2>

<p>
The makeheaders program will automatically generate a minimal header file 
for each of a set of C source and header files, and will
generate a composite header file for the entire source file suite,
for either internal or external use.







|







 







|







 







|







 







|







 







|











|







 







|







 







|







 







|







 







|







 







|







 







|







 







|







 







|







 







|












|







41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
..
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
...
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
...
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
...
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
...
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
...
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
...
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
...
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
...
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
...
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
...
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
...
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
....
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
<li><a href=makeheaders.html#H0014>3.8 Caveats</a>
</ul>
<li><a href=makeheaders.html#H0015>4.0 Using Makeheaders To Generate Documentation</a>

<li><a href=makeheaders.html#H0016>5.0 Compiling The Makeheaders Program</a>

<li><a href=makeheaders.html#H0017>6.0 Summary And Conclusion</a>
</ul><a name="H0002"></a>
<h2>1.0 Background</h2>

<p>
A piece of C source code can be one of two things:
a <em>declaration</em> or a <em>definition</em>.
A declaration is source text that gives information to the
compiler but doesn't directly result in any code being generated.
................................................................................
The .c files contain ``<code>#include</code>'' preprocessor statements
that cause the contents of .h files to be included as part of the
source code when the .c file is compiled.
In this way, the .h files define the interface to a subsystem and
the .c files define how the subsystem is implemented.
</p>

<a name="H0003"></a>
<h3>1.1 Problems With The Traditional Approach</h3>

<p>
As the art of computer programming continues to advance, and the size
and complexity of programs continues to swell, the traditional C
approach of placing declarations and definitions in separate files begins
to present the programmer with logistics and
................................................................................
In a program with complex, interwoven data structures, the correct
declaration order can become very difficult to determine manually, 
especially when the declarations involved are spread out over several
files.
</ol>
</p>

<a name="H0004"></a>
<h3>1.2 The Makeheaders Solution</h3>

<p>
The makeheaders program is designed to ameliorate the problems associated
with the traditional C programming model by automatically generating
the interface information in the .h files from 
interface information contained in other .h files and
................................................................................
so that makeheaders will be run automatically whenever the project
is rebuilt.
And the burden of running makeheaders is light.
It will easily process tens of thousands of lines of source
code per second.
</p>

<a name="H0005"></a>
<h2>2.0 Running The Makeheaders Program</h2>

<p>
The makeheaders program is very easy to run.
If you have a collection of C source code and include files in the working
directory, then you can run makeheaders to generate appropriate .h
files using the following command:
................................................................................
you can prepend a ``./'' to its name in order to get it
accepted by the command line parser.
Or, you can insert the special option ``--'' on the command
line to cause all subsequent command line arguments to be treated as
filenames even if their names beginn with ``-''.
</p>

<a name="H0006"></a>
<h2>3.0 Preparing Source Files For Use With Makeheaders</h2>

<p>
Very little has to be done to prepare source files for use with
makeheaders since makeheaders will read and understand ordinary
C code.
But it is important that you structure your files in a way that
makes sense in the makeheaders context.
This section will describe several typical uses of makeheaders.
</p>

<a name="H0007"></a>
<h3>3.1 The Basic Setup</h3>

<p>
The simpliest way to use makeheaders is to put all definitions in
one or more .c files and all structure and type declarations in
separate .h files.
The only restriction is that you should take care to chose basenames 
................................................................................
those entered manually be the programmer and others generated automatically
by a prior run of makeheaders.
But that is not a problem.
The makeheaders program will recognize and ignore any files it 
has previously generated that show up on its input list.
</p>

<a name="H0008"></a>
<h3>3.2 What Declarations Get Copied</h3>

<p>
The following list details all of the code constructs that makeheaders
will extract and place in
the automatically generated .h files:
</p>
................................................................................
As a final note, we observe that automatically generated declarations
are ordered as required by the ANSI-C programming language.
If the declaration of some structure ``X'' requires a prior
declaration of another structure ``Y'', then Y will appear
first in the generated headers.
</p>

<a name="H0009"></a>
<h3>3.3 How To Avoid Having To Write Any Header Files</h3>

<p>
In my experience, large projects work better if all of the manually
written code is placed in .c files and all .h files are generated
automatically.
This is slightly different for the traditional C method of placing
................................................................................
``#if INTERFACE'' regions of .c files.
Makeheaders treats all declarations alike, no matter where they
come from.
You should also note that a single .c file can contain as many
``#if INTERFACE'' regions as desired.
</p>

<a name="H0010"></a>
<h3>3.4 Designating Declarations For Export</h3>

<p>
In a large project, one will often construct a hierarchy of
interfaces.
For example, you may have a group of 20 or so files that form
a library used in several other parts of the system.
................................................................................
The ``#if EXPORT_INTERFACE'' mechanism can be used in either
.c or .h files.
(The ``#if INTERFACE'' can also be used in both .h and .c files, 
but since it's use in a .h file would be redundant, we haven't mentioned
it before.)
</p>

<a name="H0011"></a>
<h3>3.5 Local declarations processed by makeheaders</h3>

<p>
Structure declarations and typedefs that appear in .c files are normally
ignored by makeheaders.
Such declarations are only intended for use by the source file in which
they appear and so makeheaders doesn't need to copy them into any
................................................................................
A ``LOCAL_INTERFACE'' block works very much like the
``INTERFACE'' and ``EXPORT_INTERFACE''
blocks described above, except that makeheaders insures that the
objects declared in a LOCAL_INTERFACE are only visible to the
file containing the LOCAL_INTERFACE.
</p>

<a name="H0012"></a>
<h3>3.6 Using Makeheaders With C++ Code</h3>

<p>
You can use makeheaders to generate header files for C++ code, in
addition to C.
Makeheaders will recognize and copy both ``class'' declarations
and inline function definitions, and it knows not to try to generate
................................................................................

<p>
Makeheaders does not understand more recent
C++ syntax such as templates and namespaces.
Perhaps these issued will be addressed in future revisions.
</p>

<a name="H0013"></a>
<h3>3.7 Conditional Compilation</h3>

<p>
The makeheaders program understands and tracks the conditional 
compilation constructs in the source code files it scans.
Hence, if the following code appears in a source file
<pre>
................................................................................
<pre>
  #if 0
  #endif
</pre>
and treats the enclosed text as a comment.
</p>

<a name="H0014"></a>
<h3>3.8 Caveats</h3>

<p>
The makeheaders system is designed to be robust
but it is possible for a devious programmer to fool the system,
usually with unhelpful consequences.
This subsection is a guide to helping you avoid trouble.
................................................................................
For most projects the code constructs that makeheaders cannot
handle are very rare.
As long as you avoid excessive cleverness, makeheaders will
probably be able to figure out what you want and will do the right
thing.
</p>

<a name="H0015"></a>
<h2>4.0 Using Makeheaders To Generate Documentation</h2>

<p>
Many people have observed the advantages of generating program
documentation directly from the source code:
<ul>
<li> Less effort is involved.  It is easier to write a program than
................................................................................
<li> The complete text of a declaration for the object.
</ul>
The exact output format will not be described here.
It is simple to understand and parse and should be obvious to
anyone who inspects some sample output.
</p>

<a name="H0016"></a>
<h2>5.0 Compiling The Makeheaders Program</h2>

<p>
The source code for makeheaders is a single file of ANSI-C code,
less than 3000 lines in length.
The program makes only modest demands of the system and C library
and should compile without alteration on most ANSI C compilers
and on most operating systems.
It is known to compile using several variations of GCC for Unix
as well as Cygwin32 and MSVC 5.0 for Win32.
</p>

<a name="H0017"></a>
<h2>6.0 Summary And Conclusion</h2>

<p>
The makeheaders program will automatically generate a minimal header file 
for each of a set of C source and header files, and will
generate a composite header file for the entire source file suite,
for either internal or external use.