Differential D577 Diff 1026 en_US.ISO8859-1/books/porters-handbook/special/chapter.xml

Changeset View

Standalone View

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml

Show First 20 Lines • Show All 85 Lines • ▼ Show 20 Lines	<para>The source path
shorter.</para>		shorter.</para>

<para>Ports that install kernel modules must prepend the		<para>Ports that install kernel modules must prepend the
<varname>STAGEDIR</varname> variable to		<varname>STAGEDIR</varname> variable to
their destination, by default		their destination, by default
<filename>/boot/modules</filename>.</para>		<filename>/boot/modules</filename>.</para>
</sect1>		</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>
		wblockUnsubmitted Not Done Inline Actions s/bad form/bad/ to be consistent with the next section. wblock: s/bad form/bad/ to be consistent with the next section.

		<sect2 xml:id="bundled-libs-why-bad">
		<title>Why Bundled Libraries Are Bad</title>

		<para>Some software requires the porter to locate third-party
		wblockUnsubmitted Not Done Inline Actions Avoid the informal "you" and "your". Also, there are some tense problems in this paragraph. Some software requires the porter to locate third-part libraries and add the required dependencies to the port. Other software bundles all needed libraries into the distfile. The second approach seems easier at first, but there are some serious drawbacks. wblock: Avoid the informal "you" and "your". Also, there are some tense problems in this paragraph.
		reneAuthorUnsubmitted Not Done Inline Actions Paragraph rewritten. rene: Paragraph rewritten.
		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>
		wblockUnsubmitted Not Done Inline Actions Consider using a variablelist here: http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/docbook-markup-block-elements.html#docbook-markup-variablelist-example wblock: Consider using a variablelist here: http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp…
		reneAuthorUnsubmitted Not Done Inline Actions This indeed looks better, but caused a considerable diff due to line lengths. rene: This indeed looks better, but caused a considerable diff due to line lengths.
		<varlistentry>
		<term>Security</term>

		<listitem>
		wblockUnsubmitted Not Done Inline Actions s/your/the/ wblock: s/your/the/
		reneAuthorUnsubmitted Not Done Inline Actions Done. rene: Done.
		<para>If vulnerabilities are found in the upstream library
		and fixed there, they might not be fixed in the library
		wblockUnsubmitted Not Done Inline Actions This means that the porter must fix them, or wblock: This means that the porter must fix them, or
		reneAuthorUnsubmitted Not Done Inline Actions Done. rene: Done.
		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>

		wblockUnsubmitted Not Done Inline Actions s/gets/is/ wblock: s/gets/is/
		reneAuthorUnsubmitted Not Done Inline Actions Done. rene: Done.
		<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
		wblockUnsubmitted Not Done Inline Actions s/your/the/ wblock: s/your/the/
		reneAuthorUnsubmitted Not Done Inline Actions Done rene: Done
		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>
		<!-- XXX(rene) policy to be extended/formalized in the future? -->
		</sect2>
		</sect1>

<sect1 xml:id="porting-shlibs">		<sect1 xml:id="porting-shlibs">
<title>Shared Libraries</title>		<title>Shared Libraries</title>

<para>If your port installs one or more shared libraries, define		<para>If your port installs one or more shared libraries, define
a <varname>USE_LDCONFIG</varname> make variable, which will		a <varname>USE_LDCONFIG</varname> make variable, which will
instruct a <filename>bsd.port.mk</filename> to run		instruct a <filename>bsd.port.mk</filename> to run
<literal>&dollar;{LDCONFIG} -m</literal> on the directory		<literal>&dollar;{LDCONFIG} -m</literal> on the directory
where the new library is installed (usually		where the new library is installed (usually
▲ Show 20 Lines • Show All 4,367 Lines • Show Last 20 Lines