From 8ab61d308942de33c7c2ef581a0cf0032f4a45b1 Mon Sep 17 00:00:00 2001
From: Pav Lucistnik <pav@FreeBSD.org>
Date: Wed, 14 Sep 2005 17:51:06 +0000
Subject: [PATCH] 6.1 Shared libraries: - mention prefered naming scheme of
 shared library files - add few words about bumping PORTREVISION of consumers
 on shlib version raise

8 Shared library versions
- kill without replacement; it's hardly useful in the modern autotools world

Approved by:	keramida (mentor)
---
 .../books/porters-handbook/book.sgml          | 46 ++++---------------
 1 file changed, 10 insertions(+), 36 deletions(-)

diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml
index a018472c65..ab1c7d314f 100644
--- a/en_US.ISO8859-1/books/porters-handbook/book.sgml
+++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml
@@ -3887,6 +3887,16 @@ LDCONFIG_DIRS=  %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar</programlisting>
 	  <makevar>PREFIX</makevar>, <literal>%%LOCALBASE%%</literal> for
 	  <makevar>LOCALBASE</makevar> and <literal>%%X11BASE%%</literal> for
 	  <makevar>X11BASE</makevar>.</para>
+
+	<para>Try to keep shared library version numbers in the
+	  <filename>libfoo.so.0</filename> format.  Our runtime linker only
+	  cares for the major (first) number.</para>
+
+	<para>When the major library version number increments in the update
+	  to the new port version, all other ports that link to the affected
+	  library should have their <makevar>PORTREVISION</makevar> incremented,
+	  to force recompilation with the new library version.</para>
+
       </sect1>
 
     <sect1 id="porting-restrictions">
@@ -5953,42 +5963,6 @@ etc/orbit.conf.sample
 
     </chapter>
 
-    <chapter id="shared">
-      <title>Shared library versions</title>
-
-      <para>Please read our <ulink url="&url.books.developers-handbook;/policies-shlib.html">policy on
-	shared library versioning</ulink> to understand what to do with
-	shared library versions in general.  Do not blindly assume software
-	authors know what they are doing; many of them do not.  It is very
-	important that these details are carefully considered, as we have
-	quite a unique situation where we are trying to have dozens of
-	potentially incompatible software pairs co-exist. Careless port
-	imports have caused great trouble regarding shared libraries in the
-	past (ever wondered why the port <filename>jpeg-6b</filename> has a
-	shared library version of 9?). If in doubt, send a message to the
-	&a.ports;.  Most of the time, your job ends by determining the right
-	shared library version and making appropriate patches to implement
-	it.</para>
-
-<!--
-      <para>However, if there is a port which is a different version of the
-	same software already in the tree, the situation is much more complex.
-	In short, the FreeBSD implementation does not allow the user to
-	specify to the linker which version of shared library to link against
-	(the linker will always pick the highest numbered version).  This
-	means, if there is a <filename>libfoo.so.3.2</filename> and
-	<filename>libfoo.so.4.0</filename> in the system, there is no way to
-	tell the linker to link a particular application to
-	<filename>libfoo.so.3.2</filename>.  It is essentially completely
-	overshadowed in terms of compilation-time linkage.  In this case, the
-	only solution  is to rename the <emphasis>base</emphasis> part of the
-	shared library.  For instance, change
-	<filename>libfoo.so.4.0</filename> to
-	<filename>libfoo4.so.1.0</filename> so both version 3.2 and 4.0 can be
-	linked from other ports.</para>
--->
-    </chapter>
-
     <chapter id="pkg-files">
       <title>The <filename>pkg-<replaceable>*</replaceable></filename> files</title>