Translate: (part 2 of 3) [cvs] web/xml/packaging packaging.en.xml, 1.99, 1.100
"David R. Morrison" <[email protected]> Mon, 9 Jun 2008 09:45:27 -0700
| Newsgroups | gmane.os.apple.fink.i18n |
|---|---|
| Message-ID | <[email protected]> |
--===============0582635844== Content-Type: multipart/alternative; boundary=Apple-Mail-2-647009713 --Apple-Mail-2-647009713 Content-Type: text/plain; charset=US-ASCII; format=flowed; delsp=yes Content-Transfer-Encoding: 7bit Begin forwarded message: > From: "David R. Morrison" <[email protected]> > Date: June 4, 2008 8:57:59 PM PDT > To: [email protected] > Subject: [cvs] web/xml/packaging packaging.en.xml,1.99,1.100 > Reply-To: [email protected] > > Update of /cvsroot/fink/web/xml/packaging > In directory sc8-pr-cvs17.sourceforge.net:/tmp/cvs-serv8533 > > Modified Files: > packaging.en.xml > Log Message: > further revisions to shlibs policy documentation > > > Index: packaging.en.xml > =================================================================== > RCS file: /cvsroot/fink/web/xml/packaging/packaging.en.xml,v > retrieving revision 1.99 > retrieving revision 1.100 > diff -u -d -r1.99 -r1.100 > --- packaging.en.xml 2 Jun 2008 18:45:03 -0000 1.99 > +++ packaging.en.xml 5 Jun 2008 03:57:57 -0000 1.100 > @@ -598,15 +598,16 @@ > > <section name="sharedlibs"><title>Shared Libraries</title> > <p> > -Fink has a new policy about shared libraries, effective in February > 2002. > +Fink's policy about shared libraries became effective in February > 2002. > This section of the documentation discusses version 4 > -of the policy, which coincides with the release of Fink's 0.5.0 > distribution > -(as well as some updates from December, 2006 to handle 64bit > libraries > -and from January, 2008 to handle private shared libraries). > +of the policy (which coincides with the release of Fink's 0.5.0 > distribution), > +as modified in December, 2006 to handle 64bit libraries > +and from January, 2008 to handle private shared libraries. (In > addition, > +the discussion was updated in June, 2008 to eliminate obsolete > references to a > +transitional period for implementing the shared libraries policy.) > We begin with a quick summary, and then discuss things in more detail. > </p><p> > -Any package which builds shared libraries and is either (1) being > put into > - the stable tree, or (2) a new package in Fink, should treat its > shared > +Any package which builds shared libraries should treat its shared > libraries according to Fink's policy. This means:</p> > <ul> > <li> verify, using <code>otool -L</code> (or <code>otool64 -L</ > code> for > @@ -621,6 +622,15 @@ > to have > no other package depend on this one.</li> > </ul> > +<p>Note that a package may also install private shared libraries, > which > +are not intended to be linked from any other package. In this > case, the > +libraries need to go into a separate package, but a <code>Shlibs</ > code> > +field must still be part of the package containing shared > libraries. Also, > +maintainers should be careful not to store a final link from > libfoo.dylib > +in the main library directory <filename>%i/lib</filename> > +(or its 64-bit equivalent), to avoid > +having other programs accidentally link to this library. > +</p> > <p> > A maintainer who has reasons to deviate from this policy and not > split the > package should explain the reasons in the DescPackaging field. > @@ -651,22 +661,9 @@ > <itemd><p>Binaries, etc.</p></itemd></item> > </itemtable> > > -<p> > -With option 2 it is harder to upgrade an existing package: at the > same > -time as you upgrade, > -you need to add <code>BuildDepends: foo-dev</code> to every > -package which says <code>Depends: foo</code>. > -One other upgrade issue to keep in mind: a package which indirectly > depends > -on your package (through another package as an intermediary) may need > -to have <code>BuildDepends: foo</code> or <code>BuildDepends: foo- > dev</code> > -added to it to ensure a successful upgrade. It is your > responsibility > -to make sure that these <code>BuildDepends</code> entries are added. > -</p> > <p><em>The policy in detail</em></p> > <p> > -We now discuss things in more detail, first discussing the policy as > -applied to newly ported software, and > -then turning to the question of upgrading existing fink packages. > For > +We now discuss things in more detail; for > examples of the policy in action, see the libpng, libjpeg and > libtiff packages. > </p><p> > @@ -720,9 +717,10 @@ > BuildDepends: barN > </codeblock> > <p> > -Once this system is fully in place, it will not be permitted for > -another package to depend on barN itself. (For backward > compatibility, > -such dependencies are allowed for pre-existing packages.) This is > +It is not be permitted for > +another package to depend on barN itself. (Although there may > still be > +a few such dependencies involving packages which were in place > prior to > +February, 2002.) This is > signaled to other developers by a boolean field > </p> > <codeblock> > @@ -742,7 +740,7 @@ > (You can > find the install_name by running <code>otool -L</code> on your > library, > or <code>otool64 -L</code> for 64bit libraries.) The > -actual library file should be installed at > +actual library file may be installed at another location, such as > </p> > <codeblock> > %i/lib/bar.N.x.y.dylib > @@ -754,6 +752,10 @@ > %i/lib/bar.N.dylib -> %p/lib/bar.N.x.y.dylib > %i/lib/bar.dylib -> %p/lib/bar.N.x.y.dylib > </codeblock> > +<p>from the install_name path and from the linking path to the actual > +library. (The first will not be needed if the library is in fact > +installed at the install_name path, which is becoming more common.) > +</p> > <p> > If the static library is also built, then it will be installed at > </p> > @@ -859,7 +861,9 @@ > <p>and the reason must be given in the DescPackaging field. > </p><p> > The BuildDependsOnly field should only be mentioned in the > package's .info > -file if the package contains header files, installed into /sw/ > include. > +file if the package contains header files, installed into > +<filename>%i/include</filename>, and need not be declared if the > header > +files are installed into another, private, location. > </p><p> > As of fink 0.20.5, "fink validate" will issue a warning for any .deb > which contains header files and at least one dylib, and does not > declare > @@ -877,7 +881,7 @@ > that come with a back-end library of utility functions or a program > that comes with plugins to handle various features. Because these > libraries are "private" to the package that has them, they do not > - require being packages with separate -shlibs > + require being packaged with separate -shlibs > or <code>BuildDependsOnly</code> SplitOffs. > </p> > <p><em>The Shlibs field</em> > @@ -916,14 +920,34 @@ > Note the use of %p in the name of the library, which allows the > correct > <code>-install_name</code> to be found by all users of Fink, no matter > what prefix they have chosen. > -</p><p> > -When a package is updated, usually the <code>Shlibs</code> field > can simply > +</p> > +<p>When a package is updated, usually the <code>Shlibs</code> field > can simply > be copied to the next version/revision of the package. The > exception to > this is if the <code>-compatibility_version</code> increases: in that > case, the version number in the dependency information should be > changed > to the current version/revision (which is the first version/revision > to > provide the library with the new compatibility version number). > -</p><p> > +</p> > +<p> > +The <code>Shlibs</code> > +entry for a private library uses a different syntax: > +</p> > +<codeblock> > + Shlibs: << > + !%p/lib/%N/bar.1.dylib > + << > +</codeblock> > +<p>The leading exclamation point indicates that this is a private > library, > +and since the other information is not relevant in this case, it is > +not included.</p> > +<p>Note that in this example, the private shared library has been > placed > +in its own subdirectory <filename>%N</filename> of the > +<filename>%i/lib</filename> directory (which was named after the > +package). This is a recommended procedure for private libraries, > +as an additional safety measure, to prevent other packages from > accidentally > +linking to this library. > +</p> > +<p> > <em>What to do when the major version number changes:</em> > </p><p> > If the major version number changes from N to M, you will create two > new > @@ -946,36 +970,8 @@ > Users will then see barN and barM shuffling in and out as various > other > packages are built which depend on one version or another of the > shared > library, while barN-shlibs and barM-shlibs remain permanently > installed. > -</p><p> > -<em>How to upgrade an existing fink package:</em> > -</p><p> > -For an existing fink package which installs either static or shared > -libraries, the best way to upgrade is to create a new version foo of > -your package, accompanied by a new package foo-shlibs, which satisfy > -the above policy. If shared libraries (or any other files now > present > -in foo-shlibs) were installed previously, then these new packages > should > -say > </p> > -<codeblock> > - Replaces: foo (<< earliest.compliant.version) > -</codeblock> > <p> > -so that upgrading will be transparent to users. (You should > <em>not</em> > -say "Conflicts: foo" because this will prevent the upgrade.) > -</p><p> > -After your upgrade, packages which say "Depends: foo" will continue > to > -function normally. However, you should contact the fink maintainers > -of all such packages and urge them to modify their packages to say > -"Depends: foo-shlibs, BuildDepends: foo" as soon as possible. You > will > -not be able to create new packages fooM, fooM-shlibs which > implement a > -new major version of the shared library until they have done so. > -</p><p> > -Existing fink packages which have not used the correct install_name > or > -which have not used the correct names or symbolic links for shared > libraries > -must be upgraded carefully, on a case-by-case basis. If you are > -having trouble finding an upgrade strategy to make your packages > compliant > -with the new policy, please discuss it on the fink-devel mailing > list. > -</p><p> > <em>Packages containing both binary files and libraries:</em> > </p><p> > When an upstream package contains both binary files and public > libraries, some > > > ------------------------------------------------------------------------- > Check out the new SourceForge.net Marketplace. > It's the best place to buy or sell services for > just about anything Open Source. > http://sourceforge.net/services/buy/index.php > _______________________________________________ > Fink-commits mailing list > [email protected] > http://news.gmane.org/gmane.os.apple.fink.cvs --Apple-Mail-2-647009713 Content-Type: text/html; charset=US-ASCII Content-Transfer-Encoding: quoted-printable <html><body style=3D"word-wrap: break-word; -webkit-nbsp-mode: space; = -webkit-line-break: after-white-space; "><br><div><br><div>Begin = forwarded message:</div><br = class=3D"Apple-interchange-newline"><blockquote type=3D"cite"><div><div = style=3D"margin-top: 0px; margin-right: 0px; margin-bottom: 0px; = margin-left: 0px; "><font face=3D"Helvetica" size=3D"4" color=3D"#000000" = style=3D"font: 14.0px Helvetica; color: #000000"><b>From: = </b></font><font face=3D"Helvetica" size=3D"4" style=3D"font: 14.0px = Helvetica">"David R. Morrison" <<a = href=3D"mailto:[email protected]">[email protected]<= /a>></font></div><div style=3D"margin-top: 0px; margin-right: 0px; = margin-bottom: 0px; margin-left: 0px; "><font face=3D"Helvetica" = size=3D"4" color=3D"#000000" style=3D"font: 14.0px Helvetica; color: = #000000"><b>Date: </b></font><font face=3D"Helvetica" size=3D"4" = style=3D"font: 14.0px Helvetica">June 4, 2008 8:57:59 PM = PDT</font></div><div style=3D"margin-top: 0px; margin-right: 0px; = margin-bottom: 0px; margin-left: 0px; "><font face=3D"Helvetica" = size=3D"4" color=3D"#000000" style=3D"font: 14.0px Helvetica; color: = #000000"><b>To: </b></font><font face=3D"Helvetica" size=3D"4" = style=3D"font: 14.0px Helvetica"><a = href=3D"mailto:[email protected]">[email protected]= ceforge.net</a></font></div><div style=3D"margin-top: 0px; margin-right: = 0px; margin-bottom: 0px; margin-left: 0px; "><font face=3D"Helvetica" = size=3D"4" color=3D"#000000" style=3D"font: 14.0px Helvetica; color: = #000000"><b>Subject: </b></font><font face=3D"Helvetica" size=3D"4" = style=3D"font: 14.0px Helvetica"><b>[cvs] web/xml/packaging = packaging.en.xml,1.99,1.100</b></font></div><div style=3D"margin-top: = 0px; margin-right: 0px; margin-bottom: 0px; margin-left: 0px; "><font = face=3D"Helvetica" size=3D"4" color=3D"#000000" style=3D"font: 14.0px = Helvetica; color: #000000"><b>Reply-To: </b></font><font = face=3D"Helvetica" size=3D"4" style=3D"font: 14.0px Helvetica"><a = href=3D"mailto:[email protected]">[email protected]= rge.net</a></font></div><div style=3D"margin-top: 0px; margin-right: = 0px; margin-bottom: 0px; margin-left: 0px; min-height: 14px; = "><br></div> </div><div>Update of /cvsroot/fink/web/xml/packaging<br>In = directory sc8-pr-cvs17.sourceforge.net:/tmp/cvs-serv8533<br><br>Modified = Files:<br><span class=3D"Apple-tab-span" style=3D"white-space:pre"> = </span>packaging.en.xml <br>Log Message:<br>further revisions to shlibs = policy documentation<br><br><br>Index: = packaging.en.xml<br>=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D<b= r>RCS file: = /cvsroot/fink/web/xml/packaging/packaging.en.xml,v<br>retrieving = revision 1.99<br>retrieving revision 1.100<br>diff -u -d -r1.99 = -r1.100<br>--- packaging.en.xml<span class=3D"Apple-tab-span" = style=3D"white-space:pre"> </span>2 Jun 2008 18:45:03 -0000<span = class=3D"Apple-tab-span" style=3D"white-space:pre"> = </span>1.99<br>+++ packaging.en.xml<span class=3D"Apple-tab-span" = style=3D"white-space:pre"> </span>5 Jun 2008 03:57:57 -0000<span = class=3D"Apple-tab-span" style=3D"white-space:pre"> = </span>1.100<br>@@ -598,15 +598,16 @@<br><br> <section = name=3D"sharedlibs"><title>Shared Libraries</title><br> = <p><br>-Fink has a new policy about shared libraries, effective in = February 2002.<br>+Fink's policy about shared libraries became effective = in February 2002.<br> This section of the documentation discusses = version 4<br>-of the policy, which coincides with the release of Fink's = 0.5.0 distribution<br>-(as well as some updates from December, 2006 to = handle 64bit libraries<br>-and from January, 2008 to handle private = shared libraries).<br>+of the policy (which coincides with the release = of Fink's 0.5.0 distribution),<br>+as modified in December, 2006 to = handle 64bit libraries<br>+and from January, 2008 to handle private = shared libraries. (In addition,<br>+the discussion was updated in June, = 2008 to eliminate obsolete references to a<br>+transitional period for = implementing the shared libraries policy.)<br> We begin with a quick = summary, and then discuss things in more detail.<br> = </p><p><br>-Any package which builds shared libraries and is = either (1) being put into<br>- the stable tree, or (2) a new = package in Fink, should treat its shared<br>+Any package which builds = shared libraries should treat its shared<br> libraries = according to Fink's policy. This means:</p><br> <ul><br> = <li> verify, using <code>otool -L</code> (or = <code>otool64 -L</code> for<br>@@ -621,6 +622,15 @@<br> = to have<br> = no other package depend on = this one.</li><br> </ul><br>+<p>Note that a package may also = install private shared libraries, which<br>+are not intended to be = linked from any other package. In this case, the<br>+libraries = need to go into a separate package, but a = <code>Shlibs</code><br>+field must still be part of the package = containing shared libraries. Also,<br>+maintainers should be = careful not to store a final link from libfoo.dylib<br>+in the main = library directory <filename>%i/lib</filename> <br>+(or its 64-bit = equivalent), to avoid<br>+having other programs accidentally link to = this library.<br>+</p><br> <p><br> A maintainer who = has reasons to deviate from this policy and not split the<br> = package should explain the reasons in the DescPackaging = field.<br>@@ -651,22 +661,9 @@<br> <itemd><p>Binaries, = etc.</p></itemd></item><br> = </itemtable><br><br>-<p><br>-With option 2 it is harder to upgrade = an existing package: at the same<br>-time as you upgrade, <br>-you = need to add <code>BuildDepends: foo-dev</code> to = every<br>-package which says <code>Depends: foo</code>.<br>-One = other upgrade issue to keep in mind: a package which indirectly = depends<br>-on your package (through another package as an intermediary) = may need<br>-to have <code>BuildDepends: foo</code> or = <code>BuildDepends: foo-dev</code><br>-added to it to ensure a = successful upgrade. It is your responsibility<br>-to make sure = that these <code>BuildDepends</code> entries are = added.<br>-</p><br> <p><em>The policy in = detail</em></p><br> <p><br>-We now discuss things in more = detail, first discussing the policy as <br>-applied to newly ported = software, and <br>-then turning to the question of upgrading existing = fink packages. For <br>+We now discuss things in more detail; = for<br> examples of the policy in action, see the libpng, libjpeg = and <br> libtiff packages.<br> </p><p><br>@@ -720,9 +717,10 = @@<br> BuildDepends: barN<br> </codeblock><br> = <p><br>-Once this system is fully in place, it will not be permitted = for <br>-another package to depend on barN itself. (For backward = compatibility,<br>-such dependencies are allowed for pre-existing = packages.) This is<br>+It is not be permitted for <br>+another = package to depend on barN itself. (Although there may still = be<br>+a few such dependencies involving packages which were in place = prior to <br>+February, 2002.) This is<br> signaled to other = developers by a boolean field<br> </p><br> <codeblock><br>@@ = -742,7 +740,7 @@<br> (You can<br> find the install_name by running = <code>otool -L</code> on your library,<br> or <code>otool64 = -L</code> for 64bit libraries.) The<br>-actual library file = should be installed at<br>+actual library file may be installed at = another location, such as<br> </p><br> <codeblock><br> = %i/lib/bar.N.x.y.dylib<br>@@ -754,6 +752,10 @@<br> = %i/lib/bar.N.dylib -> %p/lib/bar.N.x.y.dylib<br> = %i/lib/bar.dylib -> %p/lib/bar.N.x.y.dylib<br> = </codeblock><br>+<p>from the install_name path and from the = linking path to the actual<br>+library. (The first will not be = needed if the library is in fact<br>+installed at the install_name path, = which is becoming more common.)<br>+</p><br> <p><br> If the static = library is also built, then it will be installed at<br> </p><br>@@ = -859,7 +861,9 @@<br> <p>and the reason must be given in the = DescPackaging field.<br> </p><p><br> The BuildDependsOnly field = should only be mentioned in the package's .info<br>-file if the package = contains header files, installed into /sw/include.<br>+file if the = package contains header files, installed into = <br>+<filename>%i/include</filename>, and need not be declared if = the header<br>+files are installed into another, private, location.<br> = </p><p><br> As of fink 0.20.5, "fink validate" will issue a = warning for any .deb<br> which contains header files and at least one = dylib, and does not declare<br>@@ -877,7 +881,7 @@<br> that = come with a back-end library of utility functions or a program<br> = that comes with plugins to handle various features. Because = these<br> libraries are "private" to the package that has = them, they do not<br>- require being packages with separate = -shlibs<br>+ require being packaged with separate -shlibs<br> = or <code>BuildDependsOnly</code> SplitOffs.<br> = </p><br> <p><em>The Shlibs field</em><br>@@ -916,14 +920,34 = @@<br> Note the use of %p in the name of the library, which allows the = correct<br> <code>-install_name</code> to be found by all users of = Fink, no matter<br> what prefix they have = chosen.<br>-</p><p><br>-When a package is updated, usually the = <code>Shlibs</code> field can simply<br>+</p><br>+<p>When a = package is updated, usually the <code>Shlibs</code> field can = simply<br> be copied to the next version/revision of the package. = The exception to<br> this is if the = <code>-compatibility_version</code> increases: in that<br> case, = the version number in the dependency information should be changed<br> = to the current version/revision (which is the first version/revision = to<br> provide the library with the new compatibility version = number).<br>-</p><p><br>+</p><br>+<p><br>+The = <code>Shlibs</code><br>+entry for a private library uses a = different syntax:<br>+</p><br>+<codeblock><br>+ Shlibs: = &lt;&lt;<br>+ !%p/lib/%N/bar.1.dylib<br>+ = &lt;&lt;<br>+</codeblock><br>+<p>The leading = exclamation point indicates that this is a private library,<br>+and = since the other information is not relevant in this case, it is <br>+not = included.</p><br>+<p>Note that in this example, the private shared = library has been placed<br>+in its own subdirectory = <filename>%N</filename> of the = <br>+<filename>%i/lib</filename> directory (which was named after = the<br>+package). This is a recommended procedure for private = libraries,<br>+as an additional safety measure, to prevent other = packages from accidentally<br>+linking to this = library.<br>+</p><br>+<p><br> <em>What to do when the major = version number changes:</em><br> </p><p><br> If the major = version number changes from N to M, you will create two new<br>@@ = -946,36 +970,8 @@<br> Users will then see barN and barM shuffling in and = out as various other<br> packages are built which depend on one version = or another of the shared<br> library, while barN-shlibs and barM-shlibs = remain permanently installed.<br>-</p><p><br>-<em>How to = upgrade an existing fink package:</em><br>-</p><p><br>-For an = existing fink package which installs either static or shared = <br>-libraries, the best way to upgrade is to create a new version foo = of<br>-your package, accompanied by a new package foo-shlibs, which = satisfy<br>-the above policy. If shared libraries (or any other = files now present<br>-in foo-shlibs) were installed previously, then = these new packages should <br>-say<br> </p><br>-<codeblock><br>- = Replaces: foo (&lt;&lt; = earliest.compliant.version)<br>-</codeblock><br> <p><br>-so that = upgrading will be transparent to users. (You should = <em>not</em><br>-say "Conflicts: foo" because this will prevent = the upgrade.)<br>-</p><p><br>-After your upgrade, packages which = say "Depends: foo" will continue to<br>-function normally. = However, you should contact the fink maintainers<br>-of all such = packages and urge them to modify their packages to say <br>-"Depends: = foo-shlibs, BuildDepends: foo" as soon as possible. You will = <br>-not be able to create new packages fooM, fooM-shlibs which = implement a <br>-new major version of the shared library until they have = done so.<br>-</p><p><br>-Existing fink packages which have not = used the correct install_name or<br>-which have not used the correct = names or symbolic links for shared libraries<br>-must be upgraded = carefully, on a case-by-case basis. If you are<br>-having trouble = finding an upgrade strategy to make your packages compliant<br>-with the = new policy, please discuss it on the fink-devel mailing = list.<br>-</p><p><br> <em>Packages containing both binary files = and libraries:</em><br> </p><p><br> When an upstream package = contains both binary files and public libraries, = some<br><br><br>----------------------------------------------------------= ---------------<br>Check out the new SourceForge.net = Marketplace.<br>It's the best place to buy or sell services for<br>just = about anything Open Source.<br><a = href=3D"http://sourceforge.net/services/buy/index.php">http://sourceforge.= net/services/buy/index.php</a><br>________________________________________= _______<br>Fink-commits mailing = list<br>[email protected]<br>http://news.gmane.org/gmane.= os.apple.fink.cvs<br></div></blockquote></div><br></body></html>= --Apple-Mail-2-647009713-- --===============0582635844== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline ------------------------------------------------------------------------- Check out the new SourceForge.net Marketplace. It's the best place to buy or sell services for just about anything Open Source. http://sourceforge.net/services/buy/index.php --===============0582635844== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ fink-i18n mailing list [email protected] http://news.gmane.org/gmane.os.apple.fink.i18n --===============0582635844==--