svn commit: r44420 - head/en_US.ISO8859-1/books/handbook/ports

Dru Lavigne dru at
Wed Apr 2 18:12:19 UTC 2014

Author: dru
Date: Wed Apr  2 18:12:18 2014
New Revision: 44420

  Editorial review of Poudriere section. Expand on the intro some.
  Sponsored by:	iXsystems


Modified: head/en_US.ISO8859-1/books/handbook/ports/chapter.xml
--- head/en_US.ISO8859-1/books/handbook/ports/chapter.xml	Wed Apr  2 17:59:41 2014	(r44419)
+++ head/en_US.ISO8859-1/books/handbook/ports/chapter.xml	Wed Apr  2 18:12:18 2014	(r44420)
@@ -1545,56 +1545,61 @@ The deinstallation will free 229 kB
     <title>Building Packages with
-    <para><application>Poudriere</application> uses &os; jails to set
-      up isolated compilation environments.  Inside, ports are
-      compiled and packaged using standard &man.make.1; targets and
-      &man.pkg.8;.</para>
-    <sect2 xml:id="poudriere-installation-and-configuration">
-      <title>Installation and Configuration</title>
-      <para>Install <application>Poudriere</application> from the
-	Ports Collection
-	(<package role="port">ports-mgmt/poudriere</package>).</para>
-      <para>Configuration files are
+    <para><application>Poudriere</application> is a 
+      <acronym>BSD</acronym>-licensed utility for creating and testing
+      &os; packages. It uses &os; jails to set
+      up isolated compilation environments which can be used to build
+      packages for versions of &os; that are different from the box
+      on which it is installed, and also to build packages for i386 if
+      the host is an &arch.amd64; system.  Once the packages are built, they
+      will be in a layout identical to the official mirrors and are
+      therefore useable by
+      &man.pkg.8; and other package management tools.</para>
+      <para><application>Poudriere</application> can be installed
+	using the
+	<package role="port">ports-mgmt/poudriere</package> package or
+	port.  The installation will include a sample configuration file
+	<filename>/usr/local/etc/poudriere.conf.sample</filename>.
+	This file should be copied to
+	<filename>/usr/local/etc/poudriere.conf</filename> which can
+	then be edited to suit the local configuration.</para>
+      <para>While <acronym>ZFS</acronym> is not required on the
+	system running <application>poudriere</application>,
+	it is beneficial.  When <acronym>ZFS</acronym> is used, the
+	<varname>ZPOOL</varname> must be
+	specified in
 	<filename>/usr/local/etc/poudriere.conf</filename> and
-	<filename>/usr/local/etc/poudriere.d/</filename>.  Example
-	settings are shown in
-	<filename>/usr/local/etc/poudriere.conf.sample</filename>.</para>
-      <para>Using <acronym>ZFS</acronym> is not required,
-	but beneficial.  When <acronym>ZFS</acronym> is used, the
-	<varname>ZPOOL</varname> for
-	<application>Poudriere</application>'s datasets must be
-	specified.  Set <varname>FREEBSD_HOST</varname> to a nearby
-	mirror.  Defaults for the other values are adequate.  Defining
+	<varname>FREEBSD_HOST</varname> should be set to a nearby
+	mirror.  Defining
 	<varname>CCACHE_DIR</varname> enables the use of
 	<package role="port">devel/ccache</package> to cache
-	compilation.  This will reduce build times for
-	frequently-compiled code.  It is convenient to put
-	<application>Poudriere</application> datasets in an isolated
+	compilation and reduce build times for
+	frequently-compiled code.  It may be convenient to put
+	<application>poudriere</application> datasets in an isolated
 	tree mounted at
-	<filename class="directory">/poudriere</filename>.  That is
-	not a functional modification, but a matter of taste.</para>
+	<filename class="directory">/poudriere</filename>.  Defaults
+	for the other configuration values are adequate.</para>
       <para>The number of processor cores detected is used to define
 	how many builds should run in parallel.  Supply enough virtual
 	memory, either with <acronym>RAM</acronym> or swap space.  If
 	virtual memory runs out, compiling jails will stop and be torn
 	down, resulting in weird error messages.</para>
-    </sect2>
     <sect2 xml:id="poudriere-initialization">
       <title>Initialize Jails and Port Trees</title>
-      <para>Initially, it is sufficient to install a &os; tree and a
-	ports tree.  Creating a simple setup only requires supplying a
-	name with <option>-j</option> and a version with
+      <para>Once configured, initialize
+	<application>poudriere</application> so that it installs a
+	jail with the required &os; tree and a
+	ports tree.  Specify a name for the jail using
+	<option>-j</option> and the &os; version with
 	<option>-v</option>.  On systems running &os;/&arch.amd64;,
 	the architecture can be set with <option>-a</option> to
 	either <literal>i386</literal> or <literal>amd64</literal>.
-	The default is the architecture shown by
+	The default is to use the architecture shown by
       <screen>&prompt.root; <userinput>poudriere jail -c -j <replaceable>10amd64</replaceable> -v <replaceable>10.0-RELEASE</replaceable></userinput>
@@ -1644,12 +1649,12 @@ Fetching 1 new ports or files... done.
 Building new INDEX files... done.</screen>
-      <para>On a single computer, <application>Poudriere</application>
+      <para>On a single computer, <application>poudriere</application>
 	can build ports with multiple configurations, in multiple
 	jails, and from different port trees.  Custom configurations
 	for these combinations are called <emphasis>sets</emphasis>.
 	See the CUSTOMIZATION section of &man.poudriere.8; for
-	detail.</para>
+	details.</para>
       <para>The basic configuration shown here puts a single jail-,
 	port-, and set-specific <filename>make.conf</filename> in
@@ -1670,29 +1675,29 @@ devel/git
-      <para>Options and dependencies for the specified ports are
-	configured:</para>
+      <para>To configure the options and dependencies for the
+	specified ports:</para>
       <screen>&prompt.root; <userinput>poudriere options -j <replaceable>10amd64</replaceable> -p <replaceable>local</replaceable> -z <replaceable>workstation</replaceable> -f <replaceable>workstation-pkglist</replaceable></userinput></screen>
-      <para>Finally, packages are built and a &man.pkg.8; repository
-	is created:</para>
+      <para>Finally, to build the packages and create the package
+	repository:</para>
       <screen>&prompt.root; <userinput>poudriere bulk -j <replaceable>10amd64</replaceable> -p <replaceable>local</replaceable> -z <replaceable>workstation</replaceable> -f <replaceable>workstation-pkglist</replaceable></userinput></screen>
-	displays the current state.
+	displays the current state of the build.
 	<application>Poudriere</application> also builds files in
 	that can be used with a web server to display build
-      <para>Packages are now available for installation from the
-	<application>Poudriere</application> repository.</para>
+      <para>Once the build is complete, packages are now available for installation from the
+	<application>poudriere</application> repository.</para>
-      <para>For more information on
-	<application>Poudriere</application>, see &man.poudriere.8;
+      <para>For more information on using
+	<application>poudriere</application>, see &man.poudriere.8;
 	and the main web site, <link

More information about the svn-doc-all mailing list