<div>The following is the design spec so far for this project. It has to be fleshed out a bit more but most of the basic structure is there. Anyone who cares to give input is more than welcome.</div><div>A further update will be posted on Monday to my blog, planet debian, the wiki page and to the dpkg mailing list.</div>
<div><br></div><div>DECLARATIVE DIVERSIONS</div><div>======================</div><div>------------</div><div>Introduction</div><div>------------</div><div>A diversion is when it is possible to have dpkg not overwrite a file when it </div>
<div>reinstalls the package it belongs to, and to have it put the file from the </div><div>package somewhere else instead.</div><div><br></div><div>Declarative diversions involves a new control file with a declarative </div>
<div>syntax which dpkg will parse and process directly as part of the package unpack </div><div>and removal phases, eliminating the problems resulting from non-atomic </div><div>handling of diversions.</div><div><br></div>
<div><br></div><div>------</div><div>Topics</div><div>------</div><div>There are a number of topics involved in implementing this kind of project</div><div><br></div><div> * What syntax do we use for the new control file?</div>
<div> * What dpkg does with the control file</div><div> * How do we handle diversions to a non-existant directory?</div><div> * How do we order unpacking a new package which adds a diversion?</div><div> * How do we order removing a package which had a diversion?</div>
<div> * How do we handle errors?</div><div> * What happens to dpkg-divert?</div><div><br></div><div><br></div><div>-----------------------------</div><div>Details - Control File Syntax</div><div>-----------------------------</div>
<div>It will conform to RFC2822 style with the following format:</div><div> * Divert-From:</div><div> * Divert-To:</div><div> * Blank lines and lines beginning with '#' will be comments</div><div> </div><div>'Divert-To' will be optional and if it is ommitted then files being diverted </div>
<div>will have their filename changed to 'file.distrib'</div><div><br></div><div>The above style has it's advantages, one of the main ones being that there is</div><div>no need to escape whitespace within filenames.</div>
<div><br></div><div><br></div><div>-------------------------------</div><div>Details - Control File Handling</div><div>-------------------------------</div><div>Within control.tar.gz the file should be named 'diversions'</div>
<div>This file is then copied to /var/lib/info/$package.diversions</div><div>This is ensuring we have a copy of the control file just in case it is needed.</div><div>Any input on this subject would be appreciated.</div><div>
<br></div><div><br></div><div>---------------------------------------------------------</div><div>Details - Handling Diversions to non-existant directories</div><div>---------------------------------------------------------</div>
<div>Diverting files to directories that don't exist can cause a number of problems. </div><div>If the package does not 'own' the directory it may be left orphaned on</div><div>removal of the package</div><div>
The package is responsible for ensuring the availability of the target directory in the unpack phase.</div><div><br></div><div><br></div><div>-------------------------------</div><div>Details - Ordering Requirements</div>
<div>-------------------------------</div><div> =>Unpacking a new package that adds a diversion</div><div> *1. Unpack folders</div><div> *2. Add diversions</div><div> *3. Unpack files</div><div> ==Notes==</div>
<div> Performing diversions this way avoids trouble with creating folders and </div><div> accidentally overwrtiting the wrong version of files. </div><div> If we don't use this method the problems that can occur include creating </div>
<div> folders before the package itself would create them which may cause </div><div> permission errors. </div><div> Another major problem would be extracting a new version of the file and </div><div> overwriting the old one. </div>
<div> This might cause the wrong version of the file to be diverted and the </div><div> package to break.</div><div><div> </div></div><div> </div><div> =>Removing a package which had a diversion</div><div> *1. Remove files</div>
<div> *2. Remove diversions</div><div> *3. Remove folders</div><div> ==Notes==</div><div> This ensures that all files, diversions and folders are removed correctly</div><div><br></div><div> </div><div>------------------------</div>
<div>Details - Error handling</div><div>------------------------</div><div>Errors in diversions will have to handled with a great deal of care due to</div><div>the fact that if they are not the package could be broken.</div>
<div>This means that a great deal of checks must be done to ensure that all the files</div><div>can be diverted properly before any actual diverting takes place. If they can't </div><div>the package installation/update must be stopped and rolled back to avoid the </div>
<div>package being installed incorrectly or broken.</div><div><br></div><div><br></div><div>-----------------------</div><div>Details - 'dpkg-divert'</div><div>-----------------------</div><div>When we impliment the new diversion method we should keep the current </div>
<div>dpkg-divert. This allows maintainers to catch up with the new method without </div><div>breaking their packages. It also allows maintainers to perform some operations </div><div>that aren't support by the new method.</div>
<div><br></div><div><br></div><div>----------------</div><div>Example Usage #1</div><div>----------------</div><div>The file to be diverted is '/usr/share/foo'</div><div>It needs to be moved to '/usr/share/bar'</div>
<div><br></div><div>The syntax of the control file would be:</div><div><br></div><div>#Start File</div><div>Divert-From: /usr/share/foo</div><div>Divert-To: /usr/share/bar</div><div>#End File</div><div><br></div><div><br>
</div><div>----------------</div><div>Example Usage #2</div><div>----------------</div><div>In this example the maintainer doesn't want to move the file to any specific</div><div>folder</div><div><br></div><div>The syntax of the control file would be:</div>
<div><br></div><div>#Start File</div><div>Divert-From: /usr/share/foo</div><div>#End File</div><div><br></div><div>This would divert the file to '/usr/share/foo.distrib'</div><div><br></div><div><br></div><div>---------</div>
<div>Footnotes</div><div>---------</div><div>RFC2822 Guide: </div><div> * <a href="http://www.faqs.org/rfcs/rfc2822.html">http://www.faqs.org/rfcs/rfc2822.html</a></div><div><br></div><div>First Email Thread on Declarative Diversions (First Message in Thread):</div>
<div> * <a href="http://lists.debian.org/debian-dpkg/2011/05/msg00102.html">http://lists.debian.org/debian-dpkg/2011/05/msg00102.html</a></div><div> </div><div>Declarative Diversions Wiki:</div><div> * <a href="http://wiki.debian.org/SummerOfCode2011/DeclarativeDiversions">http://wiki.debian.org/SummerOfCode2011/DeclarativeDiversions</a></div>
<div> </div><div>My Blog for this Project: </div><div> * <a href="http://blog.sam-dunne.com">http://blog.sam-dunne.com</a></div><br>-- <br>Sam Dunne<div><br></div><div>BSc Computer Science, UCD Dublin.</div><br>