20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
|
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
|
-
+
-
+
-
+
-
+
|
for special comments that contain "help" text and which identify routines
that implement specific commands or which generate particular web pages.
2. The <b>makeheaders</b> preprocessor generates all the ".h" files
automatically. Fossil programmers write ".c" files only and let the
makeheaders preprocessor create the ".h" files.
3. The <b>translate</b> preprocessor converts source code lines that
3. The <b>translate</b> preprocessor converts source code lines that
begin with "@" into string literals, or into print statements that
generate web page output, depending on context.
The [./makefile.wiki|Makefile] for Fossil takes care of running these
preprocessors with all the right arguments and in the right order. So it is
not necessary to understand the details of how these preprocessors work.
(Though, the sources for all three preprocessors are included in the source
tree and are well commented, if you want to dig deeper.) It is only necessary
to know that these preprocessors exist and hence will effect the way you
write code.
<h2>3.0 Adding New Source Code Files</h2>
New source code files are added in the "src/" subdirectory of the Fossil
source tree. Suppose one wants to add a new source code file named
"xyzzy.c". The first step is to add this file to the various makefiles.
Do so by editing the file src/makemake.tcl and adding "xyzzy" (without
Do so by editing the file src/makemake.tcl and adding "xyzzy" (without
the final ".c") to the list of source modules at the top of that script.
Save the result and then run the makemake.tcl script using a TCL
Save the result and then run the makemake.tcl script using a TCL
interpreter. The command to run the makemake.tcl script is:
<b>tclsh makemake.tcl</b>
The working directory must be src/ when the command above is run.
Note that TCL is not normally required to build Fossil, but
it is required for this step. If you do not have a TCL interpreter on
your system already, they are easy to install. A popular choice is the
[http://www.activestate.com/activetcl|Active Tcl] installation from
ActiveState.
After the makefiles have been updated, create the xyzzy.c source file
from the following template:
<blockquote><verbatim>
/*
** Copyright boilerplate goes here.
*****************************************************
** High-level description of what this module goes
** High-level description of what this module goes
** here.
*/
#include "config.h"
#include "xyzzy.h"
#if INTERFACE
/* Exported object (structure) definitions or #defines
|
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
-
+
|
normal Fossil source file must have a #include at the top that imports
its private header file. (Some source files, such as "sqlite3.c" are
exceptions to this rule. Don't worry about those exceptions. The
files you write will require this #include line.)
The "#if INTERFACE ... #endif" section is optional and is only needed
if there are structure definitions or typedefs or macros that need to
be used by other source code files. The makeheaders preprocessor
be used by other source code files. The makeheaders preprocessor
uses definitions in the INTERFACE section to help it generate header
files. See [../src/makeheaders.html | makeheaders.html] for additional
information.
After creating a template file such as shown above, and after updating
the makefiles, you should be able to recompile Fossil and have it include
your new source file, even before you source file contains any code.
|