[TRANSLATE] web/xml/packaging packaging.en.xml,1.46,1.48

packaging manual additions:

  * Revision field: add notes about Revision field incrementing

  * Depends field: add note about mixing multiple lib major verions
    being bad

  * BuildDependsOnly field: add note about undefined vs. false, add
    xref to shlibs policy

Index: packaging.en.xml
===================================================================
RCS file: /cvsroot/fink/web/xml/packaging/packaging.en.xml,v
retrieving revision 1.46
retrieving revision 1.48
diff -u -r1.46 -r1.48
--- packaging.en.xml	6 Aug 2004 11:55:57 -0000	1.46
+++ packaging.en.xml	7 Sep 2004 11:52:24 -0000	1.48
@@ -1302,6 +1302,20 @@
 Revision numbers start at 1.
 Required field.
 </p>
+<p>
+  Fink's policy is that <em>any</em> time you make a change to the
+  <filename>.info</filename> file that results in changes to the
+  binary (compiled) form of a package (the <filename>.deb</filename>
+  file), you <em>must</em> increase <code>Revision</code>. This
+  includes changing the <code>Depends</code> or other package lists,
+  with the exception of<code>BuildDepends</code>, and adding,
+  removing, or renaming splitoff packages or shifting files among
+  them. When migrating a package to a new tree (from 10.2 to 10.3, for
+  example) involves such changes, you should
+  increase <code>Revision</code> by 10 in the newer tree in order to
+  leave space space for future updates to the package in the older
+  tree.
+</p>
 </itemd></item>
 
 <item><itemt>Epoch</itemt>
@@ -1528,6 +1542,33 @@
 would set the package x11 as a dependency for the nethack-x11 variant
 but not for the nethack variant.
 </p>
+<p>
+  Note that when using Depends/BuildDepends for shared library packages
+  for which more than one major-version is available, you must
+  <em>not</em> do the following:
+</p>
+<codeblock>
+  Package: foo
+  Depends: id3lib3.7-shlibs | id3lib3.7-shlibs
+  BuildDepends: id3lib3.7-dev | id3lib4-dev
+</codeblock>
+<p>
+  even if your package could work with either library. Pick one
+  (preferably the highest version that can be used successfully) and
+  use it consistently in your package.
+</p>
+<p>
+  As explained in the <xref chapter="policy"
+  section="sharedlibs">Shared Library Policy</xref>, only one of the
+  -dev packages can be installed at a time, and each has links of the
+  same name that could point to different filenames in the associated
+  -shlibs package. When compiling package foo, the actual filename (in
+  the -shlibs package) gets hard-coded into the foo binary. That means
+  the resulting package needs the specific -shlibs package associated
+  with the -dev that was installed at compile-time. As a result, one
+  cannot have a <code>Depends</code> that indicates that either one
+  will suffice.
+</p>
 </itemd></item>
 
 <item><itemt>BuildDepends</itemt>
@@ -1634,6 +1675,11 @@
 <em>Introduced in fink 0.9.9.</em>
 A boolean value which indicates that no other packages should Depend on
 this one, they should only BuildDepend.
+Unlike usual boolean fields, <code>BuildDependsOnly</code> is
+tri-state: leaving it undefined (not specifying it at all) is
+different than defining it as logically false. See the <xref
+chapter="policy" section="sharedlibs">Shared Library Policy</xref> for
+more information.
 </p>
 <p>As of fink 0.20.5, the presence or absence of this field, and its value
 if present, are recorded into the .deb


-------------------------------------------------------
This SF.Net email is sponsored by BEA Weblogic Workshop
FREE Java Enterprise J2EE developer tools!
Get your free copy of BEA WebLogic Workshop 8.1 today.
http://ads.osdn.com/?ad_id=5047&alloc_id=10808&op=click