Documentation Source Text

be accomplished using start-time [sqlite3_config | (1)]
or runtime
[sqlite3_db_config | (2)]
[sqlite3_limit | (3)]
[sqlite3_vfs_register | (4)] configuration methods
or via [compile-time options].  It is very rare that an application 
developer will need to edit the SQLite source code in order to 
incorporate SQLite into a product.<p>

<p>We call custom modifications to the SQLite source code that are held
for the use of a single application a "private branch".  When a private
branch becomes necessary, the application developer must take on the
task of keeping the private branch in synchronization with the public
SQLite sources.  This is tedious.  It can also be tricky, since while
the SQLite file format and published interfaces are very stable, the
internal implementation of SQLite changes quite rapidly.  Hundreds or
thousands of lines of code might change for any given SQLite point release.
</p>

<p>This article outlines one possible method for keeping a private branch
of SQLite in sync with the public SQLite source code.
There are many ways of maintaining a private branch, of course.
Nobody is compelled to use the method describe here.
This article is not trying to impose a particular procedure on 
maintainers of private branches.  The point of this article is to offer
an example of one process for maintaining a private branch which can
be used as a template for designing processes best suited for the
circumstances of each individual project.</p>

<img src="images/private_branch.gif" align="right">
<h1>2.0 The Basic Idea</h1>


<p>We propose to use the
<a href="http://www.fossil-scm.org">fossil software configuration management</a>
system to set up two branches.  One branch (the "public branch" or "trunk")
contains the published SQLite sources and the other branch is the 
private branch which contains the code that is customized for the project.
Whenever a new public release of SQLite is made, that release is added to
the public branch and then the changes are merged into the private branch.</p>

<p>This document proposed to use
<a href="http://www.fossil-scm.org/">fossil</a>,
but any other distributed software configuration management system such as
<a href="http://www.monotone.ca/">monotone</a> or
<a href="http://www.selenic.com/mercurial/wiki/">mercurial</a> (a.k.a. "hg"), or
<a href="http://www.git-scm.org/">git</a> could serve just as well.
The concept will be the same, 
though the specifics of the procedure will vary.</p>

<p>The diagram at the right illustrates the concept.
One begins with a standard SQLite release.  For the
sake of example, suppose that one intends to create a
private branch off of SQLite version 3.6.15.  In the
diagram this is version (1).  The
maintainer makes an exact copy of the the baseline
SQLite into the branch space, shown as version (2).
Note that (1) and (2) are exactly the same.  Then
the maintainer applies the private changes to 
version (2) resulting in version (3).  In other words,
version (3) is SQLite version 3.6.15 plus edits.</p>

<p>Later, SQLite version 3.6.15 is released, as shown 
by circle (4) in the diagram.  At the point, the private
branch maintainer does a merge which takes all of the
changes going from (1) to (4) and applies those changes to
(3).  The result is version (5), which is SQLite 3.6.12
plus edits.</p>

<p>There might be merge conflicts.  In other words, it might
be that the changes from (2) to (3) are incompatible with the
changes from (1) to (4).  In that case, the maintainer will
have to manually resolve the conflicts.  Hopefully conflicts
will not come up that often.  Conflicts are less likely to
occur when the private edits are kept to a minimum.</p>

<p>The cycle above can be repeated many times.  The
diagram shows a third SQLite release, 3.6.17 in
circle (6).  The private branch maintainer can do
another merge in order to incorporate the changes
moving from (4) to (6) into the private branch, resulting
in version (7).</p>

<h1>3.0 The Procedure</h1>

<p>The remainder of this document will guide the reader through
the steps needed to maintain a private branch.  The general idea
is the same as outlined above.  This section merely provides more
detail.</p>

<p>We emphasize again that these steps are not intended to be the only
acceptable method for maintaining private branch.  This approach
is one of many.  Use this document as a baseline for preparing
project-specific procedures.  Do not be afraid to experiment.</p>

<h2>3.1 Obtain The Software</h2>

<p><a href="http://www.fossil-scm.org/">Fossil</a> is a computer program
that must be installed on your machine before you use it.
Fortunately, installing fossil is very easy.  Fossil is a single
"*.exe" file that you simply download and run.  To uninstall fossil,
simply delete the exe file.  
<a href="http://www.fossil-scm.org/index.html/doc/tip/www/quickstart.wiki">
Detailed instructions</a> for installing and getting started with
fossil are available on the 
<a href="http://www.fossil-scm.org">fossil website</a>.</p>

<p>If you want to configure the new project, type:</p>

<blockquote><pre>
fossil ui private-project.fossil
</pre></blockquote>

<p>The "ui" command will cause fossil to run a miniature built-in webserver
and to launch your web-browser pointing
at that webserver.  You can use your web-browser to configure your project
in various ways.  See the instructions on the fossil website for additional
information.</p>

<p>Once the project repository is created, create an open checkout of the
project by moving to the directory where you want to keep all of the
project source code and typing:</p>

<blockquote><pre>
fossil open private-project.fossil
</pre></blockquote>

<p>You can have multiple checkouts of the same project if you want. 
And you can "clone" the repository to different machines so that multiple
developers can use it.  See the fossil website for further information.</p>

<h2>3.3 Installing The SQLite Baseline In Fossil</h2>

<p>The repository created in the previous set is initially empty.  The
next step is to load the baseline SQLite release - circle (1) in the diagram
above.</p>

<p>Begin by obtaining a copy of SQLite in whatever form you use it.
The public SQLite you obtain should be as close to your private edited
copy as possible.  If your project uses the SQLite amalgamation, then
get a copy of the the amalgamation.  If you use the preprocessed separate
source files, get those instead.  Put all the source files in the

fossil timeline
fossil info
fossil status
</pre></blockquote>

<h2>3.4 Creating The Private Branch</h2>

<p>The previous step created circle (1) in the diagram above.
This step will create circle (2).  Run the following command:</p>

<blockquote><pre> 
fossil branch new private trunk -bgcolor "#add8e8"
</pre></blockquote>

<p>This command will create a new branch named "private" (you can use
a different name if you like) and assign it a background color

<blockquote><pre>
fossil commit
</pre></blockquote>

<p>You will be prompted once again to enter a commit describing your
changes.  Then the commit will occur.  The commit creates a new checkin
in the repository that corresponds to circle (3) in the diagram above.</p>

<p>Now that the public and private branches are different, you can run
the "<tt>fossil update trunk</tt>" and "<tt>fossil update private</tt>"
commands and see that fossil really does change the files in the checkout
as you switch back and forth between branches.</p>

<p>Note that in the diagram above, we showed the private edits as a single
commit.  This was for clarity of presentation only.  There is nothing to stop
you from doing dozens or hundreds of separate tiny changes and committing
each separately.  In fact, making many small changes is the preferred way
to work.  The only reason for doing all the changes in a single commit
is that it makes the diagram easier to draw.</p>

<h2>3.6 Incorporating New Public SQLite Releases</h2>

<p>Suppose that after a while (about a month, usually) a new version of

files that are in the checkout.<p>

<p>If you made NL to CR-NL line ending changes or space to tab
indentation changes in the original baseline, make the same changes
to the new source file.</p>

<p>Once everything is ready, run the "<tt>fossil commit</tt>" command to
check in the changes.  This creates circle (4) in the diagram above.</p>

<h2>3.7 Merging Public SQLite Updates Into The Private Branch</h2>

<p>The next step is to move the changes in the public branch over into
the private branch.  In other words, we want to create circle (5) in the
diagram above.  Begin by changing to the private branch using
"<tt>fossil update private</tt>".  Then type this command:</p>

<blockquote><pre>
fossil merge trunk
</pre></blockquote>

<p>The "merge" command attempts to apply all the changes between
circles (1) and (4) to the files in the local checkout.  Note that
circle (5) has not been created yet.  You will need to run the
"commit" to create circle (5).</p>

<p>It might be that there are conflicts in the merge.  Conflicts
occur when the same line of code was changed in different ways between
circles (1) and "4 versus circles (2) and (3).  The merge command will
announce any conflicts and will include both versions of the conflicting
lines in the output.  You will need to bring up the files that contain
conflicts and manually resolve the conflicts.</p>

<p>After resolving conflicts, many users like to compile and test the
new version before committing it to the repository.  Or you can commit
first and test later.  Either way, run the "<tt>fossil commit</tt>"
command to check-in the circle (5) version.

<h2>3.8 Further Updates</h2>

<p>As new versions of SQLite are released, repeat steps 3.6 and 3.7 to
add changes in the new release to the private branch.
Additional private changes can be
made on the private branch in between releases if desired.</p>