Skip site navigation (1)Skip section navigation (2)
Date:      Sun, 16 Feb 2014 02:10:30 +0000 (UTC)
From:      Warren Block <wblock@FreeBSD.org>
To:        doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org
Subject:   svn commit: r43952 - head/en_US.ISO8859-1/books/porters-handbook/quick-porting
Message-ID:  <201402160210.s1G2AUQT041951@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: wblock
Date: Sun Feb 16 02:10:29 2014
New Revision: 43952
URL: http://svnweb.freebsd.org/changeset/doc/43952

Log:
  Whitespace-only cleanup, translators please ignore.

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml	Sun Feb 16 00:44:25 2014	(r43951)
+++ head/en_US.ISO8859-1/books/porters-handbook/quick-porting/chapter.xml	Sun Feb 16 02:10:29 2014	(r43952)
@@ -4,45 +4,47 @@
 
      $FreeBSD$
 -->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="quick-porting">
+<chapter xmlns="http://docbook.org/ns/docbook"
+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+  xml:id="quick-porting">
+
+  <title>Quick Porting</title>
+
+  <para>This section tells you how to quickly create a new port.  In
+    many cases, it is not sufficient, so you will have to read
+    further on into the document.</para>
+
+  <para>First, get the original tarball and put it into
+    <varname>DISTDIR</varname>, which defaults to
+    <filename>/usr/ports/distfiles</filename>.</para>
+
+  <note>
+    <para>The following assumes that the software compiled
+      out-of-the-box, i.e., there was absolutely no change required
+      for the port to work on your &os; box.  If you needed to
+      change something, you will have to refer to the next section
+      too.</para>
+  </note>
+
+  <note>
+    <para>It is recommended to set the <varname>DEVELOPER</varname>
+      &man.make.1; variable in <filename>/etc/make.conf</filename>
+      before getting into porting.</para>
+
+    <screen>&prompt.root; <userinput>echo DEVELOPER=yes &gt;&gt; /etc/make.conf</userinput></screen>
+
+    <para>This setting enables the <quote>developer mode</quote>
+      that displays deprecation warnings and activates some further
+      quality checks on calling <command>make</command>.</para>
+  </note>
 
-    <title>Quick Porting</title>
+  <sect1 xml:id="porting-makefile">
+    <title>Writing the <filename>Makefile</filename></title>
 
-    <para>This section tells you how to quickly create a new port.  In
-      many cases, it is not sufficient, so you will have to read
-      further on into the document.</para>
+    <para>The minimal <filename>Makefile</filename> would look
+      something like this:</para>
 
-    <para>First, get the original tarball and put it into
-      <varname>DISTDIR</varname>, which defaults to
-      <filename>/usr/ports/distfiles</filename>.</para>
-
-    <note>
-      <para>The following assumes that the software compiled
-	out-of-the-box, i.e., there was absolutely no change required
-	for the port to work on your &os; box.  If you needed to
-	change something, you will have to refer to the next section
-	too.</para>
-    </note>
-
-    <note>
-      <para>It is recommended to set the <varname>DEVELOPER</varname>
-	&man.make.1; variable in <filename>/etc/make.conf</filename>
-	before getting into porting.</para>
-
-      <screen>&prompt.root; <userinput>echo DEVELOPER=yes &gt;&gt; /etc/make.conf</userinput></screen>
-
-      <para>This setting enables the <quote>developer mode</quote>
-	that displays deprecation warnings and activates some further
-	quality checks on calling <command>make</command>.</para>
-    </note>
-
-    <sect1 xml:id="porting-makefile">
-      <title>Writing the <filename>Makefile</filename></title>
-
-      <para>The minimal <filename>Makefile</filename> would look
-	something like this:</para>
-
-      <programlisting># &dollar;FreeBSD&dollar;
+    <programlisting># &dollar;FreeBSD&dollar;
 
 PORTNAME=	oneko
 PORTVERSION=	1.1b
@@ -54,101 +56,100 @@ COMMENT=	Cat chasing a mouse all over th
 
 .include &lt;bsd.port.mk&gt;</programlisting>
 
+    <note>
+      <para>In some cases, the <filename>Makefile</filename> of an
+	existing port may contain additional lines in the header,
+	such as the name of the port and the date it was created.
+	This additional information has been declared obsolete, and
+	is being phased out.</para>
+    </note>
+
+    <para>See if you can figure it out.  Do not worry about the
+      contents of the <literal>&dollar;FreeBSD&dollar;</literal>
+      line, it will be filled in automatically by
+      <application>Subversion</application> when the port is
+      imported to our main ports tree.  You can find a more detailed
+      example in the
+      <link linkend="porting-samplem">sample Makefile</link>
+      section.</para>
+  </sect1>
+
+  <sect1 xml:id="porting-desc">
+    <title>Writing the Description Files</title>
+
+    <para>There are two description files that are required for
+      any port, whether they actually package or not.  They are
+      <filename>pkg-descr</filename> and
+      <filename>pkg-plist</filename>.  Their
+      <filename>pkg-</filename> prefix distinguishes them from other
+      files.</para>
+
+    <sect2>
+      <title><filename>pkg-descr</filename></title>
+
+      <para>This is a longer description of the port.  One to a few
+	paragraphs concisely explaining what the port does is
+	sufficient.</para>
+
       <note>
-	<para>In some cases, the <filename>Makefile</filename> of an
-	  existing port may contain additional lines in the header,
-	  such as the name of the port and the date it was created.
-	  This additional information has been declared obsolete, and
-	  is being phased out.</para>
+	<para>This is <emphasis>not</emphasis> a manual or an
+	  in-depth description on how to use or compile the port!
+	  <emphasis>Please be careful if you are copying from the
+	  <filename>README</filename> or manpage</emphasis>; too
+	  often they are not a concise description of the port or
+	  are in an awkward format (e.g., manpages have justified
+	  spacing, which looks particularly bad with monospaced
+	  fonts).</para>
       </note>
 
-      <para>See if you can figure it out.  Do not worry about the
-	contents of the <literal>&dollar;FreeBSD&dollar;</literal>
-	line, it will be filled in automatically by
-	<application>Subversion</application> when the port is
-	imported to our main ports tree.  You can find a more detailed
-	example in the
-	<link linkend="porting-samplem">sample Makefile</link>
-	section.</para>
-    </sect1>
-
-    <sect1 xml:id="porting-desc">
-      <title>Writing the Description Files</title>
-
-      <para>There are two description files that are required for
-	any port, whether they actually package or not.  They are
-	<filename>pkg-descr</filename> and
-	<filename>pkg-plist</filename>.  Their
-	<filename>pkg-</filename> prefix distinguishes them from other
-	files.</para>
-
-      <sect2>
-	<title><filename>pkg-descr</filename></title>
-
-	<para>This is a longer description of the port.  One to a few
-	  paragraphs concisely explaining what the port does is
-	  sufficient.</para>
-
-	<note>
-	  <para>This is <emphasis>not</emphasis> a manual or an
-	    in-depth description on how to use or compile the port!
-	    <emphasis>Please be careful if you are copying from the
-	    <filename>README</filename> or manpage</emphasis>; too
-	    often they are not a concise description of the port or
-	    are in an awkward format (e.g., manpages have justified
-	    spacing, which looks particularly bad with monospaced
-	    fonts).</para>
-	</note>
-
-	<para>A well-written <filename>pkg-descr</filename> describes
-	  the port completely enough that users would not have to
-	  consult the documentation or visit the website to understand
-	  what the software does, how it can be useful, or what
-	  particularly nice features it has.  Mentioning certain
-	  requirements like a graphical toolkit, heavy dependencies,
-	  runtime environment, or implementation languages help users
-	  decide whether this port will work for them.</para>
-
-	<para>Include a URL to the official WWW homepage.  Prepend
-	  <emphasis>one</emphasis> of the websites (pick the most
-	  common one) with <literal>WWW:</literal> (followed by single
-	  space) so that automated tools will work correctly.  If the
-	  URI is the root of the website or directory, it should be
-	  terminated with a slash.</para>
-
-	<note>
-	  <para>If the listed webpage for a port is not available, try
-	    to search the Internet first to see if the official site
-	    moved, was renamed, or is hosted elsewhere.</para>
-	</note>
+      <para>A well-written <filename>pkg-descr</filename> describes
+	the port completely enough that users would not have to
+	consult the documentation or visit the website to understand
+	what the software does, how it can be useful, or what
+	particularly nice features it has.  Mentioning certain
+	requirements like a graphical toolkit, heavy dependencies,
+	runtime environment, or implementation languages help users
+	decide whether this port will work for them.</para>
+
+      <para>Include a URL to the official WWW homepage.  Prepend
+	<emphasis>one</emphasis> of the websites (pick the most
+	common one) with <literal>WWW:</literal> (followed by single
+	space) so that automated tools will work correctly.  If the
+	URI is the root of the website or directory, it should be
+	terminated with a slash.</para>
 
-	<para>The following example shows how your
-	  <filename>pkg-descr</filename> should look:</para>
+      <note>
+	<para>If the listed webpage for a port is not available, try
+	  to search the Internet first to see if the official site
+	  moved, was renamed, or is hosted elsewhere.</para>
+      </note>
+
+      <para>The following example shows how your
+	<filename>pkg-descr</filename> should look:</para>
 
-	<programlisting>This is a port of oneko, in which a cat chases a poor mouse all over
+      <programlisting>This is a port of oneko, in which a cat chases a poor mouse all over
 the screen.
  :
 (etc.)
 
 WWW: http://www.oneko.org/</programlisting>;
-      </sect2>
+    </sect2>
 
-      <sect2>
-	<title><filename>pkg-plist</filename></title>
+    <sect2>
+      <title><filename>pkg-plist</filename></title>
 
-	<para>This file lists all the files installed by the port.  It
-	  is also called the <quote>packing list</quote> because the
-	  package is generated by packing the files listed here.  The
-	  pathnames are relative to the installation prefix (usually
-	  <filename>/usr/local</filename>.
-	  If the
-	  port creates directories during installation, make sure to
-	  add <literal>@dirrm</literal> lines to remove them when the
-	  package is deleted.</para>
+      <para>This file lists all the files installed by the port.  It
+	is also called the <quote>packing list</quote> because the
+	package is generated by packing the files listed here.  The
+	pathnames are relative to the installation prefix (usually
+	<filename>/usr/local</filename>.  If the port creates
+	directories during installation, make sure to add
+	<literal>@dirrm</literal> lines to remove them when the
+	package is deleted.</para>
 
-	<para>Here is a small example:</para>
+      <para>Here is a small example:</para>
 
-	<programlisting>bin/oneko
+      <programlisting>bin/oneko
 man/man1/oneko.1.gz
 lib/X11/app-defaults/Oneko
 lib/X11/oneko/cat1.xpm
@@ -156,34 +157,34 @@ lib/X11/oneko/cat2.xpm
 lib/X11/oneko/mouse.xpm
 @dirrm lib/X11/oneko</programlisting>
 
-	<para>Refer to the &man.pkg-create.8; manual page for details
-	  on the packing list.</para>
+      <para>Refer to the &man.pkg-create.8; manual page for details
+	on the packing list.</para>
 
-	<note>
-	  <para>It is recommended that you keep all the filenames in
-	    this file sorted alphabetically.  It will make verifying
-	    the changes when you upgrade the port much easier.</para>
-	</note>
-
-	<note>
-	  <para>Creating a packing list manually can be a very tedious
-	    task.  If the port installs a large numbers of files,
-	    <link linkend="plist-autoplist">creating the packing list
-	      automatically</link> might save time.</para>
-	</note>
-
-	<para>There is only one case when
-	  <filename>pkg-plist</filename> can be omitted from a port.
-	  If the port installs just a handful of files, and perhaps
-	  directories, the files and directories may be listed in the
-	  variables <varname>PLIST_FILES</varname> and
-	  <varname>PLIST_DIRS</varname>, respectively, within the
-	  port's <filename>Makefile</filename>.  For instance, we
-	  could get along without <filename>pkg-plist</filename> in
-	  the above <filename>oneko</filename> port by adding the
-	  following lines to the <filename>Makefile</filename>:</para>
+      <note>
+	<para>It is recommended that you keep all the filenames in
+	  this file sorted alphabetically.  It will make verifying
+	  the changes when you upgrade the port much easier.</para>
+      </note>
+
+      <note>
+	<para>Creating a packing list manually can be a very tedious
+	  task.  If the port installs a large numbers of files,
+	  <link linkend="plist-autoplist">creating the packing list
+	    automatically</link> might save time.</para>
+      </note>
 
-	<programlisting>PLIST_FILES=	bin/oneko \
+      <para>There is only one case when
+	<filename>pkg-plist</filename> can be omitted from a port.
+	If the port installs just a handful of files, and perhaps
+	directories, the files and directories may be listed in the
+	variables <varname>PLIST_FILES</varname> and
+	<varname>PLIST_DIRS</varname>, respectively, within the
+	port's <filename>Makefile</filename>.  For instance, we
+	could get along without <filename>pkg-plist</filename> in
+	the above <filename>oneko</filename> port by adding the
+	following lines to the <filename>Makefile</filename>:</para>
+
+      <programlisting>PLIST_FILES=	bin/oneko \
 		man/man1/oneko.1.gz \
 		lib/X11/app-defaults/Oneko \
 		lib/X11/oneko/cat1.xpm \
@@ -191,215 +192,211 @@ lib/X11/oneko/mouse.xpm
 		lib/X11/oneko/mouse.xpm
 PLIST_DIRS=	lib/X11/oneko</programlisting>
 
-	<para>Of course, <varname>PLIST_DIRS</varname> should be left
-	  unset if a port installs no directories of its own.</para>
-
-	<note>
-
-	  <para>Several ports can share a common directory.  In that
-	    case, <varname>PLIST_DIRS</varname> should be replaced by
-	    <varname>PLIST_DIRSTRY</varname> so that the directory is
-	    removed only if empty, otherwise it is silently ignored.
-	    <varname>PLIST_DIRS</varname> and
-	    <varname>PLIST_DIRSTRY</varname> are equivalent to using
-	    <literal>@dirrm</literal> and <literal>@dirrmtry</literal>
-	    in <filename>pkg-plist</filename>, as described in
-	    <xref linkend="plist-dir-cleaning"/>.</para>
-	</note>
-
-	<para>The price for this way of listing port's files and
-	  directories is that you cannot use command sequences
-	  described in &man.pkg-create.8;.  Therefore, it is suitable
-	  only for simple ports and makes them even simpler.  At the
-	  same time, it has the advantage of reducing the number of
-	  files in the ports collection.  Please consider using this
-	  technique before you resort to
-	  <filename>pkg-plist</filename>.</para>
-
-	<para>Later we will see how <filename>pkg-plist</filename>
-	  and <varname>PLIST_FILES</varname> can be used to fulfill
-	  <link linkend="plist">more sophisticated
-	    tasks</link>.</para>
-      </sect2>
-    </sect1>
-
-    <sect1 xml:id="porting-checksum">
-      <title>Creating the Checksum File</title>
-
-      <para>Just type <command>make makesum</command>.  The ports make
-	rules will automatically generate the file
-	<filename>distinfo</filename>.</para>
-
-      <para>If a file fetched has its checksum changed regularly and
-	you are certain the source is trusted (i.e., it comes from
-	manufacturer CDs or documentation generated daily), you should
-	specify these files in the <varname>IGNOREFILES</varname>
-	variable.  Then the checksum is not calculated for that file
-	when you run <command>make makesum</command>, but set to
-	<literal>IGNORE</literal>.</para>
-    </sect1>
-
-    <sect1 xml:id="porting-testing">
-      <title>Testing the Port</title>
-
-      <para>You should make sure that the port rules do exactly what
-	you want them to do, including packaging up the port.  These
-	are the important points you need to verify.</para>
-
-      <itemizedlist>
-	<listitem>
-	  <para><filename>pkg-plist</filename> does not contain
-	    anything not installed by the port.</para>
-	</listitem>
-
-	<listitem>
-	  <para><filename>pkg-plist</filename> contains everything
-	    that is installed by the port.</para>
-	</listitem>
-
-	<listitem>
-	  <para>The port can be installed using the
-	    <buildtarget>install</buildtarget> target.  This verifies
-	    that the install script works correctly.</para>
-	</listitem>
-
-	<listitem>
-	  <para>The port can be deinstalled properly using the
-	    <buildtarget>deinstall</buildtarget> target.  This
-	    verifies that the deinstall script works correctly.</para>
-	</listitem>
-
-	<listitem>
-	  <para>Make sure that <command>make package</command> can be
-	    run as a normal user (that is, not as
-	    <systemitem class="username">root</systemitem>).  If that
-	    fails, <literal>NEED_ROOT=yes</literal> must be added to
-	    the port <filename>Makefile</filename>.</para>
-	</listitem>
-      </itemizedlist>
-
-      <procedure>
-	<title>Recommended Test Ordering</title>
-
-	<step>
-	  <para><command>make stage</command></para>
-	</step>
-
-	<step>
-	  <para><command>make check-orphans</command></para>
-	</step>
-
-	<step>
-	  <para><command>make package</command></para>
-	</step>
-
-	<step>
-	  <para><command>make install</command></para>
-	</step>
-
-	<step>
-	  <para><command>make deinstall</command></para>
-	</step>
-
-	<step>
-	  <para><command>pkg add package-filename</command></para>
-	</step>
-
-	<step>
-	  <para><command>make package</command> (as user)</para>
-	</step>
-      </procedure>
-
-      <para>Make certain no warnings are shown in any of
-	the stages.</para>
-
-      <para>Thorough automated testing can be done with
-	<package role="port">ports-mgmt/tinderbox</package> or
-	<package role="port">ports-mgmt/poudriere</package> from the
-	Ports Collection.  These applications maintain
-	<literal>jails</literal> where all of the steps shown above
-	can be tested without affecting the state of the host
-	system.</para>
-    </sect1>
-
-    <sect1 xml:id="porting-portlint">
-      <title>Checking Your Port with
-	<command>portlint</command></title>
-
-      <para>Please use <command>portlint</command> to see if your port
-	conforms to our guidelines.  The
-	<package role="port">ports-mgmt/portlint</package>
-	program is part of the ports collection.  In particular, you
-	may want to check if the
-	<link linkend="porting-samplem">Makefile</link> is in the
-	right shape and the
-	<link linkend="porting-pkgname">package</link> is named
-	appropriately.</para>
-    </sect1>
-
-    <sect1 xml:id="porting-submitting">
-      <title>Submitting the New Port</title>
-
-      <para>Before submitting the new port, read
-	the <link linkend="porting-dads">DOs and DON'Ts</link>
-	section.</para>
-
-      <para>Once happy with your port, the only thing remaining is to
-	put it in the main &os; ports tree and make everybody else
-	happy about it too.  We do not need the
-	<filename>work</filename> directory or the
-	<filename>pkgname.tgz</filename> package, so delete them
-	now.</para>
-
-      <para>Next, build the &man.shar.1; file.  Assuming the port is
-	called <literal>oneko</literal>, <command>cd</command> to the
-	directory above where the <literal>oneko</literal> directory
-	is located, and then type:
-	<command>shar `find oneko` &gt; oneko.shar</command></para>
-
-      <para>Include <filename>oneko.shar</filename> in a bug
-	report and send it with &man.send-pr.1;.  See
-	<link
-	  xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug
-	  Reports and General Commentary</link> for more information
-	about &man.send-pr.1;.</para>
-
-      <para>Classify the bug report as Category
-	<literal>ports</literal> and Class
-	<literal>change-request</literal>.  Do
-	<emphasis>not</emphasis> mark the report
-	<literal>confidential</literal>!  Add a short description of
-	the program to the Description field of the PR (perhaps a
-	short version of the <varname>COMMENT</varname>), and add the
-	<filename>.shar</filename> file to the Fix field.</para>
+      <para>Of course, <varname>PLIST_DIRS</varname> should be left
+	unset if a port installs no directories of its own.</para>
 
       <note>
-	<para>Giving a good description in the synopsis of the problem
-	  report makes the work of port committers a lot easier.  We
-	  prefer something like <quote>New port:
-	    &lt;category&gt;/&lt;portname&gt; &lt;short description of
-	    the port&gt;</quote> for new ports.  Using this
-	  scheme makes it easier and faster to begin the work of
-	  committing the new port.</para>
+	<para>Several ports can share a common directory.  In that
+	  case, <varname>PLIST_DIRS</varname> should be replaced by
+	  <varname>PLIST_DIRSTRY</varname> so that the directory is
+	  removed only if empty, otherwise it is silently ignored.
+	  <varname>PLIST_DIRS</varname> and
+	  <varname>PLIST_DIRSTRY</varname> are equivalent to using
+	  <literal>@dirrm</literal> and <literal>@dirrmtry</literal>
+	  in <filename>pkg-plist</filename>, as described in
+	  <xref linkend="plist-dir-cleaning"/>.</para>
       </note>
 
-      <para>One more time, <emphasis>do not include the original
-	  source distfile, the <filename>work</filename> directory, or
-	  the package you built with
-	  <command>make package</command></emphasis>; and, do use
-	&man.shar.1; for new ports, not &man.diff.1;.</para>
-
-      <para>After submitting the port, please be patient.  The time
-	needed to include a new port in &os; can vary from a few days
-	to a few months.  The list of pending port
-	<acronym>PR</acronym>s can be viewed at <link
-	  xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports"></link>.</para>;
-
-      <para>After looking at the new port, we will reply if necessary,
-	and put it in the tree.  Your name will also be added to the
-	list of <link
-	  xlink:href="&url.articles.contributors;/contrib-additional.html">Additional
-	  &os; Contributors</link> and other files.</para>
-    </sect1>
-  </chapter>
+      <para>The price for this way of listing port's files and
+	directories is that you cannot use command sequences
+	described in &man.pkg-create.8;.  Therefore, it is suitable
+	only for simple ports and makes them even simpler.  At the
+	same time, it has the advantage of reducing the number of
+	files in the ports collection.  Please consider using this
+	technique before you resort to
+	<filename>pkg-plist</filename>.</para>
+
+      <para>Later we will see how <filename>pkg-plist</filename>
+	and <varname>PLIST_FILES</varname> can be used to fulfill
+	<link linkend="plist">more sophisticated
+	  tasks</link>.</para>
+    </sect2>
+  </sect1>
+
+  <sect1 xml:id="porting-checksum">
+    <title>Creating the Checksum File</title>
+
+    <para>Just type <command>make makesum</command>.  The ports make
+      rules will automatically generate the file
+      <filename>distinfo</filename>.</para>
+
+    <para>If a file fetched has its checksum changed regularly and
+      you are certain the source is trusted (i.e., it comes from
+      manufacturer CDs or documentation generated daily), you should
+      specify these files in the <varname>IGNOREFILES</varname>
+      variable.  Then the checksum is not calculated for that file
+      when you run <command>make makesum</command>, but set to
+      <literal>IGNORE</literal>.</para>
+  </sect1>
+
+  <sect1 xml:id="porting-testing">
+    <title>Testing the Port</title>
+
+    <para>You should make sure that the port rules do exactly what
+      you want them to do, including packaging up the port.  These
+      are the important points you need to verify.</para>
+
+    <itemizedlist>
+      <listitem>
+	<para><filename>pkg-plist</filename> does not contain
+	  anything not installed by the port.</para>
+      </listitem>
+
+      <listitem>
+	<para><filename>pkg-plist</filename> contains everything
+	  that is installed by the port.</para>
+      </listitem>
+
+      <listitem>
+	<para>The port can be installed using the
+	  <buildtarget>install</buildtarget> target.  This verifies
+	  that the install script works correctly.</para>
+      </listitem>
+
+      <listitem>
+	<para>The port can be deinstalled properly using the
+	  <buildtarget>deinstall</buildtarget> target.  This
+	  verifies that the deinstall script works correctly.</para>
+      </listitem>
+
+      <listitem>
+	<para>Make sure that <command>make package</command> can be
+	  run as a normal user (that is, not as
+	  <systemitem class="username">root</systemitem>).  If that
+	  fails, <literal>NEED_ROOT=yes</literal> must be added to
+	  the port <filename>Makefile</filename>.</para>
+      </listitem>
+    </itemizedlist>
+
+    <procedure>
+      <title>Recommended Test Ordering</title>
+
+      <step>
+	<para><command>make stage</command></para>
+      </step>
+
+      <step>
+	<para><command>make check-orphans</command></para>
+      </step>
+
+      <step>
+	<para><command>make package</command></para>
+      </step>
+
+      <step>
+	<para><command>make install</command></para>
+      </step>
+
+      <step>
+	<para><command>make deinstall</command></para>
+      </step>
+
+      <step>
+	<para><command>pkg add package-filename</command></para>
+      </step>
+
+      <step>
+	<para><command>make package</command> (as user)</para>
+      </step>
+    </procedure>
+
+    <para>Make certain no warnings are shown in any of
+      the stages.</para>
+
+    <para>Thorough automated testing can be done with
+      <package role="port">ports-mgmt/tinderbox</package> or
+      <package role="port">ports-mgmt/poudriere</package> from the
+      Ports Collection.  These applications maintain
+      <literal>jails</literal> where all of the steps shown above
+      can be tested without affecting the state of the host
+      system.</para>
+  </sect1>
+
+  <sect1 xml:id="porting-portlint">
+    <title>Checking Your Port with
+      <command>portlint</command></title>
+
+    <para>Please use <command>portlint</command> to see if your port
+      conforms to our guidelines.  The
+      <package role="port">ports-mgmt/portlint</package>
+      program is part of the ports collection.  In particular, you
+      may want to check if the
+      <link linkend="porting-samplem">Makefile</link> is in the
+      right shape and the
+      <link linkend="porting-pkgname">package</link> is named
+      appropriately.</para>
+  </sect1>
+
+  <sect1 xml:id="porting-submitting">
+    <title>Submitting the New Port</title>
+
+    <para>Before submitting the new port, read the
+      <link linkend="porting-dads">DOs and DON'Ts</link>
+      section.</para>
+
+    <para>Once happy with your port, the only thing remaining is to
+      put it in the main &os; ports tree and make everybody else
+      happy about it too.  We do not need the
+      <filename>work</filename> directory or the
+      <filename>pkgname.tgz</filename> package, so delete them
+      now.</para>
+
+    <para>Next, build the &man.shar.1; file.  Assuming the port is
+      called <literal>oneko</literal>, <command>cd</command> to the
+      directory above where the <literal>oneko</literal> directory
+      is located, and then type:
+      <command>shar `find oneko` &gt; oneko.shar</command></para>
+
+    <para>Include <filename>oneko.shar</filename> in a bug
+      report and send it with &man.send-pr.1;.  See <link
+	xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug
+	Reports and General Commentary</link> for more information
+      about &man.send-pr.1;.</para>
+
+    <para>Classify the bug report as Category
+      <literal>ports</literal> and Class
+      <literal>change-request</literal>.  Do <emphasis>not</emphasis>
+      mark the report <literal>confidential</literal>!  Add a short
+      description of the program to the Description field of the PR
+      (perhaps a short version of the <varname>COMMENT</varname>), and
+      add the <filename>.shar</filename> file to the Fix field.</para>
+
+    <note>
+      <para>Giving a good description in the synopsis of the problem
+	report makes the work of port committers a lot easier.  We
+	prefer something like <quote>New port:
+	  &lt;category&gt;/&lt;portname&gt; &lt;short description of
+	  the port&gt;</quote> for new ports.  Using this
+	scheme makes it easier and faster to begin the work of
+	committing the new port.</para>
+    </note>
 
+    <para>One more time, <emphasis>do not include the original
+	source distfile, the <filename>work</filename> directory, or
+	the package you built with
+	<command>make package</command></emphasis>; and, do use
+      &man.shar.1; for new ports, not &man.diff.1;.</para>
+
+    <para>After submitting the port, please be patient.  The time
+      needed to include a new port in &os; can vary from a few days
+      to a few months.  The list of pending port
+      <acronym>PR</acronym>s can be viewed at <link
+	xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports"></link>.</para>;
+
+    <para>After looking at the new port, we will reply if necessary,
+      and put it in the tree.  Your name will also be added to the
+      list of <link
+	xlink:href="&url.articles.contributors;/contrib-additional.html">Additional
+	&os; Contributors</link> and other files.</para>
+  </sect1>
+</chapter>



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402160210.s1G2AUQT041951>