Adding upstream version 3.40.1.upstream/3.40.1 upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
author: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-05-05 17:28:19 +0000
committer: Daniel Baumann <daniel.baumann@progress-linux.org> 2024-05-05 17:28:19 +0000
commit: 18657a960e125336f704ea058e25c27bd3900dcb (patch)
tree: 17b438b680ed45a996d7b59951e6aa34023783f2 /www/privatebranch.html
parent: Initial commit. (diff)
download: sqlite3-18657a960e125336f704ea058e25c27bd3900dcb.tar.xz
sqlite3-18657a960e125336f704ea058e25c27bd3900dcb.zip
1 files changed, 532 insertions, 0 deletions
diff --git a/www/privatebranch.html b/www/privatebranch.html
new file mode 100644
index 0000000..acf18a2
--- /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">&#x25ba;</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 = "&#x25bc;";
+} else {
+sub.style.display = "none";
+mk.innerHTML = "&#x25ba;";
+}
+}
+</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="http://www.sqlite.org/src">http://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 http://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>
+<p align="center"><small><i>This page last modified on  <a href="https://sqlite.org/docsrc/honeypot" id="mtimelink"  data-href="https://sqlite.org/docsrc/finfo/pages/privatebranch.in?m=4a84b75757d9857d3">2021-04-07 11:02:17</a> UTC </small></i></p>
+
author	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-05-05 17:28:19 +0000
committer	Daniel Baumann <daniel.baumann@progress-linux.org>	2024-05-05 17:28:19 +0000
commit	18657a960e125336f704ea058e25c27bd3900dcb (patch)
tree	17b438b680ed45a996d7b59951e6aa34023783f2 /www/privatebranch.html
parent	Initial commit. (diff)
download	sqlite3-18657a960e125336f704ea058e25c27bd3900dcb.tar.xz sqlite3-18657a960e125336f704ea058e25c27bd3900dcb.zip