diff options
Diffstat (limited to 'www/privatebranch.html')
| -rw-r--r-- | www/privatebranch.html | 532 |
1 files changed, 532 insertions, 0 deletions
diff --git a/www/privatebranch.html b/www/privatebranch.html new file mode 100644 index 0000000..d2a2bf8 --- /dev/null +++ b/www/privatebranch.html @@ -0,0 +1,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> + + |