1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
3
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
4
<title>Private Branches Of SQLite</title>
5
<style type="text/css">
8
font-family: Verdana, sans-serif;
13
a:visited { color: #734559 }
15
.logo { position:absolute; margin:3px; }
31
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
32
.toolbar a:visited { color: white; }
33
.toolbar a:hover { color: #044a64; background: white; }
35
.content { margin: 5%; }
36
.content dt { font-weight:bold; }
37
.content dd { margin-bottom: 25px; margin-left:20%; }
38
.content ul { padding:0px; padding-left: 15px; margin:0px; }
41
.se { background: url(images/se.gif) 100% 100% no-repeat #044a64}
42
.sw { background: url(images/sw.gif) 0% 100% no-repeat }
43
.ne { background: url(images/ne.gif) 100% 0% no-repeat }
44
.nw { background: url(images/nw.gif) 0% 0% no-repeat }
46
/* Things for "fancyformat" documents start here. */
47
.fancy img+p {font-style:italic}
48
.fancy .codeblock i { color: darkblue; }
49
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
50
.fancy h2 { margin-left: 10px }
51
.fancy h3 { margin-left: 20px }
52
.fancy h4 { margin-left: 30px }
53
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
54
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
55
.fancy #toc a { color: darkblue ; text-decoration: none }
56
.fancy .todo { color: #AA3333 ; font-style : italic }
57
.fancy .todo:before { content: 'TODO:' }
58
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
59
.fancy img { display:block; }
60
.fancy :link:hover, .fancy :visited:hover { background: wheat }
61
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
62
.fancy li p { margin: 1em 0 }
63
/* End of "fancyformat" specific rules. */
69
<div><!-- container div to satisfy validator -->
72
<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite Logo"
74
<div><!-- IE hack to prevent disappearing logo--></div>
75
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
77
<table width=100% style="clear:both"><tr><td>
78
<div class="se"><div class="sw"><div class="ne"><div class="nw">
79
<table width=100% style="padding:0;margin:0;cell-spacing:0"><tr>
82
<a href="about.html">About</a>
83
<a href="sitemap.html">Sitemap</a>
84
<a href="docs.html">Documentation</a>
85
<a href="download.html">Download</a>
86
<a href="copyright.html">License</a>
87
<a href="news.html">News</a>
88
<a href="support.html">Support</a>
91
gMsg = "Search SQLite Docs..."
92
function entersearch() {
93
var q = document.getElementById("q");
94
if( q.value == gMsg ) { q.value = "" }
95
q.style.color = "black"
96
q.style.fontStyle = "normal"
98
function leavesearch() {
99
var q = document.getElementById("q");
100
if( q.value == "" ) {
102
q.style.color = "#044a64"
103
q.style.fontStyle = "italic"
108
<div style="padding:0 1em 0px 0;white-space:nowrap">
109
<form name=f method="GET" action="http://www.sqlite.org/search">
110
<input id=q name=q type=text
111
onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
112
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
116
</div></div></div></div>
118
<div class=startsearch></div>
124
Maintaining Private Branches Of SQLite
127
<h2>1.0 Introduction</h2>
129
<p>SQLite is designed to meet most developer's needs without any
130
changes or customization. When changes are needed, they can normally
131
be accomplished using start-time <a href="c3ref/config.html">(1)</a>
133
<a href="c3ref/db_config.html">(2)</a>
134
<a href="c3ref/limit.html">(3)</a>
135
<a href="c3ref/vfs_find.html">(4)</a> configuration methods
136
or via <a href="compile.html">compile-time options</a>. It is very rare that an application
137
developer will need to edit the SQLite source code in order to
138
incorporate SQLite into a product.<p>
140
<p>We call custom modifications to the SQLite source code that are held
141
for the use of a single application a "private branch". When a private
142
branch becomes necessary, the application developer must take on the
143
task of keeping the private branch in synchronization with the public
144
SQLite sources. This is tedious. It can also be tricky, since while
145
the SQLite file format and published interfaces are very stable, the
146
internal implementation of SQLite changes quite rapidly. Hundreds or
147
thousands of lines of code might change for any given SQLite point release.
150
<p>This article outlines one possible method for keeping a private branch
151
of SQLite in sync with the public SQLite source code.
152
There are many ways of maintaining a private branch, of course.
153
Nobody is compelled to use the method describe here.
154
This article is not trying to impose a particular procedure on
155
maintainers of private branches. The point of this article is to offer
156
an example of one process for maintaining a private branch which can
157
be used as a template for designing processes best suited for the
158
circumstances of each individual project.</p>
160
<img src="images/private_branch.gif" align="right">
161
<h2>2.0 The Basic Idea</h2>
164
<p>We propose to use the
165
<a href="http://www.fossil-scm.org">fossil software configuration management</a>
166
system to set up two branches. One branch (the "public branch" or "trunk")
167
contains the published SQLite sources and the other branch is the
168
private branch which contains the code that is customized for the project.
169
Whenever a new public release of SQLite is made, that release is added to
170
the public branch and then the changes are merged into the private branch.</p>
172
<p>This document proposes to use
173
<a href="http://www.fossil-scm.org/">fossil</a>,
174
but any other distributed software configuration management system such as
175
<a href="http://www.monotone.ca/">monotone</a> or
176
<a href="http://www.selenic.com/mercurial/wiki/">mercurial</a> (a.k.a. "hg"), or
177
<a href="http://www.git-scm.org/">git</a> could serve just as well.
178
The concept will be the same,
179
though the specifics of the procedure will vary.</p>
181
<p>The diagram at the right illustrates the concept.
182
One begins with a standard SQLite release. For the
183
sake of example, suppose that one intends to create a
184
private branch off of SQLite version 3.6.15. In the
185
diagram this is version (1). The
186
maintainer makes an exact copy of the baseline
187
SQLite into the branch space, shown as version (2).
188
Note that (1) and (2) are exactly the same. Then
189
the maintainer applies the private changes to
190
version (2) resulting in version (3). In other words,
191
version (3) is SQLite version 3.6.15 plus edits.</p>
193
<p>Later, SQLite version 3.6.16 is released, as shown
194
by circle (4) in the diagram. At the point, the private
195
branch maintainer does a merge which takes all of the
196
changes going from (1) to (4) and applies those changes to
197
(3). The result is version (5), which is SQLite 3.6.16
200
<p>There might be merge conflicts. In other words, it might
201
be that the changes from (2) to (3) are incompatible with the
202
changes from (1) to (4). In that case, the maintainer will
203
have to manually resolve the conflicts. Hopefully conflicts
204
will not come up that often. Conflicts are less likely to
205
occur when the private edits are kept to a minimum.</p>
207
<p>The cycle above can be repeated many times. The
208
diagram shows a third SQLite release, 3.6.17 in
209
circle (6). The private branch maintainer can do
210
another merge in order to incorporate the changes
211
moving from (4) to (6) into the private branch, resulting
214
<h2>3.0 The Procedure</h2>
216
<p>The remainder of this document will guide the reader through
217
the steps needed to maintain a private branch. The general idea
218
is the same as outlined above. This section merely provides more
221
<p>We emphasize again that these steps are not intended to be the only
222
acceptable method for maintaining private branch. This approach
223
is one of many. Use this document as a baseline for preparing
224
project-specific procedures. Do not be afraid to experiment.</p>
226
<h3>3.1 Obtain The Software</h3>
228
<p><a href="http://www.fossil-scm.org/">Fossil</a> is a computer program
229
that must be installed on your machine before you use it.
230
Fortunately, installing fossil is very easy. Fossil is a single
231
"*.exe" file that you simply download and run. To uninstall fossil,
232
simply delete the exe file.
233
<a href="http://www.fossil-scm.org/index.html/doc/tip/www/quickstart.wiki">Detailed instructions</a> for installing and getting started with
234
fossil are available on the
235
<a href="http://www.fossil-scm.org">fossil website</a>.</p>
237
<h3>3.2 Create A Project Repository</h3>
239
<p>Create a fossil repository to host the private branch using the
240
following command:</p>
243
fossil new private-project.fossil
246
<p>You can call your project anything you like. The "<tt>.fossil</tt>"
247
suffix is optional. For this document, we will continue to call the
248
project "<tt>private-project.fossil</tt>". Note that
249
<tt>private-project.fossil</tt> is an ordinary disk file (actually an
250
SQLite database) that will contain your complete project history.
251
You can make a backup of the project simply by making a copy of that
254
<p>If you want to configure the new project, type:</p>
257
fossil ui private-project.fossil
260
<p>The "ui" command will cause fossil to run a miniature built-in webserver
261
and to launch your web-browser pointing
262
at that webserver. You can use your web-browser to configure your project
263
in various ways. See the instructions on the fossil website for additional
266
<p>Once the project repository is created, create an open checkout of the
267
project by moving to the directory where you want to keep all of the
268
project source code and typing:</p>
271
fossil open private-project.fossil
274
<p>You can have multiple checkouts of the same project if you want.
275
And you can "clone" the repository to different machines so that multiple
276
developers can use it. See the fossil website for further information.</p>
278
<h3>3.3 Installing The SQLite Baseline In Fossil</h3>
280
<p>The repository created in the previous step is initially empty. The
281
next step is to load the baseline SQLite release - circle (1) in the diagram
284
<p>Begin by obtaining a copy of SQLite in whatever form you use it.
285
The public SQLite you obtain should be as close to your private edited
286
copy as possible. If your project uses the SQLite amalgamation, then
287
get a copy of the amalgamation. If you use the preprocessed separate
288
source files, get those instead. Put all the source files in the
289
checkout directory created in the previous step.</p>
291
<p>The source code in public SQLite releases uses unix line endings
292
(ASCII code 10: "newline" only, NL) and spaces instead of tabs. If you will
293
be changing the line ending to windows-style line endings
294
(ASCII codes 13, 10: "carriage-return" and "newline"; CR-NL) or if you will be
295
changing space indents into tab indents, <b>make that change now</b>
296
before you check in the baseline. The merging process will only work
297
well if the differences between the public and the private branches are
298
minimal. If every single line of the source file is changed in the
299
private branch because you changed from NL to CR-NL line endings, then
300
the merge steps will not work correctly.</p>
302
<p>Let us assume that you are using the amalgamation source code.
303
Add the baseline to your project as follows:</p>
306
fossil add sqlite3.c sqlite3.h
309
<p>If you are using separate source files, name all of the source files instead
310
of just the two amalgamation source files. Once this is done, commit your
311
changes as follows:</p>
317
<p>You will be prompted for a check-in comment. Say whatever you like.
318
After the commit completes, your baseline will be part of the repository.
319
The following command, if you like, to see this on the "timeline":
326
<p>That last command is the same "ui" command that we ran before. It
327
starts a mini-webserver running and points your web browser at it. But
328
this time we didn't have to specify the repository file because we are
329
located inside a checkout and so fossil can figure out the repository for
330
itself. If you want to type in the repository filename as the second
331
argument, you can. But it is optional.</p>
333
<p>If you do not want to use your web browser to view the new check-in,
334
you can get some information from the command-line using commands like
343
<h3>3.4 Creating The Private Branch</h3>
345
<p>The previous step created circle (1) in the diagram above.
346
This step will create circle (2). Run the following command:</p>
349
fossil branch new private trunk -bgcolor "#add8e8"
352
<p>This command will create a new branch named "private" (you can use
353
a different name if you like) and assign it a background color
354
of light blue ("#add8e8"). You can omit the background color if you want,
355
though having a distinct background does make it easier to tell the
356
branch from the "trunk" (the public branch) on timeline displays. You
357
can change the background color of the private branch or of the public
358
branch (the "trunk") using the web interface if you like.</p>
360
<p>The command above created the new branch. But your checkout is
361
still on the trunk - a fact you can see by running the command:</p>
367
<p>To change your check-out to the private branch, type:</p>
370
fossil update private
373
<p>You can run the "info" command again to verify that you are on the
374
private branch. To go back to the public branch, type:</p>
380
<p>Normally, fossil will modify all the files in your checkout when switching
381
between the private and the public branches. But at this point, the files
382
are identical in both branches so not modifications need to be made.</p>
384
<h3>3.5 Adding Customizations To The Code In The Private Branch</h3>
386
<p>Now it is time to make the private, custom modifications to SQLite
387
which are the whole point of this exercise. Switch to the private branch
388
(if you are not already there) using the "<tt>fossil update private</tt>"
389
command, then bring up the source files in your text editor and make
390
whatever changes you want to make. Once you have finished making
391
changes, commit those changes using this command:</p>
397
<p>You will be prompted once again to enter a commit describing your
398
changes. Then the commit will occur. The commit creates a new checkin
399
in the repository that corresponds to circle (3) in the diagram above.</p>
401
<p>Now that the public and private branches are different, you can run
402
the "<tt>fossil update trunk</tt>" and "<tt>fossil update private</tt>"
403
commands and see that fossil really does change the files in the checkout
404
as you switch back and forth between branches.</p>
406
<p>Note that in the diagram above, we showed the private edits as a single
407
commit. This was for clarity of presentation only. There is nothing to stop
408
you from doing dozens or hundreds of separate tiny changes and committing
409
each separately. In fact, making many small changes is the preferred way
410
to work. The only reason for doing all the changes in a single commit
411
is that it makes the diagram easier to draw.</p>
413
<h3>3.6 Incorporating New Public SQLite Releases</h3>
415
<p>Suppose that after a while (about a month, usually) a new version of
416
SQLite is released: 3.6.16. You will want to incorporate this new
417
public version of SQLite into your repository in the public branch (the
418
trunk). To do this, first change your repository over to the trunk:</p>
424
<p>Then download the new version of the SQLite sources and overwrite the
425
files that are in the checkout.<p>
427
<p>If you made NL to CR-NL line ending changes or space to tab
428
indentation changes in the original baseline, make the same changes
429
to the new source file.</p>
431
<p>Once everything is ready, run the "<tt>fossil commit</tt>" command to
432
check in the changes. This creates circle (4) in the diagram above.</p>
434
<h3>3.7 Merging Public SQLite Updates Into The Private Branch</h3>
436
<p>The next step is to move the changes in the public branch over into
437
the private branch. In other words, we want to create circle (5) in the
438
diagram above. Begin by changing to the private branch using
439
"<tt>fossil update private</tt>". Then type this command:</p>
445
<p>The "merge" command attempts to apply all the changes between
446
circles (1) and (4) to the files in the local checkout. Note that
447
circle (5) has not been created yet. You will need to run the
448
"commit" to create circle (5).</p>
450
<p>It might be that there are conflicts in the merge. Conflicts
451
occur when the same line of code was changed in different ways between
452
circles (1) and (4) versus circles (2) and (3). The merge command will
453
announce any conflicts and will include both versions of the conflicting
454
lines in the output. You will need to bring up the files that contain
455
conflicts and manually resolve the conflicts.</p>
457
<p>After resolving conflicts, many users like to compile and test the
458
new version before committing it to the repository. Or you can commit
459
first and test later. Either way, run the "<tt>fossil commit</tt>"
460
command to check-in the circle (5) version.
462
<h3>3.8 Further Updates</h3>
464
<p>As new versions of SQLite are released, repeat steps 3.6 and 3.7 to
465
add changes in the new release to the private branch.
466
Additional private changes can be
467
made on the private branch in between releases if desired.</p>
469
<h2>4.0 Variations</h2>
471
<p>Since this document was first written, the canonical SQLite source code
472
has been moved from the venerable CVS system into a Fossil repository at
473
<a href="http://www.sqlite.org/src">http://www.sqlite.org/src</a>. This means that if you are working with
474
canonical SQLite source code (as opposed to the <a href="amalgamation.html">amalgamation</a> source code
475
files, sqlite3.c and sqlite3.h) then you can create a private repository
476
simply by cloning the official repository:</p>
479
fossil clone http://www.sqlite.org/src private-project.fossil
482
<p>This command both creates the new repository and populates it with
483
all the latest SQLite could. You can the create a private branch as
484
described in section 3.4.</p>
486
<p>When the private repository is created by cloning, incorporating new
487
public SQLite releases becomes much easier too. To pull in all of the
488
latest changes from the public SQLite repository, simply move into
489
the open check-out and do:</p>
495
<p>Then continue to merge the changes in "trunk" with your "private"
496
changes as described in section 3.7.</p>
added
removed
privatebranch.html
