1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
|
<!DOCTYPE html>
<html><head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link href="sqlite.css" rel="stylesheet">
<title>Maintaining Private Branches Of SQLite</title>
<!-- path= -->
</head>
<body>
<div class=nosearch>
<a href="index.html">
<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite" border="0">
</a>
<div><!-- IE hack to prevent disappearing logo --></div>
<div class="tagline desktoponly">
Small. Fast. Reliable.<br>Choose any three.
</div>
<div class="menu mainmenu">
<ul>
<li><a href="index.html">Home</a>
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
<li class='wideonly'><a href='about.html'>About</a>
<li class='desktoponly'><a href="docs.html">Documentation</a>
<li class='desktoponly'><a href="download.html">Download</a>
<li class='wideonly'><a href='copyright.html'>License</a>
<li class='desktoponly'><a href="support.html">Support</a>
<li class='desktoponly'><a href="prosupport.html">Purchase</a>
<li class='search' id='search_menubutton'>
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
</ul>
</div>
<div class="menu submenu" id="submenu">
<ul>
<li><a href='about.html'>About</a>
<li><a href='docs.html'>Documentation</a>
<li><a href='download.html'>Download</a>
<li><a href='support.html'>Support</a>
<li><a href='prosupport.html'>Purchase</a>
</ul>
</div>
<div class="searchmenu" id="searchmenu">
<form method="GET" action="search">
<select name="s" id="searchtype">
<option value="d">Search Documentation</option>
<option value="c">Search Changelog</option>
</select>
<input type="text" name="q" id="searchbox" value="">
<input type="submit" value="Go">
</form>
</div>
</div>
<script>
function toggle_div(nm) {
var w = document.getElementById(nm);
if( w.style.display=="block" ){
w.style.display = "none";
}else{
w.style.display = "block";
}
}
function toggle_search() {
var w = document.getElementById("searchmenu");
if( w.style.display=="block" ){
w.style.display = "none";
} else {
w.style.display = "block";
setTimeout(function(){
document.getElementById("searchbox").focus()
}, 30);
}
}
function div_off(nm){document.getElementById(nm).style.display="none";}
window.onbeforeunload = function(e){div_off("submenu");}
/* Disable the Search feature if we are not operating from CGI, since */
/* Search is accomplished using CGI and will not work without it. */
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
document.getElementById("search_menubutton").style.display = "none";
}
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
function hideorshow(btn,obj){
var x = document.getElementById(obj);
var b = document.getElementById(btn);
if( x.style.display!='none' ){
x.style.display = 'none';
b.innerHTML='show';
}else{
x.style.display = '';
b.innerHTML='hide';
}
return false;
}
var antiRobot = 0;
function antiRobotGo(){
if( antiRobot!=3 ) return;
antiRobot = 7;
var j = document.getElementById("mtimelink");
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
}
function antiRobotDefense(){
document.body.onmousedown=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousedown=null;
}
document.body.onmousemove=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousemove=null;
}
setTimeout(function(){
antiRobot |= 1;
antiRobotGo();
}, 100)
antiRobotGo();
}
antiRobotDefense();
</script>
<div class=fancy>
<div class=nosearch>
<div class="fancy_title">
Maintaining Private Branches Of SQLite
</div>
<div class="fancy_toc">
<a onclick="toggle_toc()">
<span class="fancy_toc_mark" id="toc_mk">►</span>
Table Of Contents
</a>
<div id="toc_sub"><div class="fancy-toc1"><a href="#_introduction">1. Introduction</a></div>
<div class="fancy-toc1"><a href="#_the_basic_idea">2. The Basic Idea</a></div>
<div class="fancy-toc1"><a href="#_the_procedure">3. The Procedure</a></div>
<div class="fancy-toc2"><a href="#_obtain_the_software">3.1. Obtain The Software</a></div>
<div class="fancy-toc2"><a href="#_create_a_project_repository">3.2. Create A Project Repository</a></div>
<div class="fancy-toc2"><a href="#_installing_the_sqlite_baseline_in_fossil">3.3. Installing The SQLite Baseline In Fossil</a></div>
<div class="fancy-toc2"><a href="#_creating_the_private_branch">3.4. Creating The Private Branch</a></div>
<div class="fancy-toc2"><a href="#_adding_customizations_to_the_code_in_the_private_branch">3.5. Adding Customizations To The Code In The Private Branch</a></div>
<div class="fancy-toc2"><a href="#_incorporating_new_public_sqlite_releases">3.6. Incorporating New Public SQLite Releases</a></div>
<div class="fancy-toc2"><a href="#_merging_public_sqlite_updates_into_the_private_branch">3.7. Merging Public SQLite Updates Into The Private Branch</a></div>
<div class="fancy-toc2"><a href="#_further_updates">3.8. Further Updates</a></div>
<div class="fancy-toc1"><a href="#_variations">4. Variations</a></div>
</div>
</div>
<script>
function toggle_toc(){
var sub = document.getElementById("toc_sub")
var mk = document.getElementById("toc_mk")
if( sub.style.display!="block" ){
sub.style.display = "block";
mk.innerHTML = "▼";
} else {
sub.style.display = "none";
mk.innerHTML = "►";
}
}
</script>
</div>
<h1 id="_introduction"><span>1. </span> Introduction</h1>
<p>SQLite is designed to meet most developer's needs without any
changes or customization. When changes are needed, they can normally
be accomplished using start-time <a href="c3ref/config.html">(1)</a>
or runtime
<a href="c3ref/db_config.html">(2)</a>
<a href="c3ref/limit.html">(3)</a>
<a href="c3ref/vfs_find.html">(4)</a> configuration methods
or via <a href="compile.html">compile-time options</a>. 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>
</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 id="_the_basic_idea"><span>2. </span> 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 proposes 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 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.16 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.16
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 id="_the_procedure"><span>3. </span> 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 id="_obtain_the_software"><span>3.1. </span> 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>
<h2 id="_create_a_project_repository"><span>3.2. </span> Create A Project Repository</h2>
<p>Create a fossil repository to host the private branch using the
following command:</p>
<blockquote><pre>
fossil new private-project.fossil
</pre></blockquote>
<p>You can call your project anything you like. The "<tt>.fossil</tt>"
suffix is optional. For this document, we will continue to call the
project "<tt>private-project.fossil</tt>". Note that
<tt>private-project.fossil</tt> is an ordinary disk file (actually an
SQLite database) that will contain your complete project history.
You can make a backup of the project simply by making a copy of that
one file.</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 id="_installing_the_sqlite_baseline_in_fossil"><span>3.3. </span> Installing The SQLite Baseline In Fossil</h2>
<p>The repository created in the previous step 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 amalgamation. If you use the preprocessed separate
source files, get those instead. Put all the source files in the
checkout directory created in the previous step.</p>
<p>The source code in public SQLite releases uses unix line endings
(ASCII code 10: "newline" only, NL) and spaces instead of tabs. If you will
be changing the line ending to windows-style line endings
(ASCII codes 13, 10: "carriage-return" and "newline"; CR-NL) or if you will be
changing space indents into tab indents, <b>make that change now</b>
before you check in the baseline. The merging process will only work
well if the differences between the public and the private branches are
minimal. If every single line of the source file is changed in the
private branch because you changed from NL to CR-NL line endings, then
the merge steps will not work correctly.</p>
<p>Let us assume that you are using the amalgamation source code.
Add the baseline to your project as follows:</p>
<blockquote><pre>
fossil add sqlite3.c sqlite3.h
</pre></blockquote>
<p>If you are using separate source files, name all of the source files instead
of just the two amalgamation source files. Once this is done, commit your
changes as follows:</p>
<blockquote><pre>
fossil commit
</pre></blockquote>
<p>You will be prompted for a check-in comment. Say whatever you like.
After the commit completes, your baseline will be part of the repository.
The following command, if you like, to see this on the "timeline":
</p>
<blockquote><pre>
fossil ui
</pre></blockquote>
<p>That last command is the same "ui" command that we ran before. It
starts a mini-webserver running and points your web browser at it. But
this time we didn't have to specify the repository file because we are
located inside a checkout and so fossil can figure out the repository for
itself. If you want to type in the repository filename as the second
argument, you can. But it is optional.</p>
<p>If you do not want to use your web browser to view the new check-in,
you can get some information from the command-line using commands like
these:
</p><blockquote><pre>
fossil timeline
fossil info
fossil status
</pre></blockquote>
<h2 id="_creating_the_private_branch"><span>3.4. </span> 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
of light blue ("#add8e8"). You can omit the background color if you want,
though having a distinct background does make it easier to tell the
branch from the "trunk" (the public branch) on timeline displays. You
can change the background color of the private branch or of the public
branch (the "trunk") using the web interface if you like.</p>
<p>The command above created the new branch. But your checkout is
still on the trunk - a fact you can see by running the command:</p>
<blockquote><pre>
fossil info
</pre></blockquote>
<p>To change your check-out to the private branch, type:</p>
<blockquote><pre>
fossil update private
</pre></blockquote>
<p>You can run the "info" command again to verify that you are on the
private branch. To go back to the public branch, type:</p>
<blockquote><pre>
fossil update trunk
</pre></blockquote>
<p>Normally, fossil will modify all the files in your checkout when switching
between the private and the public branches. But at this point, the files
are identical in both branches so no modifications need to be made.</p>
<h2 id="_adding_customizations_to_the_code_in_the_private_branch"><span>3.5. </span> Adding Customizations To The Code In The Private Branch</h2>
<p>Now it is time to make the private, custom modifications to SQLite
which are the whole point of this exercise. Switch to the private branch
(if you are not already there) using the "<tt>fossil update private</tt>"
command, then bring up the source files in your text editor and make
whatever changes you want to make. Once you have finished making
changes, commit those changes using this command:</p>
<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 id="_incorporating_new_public_sqlite_releases"><span>3.6. </span> Incorporating New Public SQLite Releases</h2>
<p>Suppose that after a while (about a month, usually) a new version of
SQLite is released: 3.6.16. You will want to incorporate this new
public version of SQLite into your repository in the public branch (the
trunk). To do this, first change your repository over to the trunk:</p>
<blockquote><pre>
fossil update trunk
</pre></blockquote>
<p>Then download the new version of the SQLite sources and overwrite the
files that are in the checkout.</p><p>
</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 id="_merging_public_sqlite_updates_into_the_private_branch"><span>3.7. </span> 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.
</p><h2 id="_further_updates"><span>3.8. </span> 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>
<h1 id="_variations"><span>4. </span> Variations</h1>
<p>Since this document was first written, the canonical SQLite source code
has been moved from the venerable CVS system into a Fossil repository at
<a href="https://www.sqlite.org/src">https://www.sqlite.org/src</a>. This means that if you are working with
canonical SQLite source code (as opposed to the <a href="amalgamation.html">amalgamation</a> source code
files, sqlite3.c and sqlite3.h) then you can create a private repository
simply by cloning the official repository:</p>
<blockquote><pre>
fossil clone https://www.sqlite.org/src private-project.fossil
</pre></blockquote>
<p>This command both creates the new repository and populates it with
all the latest SQLite code. You can then create a private branch as
described in section 3.4.</p>
<p>When the private repository is created by cloning, incorporating new
public SQLite releases becomes much easier too. To pull in all of the
latest changes from the public SQLite repository, simply move into
the open check-out and do:</p>
<blockquote><pre>
fossil update
</pre></blockquote>
<p>Then continue to merge the changes in "trunk" with your "private"
changes as described in section 3.7.</p>
|
