Skip site navigation (1)Skip section navigation (2)
Date:      Sun, 16 Feb 2014 02:39:13 +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: r43954 - head/en_US.ISO8859-1/books/porters-handbook/slow-porting
Message-ID:  <201402160239.s1G2dDF0052951@svn.freebsd.org>

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

Log:
  Whitespace-only fixes, translators please ignore.

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

Modified: head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml	Sun Feb 16 02:24:38 2014	(r43953)
+++ head/en_US.ISO8859-1/books/porters-handbook/slow-porting/chapter.xml	Sun Feb 16 02:39:13 2014	(r43954)
@@ -4,427 +4,414 @@
 
      $FreeBSD$
 -->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="slow-porting">
+<chapter xmlns="http://docbook.org/ns/docbook"
+  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+  xml:id="slow-porting">
+
+  <title>Slow Porting</title>
+
+  <para>Okay, so it was not that simple, and the port required some
+    modifications to get it to work.  In this section, we will
+    explain, step by step, how to modify it to get it to work with the
+    ports paradigm.</para>
+
+  <sect1 xml:id="slow-work">
+    <title>How Things Work</title>
+
+    <para>First, this is the sequence of events which occurs when the
+      user first types <command>make</command> in your port's
+      directory.  You may find that having
+      <filename>bsd.port.mk</filename> in another window while you
+      read this really helps to understand it.</para>
+
+    <para>But do not worry if you do not really understand what
+      <filename>bsd.port.mk</filename> is doing, not many people do...
+      <!-- smiley --><emphasis>:-)</emphasis></para>
+
+    <procedure>
+      <step>
+	<para>The <buildtarget>fetch</buildtarget> target is run.  The
+	  <buildtarget>fetch</buildtarget> target is responsible for
+	  making sure that the tarball exists locally in
+	  <varname>DISTDIR</varname>.  If
+	  <buildtarget>fetch</buildtarget> cannot find the required
+	  files in <varname>DISTDIR</varname> it will look up the URL
+	  <varname>MASTER_SITES</varname>, which is set in the
+	  Makefile, as well as our FTP mirrors where we put distfiles
+	  as backup.  It will then attempt to fetch the named
+	  distribution file with <varname>FETCH</varname>, assuming
+	  that the requesting site has direct access to the Internet.
+	  If that succeeds, it will save the file in
+	  <varname>DISTDIR</varname> for future use and
+	  proceed.</para>
+      </step>
+
+      <step>
+	<para>The <buildtarget>extract</buildtarget> target is run.
+	  It looks for your port's distribution file (typically a
+	  <command>gzip</command>ped tarball) in
+	  <varname>DISTDIR</varname> and unpacks it into a temporary
+	  subdirectory specified by <varname>WRKDIR</varname>
+	  (defaults to <filename>work</filename>).</para>
+      </step>
+
+      <step>
+	<para>The <buildtarget>patch</buildtarget> target is run.
+	  First, any patches defined in <varname>PATCHFILES</varname>
+	  are applied.  Second, if any patch files named
+	  <filename>patch-*</filename> are found in
+	  <varname>PATCHDIR</varname> (defaults to the
+	  <filename>files</filename> subdirectory), they are applied
+	  at this time in alphabetical order.</para>
+      </step>
+
+      <step>
+	<para>The <buildtarget>configure</buildtarget> target is run.
+	  This can do any one of many different things.</para>
+
+	<orderedlist>
+	  <listitem>
+	    <para>If it exists, <filename>scripts/configure</filename>
+	      is run.</para>
+	  </listitem>
+
+	  <listitem>
+	    <para>If <varname>HAS_CONFIGURE</varname> or
+	      <varname>GNU_CONFIGURE</varname> is set,
+	      <filename>WRKSRC/configure</filename> is run.</para>
+	  </listitem>
+	</orderedlist>
+      </step>
+
+      <step>
+	<para>The <buildtarget>build</buildtarget> target is run.
+	  This is responsible for descending into the port's private
+	  working directory (<varname>WRKSRC</varname>) and building
+	  it.</para>
+      </step>
+
+      <step>
+	<para>The <buildtarget>stage</buildtarget> target is run.
+	  This puts the final set of built files into a temporary
+	  directory (<varname>STAGEDIR</varname>, see
+	  <xref linkend="staging"/>).  The hierarchy of this directory
+	  mirrors that of the system on which the package will be
+	  installed.</para>
+      </step>
+
+      <step>
+	<para>The <buildtarget>install</buildtarget> target is run.
+	  This copies the files listed in the port's pkg-plist to the
+	  host system.</para>
+      </step>
+    </procedure>
+
+    <para>The above are the default actions.  In addition, you can
+      define targets
+      <buildtarget>pre-<replaceable>something</replaceable></buildtarget>
+      or
+      <buildtarget>post-<replaceable>something</replaceable></buildtarget>,
+      or put scripts with those names, in the
+      <filename>scripts</filename> subdirectory, and they will be
+      run before or after the default actions are done.</para>
+
+    <para>For example, if you have a
+      <buildtarget>post-extract</buildtarget> target defined in your
+      <filename>Makefile</filename>, and a file
+      <filename>pre-build</filename> in the
+      <filename>scripts</filename> subdirectory, the
+      <buildtarget>post-extract</buildtarget> target will be called
+      after the regular extraction actions, and the
+      <filename>pre-build</filename> script will be executed before
+      the default build rules are done.  It is recommended that you
+      use <filename>Makefile</filename> targets if the actions are
+      simple enough, because it will be easier for someone to figure
+      out what kind of non-default action the port requires.</para>
+
+    <para>The default actions are done by the
+      <filename>bsd.port.mk</filename> targets
+      <buildtarget>do-<replaceable>something</replaceable></buildtarget>.
+      For example, the commands to extract a port are in the target
+      <buildtarget>do-extract</buildtarget>.  If you are not happy
+      with the default target, you can fix it by redefining the
+      <buildtarget>do-<replaceable>something</replaceable></buildtarget>
+      target in your <filename>Makefile</filename>.</para>
+
+    <note>
+      <para>The <quote>main</quote> targets (e.g.,
+	<buildtarget>extract</buildtarget>,
+	<buildtarget>configure</buildtarget>, etc.) do nothing more
+	than make sure all the stages up to that one are completed and
+	call the real targets or scripts, and they are not intended to
+	be changed.  If you want to fix the extraction, fix
+	<buildtarget>do-extract</buildtarget>, but never ever change
+	the way <buildtarget>extract</buildtarget> operates!
+	Additionally, the target
+	<buildtarget>post-deinstall</buildtarget> is invalid and is
+	not run by the ports infrastructure.</para>
+    </note>
+
+    <para>Now that you understand what goes on when the user types
+      <command>make install</command>, let us go through the
+      recommended steps to create the perfect port.</para>
+  </sect1>
+
+  <sect1 xml:id="slow-sources">
+    <title>Getting the Original Sources</title>
+
+    <para>Get the original sources (normally) as a compressed tarball
+      (<filename>foo.tar.gz</filename> or
+      <filename>foo.tar.bz2</filename>) and copy it into
+      <varname>DISTDIR</varname>.  Always use
+      <emphasis>mainstream</emphasis> sources when and where you
+      can.</para>
+
+    <para>You will need to set the variable
+      <varname>MASTER_SITES</varname> to reflect where the original
+      tarball resides.  You will find convenient shorthand definitions
+      for most mainstream sites in <filename>bsd.sites.mk</filename>.
+      Please use these sites&mdash;and the associated
+      definitions&mdash;if at all possible, to help avoid the problem
+      of having the same information repeated over again many times in
+      the source base.  As these sites tend to change over time, this
+      becomes a maintenance nightmare for everyone involved.</para>
+
+    <para>If you cannot find a FTP/HTTP site that is well-connected to
+      the net, or can only find sites that have irritatingly
+      non-standard formats, you might want to put a copy on a reliable
+      FTP or HTTP server that you control (e.g., your home
+      page).</para>
+
+    <para>If you cannot find somewhere convenient and reliable to put
+      the distfile we can <quote>house</quote> it ourselves on
+      <systemitem>ftp.FreeBSD.org</systemitem>; however, this is the
+      least-preferred solution.  The distfile must be placed into
+      <filename>~/public_distfiles/</filename> of someone's
+      <systemitem>freefall</systemitem> account.  Ask the person who
+      commits your port to do this.  This person will also set
+      <varname>MASTER_SITES</varname> to
+      <varname>MASTER_SITE_LOCAL</varname> and
+      <varname>MASTER_SITE_SUBDIR</varname> to their
+      <systemitem>freefall</systemitem> username.</para>
+
+    <para>If your port's distfile changes all the time without any
+      kind of version update by the author, consider putting the
+      distfile on your home page and listing it as the first
+      <varname>MASTER_SITES</varname>.  If you can, try to talk the
+      port author out of doing this; it really does help to establish
+      some kind of source code control.  Hosting your own version will
+      prevent users from getting
+      <errorname>checksum mismatch</errorname> errors, and also reduce
+      the workload of maintainers of our FTP site.  Also, if there is
+      only one master site for the port, it is recommended that you
+      house a backup at your site and list it as the second
+      <varname>MASTER_SITES</varname>.</para>
+
+    <para>If your port requires some additional `patches' that are
+      available on the Internet, fetch them too and put them in
+      <varname>DISTDIR</varname>.  Do not worry if they come from a
+      site other than where you got the main source tarball, we have a
+      way to handle these situations (see the description of <link
+	linkend="porting-patchfiles">PATCHFILES</link> below).</para>
+  </sect1>
+
+  <sect1 xml:id="slow-modifying">
+    <title>Modifying the Port</title>
+
+    <para>Unpack a copy of the tarball in a private directory and make
+      whatever changes are necessary to get the port to compile
+      properly under the current version of &os;.  Keep
+      <emphasis>careful track</emphasis> of everything you do, as you
+      will be automating the process shortly.  Everything, including
+      the deletion, addition, or modification of files should be
+      doable using an automated script or patch file when your port is
+      finished.</para>
+
+    <para>If your port requires significant user
+      interaction/customization to compile or install, you should take
+      a look at one of Larry Wall's classic
+      <application>Configure</application> scripts and perhaps do
+      something similar yourself.  The goal of the new ports
+      collection is to make each port as <quote>plug-and-play</quote>
+      as possible for the end-user while using a minimum of disk
+      space.</para>
+
+    <note>
+      <para>Unless explicitly stated, patch files, scripts, and other
+	files you have created and contributed to the &os; ports
+	collection are assumed to be covered by the standard BSD
+	copyright conditions.</para>
+    </note>
+  </sect1>
+
+  <sect1 xml:id="slow-patch">
+    <title>Patching</title>
+
+    <para>In the preparation of the port, files that have been added
+      or changed can be recorded with &man.diff.1; for later feeding
+      to &man.patch.1;.  Doing this with a typical file involves
+      saving a copy of the original file before making any
+      changes.</para>
+
+    <screen>&prompt.user; <userinput>cp <replaceable>file</replaceable> <replaceable>file</replaceable>.orig</userinput></screen>
+
+    <para>Patches are saved into files named
+      <filename>patch-*</filename> where <replaceable>*</replaceable>
+      indicates the pathname of the file that is patched, such as
+      <filename>patch-Imakefile</filename> or
+      <filename>patch-src-config.h</filename>.</para>
+
+    <para>After the file has been modified, &man.diff.1; is used to
+      record the differences between the original and the modified
+      version.  <option>-u</option> causes &man.diff.1; to produce
+      <quote>unified</quote> diffs, the preferred form.</para>
+
+    <screen>&prompt.user; <userinput>diff -u <replaceable>file</replaceable>.orig <replaceable>file</replaceable> &gt; patch-<replaceable>pathname-file</replaceable></userinput></screen>
+
+    <para>When generating patches for new, added files,
+      <option>-N</option> is added to tell &man.diff.1; to treat the
+      non-existent original file as if it existed but was
+      empty:</para>
+
+    <screen>&prompt.user; <userinput>diff -u -N <replaceable>newfile</replaceable>.orig <replaceable>newfile</replaceable> &gt; patch-<replaceable>pathname-newfile</replaceable></userinput></screen>
+
+    <para>Patch files are stored in <varname>PATCHDIR</varname>
+      (usually <filename class="directory">files/</filename>, from
+      where they will be automatically applied.  All patches must be
+      relative to <varname>WRKSRC</varname> (generally the directory
+      the port's tarball unpacks itself into, that being where the
+      build is done).  To make fixes and upgrades easier, avoid having
+      more than one patch fix the same file (that is,
+      <filename>patch-file</filename> and
+      <filename>patch-file2</filename> both changing
+      <filename>WRKSRC/foobar.c</filename>).  Note that if the path of
+      a patched file contains an underscore (<literal>_</literal>)
+      character, the patch needs to have two underscores instead in
+      its name.  For example, to patch a file named
+      <filename>src/freeglut_joystick.c</filename>, the corresponding
+      patch should be named
+      <filename>patch-src-freeglut__joystick.c</filename>.</para>
+
+    <para>Please only use characters
+      <literal>[-+._a-zA-Z0-9]</literal> for naming patches.  Do not
+      use any other characters besides them.  Do not name patches like
+      <filename>patch-aa</filename> or <filename>patch-ab</filename>,
+      always mention the path and file name in patch names.</para>
+
+    <para>There is an alternate, easier method for creating patches to
+      existing files.  The first steps are the same, make a copy of
+      the unmodified file with an <filename>.orig</filename>
+      extension, then make modifications.  Then use
+      <command>make makepatch</command> to write updated patch files
+      to the <filename>files</filename> directory of the port.</para>
+
+    <para>Do not put RCS strings in patches.
+      <application>Subversion</application> will mangle them when we
+      put the files into the ports tree, and when we check them out
+      again, they will come out different and the patch will fail.
+      RCS strings are surrounded by dollar
+      (<literal>&dollar;</literal>) signs, and typically start with
+      <literal>&dollar;Id</literal> or
+      <literal>&dollar;RCS</literal>.</para>
+
+    <para>Using the recurse (<option>-r</option>) option to
+      &man.diff.1; to generate patches is fine, but please look at the
+      resulting patches to make sure there is no unnecessary junk in
+      there.  In particular, diffs between two backup files,
+      <filename>Makefile</filename>s when the port uses
+      <command>Imake</command> or GNU <command>configure</command>,
+      etc., are unnecessary and should be deleted.  If it was
+      necessary to edit <filename>configure.in</filename> and run
+      <command>autoconf</command> to regenerate
+      <command>configure</command>, do not take the diffs of
+      <command>configure</command> (it often grows to a few thousand
+      lines!).  Instead, define
+      <literal>USE_AUTOTOOLS=autoconf:261</literal> and take the diffs
+      of <filename>configure.in</filename>.</para>
+
+    <para>Try to minimize the amount of non-functional whitespace
+      changes in patches.  It is common in the Open Source world for
+      projects to share large amounts of a code base, but obey
+      different style and indenting rules.  When taking a working
+      piece of functionality from one project to fix similar areas in
+      another, please be careful: the resulting line patch may be full
+      of non-functional changes.  It not only increases the size of
+      the <application>Subversion</application> repository but makes
+      it hard to find out what exactly caused the problem and what was
+      changed at all.</para>
+
+    <para>If a file must be deleted, do it in the
+      <buildtarget>post-extract</buildtarget> target rather than as
+      part of the patch.</para>
+
+    <para>Simple replacements can be performed directly from the port
+      <filename>Makefile</filename> using the in-place mode of
+      &man.sed.1;.  This is useful when changes use the value of a
+      variable:</para>
+
+    <programlisting>post-patch:
+      @${REINPLACE_CMD} -e 's|for Linux|for FreeBSD|g' ${WRKSRC}/README</programlisting>
+
+    <para>Quite often, software being ported uses the CR/LF convention
+      in source files.  This may cause problems with further patching,
+      compiler warnings, or script execution (like
+      <literal>/bin/sh^M not found</literal>.)  To quickly convert all
+      files from CR/LF to just LF, add this entry to the port
+      <filename>Makefile</filename>:</para>
 
-    <title>Slow Porting</title>
+    <programlisting>USES=	dos2unix</programlisting>
 
-    <para>Okay, so it was not that simple, and the port required some
-      modifications to get it to work.  In this section, we will
-      explain, step by step, how to modify it to get it to work with
-      the ports paradigm.</para>
-
-    <sect1 xml:id="slow-work">
-      <title>How Things Work</title>
-
-      <para>First, this is the sequence of events which occurs when
-	the user first types <command>make</command> in your port's
-	directory.  You may find that having
-	<filename>bsd.port.mk</filename> in another window while you
-	read this really helps to understand it.</para>
-
-      <para>But do not worry if you do not really understand what
-	<filename>bsd.port.mk</filename> is doing, not many people
-	do...  <!-- smiley --><emphasis>:-)</emphasis></para>
-
-      <procedure>
-	<step>
-	  <para>The <buildtarget>fetch</buildtarget> target is run.
-	    The <buildtarget>fetch</buildtarget> target is responsible
-	    for making sure that the tarball exists locally in
-	    <varname>DISTDIR</varname>.  If
-	    <buildtarget>fetch</buildtarget> cannot find the required
-	    files in <varname>DISTDIR</varname> it will look up the
-	    URL <varname>MASTER_SITES</varname>, which is set in the
-	    Makefile, as well as our FTP mirrors where we put
-	    distfiles as backup.  It will then attempt to fetch the
-	    named distribution file with <varname>FETCH</varname>,
-	    assuming that the requesting site has direct access to the
-	    Internet.  If that succeeds, it will save the file in
-	    <varname>DISTDIR</varname> for future use and
-	    proceed.</para>
-	</step>
-
-	<step>
-	  <para>The <buildtarget>extract</buildtarget> target is run.
-	    It looks for your port's distribution file (typically a
-	    <command>gzip</command>ped tarball) in
-	    <varname>DISTDIR</varname> and unpacks it into a temporary
-	    subdirectory specified by <varname>WRKDIR</varname>
-	    (defaults to <filename>work</filename>).</para>
-	</step>
-
-	<step>
-	  <para>The <buildtarget>patch</buildtarget> target is run.
-	    First, any patches defined in
-	    <varname>PATCHFILES</varname> are applied.  Second, if any
-	    patch files named
-	    <filename>patch-*</filename>
-	    are found in <varname>PATCHDIR</varname> (defaults to the
-	    <filename>files</filename> subdirectory), they are applied
-	    at this time in alphabetical order.</para>
-	</step>
-
-	<step>
-	  <para>The <buildtarget>configure</buildtarget> target is
-	    run.  This can do any one of many different things.</para>
-
-	  <orderedlist>
-	    <listitem>
-	      <para>If it exists,
-		<filename>scripts/configure</filename> is run.</para>
-	    </listitem>
-
-	    <listitem>
-	      <para>If <varname>HAS_CONFIGURE</varname> or
-		<varname>GNU_CONFIGURE</varname> is set,
-		<filename>WRKSRC/configure</filename>
-		is run.</para>
-	    </listitem>
-
-	  </orderedlist>
-	</step>
-
-	<step>
-	  <para>The <buildtarget>build</buildtarget> target is run.
-	    This is responsible for descending into the port's private
-	    working directory (<varname>WRKSRC</varname>) and building
-	    it.</para>
-	</step>
-
-	<step>
-	  <para>The <buildtarget>stage</buildtarget> target is run.
-	    This puts the final set of built files into a temporary
-	    directory (<varname>STAGEDIR</varname>, see
-	    <xref linkend="staging"/>).  The hierarchy of this
-	    directory mirrors that of the system on which the package
-	    will be installed.</para>
-	</step>
-
-	<step>
-	  <para>The <buildtarget>install</buildtarget> target is run.
-	    This copies the files listed in the port's pkg-plist to
-	    the host system.</para>
-	</step>
-      </procedure>
-
-      <para>The above are the default actions.  In addition, you can
-	define targets
-	<buildtarget>pre-<replaceable>something</replaceable></buildtarget>
-	or
-	<buildtarget>post-<replaceable>something</replaceable></buildtarget>,
-	or put scripts with those names, in the
-	<filename>scripts</filename> subdirectory, and they will be
-	run before or after the default actions are done.</para>
-
-      <para>For example, if you have a
-	<buildtarget>post-extract</buildtarget> target defined in your
-	<filename>Makefile</filename>, and a file
-	<filename>pre-build</filename> in the
-	<filename>scripts</filename> subdirectory, the
-	<buildtarget>post-extract</buildtarget> target will be called
-	after the regular extraction actions, and the
-	<filename>pre-build</filename> script will be executed before
-	the default build rules are done.  It is recommended that you
-	use <filename>Makefile</filename> targets if the actions are
-	simple enough, because it will be easier for someone to figure
-	out what kind of non-default action the port requires.</para>
-
-      <para>The default actions are done by the
-	<filename>bsd.port.mk</filename> targets
-	<buildtarget>do-<replaceable>something</replaceable></buildtarget>.
-	For example, the commands to extract a port are in the target
-	<buildtarget>do-extract</buildtarget>.  If you are not happy
-	with the default target, you can fix it by redefining the
-	<buildtarget>do-<replaceable>something</replaceable></buildtarget>
-	target in your <filename>Makefile</filename>.</para>
-
-      <note>
-	<para>The <quote>main</quote> targets (e.g.,
-	  <buildtarget>extract</buildtarget>,
-	  <buildtarget>configure</buildtarget>, etc.) do nothing more
-	  than make sure all the stages up to that one are completed
-	  and call the real targets or scripts, and they are not
-	  intended to be changed.  If you want to fix the extraction,
-	  fix <buildtarget>do-extract</buildtarget>, but never ever
-	  change the way <buildtarget>extract</buildtarget>
-	  operates! Additionally, the target
-	  <buildtarget>post-deinstall</buildtarget> is invalid and
-	  is not run by the ports infrastructure.</para>
-      </note>
-
-      <para>Now that you understand what goes on when the user types
-	<command>make install</command>, let
-	us go through the recommended steps to create the perfect
-	port.</para>
-    </sect1>
-
-    <sect1 xml:id="slow-sources">
-      <title>Getting the Original Sources</title>
-
-      <para>Get the original sources (normally) as a compressed
-	tarball
-	(<filename>foo.tar.gz</filename> or
-	<filename>foo.tar.bz2</filename>)
-	and copy it into <varname>DISTDIR</varname>.  Always use
-	<emphasis>mainstream</emphasis> sources when and where you
-	can.</para>
-
-      <para>You will need to set the variable
-	<varname>MASTER_SITES</varname> to reflect where the original
-	tarball resides.  You will find convenient shorthand
-	definitions for most mainstream sites in
-	<filename>bsd.sites.mk</filename>.  Please use these
-	sites&mdash;and the associated definitions&mdash;if at all
-	possible, to help avoid the problem of having the same
-	information repeated over again many times in the source base.
-	As these sites tend to change over time, this becomes a
-	maintenance nightmare for everyone involved.</para>
-
-      <para>If you cannot find a FTP/HTTP site that is well-connected
-	to the net, or can only find sites that have irritatingly
-	non-standard formats, you might want to put a copy on a
-	reliable FTP or HTTP server that you control (e.g., your home
-	page).</para>
-
-      <para>If you cannot find somewhere convenient and reliable to
-	put the distfile we can <quote>house</quote> it ourselves on
-	<systemitem>ftp.FreeBSD.org</systemitem>; however, this is the
-	least-preferred solution.  The distfile must be placed into
-	<filename>~/public_distfiles/</filename> of someone's
-	<systemitem>freefall</systemitem> account.  Ask the person who
-	commits your port to do this.  This person will also set
-	<varname>MASTER_SITES</varname> to
-	<varname>MASTER_SITE_LOCAL</varname> and
-	<varname>MASTER_SITE_SUBDIR</varname> to their
-	<systemitem>freefall</systemitem> username.</para>
-
-      <para>If your port's distfile changes all the time without any
-	kind of version update by the author, consider putting the
-	distfile on your home page and listing it as the first
-	<varname>MASTER_SITES</varname>.  If you can, try to talk the
-	port author out of doing this; it really does help to
-	establish some kind of source code control.  Hosting your own
-	version will prevent users from getting
-	<errorname>checksum mismatch</errorname> errors, and also
-	reduce the workload of maintainers of our FTP site.  Also, if
-	there is only one master site for the port, it is recommended
-	that you house a backup at your site and list it as the second
-	<varname>MASTER_SITES</varname>.</para>
-
-      <para>If your port requires some additional `patches' that are
-	available on the Internet, fetch them too and put them in
-	<varname>DISTDIR</varname>.  Do not worry if they come from a
-	site other than where you got the main source tarball, we have
-	a way to handle these situations (see the description of
-	<link linkend="porting-patchfiles">PATCHFILES</link>
-	below).</para>
-    </sect1>
-
-    <sect1 xml:id="slow-modifying">
-      <title>Modifying the Port</title>
-
-      <para>Unpack a copy of the tarball in a private directory and
-	make whatever changes are necessary to get the port to compile
-	properly under the current version of &os;.  Keep
-	<emphasis>careful track</emphasis> of everything you do, as
-	you will be automating the process shortly.  Everything,
-	including the deletion, addition, or modification of files
-	should be doable using an automated script or patch file when
-	your port is finished.</para>
-
-      <para>If your port requires significant user
-	interaction/customization to compile or install, you should
-	take a look at one of Larry Wall's classic
-	<application>Configure</application> scripts and perhaps do
-	something similar yourself.  The goal of the new ports
-	collection is to make each port as
-	<quote>plug-and-play</quote> as possible for the end-user
-	while using a minimum of disk space.</para>
-
-      <note>
-	<para>Unless explicitly stated, patch files, scripts, and
-	  other files you have created and contributed to the &os;
-	  ports collection are assumed to be covered by the standard
-	  BSD copyright conditions.</para>
-      </note>
-    </sect1>
-
-    <sect1 xml:id="slow-patch">
-      <title>Patching</title>
-
-      <para>In the preparation of the port, files that have been added
-	or changed can be recorded with &man.diff.1; for later
-	feeding to &man.patch.1;.  Doing this with a typical file
-	involves saving a copy of the original file before making any
-	changes.</para>
-
-      <screen>&prompt.user; <userinput>cp <replaceable>file</replaceable> <replaceable>file</replaceable>.orig</userinput></screen>
-
-      <para>Patches are saved into files named
-	<filename>patch-*</filename> where
-	<replaceable>*</replaceable> indicates the pathname of the
-	file that is patched, such as
-	<filename>patch-Imakefile</filename> or
-	<filename>patch-src-config.h</filename>.</para>
-
-      <para>After the file has been modified, &man.diff.1; is used to
-	record the differences between the original and the modified
-	version.  <option>-u</option> causes &man.diff.1; to produce
-	<quote>unified</quote> diffs, the preferred form.</para>
-
-      <screen>&prompt.user; <userinput>diff -u <replaceable>file</replaceable>.orig <replaceable>file</replaceable> &gt; patch-<replaceable>pathname-file</replaceable></userinput></screen>
-
-      <para>When generating patches for new, added files,
-	<option>-N</option> is added to tell &man.diff.1; to treat the
-	non-existent original file as if it existed but was
-	empty:</para>
-
-      <screen>&prompt.user; <userinput>diff -u -N <replaceable>newfile</replaceable>.orig <replaceable>newfile</replaceable> &gt; patch-<replaceable>pathname-newfile</replaceable></userinput></screen>
-
-      <para>Patch files are stored in <varname>PATCHDIR</varname>
-	(usually <filename class="directory">files/</filename>, from
-	where they will be automatically applied.  All patches must be
-	relative to <varname>WRKSRC</varname> (generally the directory
-	the port's tarball unpacks itself into, that being where the
-	build is done).  To make fixes and upgrades easier, avoid
-	having more than one patch fix the same file (that is,
-	<filename>patch-file</filename> and
-	<filename>patch-file2</filename> both changing
-	<filename>WRKSRC/foobar.c</filename>).  Note that if the path
-	of a patched file contains an underscore
-	(<literal>_</literal>) character, the patch needs to have two
-	underscores instead in its name.  For example, to patch a file
-	named <filename>src/freeglut_joystick.c</filename>, the
-	corresponding patch should be named
-	<filename>patch-src-freeglut__joystick.c</filename>.</para>
-
-      <para>Please only use characters
-	<literal>[-+._a-zA-Z0-9]</literal> for naming patches.  Do not
-	use any other characters besides them.  Do not name patches
-	like <filename>patch-aa</filename> or
-	<filename>patch-ab</filename>, always mention the path and
-	file name in patch names.</para>
-
-      <para>There is an alternate, easier method for creating patches
-	to existing files.  The first steps are the same, make a copy
-	of the unmodified file with an <filename>.orig</filename>
-	extension, then make modifications.  Then use
-	<command>make makepatch</command> to write updated patch files
-	to the <filename>files</filename> directory of the
-	port.</para>
-
-      <para>Do not put RCS strings in patches.
-	<application>Subversion</application> will mangle them when we
-	put the files into the ports tree, and when we check them out
-	again, they will come out different and the patch will fail.
-	RCS strings are surrounded by dollar
-	(<literal>&dollar;</literal>) signs, and typically start with
-	<literal>&dollar;Id</literal> or
-	<literal>&dollar;RCS</literal>.</para>
-
-      <para>Using the recurse (<option>-r</option>) option to
-	&man.diff.1; to generate patches is fine, but please
-	look at the resulting patches to make sure there is no
-	unnecessary junk in there.  In particular, diffs between two
-	backup files, <filename>Makefile</filename>s when the port
-	uses <command>Imake</command> or GNU
-	<command>configure</command>, etc., are unnecessary and should
-	be deleted.  If it was necessary to edit
-	<filename>configure.in</filename> and run
-	<command>autoconf</command> to regenerate
-	<command>configure</command>, do not take the diffs of
-	<command>configure</command> (it often grows to a few thousand
-	lines!).  Instead, define
-	<literal>USE_AUTOTOOLS=autoconf:261</literal> and take the
-	diffs of <filename>configure.in</filename>.</para>
-
-      <para>Try to minimize the amount of non-functional whitespace
-	changes in patches.  It is common in the Open Source world for
-	projects to share large amounts of a code base, but obey
-	different style and indenting rules.  When taking a working
-	piece of functionality from one project to fix similar areas
-	in another, please be careful: the resulting line patch may be
-	full of non-functional changes.  It not only increases the
-	size of the <application>Subversion</application> repository
-	but makes it hard to find out what exactly caused the problem
-	and what was changed at all.</para>
-
-      <para>If a file must be deleted, do it in the
-	<buildtarget>post-extract</buildtarget> target rather than as
-	part of the patch.</para>
-
-      <para>Simple replacements can be performed directly from the
-	port <filename>Makefile</filename> using the in-place mode of
-	&man.sed.1;.  This is useful when changes use the value of a
-	variable:</para>
-
-      <programlisting>post-patch:
-	@${REINPLACE_CMD} -e 's|for Linux|for FreeBSD|g' ${WRKSRC}/README</programlisting>
-
-      <para>Quite often, software being ported uses the CR/LF
-	convention in source files.  This may cause problems with
-	further patching, compiler warnings, or script execution (like
-	<literal>/bin/sh^M not found</literal>.) To quickly convert
-	all files from CR/LF to just LF, add this entry to the port
-	<filename>Makefile</filename>:</para>
+    <para>A list of specific files to convert can be given:</para>
 
-      <programlisting>USES=	dos2unix</programlisting>
-
-      <para>A list of specific files to convert can
-	be given:</para>
-
-      <programlisting>USES=	dos2unix
+    <programlisting>USES=	dos2unix
 DOS2UNIX_FILES=	util.c util.h</programlisting>
 
-      <para>Use <varname>DOS2UNIX_REGEX</varname> to convert a group
-	of files across subdirectories.  Its argument is a
-	&man.find.1;-compatible regular expression.  More on the
-	format is in &man.re.format.7;.  This option is useful for
-	converting all files of a given extension.  For example,
-	convert all source code files, leaving binary files
-	intact:</para>
+    <para>Use <varname>DOS2UNIX_REGEX</varname> to convert a group of
+      files across subdirectories.  Its argument is a
+      &man.find.1;-compatible regular expression.  More on the format
+      is in &man.re.format.7;.  This option is useful for converting
+      all files of a given extension.  For example, convert all source
+      code files, leaving binary files intact:</para>
 
-      <programlisting>USES=	dos2unix
+    <programlisting>USES=	dos2unix
 DOS2UNIX_REGEX=	.*\.([ch]|cpp)</programlisting>
 
-      <para>A similar option is <varname>DOS2UNIX_GLOB</varname>,
-	which invokes <command>find</command> for each element listed
-	in it.</para>
+    <para>A similar option is <varname>DOS2UNIX_GLOB</varname>, which
+      invokes <command>find</command> for each element listed in
+      it.</para>
 
-      <programlisting>USES=	dos2unix
+    <programlisting>USES=	dos2unix
 DOS2UNIX_GLOB=	*.c *.cpp *.h</programlisting>
-    </sect1>
-
-    <sect1 xml:id="slow-configure">
-      <title>Configuring</title>
+  </sect1>
 
-      <para>Include any additional customization commands in your
-	<filename>configure</filename> script and save it in the
-	<filename>scripts</filename> subdirectory.  As mentioned
-	above, you can also do this with <filename>Makefile</filename>
-	targets and/or scripts with the name
-	<filename>pre-configure</filename> or
-	<filename>post-configure</filename>.</para>
-    </sect1>
-
-    <sect1 xml:id="slow-user-input">
-      <title>Handling User Input</title>
-
-      <para>If your port requires user input to build, configure, or
-	install, you must set <varname>IS_INTERACTIVE</varname> in
-	your <filename>Makefile</filename>.  This will allow
-	<quote>overnight builds</quote> to skip your port if the user
-	sets the variable <envar>BATCH</envar> in his environment (and
-	if the user sets the variable <envar>INTERACTIVE</envar>, then
-	<emphasis>only</emphasis> those ports requiring interaction
-	are built).  This will save a lot of wasted time on the set of
-	machines that continually build ports (see below).</para>
-
-      <para>It is also recommended that if there are reasonable
-	default answers to the questions, you check the
-	<varname>PACKAGE_BUILDING</varname> variable and turn off the
-	interactive script when it is set.  This will allow us to
-	build the packages for CDROMs and FTP.</para>
-    </sect1>
-  </chapter>
+  <sect1 xml:id="slow-configure">
+    <title>Configuring</title>
 
+    <para>Include any additional customization commands in your
+      <filename>configure</filename> script and save it in the
+      <filename>scripts</filename> subdirectory.  As mentioned above,
+      you can also do this with <filename>Makefile</filename> targets
+      and/or scripts with the name <filename>pre-configure</filename>
+      or <filename>post-configure</filename>.</para>
+  </sect1>
+
+  <sect1 xml:id="slow-user-input">
+    <title>Handling User Input</title>
+
+    <para>If your port requires user input to build, configure, or
+      install, you must set <varname>IS_INTERACTIVE</varname> in your
+      <filename>Makefile</filename>.  This will allow
+      <quote>overnight builds</quote> to skip your port if the user
+      sets the variable <envar>BATCH</envar> in his environment (and
+      if the user sets the variable <envar>INTERACTIVE</envar>, then
+      <emphasis>only</emphasis> those ports requiring interaction are
+      built).  This will save a lot of wasted time on the set of
+      machines that continually build ports (see below).</para>
+
+    <para>It is also recommended that if there are reasonable default
+      answers to the questions, you check the
+      <varname>PACKAGE_BUILDING</varname> variable and turn off the
+      interactive script when it is set.  This will allow us to build
+      the packages for CDROMs and FTP.</para>
+  </sect1>
+</chapter>



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