Fossil

<title>The Fossil Build Process</title>

<h1>1.0 Introduction</h1>

The build process for Fossil is tricky in that the source code
needs to be processed by three different preprocessor programs
before it is compiled.  Most users will download a 
before it is compiled.  Most users will download a
[http://www.fossil-scm.org/download.html | precompiled binary]
so this is of no consequence to them, and even those who
want to compile the code themselves can use one of the 
[./build.wiki | existing makefiles].  
want to compile the code themselves can use one of the
[./build.wiki | existing makefiles].
So must people do not need to be concerned with the
build complexities of Fossil.  But hard-core developers who desire
a deep understanding of how Fossil is put together can benefit
from reviewing this article.

<a name="srctour"></a>
<h1>2.0 Source Code Tour</h1>

The source code for Fossil is found in the 
The source code for Fossil is found in the
[/dir?ci=trunk&name=src | src/] subdirectory of the
source tree.  The src/ subdirectory contains all code, including
the code for the separate preprocessor programs.

Each preprocessor program is a separate C program implemented in
a single file of C source code.  The three preprocessor programs
are:

shell.c file from the SQLite release.

The TH1 script engine is implemented using files:

  7.  th.c
  8.  th.h

These two files are imports like the SQLite source files, 
These two files are imports like the SQLite source files,
and so are not preprocessed.

The VERSION.h header file is generated from other information sources
using a small program called:

  9.  mkversion.c

Finally, there is one of the makefiles generated by makemake.tcl:

  13.  main.mk

The main.mk makefile is invoked from the Makefile in the top-level
directory.  The main.mk is generated by makemake.tcl and should not
be hand edited.  Other makefiles generated by makemake.tcl are in 
be hand edited.  Other makefiles generated by makemake.tcl are in
other subdirectories (currently all in the win/ subdirectory).

All the other files in the src/ subdirectory (79 files at the time of
this writing) are C source code files that are subject to the
preprocessing steps described below.  In the sequel, we will call these
other files "src.c" in order to have a convenient name.   The reader
should understand that whenever "src.c" or "src.h" is used in the text

"manifest.uuid", and "VERSION" source files in the root directory of the
source tree.
(The "manifest" and "manifest.uuid" files are automatically generated and
updated by Fossil itself.  See the [/help/setting | fossil set manifest]
command for additional information.)

The VERSION.h header file is generated by
a C program: src/mkversion.c.  
a C program: src/mkversion.c.
To run the VERSION.h generator, first compile the src/mkversion.c
 source file into a command-line program (named "mkversion.exe")
then run:

<blockquote><pre>
mkversion.exe manifest.uuid manifest VERSION &gt;VERSION.h
</pre></blockquote>

The pathnames in the above command might need to be adjusted to get the
directories right.  The point is that the manifest.uuid, manifest, and
VERSION files
in the root of the source tree are the three arguments and
the generated VERSION.h file appears on standard output.

The builtin_data.h header file is generated by a C program: src/mkbuiltin.c.
The builtin_data.h file contains C-langauge byte-array definitions for
the content of resource files used by Fossil.  To generate the 
the content of resource files used by Fossil.  To generate the
builtin_data.h file, first compile the mkbuiltin.c program, then run:

<blockquote><pre>
mkbuiltin.exe diff.tcl <i>OtherFiles...</i> &gt;builtin_data.h
</pre></blockquote>

At the time of this writing, the "diff.tcl" script (a Tcl/Tk script used

</pre></blockquote>

Note that "src.c" in the above is a stand-in for the (79) regular source
files of Fossil - all source files except for the exceptions described in
section 2.0 above.

The output of the mkindex program is a header file that is #include-ed by
the main.c source file during the final compilation step.  
the main.c source file during the final compilation step.

<h2>4.2 The translate preprocessor</h2>

The translate preprocessor looks for lines of source code that begin
with "@" and converts those lines into string constants or (depending on
context) into special "printf" operations for generating the output of
an HTTP request.  The translate preprocessor is a simple C program whose
sources are in the translate.c source file.  The translate preprocess
is run on each of the other ordinary source files separately, like this:

<blockquote><pre>
./translate src.c >src_.c
</pre></blockquote>

In this case, the "src.c" file represents any single source file from the
set of ordinary source files as described in section 2.0 above.  Note that
each source file is translated separately.  By convention, the names of
the translated source files are the names of the input sources with a 
the translated source files are the names of the input sources with a
single "_" character at the end.  But a new makefile can use any naming
convention it wants - the "_" is not critical to the build process.

After being translated, the output files (the "src_.c" files) should be
used for all subsequent preprocessing and compilation steps.

<h2>4.3 The makeheaders preprocessor</h2>

is like this:

<blockquote><pre>
makeheaders src_.c:src.h sqlite3.h th.h VERSION.h
</pre></blockquote>

In the example above the "src_.c" and "src.h" names represent all of the
(79) ordinary C source files, each as a separate argument.  
(79) ordinary C source files, each as a separate argument.

<h1>5.0 Compilation</h1>

After all generated files have been created and all ordinary source files
have been preprocessed, the generated and preprocessed files can be 
have been preprocessed, the generated and preprocessed files can be
combined into a single executable using a C compiler.  This can be done
all at once, or each preprocessed source file can be compiled into a
separate object code file and the resulting object code files linked
together in a final step.

Some files require special C-preprocessor macro definitions.
When compiling sqlite.c, the following macros are recommended:

When compiling the shell.c source file, these macros are required:

  *  -Dmain=sqlite3_main
  *  -DSQLITE_OMIT_LOAD_EXTENSION=1

The "main()" routine in the shell must be changed into sqlite3_main()
to prevent it from colliding with the real main() in Fossil, and to give
Fossil an entry point to jump to when the 
Fossil an entry point to jump to when the
[/help/sqlite3 | fossil sql] command is invoked.

All the other source code files can be compiled without any special
options.

<h1>6.0 Linkage</h1>