Debian Codegraph @

www/privatebranch.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="sqlite.css" rel="stylesheet">
6 <title>Maintaining Private Branches Of SQLite</title>
7 <!-- path= -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="index.html">
12 <img class="logo" src="images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='about.html'>About</a>
23 <li class='desktoponly'><a href="docs.html">Documentation</a>
24 <li class='desktoponly'><a href="download.html">Download</a>
25 <li class='wideonly'><a href='copyright.html'>License</a>
26 <li class='desktoponly'><a href="support.html">Support</a>
27 <li class='desktoponly'><a href="prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='about.html'>About</a>
35 <li><a href='docs.html'>Documentation</a>
36 <li><a href='download.html'>Download</a>
37 <li><a href='support.html'>Support</a>
38 <li><a href='prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118 <div class=fancy>
119 <div class=nosearch>
120 <div class="fancy_title">
121 Maintaining Private Branches Of SQLite
122 </div>
123 <details class="fancy_toc">
124 <summary>Table Of Contents</summary>
125 <div id="toc_sub"><div class="fancy-toc1"><a href="#_introduction">1. Introduction</a></div>
126 <div class="fancy-toc1"><a href="#_the_basic_idea">2. The Basic Idea</a></div>
127 <div class="fancy-toc1"><a href="#_the_procedure">3. The Procedure</a></div>
128 <div class="fancy-toc2"><a href="#_obtain_the_software">3.1. Obtain The Software</a></div>
129 <div class="fancy-toc2"><a href="#_create_a_project_repository">3.2. Create A Project Repository</a></div>
130 <div class="fancy-toc2"><a href="#_installing_the_sqlite_baseline_in_fossil">3.3. Installing The SQLite Baseline In Fossil</a></div>
131 <div class="fancy-toc2"><a href="#_creating_the_private_branch">3.4. Creating The Private Branch</a></div>
132 <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>
133 <div class="fancy-toc2"><a href="#_incorporating_new_public_sqlite_releases">3.6. Incorporating New Public SQLite Releases</a></div>
134 <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>
135 <div class="fancy-toc2"><a href="#_further_updates">3.8. Further Updates</a></div>
136 <div class="fancy-toc1"><a href="#_variations">4. Variations</a></div>
137 </div>
138 </details>
139 </div>
140
141
142
143
144
145 <h1 id="_introduction"><span>1. </span> Introduction</h1>
146
147 <p>SQLite is designed to meet most developer's needs without any
148 changes or customization. When changes are needed, they can normally
149 be accomplished using start-time <a href="c3ref/config.html">(1)</a>
150 or runtime
151 <a href="c3ref/db_config.html">(2)</a>
152 <a href="c3ref/limit.html">(3)</a>
153 <a href="c3ref/vfs_find.html">(4)</a> configuration methods
154 or via <a href="compile.html">compile-time options</a>. It is very rare that an application
155 developer will need to edit the SQLite source code in order to
156 incorporate SQLite into a product.</p><p>
157
158 </p><p>We call custom modifications to the SQLite source code that are held
159 for the use of a single application a "private branch". When a private
160 branch becomes necessary, the application developer must take on the
161 task of keeping the private branch in synchronization with the public
162 SQLite sources. This is tedious. It can also be tricky, since while
163 the SQLite file format and published interfaces are very stable, the
164 internal implementation of SQLite changes quite rapidly. Hundreds or
165 thousands of lines of code might change for any given SQLite point release.
166 </p>
167
168 <p>This article outlines one possible method for keeping a private branch
169 of SQLite in sync with the public SQLite source code.
170 There are many ways of maintaining a private branch, of course.
171 Nobody is compelled to use the method described here.
172 This article is not trying to impose a particular procedure on
173 maintainers of private branches. The point of this article is to offer
174 an example of one process for maintaining a private branch which can
175 be used as a template for designing processes best suited for the
176 circumstances of each individual project.</p>
177
178 <img src="images/private_branch.gif" align="right">
179 <h1 id="_the_basic_idea"><span>2. </span> The Basic Idea</h1>
180
181
182 <p>We propose to use the
183 <a href="http://www.fossil-scm.org">fossil software configuration management</a>
184 system to set up two branches. One branch (the "public branch" or "trunk")
185 contains the published SQLite sources and the other branch is the
186 private branch which contains the code that is customized for the project.
187 Whenever a new public release of SQLite is made, that release is added to
188 the public branch and then the changes are merged into the private branch.</p>
189
190 <p>This document proposes to use
191 <a href="http://www.fossil-scm.org/">fossil</a>,
192 but any other distributed software configuration management system such as
193 <a href="http://www.monotone.ca/">monotone</a> or
194 <a href="http://www.selenic.com/mercurial/wiki/">mercurial</a> (a.k.a. "hg"), or
195 <a href="http://www.git-scm.org/">git</a> could serve just as well.
196 The concept will be the same,
197 though the specifics of the procedure will vary.</p>
198
199 <p>The diagram at the right illustrates the concept.
200 One begins with a standard SQLite release. For the
201 sake of example, suppose that one intends to create a
202 private branch off of SQLite version 3.6.15. In the
203 diagram this is version (1). The
204 maintainer makes an exact copy of the baseline
205 SQLite into the branch space, shown as version (2).
206 Note that (1) and (2) are exactly the same. Then
207 the maintainer applies the private changes to
208 version (2) resulting in version (3). In other words,
209 version (3) is SQLite version 3.6.15 plus edits.</p>
210
211 <p>Later, SQLite version 3.6.16 is released, as shown
212 by circle (4) in the diagram. At the point, the private
213 branch maintainer does a merge which takes all of the
214 changes going from (1) to (4) and applies those changes to
215 (3). The result is version (5), which is SQLite 3.6.16
216 plus edits.</p>
217
218 <p>There might be merge conflicts. In other words, it might
219 be that the changes from (2) to (3) are incompatible with the
220 changes from (1) to (4). In that case, the maintainer will
221 have to manually resolve the conflicts. Hopefully conflicts
222 will not come up that often. Conflicts are less likely to
223 occur when the private edits are kept to a minimum.</p>
224
225 <p>The cycle above can be repeated many times. The
226 diagram shows a third SQLite release, 3.6.17 in
227 circle (6). The private branch maintainer can do
228 another merge in order to incorporate the changes
229 moving from (4) to (6) into the private branch, resulting
230 in version (7).</p>
231
232 <h1 id="_the_procedure"><span>3. </span> The Procedure</h1>
233
234 <p>The remainder of this document will guide the reader through
235 the steps needed to maintain a private branch. The general idea
236 is the same as outlined above. This section merely provides more
237 detail.</p>
238
239 <p>We emphasize again that these steps are not intended to be the only
240 acceptable method for maintaining a private branch. This approach
241 is one of many. Use this document as a baseline for preparing
242 project-specific procedures. Do not be afraid to experiment.</p>
243
244 <h2 id="_obtain_the_software"><span>3.1. </span> Obtain The Software</h2>
245
246 <p><a href="http://www.fossil-scm.org/">Fossil</a> is a computer program
247 that must be installed on your machine before you use it.
248 Fortunately, installing fossil is very easy. Fossil is a single
249 "*.exe" file that you simply download and run. To uninstall fossil,
250 simply delete the exe file.
251 <a href="http://www.fossil-scm.org/index.html/doc/tip/www/quickstart.wiki">Detailed instructions</a> for installing and getting started with
252 fossil are available on the
253 <a href="http://www.fossil-scm.org">fossil website</a>.</p>
254
255 <h2 id="_create_a_project_repository"><span>3.2. </span> Create A Project Repository</h2>
256
257 <p>Create a fossil repository to host the private branch using the
258 following command:</p>
259
260 <blockquote><pre>
261 fossil new private-project.fossil
262 </pre></blockquote>
263
264 <p>You can call your project anything you like. The "<tt>.fossil</tt>"
265 suffix is optional. For this document, we will continue to call the
266 project "<tt>private-project.fossil</tt>". Note that
267 <tt>private-project.fossil</tt> is an ordinary disk file (actually an
268 SQLite database) that will contain your complete project history.
269 You can make a backup of the project simply by making a copy of that
270 one file.</p>
271
272 <p>If you want to configure the new project, type:</p>
273
274 <blockquote><pre>
275 fossil ui private-project.fossil
276 </pre></blockquote>
277
278 <p>The "ui" command will cause fossil to run a miniature built-in webserver
279 and to launch your web-browser pointing
280 at that webserver. You can use your web-browser to configure your project
281 in various ways. See the instructions on the fossil website for additional
282 information.</p>
283
284 <p>Once the project repository is created, create an open checkout of the
285 project by moving to the directory where you want to keep all of the
286 project source code and typing:</p>
287
288 <blockquote><pre>
289 fossil open private-project.fossil
290 </pre></blockquote>
291
292 <p>You can have multiple checkouts of the same project if you want.
293 And you can "clone" the repository to different machines so that multiple
294 developers can use it. See the fossil website for further information.</p>
295
296 <h2 id="_installing_the_sqlite_baseline_in_fossil"><span>3.3. </span> Installing The SQLite Baseline In Fossil</h2>
297
298 <p>The repository created in the previous step is initially empty. The
299 next step is to load the baseline SQLite release - circle (1) in the diagram
300 above.</p>
301
302 <p>Begin by obtaining a copy of SQLite in whatever form you use it.
303 The public SQLite you obtain should be as close to your private edited
304 copy as possible. If your project uses the SQLite amalgamation, then
305 get a copy of the amalgamation. If you use the preprocessed separate
306 source files, get those instead. Put all the source files in the
307 checkout directory created in the previous step.</p>
308
309 <p>The source code in public SQLite releases uses unix line endings
310 (ASCII code 10: "newline" only, NL) and spaces instead of tabs. If you will
311 be changing the line ending to windows-style line endings
312 (ASCII codes 13, 10: "carriage-return" and "newline"; CR-NL) or if you will be
313 changing space indents into tab indents, <b>make that change now</b>
314 before you check in the baseline. The merging process will only work
315 well if the differences between the public and the private branches are
316 minimal. If every single line of the source file is changed in the
317 private branch because you changed from NL to CR-NL line endings, then
318 the merge steps will not work correctly.</p>
319
320 <p>Let us assume that you are using the amalgamation source code.
321 Add the baseline to your project as follows:</p>
322
323 <blockquote><pre>
324 fossil add sqlite3.c sqlite3.h
325 </pre></blockquote>
326
327 <p>If you are using separate source files, name all of the source files instead
328 of just the two amalgamation source files. Once this is done, commit your
329 changes as follows:</p>
330
331 <blockquote><pre>
332 fossil commit
333 </pre></blockquote>
334
335 <p>You will be prompted for a check-in comment. Say whatever you like.
336 After the commit completes, your baseline will be part of the repository.
337 The following command, if you like, to see this on the "timeline":
338 </p>
339
340 <blockquote><pre>
341 fossil ui
342 </pre></blockquote>
343
344 <p>That last command is the same "ui" command that we ran before. It
345 starts a mini-webserver running and points your web browser at it. But
346 this time we didn't have to specify the repository file because we are
347 located inside a checkout and so fossil can figure out the repository for
348 itself. If you want to type in the repository filename as the second
349 argument, you can. But it is optional.</p>
350
351 <p>If you do not want to use your web browser to view the new check-in,
352 you can get some information from the command-line using commands like
353 these:
354
355 </p><blockquote><pre>
356 fossil timeline
357 fossil info
358 fossil status
359 </pre></blockquote>
360
361 <h2 id="_creating_the_private_branch"><span>3.4. </span> Creating The Private Branch</h2>
362
363 <p>The previous step created circle (1) in the diagram above.
364 This step will create circle (2). Run the following command:</p>
365
366 <blockquote><pre>
367 fossil branch new private trunk -bgcolor "#add8e8"
368 </pre></blockquote>
369
370 <p>This command will create a new branch named "private" (you can use
371 a different name if you like) and assign it a background color
372 of light blue ("#add8e8"). You can omit the background color if you want,
373 though having a distinct background does make it easier to tell the
374 branch from the "trunk" (the public branch) on timeline displays. You
375 can change the background color of the private branch or of the public
376 branch (the "trunk") using the web interface if you like.</p>
377
378 <p>The command above created the new branch. But your checkout is
379 still on the trunk - a fact you can see by running the command:</p>
380
381 <blockquote><pre>
382 fossil info
383 </pre></blockquote>
384
385 <p>To change your check-out to the private branch, type:</p>
386
387 <blockquote><pre>
388 fossil update private
389 </pre></blockquote>
390
391 <p>You can run the "info" command again to verify that you are on the
392 private branch. To go back to the public branch, type:</p>
393
394 <blockquote><pre>
395 fossil update trunk
396 </pre></blockquote>
397
398 <p>Normally, fossil will modify all the files in your checkout when switching
399 between the private and the public branches. But at this point, the files
400 are identical in both branches so no modifications need to be made.</p>
401
402 <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>
403
404 <p>Now it is time to make the private, custom modifications to SQLite
405 which are the whole point of this exercise. Switch to the private branch
406 (if you are not already there) using the "<tt>fossil update private</tt>"
407 command, then bring up the source files in your text editor and make
408 whatever changes you want to make. Once you have finished making
409 changes, commit those changes using this command:</p>
410
411 <blockquote><pre>
412 fossil commit
413 </pre></blockquote>
414
415 <p>You will be prompted once again to enter a commit describing your
416 changes. Then the commit will occur. The commit creates a new checkin
417 in the repository that corresponds to circle (3) in the diagram above.</p>
418
419 <p>Now that the public and private branches are different, you can run
420 the "<tt>fossil update trunk</tt>" and "<tt>fossil update private</tt>"
421 commands and see that fossil really does change the files in the checkout
422 as you switch back and forth between branches.</p>
423
424 <p>Note that in the diagram above, we showed the private edits as a single
425 commit. This was for clarity of presentation only. There is nothing to stop
426 you from doing dozens or hundreds of separate tiny changes and committing
427 each separately. In fact, making many small changes is the preferred way
428 to work. The only reason for doing all the changes in a single commit
429 is that it makes the diagram easier to draw.</p>
430
431 <h2 id="_incorporating_new_public_sqlite_releases"><span>3.6. </span> Incorporating New Public SQLite Releases</h2>
432
433 <p>Suppose that after a while (about a month, usually) a new version of
434 SQLite is released: 3.6.16. You will want to incorporate this new
435 public version of SQLite into your repository in the public branch (the
436 trunk). To do this, first change your repository over to the trunk:</p>
437
438 <blockquote><pre>
439 fossil update trunk
440 </pre></blockquote>
441
442 <p>Then download the new version of the SQLite sources and overwrite the
443 files that are in the checkout.</p><p>
444
445 </p><p>If you made NL to CR-NL line ending changes or space to tab
446 indentation changes in the original baseline, make the same changes
447 to the new source file.</p>
448
449 <p>Once everything is ready, run the "<tt>fossil commit</tt>" command to
450 check in the changes. This creates circle (4) in the diagram above.</p>
451
452 <h2 id="_merging_public_sqlite_updates_into_the_private_branch"><span>3.7. </span> Merging Public SQLite Updates Into The Private Branch</h2>
453
454 <p>The next step is to move the changes in the public branch over into
455 the private branch. In other words, we want to create circle (5) in the
456 diagram above. Begin by changing to the private branch using
457 "<tt>fossil update private</tt>". Then type this command:</p>
458
459 <blockquote><pre>
460 fossil merge trunk
461 </pre></blockquote>
462
463 <p>The "merge" command attempts to apply all the changes between
464 circles (1) and (4) to the files in the local checkout. Note that
465 circle (5) has not been created yet. You will need to run the
466 "commit" to create circle (5).</p>
467
468 <p>It might be that there are conflicts in the merge. Conflicts
469 occur when the same line of code was changed in different ways between
470 circles (1) and (4) versus circles (2) and (3). The merge command will
471 announce any conflicts and will include both versions of the conflicting
472 lines in the output. You will need to bring up the files that contain
473 conflicts and manually resolve the conflicts.</p>
474
475 <p>After resolving conflicts, many users like to compile and test the
476 new version before committing it to the repository. Or you can commit
477 first and test later. Either way, run the "<tt>fossil commit</tt>"
478 command to check-in the circle (5) version.
479
480 </p><h2 id="_further_updates"><span>3.8. </span> Further Updates</h2>
481
482 <p>As new versions of SQLite are released, repeat steps 3.6 and 3.7 to
483 add changes in the new release to the private branch.
484 Additional private changes can be
485 made on the private branch in between releases if desired.</p>
486
487 <h1 id="_variations"><span>4. </span> Variations</h1>
488
489 <p>Since this document was first written, the canonical SQLite source code
490 has been moved from the venerable CVS system into a Fossil repository at
491 <a href="https://sqlite.org/src">https://sqlite.org/src</a>. This means that if you are working with
492 canonical SQLite source code (as opposed to the <a href="amalgamation.html">amalgamation</a> source code
493 files, sqlite3.c and sqlite3.h) then you can create a private repository
494 simply by cloning the official repository:</p>
495
496 <blockquote><pre>
497 fossil clone https://sqlite.org/src private-project.fossil
498 </pre></blockquote>
499
500 <p>This command both creates the new repository and populates it with
501 all the latest SQLite code. You can then create a private branch as
502 described in section 3.4.</p>
503
504 <p>When the private repository is created by cloning, incorporating new
505 public SQLite releases becomes much easier too. To pull in all of the
506 latest changes from the public SQLite repository, simply move into
507 the open check-out and do:</p>
508
509 <blockquote><pre>
510 fossil update
511 </pre></blockquote>
512
513 <p>Then continue to merge the changes in "trunk" with your "private"
514 changes as described in section 3.7.</p>
515 <p align="center"><small><i>This page was last updated on 2025-05-31 13:08:22Z </small></i></p>
516