<title>Adding Features To Fossil</title>
<h2>1.0 Introduction</h2>
This article provides a brief overview of how to write new code that extends
or enhances Fossil.
<h2>2.0 Programming Language</h2>
Fossil is written in C-89. There are specific [./style.wiki | style guidelines]
that are required for any new code that will be accepted into the Fossil core.
But, of course, if you are writing an extension just for yourself, you can
use any programming style you want.
The source code for Fossil is not sent directly into the C compiler.
There are three separate code [./makefile.wiki#preprocessing|preprocessors]
that run over the code first.
1. The <b>mkindex</b> preprocessor scans all regular source files looking
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
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
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
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
** here.
*/
#include "config.h"
#include "xyzzy.h"
#if INTERFACE
/* Exported object (structure) definitions or #defines
** go here */
#endif /* INTERFACE */
/* New code goes here */
</verbatim></blockquote>
Note in particular the <b>#include "xyzzy.h"</b> line near the top.
The "xyzzy.h" file is automatically generated by makeheaders. Every
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
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.
It is recommended that you try this.
Be sure to [/help/add|fossil add] your new source file to the self-hosting
Fossil repository and then [/help/commit|commit] your changes!
<h2>4.0 Creating A New Command</h2>
By "commands" we mean the keywords that follow "fossil" when invoking
Fossil from the command-line. So, for example, in
<b>fossil diff xyzzy.c</b>
The "command" is "diff". Commands may optionally be followed by
arguments and/or options. To create new commands in Fossil, add code
(either to an existing source file, or to a new source file created as
described above) according to the following template:
<blockquote><verbatim>
/*
** COMMAND: xyzzy
**
** Help text goes here.
*/
void xyzzy_cmd(void){
/* Implement the command here */
fossil_print("Hello, World!\n");
}
</verbatim></blockquote>
The example above creates a new command named "xyzzy" that prints the
message "Hello, World!" on the console. This command is a normal command
that will show up in the list of command from [/help/help|fossil help].
If you add an asterisk to the end of the command name, like this:
<blockquote><verbatim>
** COMMAND: xyzzy*
</verbatim></blockquote>
Then the command will only show up if you add the "--all" option to
[/help/help|fossil help]. Or, if the command name starts with
"test" then the command will be considered experimental and will only
show up when the --test option is used with [/help/help|fossil help].
The example above is a fully functioning Fossil command. You can add
the text shown to an existing Fossil source file, recompiling then test
it out by typing:
<b>./fossil xyzzy<br>
./fossil help xyzzy<br>
./fossil xyzzy --help</b>
The name of the C function that implements the command can be anything
you like (as long as it does not collide with some other symbol in the
Fossil code) but it is traditional to name the function
"<i>commandname</i><b>_cmd</b>", as is done in the example.
You could also use "printf()" instead of "fossil_print()" to generate
the output text, if desired. But "fossil_print()" is recommended as
it has extra logic to insert \r characters at the right times on
Windows systems.
Once you have the command running, you can then start adding code to
make it do useful things. There are lots of utility functions in
Fossil for parsing command-line options and for
opening and accessing and manipulating the repository and
the working check-out. Study implementations of existing commands
to get an idea of how things are done. You can easily find the implementations
of existing commands by searching for "COMMAND: <i>name</i>" in the
files of the "src/" directory.
<h2>5.0 Creating A New Web Page</h2>
As with commands, new webpages can be added simply by inserting a function
that generates the webpage together with a special header comment. A
template follows:
<blockquote><verbatim>
/*
** WEBPAGE: helloworld
*/
void helloworld_page(void){
style_header("Hello World!");
@ <p>Hello, World!</p>
style_footer();
}
</verbatim></blockquote>
Add the code above to a new or existing Fossil source code file, then
recompile fossil and run [/help/ui|fossil ui] then enter
"http://localhost:8080/helloworld" in your web browser and the routine
above will generate a web page that says "Hello World."
It really is that simple.
The special "WEBPAGE:" comment is picked up by the "mkindex" preprocessor
and used to generate a table that maps the "helloworld" webpage name
into a pointer to the "helloworld_page()" function. The function that
implements a webpage can be named anything you like (as long as it does
not collide with another name) but the traditional name is
"<i>pagename</i><b>_page</b>".
HTML pages begin with a call to style_header() and end with the call to
style_footer(). Content is generated by the "@" lines that are translated
(by the "translate" preprocessor) into printf-like code that generates the
content of the webpage. Different techniques are used to generate
non-HTML content. In the unlikely event that you need to generate
non-HTML content, look at existing webpage implementations
(ex: "logo" or "style.css") to see how that is done.
There are lots of other things that a real web-page implementation will
need to do, such verifying user credentials, parsing query parameters,
and interacting with the repository. But now that you have the general
idea of how webpages are implemented, you can look at the many other
webpage implementations already built into Fossil to see how all that
works.
<h2>6.0 See Also</h2>
* [./makefile.wiki|The Fossil Build Process]
* [./tech_overview.wiki|A Technical Overview Of Fossil]
* [./contribute.wiki|Contributing To The Fossil Project]