Date: Tue, 12 Aug 2014 16:17:01 +0000 (UTC) From: Rene Ladan <rene@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r45444 - head/en_US.ISO8859-1/books/porters-handbook/special Message-ID: <53ea3dfd.617e.546d3e10@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: rene Date: Tue Aug 12 16:17:00 2014 New Revision: 45444 URL: http://svnweb.freebsd.org/changeset/doc/45444 Log: Add a section about bundled libraries to the Porters Handbook. Describe why they are considered bad form and what to do about them. Phabric: D577 Reviewed by: wblock Approved by: portmgr (mat) Modified: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Modified: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Tue Aug 12 15:14:21 2014 (r45443) +++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Tue Aug 12 16:17:00 2014 (r45444) @@ -91,6 +91,141 @@ <filename>/boot/modules</filename>.</para> </sect1> + <sect1 xml:id="bundled-libs"> + <title>Bundled Libraries</title> + + <para>This section explains why bundled dependencies are + considered bad and what to do about them.</para> + + <sect2 xml:id="bundled-libs-why-bad"> + <title>Why Bundled Libraries Are Bad</title> + + <para>Some software requires the porter to locate third-party + libraries and add the required dependencies to the port. + Other software bundles all necessary libraries into the + distribution file. The second approach seems easier at + first, but there are some serious drawbacks:</para> + + <para>The following list is loosely based on the <link + xlink:href="https://fedoraproject.org/wiki/Packaging:No_Bundled_Libraries">Fedora</link> + and <link + xlink:href="http://wiki.gentoo.org/wiki/Why_not_bundle_dependencies">Gentoo</link> + wikis, both licensed under the <link + xlink:href="http://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA + 3.0</link> license.</para> + + <variablelist> + <varlistentry> + <term>Security</term> + + <listitem> + <para>If vulnerabilities are found in the upstream library + and fixed there, they might not be fixed in the library + bundled with the port. One reason could be that the + author is not aware of the problem. This means that the + porter must fix them, or upgrade to a non-vulnerable + version, and send a patch to the author. This all takes + time, which results in software being vulnerable longer + than necessary. This in turn makes it harder to + coordinate a fix without unnecessarily leaking + information about the vulnerability.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Bugs</term> + + <listitem> + <para>This problem is similar to the problem with security + in the last paragraph, but generally less severe.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Forking</term> + + <listitem> + <para>It is easier for the author to fork the upstream + library once it is bundled. While convenient on first + sight, it means that the code diverges from upstream + making it harder to address security or other problems + with the software. A reason for this is that patching + becomes harder.</para> + + <para>Another problem of forking is that because code + diverges from upstream, bugs get solved over and over + again instead of just once at a central location. This + defeats the idea of open source software in the first + place.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Symbol collision</term> + + <listitem> + <para>When a library is installed on the system, it might + collide with the bundled version. This can cause + immediate errors at compile or link time. It can also + cause errors when running the program which might be + harder to track down. The latter problem could be + caused because the versions of the two libraries are + incompatible.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Licensing</term> + + <listitem> + <para>When bundling projects from different sources, + license issues can arise more easily, especially when + licenses are incompatible.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Waste of resources</term> + + <listitem> + <para>Bundled libraries waste resources on several levels. + It takes longer to build the actual application, + especially if these libraries are already present on the + system. At run-time, they can take up unnecessary + memory when the system-wide library is already loaded by + one program and the bundled library is loaded by another + program.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Waste of effort</term> + + <listitem> + <para>When a library needs patches for &os;, these patches + have to be duplicated again in the bundled library. + This wastes developer time because the patches might not + apply cleanly. It can also be hard to notice that these + patches are required in the first place.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 xml:id="bundled-libs-practices"> + <title>What to do About Bundled Libraries</title> + + <para>Whenever possible, use the unbundled version of the + library by adding a <varname>LIB_DEPENDS</varname> to the + port. If such a port does not exist yet, consider creating + it.</para> + + <para>Bundled libraries should only be used if upstream has a + good track record on security and using unbundled versions + leads to overly complex patches.</para> + </sect2> + </sect1> + <sect1 xml:id="porting-shlibs"> <title>Shared Libraries</title>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?53ea3dfd.617e.546d3e10>