<!--  vim: set sw=2 sts=2 et ft=docbk:

  Part of the A-A-P recipe executive: Porting an Application

  Copyright (C) 2002-2003 Stichting NLnet Labs
  Permission to copy and use this file is specified in the file COPYING.
  If this file is missing you can find it here: http://www.a-a-p.org/COPYING

-->

<para>
Porting an application means starting with the original sources and
changing them a little bit to make the application compile and install on a
specific system.  An &Aap; port recipe offers a simple way to create a port,
because all the standard work does not need to be specified.
</para>

<para>
NOTE: not all features mentioned here fully work.  Make sure you test your
port recipe before publishing it.
</para>

<bridgehead>The Port Recipe</bridgehead>

<para>
  The basic idea is that you assign values to a number of predefined
  variables.  &Aap; will then generate the steps for building and installing
  the package, using the values you have specified.  The presence of the
  "PORTNAME" variable triggers &Aap; to handle the recipe as a port recipe.
  The list of variables is in the next section.
</para>

<para>
  This is thee list of steps performed when executing &Aap; without arguments,
  in this order:
  <informaltable frame='none'>
    <tgroup cols='2'>
      <colspec colwidth="150"/>
      <tbody>
        <row>
          <entry>dependcheck</entry>
          <entry>early check to see if dependencies can be met; abort without
          doing anything if something is known to fail</entry>
        </row>
        <row>
          <entry>fetchdepend</entry>
          <entry>handle dependencies for fetch and checksum</entry>
        </row>
        <row>
          <entry>fetch</entry>
          <entry>get the required files</entry>
        </row>
        <row>
          <entry>checksum</entry>
          <entry>check if the files have correct checksums</entry>
        </row>
        <row>
          <entry>extractdepend</entry>
          <entry>handle dependencies for extract and patch</entry>
        </row>
        <row>
          <entry>extract</entry>
          <entry>unpack archives</entry>
        </row>
        <row>
          <entry>patch</entry>
          <entry>apply patches</entry>
        </row>
        <row>
          <entry>builddepend</entry>
          <entry>handle dependencies for configuring and building</entry>
        </row>
        <row>
          <entry>config</entry>
          <entry>do pre-building configuration</entry>
        </row>
        <row>
          <entry>build</entry>
          <entry>build</entry>
        </row>
        <row>
          <entry>testdepend</entry>
          <entry>handle dependencies for testing</entry>
        </row>
        <row>
          <entry>test</entry>
          <entry>check if building was done properly</entry>
        </row>
        <row>
          <entry>package</entry>
          <entry>create a binary package</entry>
        </row>
        <row>
          <entry>install</entry>
          <entry>install the binary package</entry>
        </row>
        <row>
          <entry>rundepend</entry>
          <entry>handle runtime dependencies</entry>
        </row>
        <row>
          <entry>installtest</entry>
          <entry>test if the package fully works and was installed properly</entry>
        </row>
      </tbody>
    </tgroup>
  </informaltable>
  For each step a dependency with build commands is added.  The purpose of
  each step is further explained below.
</para>

<note>
  <title>Meaning of "dependency"</title>
<para>
  The term "dependency" is ambiguous here.  You should be able to guess from
  the context whether it is used for a dependency of one software package on
  another package, or a dependency of a target file on a source file.
</para>
</note>

<para>
  You can do part of the work by starting &Aap; with one of the step names.
  The steps before it will also be executed if necessary.
  For example, "aap package" will do all the steps necessary to generate the
  binary package but not install it.
</para>

<para>
  If your port requires non-standard stuff, you can specify your own
  build commands.  You can replace the normal step, prepend something to it
  and append something to it:
  <informaltable frame='none'>
    <tgroup cols='2'>
      <colspec colwidth="150"/>
      <tbody>
        <row>
          <entry>do-XXX</entry>
          <entry>replace the body of a step</entry>
        </row>
        <row>
          <entry>pre-XXX</entry>
          <entry>do something before a step</entry>
        </row>
        <row>
          <entry>post-XXX</entry>
          <entry>do something after a step</entry>
        </row>
      </tbody>
    </tgroup>
  </informaltable>
</para>

<para>
  Example:
</para>
<programlisting>
       post-test:
          # delete the directory used for testing
          :del {r}{f} $WRKDIR/testdir
</programlisting>


<bridgehead>Variables</bridgehead>

<para>
Various variables need to be set to specify properties of the port.

<informaltable frame='none'>
  <tgroup cols='3'>
    <colspec colwidth="200,300"/>
    <thead>
      <row>
        <entry>variable</entry>
        <entry>used for</entry>
        <entry>example value</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>PORTNAME</entry>
        <entry>name of the port</entry>
        <entry>"foobar"</entry>
      </row>

      <row>
        <entry>PORTVERSION</entry>
        <entry>app version number</entry>
        <entry>"3.8alpha"</entry>
      </row>

      <row>
        <entry>PORTREVISION</entry>
        <entry>port patchlevel (optional)</entry>
        <entry>"32"</entry>
      </row>

      <row>
        <entry>CVSMODULES</entry>
        <entry>names of CVS modules to checkout (optional)</entry>
        <entry>Exec</entry>
      </row>

      <row>
        <entry>MAINTAINER_NAME</entry>
        <entry>maintainer name (optional)</entry>
        <entry>John Doe</entry>
      </row>

      <row>
        <entry>MAINTAINER</entry>
        <entry>maintainer e-mail (optional)</entry>
        <entry>john@foobar.org</entry>
      </row>

      <row>
        <entry>PORTCOMMENT</entry>
        <entry>short description </entry>
        <entry>get foo into the bar</entry>
      </row>

      <row>
        <entry>PORTDESCR </entry>
        <entry>long description</entry>
        <entry>blah blah blah</entry>
      </row>

      <row>
        <entry>IS_INTERACTIVE</entry>
        <entry>requires user input (optional)</entry>
        <entry>yes or no</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>

</para>

<para>
Variables that can be used by the port recipe:
<informaltable frame='none'>
  <tgroup cols='4'>
    <colspec colwidth="200"/>
    <thead>
      <row>
        <entry>variable</entry>
        <entry>used for</entry>
        <entry>&nbsp;&nbsp;</entry>
        <entry>default value</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>WRKDIR</entry>
        <entry>directory all files are extracted in and the building is done
          in</entry>
        <entry>&nbsp;&nbsp;</entry>
        <entry>"work"</entry>
      </row>
      <row>
        <entry>DISTDIR</entry>
        <entry>directory where downloaded distfiles are stored</entry>
        <entry>&nbsp;&nbsp;</entry>
        <entry>"distfiles"</entry>
      </row>
      <row>
        <entry>PATCHDISTDIR</entry>
        <entry>directory where downloaded patches are stored</entry>
        <entry>&nbsp;&nbsp;</entry>
        <entry>"patches"</entry>
      </row>
      <row>
        <entry>PKGDIR</entry>
        <entry>directory where files are stored before creating a
          package</entry>
        <entry>&nbsp;&nbsp;</entry>
        <entry>"pack"</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>
</para>

<para>
Variables that may be set by the port recipe, defaults are set only after
reading the recipe:
<informaltable frame='none'>
  <tgroup cols='3'>
    <colspec colwidth="200"/>
    <thead>
      <row>
        <entry>variable</entry>
        <entry>used for</entry>
        <entry>default value</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>WRKSRC</entry>
        <entry>Directory inside $WRKDIR where the unpacked sources end up. This
          should be the common top directory in the unpacked archives.
          When using CVS it is always set to $CVSWRKSRC (also
          when $WRKSRC was already set).</entry>
        <entry>$PORTNAME-$PORTVERSION</entry>
        </row>
        <row>
        <entry>CVSWRKSRC</entry>
        <entry>Directory inside $WRKDIR where files
          obtained with CVS end up.</entry>
        <entry>the first entry in $CVSMODULES</entry>
        </row>
        <row>
          <entry>PATCHDIR</entry>
          <entry>Directory inside $WRKDIR where patches are to be
            applied.  Can be overruled for a specific patch with a "patchdir"
            attribute.</entry>
          <entry>$WRKSRC</entry>
        </row>
        <row>
          <entry>BUILDDIR</entry>
          <entry>Directory inside $WRKDIR where building is to be
            done.</entry>
          <entry>$WRKSRC</entry>
        </row>
        <row>
          <entry>TESTDIR</entry>
          <entry>Directory inside $WRKDIR where testing is to be done.</entry>
          <entry>$WRKSRC</entry>
        </row>
        <row>
          <entry>INSTALLDIR</entry>
          <entry>Directory inside $WRKDIR where $INSTALLCMD is to be
            done.</entry>
          <entry>$WRKSRC</entry>
        </row>
        <row>
          <entry>CONFIGURECMD</entry>
          <entry>Set to the command used to configure the application.  Usually
            "./configure".</entry>
          <entry>nothing</entry>
        </row>
        <row>
          <entry>BUILDCMD</entry>
          <entry>Set to the command used to build the application.  Usually
            just "make".</entry>
          <entry>"aap"</entry>
        </row>
        <row>
          <entry>TESTCMD</entry>
          <entry>Set to the command used to test the application.  Usually
            "make test".</entry>
          <entry>"aap test"</entry>
        </row>
        <row>
          <entry>INSTALLCMD</entry>
          <entry>Set to the command used to do a fake install of the
            application.</entry>
          <entry>"aap install DESTDIR=$PKGDIR"</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>
</para>


<bridgehead>Dependency Format</bridgehead>

<para>
Dependencies on other modules are specified with the various DEPEND_
variables.  The format of these variables is a list of items.
</para>

<para>
NOTE: Although you can currently specify dependencies, the code for checking
them has not been implemented yet!  Thus the user will have to figure it out
by himself...
</para>

<para>
Items are normally white space separated, which means there is an "and"
relation between them.  Alternatively "|" can be used to indicate an "or"
relation.
</para>

<programlisting>
        DEPENDS = perl python           # require both perl and python
        DEPENDS = perl | python         # require perl or python
</programlisting>

<para>
Parenthesis can be used to group items.  Parenthesis must be used when
combining "or" and "and" relations.  Example:
</para>

<programlisting>
        DEPENDS = (foo bar) | foobar    # Either both "foo" and "bar" or "foobar"
        DEPENDS = foo bar | foobar      # Illegal
        DEPENDS = foo (bar | foobar)    # "foo" and either "bar" or "foobar"
</programlisting>

<para>
When a dependency is not met the first alternative will be installed, thus the
order of "or" alternatives is significant.
</para>

<para>
Each item is in one of these formats:

<informaltable frame='none'>
  <tgroup cols='2'>
    <colspec colwidth="250"/>
    <tbody>
      <row>
        <entry>name-version_revision</entry>
        <entry>a specific version and revision</entry>
      </row>
      <row>
        <entry>name</entry>
        <entry>any version</entry>
      </row>
      <row>
        <entry>name-regexp</entry>
        <entry>a version specified with a regular expression (shell
          style)</entry>
      </row>
      <row>
        <entry>name&gt;=version_revision</entry>
        <entry>any version at or above a specific version and revision</entry>
      </row>
      <row>
        <entry>name&gt;version_revision</entry>
        <entry>any version above a specific version and revision</entry>
      </row>
      <row>
        <entry>name&lt;=version_revision</entry>
        <entry>any version at or below a specific version and revision</entry>
      </row>
      <row>
        <entry>name&lt;version_revision</entry>
          <entry>any version below a specific version and revision
            name!version_revision any version but a specific version and
            revision</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>
</para>

<para>
In the above "_revision" can be left out to ignore the revision number.  It
actually works as if there is a "*" wildcard at the end of each item.
</para>

<para>
"name" can contain wildcards.  When a part is following it is appended at the
position of the wildcard (or at -9 if it comes first).
<informaltable frame='none'>
  <tgroup cols='2'>
    <colspec colwidth="150"/>
    <tbody>
      <row>
        <entry>foo-*</entry>
        <entry>matches foo-big, foo-big-1.2 and foo-1.2</entry>
      </row>
      <row>
        <entry>foo-*!1.2</entry>
        <entry>matches foo-big, foo-big-1.2 and skips foo-1.2</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>
</para>

<para>
The version specifications can be concatenated, this creates an "and"
relation.  Example:

<informaltable frame='none'>
  <tgroup cols='2'>
    <colspec colwidth="200"/>
    <tbody>
      <row>
        <entry>foo&gt;=1.2&lt;=1.4</entry>
        <entry>versions 1.2 to 1.4 (inclusive)</entry>
      </row>
      <row>
        <entry>foo&gt;=1.2!1.8</entry>
        <entry>versions 1.2 and above, excluding 1.8</entry>
      </row>
      <row>
        <entry>xv&gt;3.10</entry>
        <entry>versions above 3.10, accepts xv-3.10a</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>
</para>

<para>
The "!" can be followed by parenthesis containing a list of specifications.
This excludes the versions matching the specifications in the parenthesis.
Example:
<informaltable frame='none'>
  <tgroup cols='2'>
    <colspec colwidth="200"/>
    <tbody>
      <row>
        <entry>foo&gt;=1.1!(&gt;=1.3&lt;=1.5)</entry>
        <entry>versions 1.1 and higher, but not versions 1.3 to 1.5</entry>
      </row>
      <row>
        <entry>foo&gt;=6.1!6.1[a-z]*</entry>
        <entry>version 6.1 and later but not 6.1a, 6.1rc3, etc.</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>
</para>

<para>
When a dependency is not met the newest version that meets the description is
used.
</para>

<para>
For systems that do not allow specifying dependencies like this in a binary
pacakge, the specific package version that exists when generating the package
is used.
</para>


<bridgehead>Dependencies For Various Steps</bridgehead>

<para>
The various variables used to specify dependencies:
<informaltable frame='none'>
  <tgroup cols='2'>
    <colspec colwidth="200"/>
    <tbody>
      <row>
        <entry>DEPEND_FETCH</entry>
        <entry>Required for fetching files.  Also for computing
          checksums.</entry>
      </row>
      <row>
        <entry>DEPEND_EXTRACT</entry>
        <entry>Required for unpacking archives.</entry>
      </row>
      <row>
        <entry>DEPEND_BUILD</entry>
        <entry>Required for building but not necessarily for running; these are not
          included in the binary package; items may also appear in
          DEPEND_RUN.</entry>
      </row>
      <row>
        <entry>DEPEND_TEST</entry>
        <entry>Required for testing only; don't include items that are already in
          DEPEND_RUN.</entry>
      </row>
      <row>
        <entry>DEPEND_RUN</entry>
        <entry>Required for running; these will also be included in the generated
          binary package.</entry>
      </row>
      <row>
        <entry>DEPENDS</entry>
        <entry>Used for DEPEND_BUILD and DEPEND_RUN when empty.</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>
</para>

<para>
Only the dependencies specified with DEPEND_RUN will end up in the generated
binary package.  When using a shared library, it is recommended to put a
dependency on the developer version (includes header files) in DEPEND_BUILD
and a dependency on the library itself in DEPEND_RUN.  The result is that when
installing binary packages the header files for the library don't need to be
installed.
</para>


<para>
The "CONFLICTS" variable should be set to specify modules with which this one
conflits.  That means only one of the two packages can be installed in the
same location.  It should still be possible to install the packages in
different locations.  The format of CONFLICTS is identical to that of the
DEPENDS_ variables.
</para>

<para>
NOTE: Although you can currently specify dependencies and conflicts, the code
for checking them has not been implemented yet!  Thus the user will have to
figure it out by himself...
</para>

<para>
Dependencies are automatically installed, unless "AUTODEPEND" is "no".
The dependencies are normally satisfied by installing a port.  When a
satisfying port can not be found a binary package is installed.
The ports and packages are first searched for on the local system.  When not
found the internet is searched.
</para>

<para>
The order of searching can be changed with "AUTODEPEND":
<informaltable frame='none'>
  <tgroup cols='2'>
    <colspec colwidth="300"/>
    <tbody>
      <row>
        <entry>binary</entry>
        <entry>only search for binary packages, default locations</entry>
      </row>
      <row>
        <entry>source</entry>
        <entry>only search for ports, default locations</entry>
      </row>
      <row>
        <entry>source {path = /usr/ports http://ports.a-a-p.org}</entry>
        <entry>only search for ports in /usr/ports and on the ports.a-a-p.org
          web site.</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>
</para>


<bridgehead>Steps</bridgehead>

<para>
These are the individual steps for installing a ported application.  Each step
up to "install" depends on the previous one.  Thus "aap install" will do all
the preceding steps.  But the steps that have already been successfully done
in a previous invocation of &Aap; will be skipped.  The "rundepend",
"installtest", "clean", etc. targets do not depend on previous steps, they can
be used separately.
</para>

<variablelist>

  <varlistentry>
    <term>
      dependcheck
    </term>
    <listitem>
      <para>
        Check if required dependencies can be fulfilled.
      </para>
      <para>
        This doesn't install anything yet, it does an early check if building
        and/or installing the port will probably work before starting to
        download files.
      </para>
      <para>
        This uses all the DEPEND_ variables that will actually be used.
        Fails if something is not available.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      fetchdepend
    </term>
    <listitem>
      <para>
       Check dependencies for fetch and checksum.
     </para>
     <para>
        Uses DEPEND_FETCH, unless disabled with AUTODEPEND=no
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      fetch
    </term>
    <listitem>
      <para>
        Get required files.
     </para>
     <para>
        If $CVSMODULES is set and $CVS is not "no", obtain files from CVS:
        <simplelist>
          <member> Uses $CVSROOT or cvsroot attribute in $CVSMODULES.</member>
          <member>$CVSWRKSRC is where the files will end up (default is first
            member in $CVSMODULES).</member>
          <member>Also obtain $CVSDISTFILES if defined.</member>
          <member>Also obtain $CVSPATCHFILES if defined.</member>
          <member>Use a post-fetch target if directories need to be renamed.</member>
        </simplelist>
        else
        <simplelist>
          <member>if $DISTFILES is set obtain them</member>
          <member>if $PATCHFILES is set obtain them</member>
        </simplelist>
        Use MASTER_SITES for [CVS]DISTFILES.
        Use PATCH_SITES for [CVS]PATCHFILES.
        The [CVS]DISTFILES are put in $DISTDIR.
        The [CVS]PATCHFILES are put in $PATCHDISTDIR.
     </para>
     <para>
        The directory can be overruled with a {distdir = dir} attribute on
        individual patch files.
     </para>
     <para>
        Files that already exist are skipped (if there is a checksum error,
        delete the file(s) manually).
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      checksum
    </term>
    <listitem>
      <para>
        Check if checksums are correct.
     </para>
     <para>
        The port recipe writer must add the "do-checksum" target with
        <link linkend="cmd-checksum">:checksum</link> commands to verify that
        downloaded files are not
        corrupted.  Example:
     </para>
     <programlisting>
        # &gt;&gt;&gt; automatically inserted by "aap makesum" &lt;&lt;&lt;
        do-checksum:
            :checksum $DISTDIR/foo-1.1.tgz {md5 = 2341423423423423434}
            :checksum $PATCHDISTDIR/foo-patch3.gz {md5 = 3923858739234}
        # &gt;&gt;&gt; end &lt;&lt;&lt;
</programlisting>
     <para>
        The "aap makesum" command can be used to generate the lines.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      extractdepend
    </term>
    <listitem>
      <para>
        Check dependencies for extract and patch.
     </para>
     <para>
        Uses DEPEND_EXTRACT, unless disabled with AUTODEPEND=no
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      extract
    </term>
    <listitem>
     <para>
        Unpack archives in the right place.
        Use $EXTRACT_ONLY if defined, otherwise $DISTFILES or
        $CVSDISTFILES when CVS was used.
     </para>
     <para>
        Uses the "extract" action.  To extract a new type of archive:
        <simplelist>
          <member> add filetype detection for this type of archive</member>
          <member> define an "extract" action for this filetype </member>
        </simplelist>
     </para>
     <para>
        Extraction is done in $WRKDIR.  A subdirectory may be specified with
        the "extractdir" attribute on each archive.
     </para>
     <programlisting>
        DISTFILES = foo-1.1.tgz   foo_doc-1.1.tgz {extractdir = doc}
</programlisting>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      patch
    </term>
    <listitem>
     <para>
        Apply patches not applied already.
     </para>
     <para>
        $PATCHCMD defines the patch command, default: "patch -p &lt; ".
        The patch file name is appended, unless "%s" appears in the
        string, then it's replaced by the file name.
     </para>
     <para>
        A "patchcmd" attribute on each patch file may specify a patch command
        that overrules $PATCHCMD.
     </para>
     <para>
        The patches are applied in $WRKDIR/$PATCHDIR (default: $WRKSRC).
        A "patchdir" attribute on each patch file may overrule the value of
        $PATCHDIR.
      </para>
    </listitem>
  </varlistentry>
        
  <varlistentry>
    <term>
      builddepend
    </term>
    <listitem>
      <para>
        Check dependencies for configure and build.
     </para>
     <para>
        Uses DEPEND_BUILD, unless disabled with "AUTODEPEND=no".
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      config
    </term>
    <listitem>
      <para>
        Perform configuration.
     </para>
     <para>
       Executes the command specified with CONFIGURECMD.  Usually
       autoconf, imake, etc.  May be empty.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      build
    </term>
    <listitem>
      <para>
        Run the command specified with BUILDCMD.  When empty "aap" is used.
        Useful values are "gmake", "make", etc.  An argument may be included.
        Example: "BUILDCMD=make foo"
     </para>
     <para>
        Done in $WRKDIR/$BUILDDIR, default: $WRKDIR/$WRKSRC
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      testdepend
    </term>
    <listitem>
      <para>
        Check test dependencies.
     </para>
     <para>
        Uses DEPEND_TEST.
     </para>
     <para>
        check if all required items are present
        try to install them automatically, unless disabled  AUTODEPEND=no
        This is skipped when "SKIPTEST=yes"
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      test
    </term>
    <listitem>
      <para>
        Check if building was done properly.
     </para>
     <para>
       Executes TESTCMD.  When it is empty "aap test" is used.  Example:
       "TESTCMD=make testall"
     </para>
     <para>
        This is skipped when "SKIPTEST=yes"
        Done in $WRKDIR/$TESTDIR, default: $WRKDIR/$WRKSRC
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      package
    </term>
    <listitem>
      <para>
        Create a package with selected files, usually including the compiled
        program.
     </para>
     <para>
        There are two methods to select files to be included in the package:
        <orderedlist>
          <listitem>
            <para>
              Specify the list of files below $WRKDIR, with a "dest" attribute
              where they should end up.  Assign the list to $PACKFILES.
              Example:
              <programlisting>
        PACKFILES = $WRKSRC/bin/prog {dest = /usr/local/bin/prog}
                    $WRKSRC/man/prog.1 {dest = usr/local/man/man1/prog.1}
</programlisting>
            </para>
          </listitem>
          <listitem>
            <para>
              Specify a command to fake-install into $PKGDIR and use all files
              that end up there.
              Set $INSTALLCMD to the command to be used.  Example:
              <programlisting>
        INSTALLCMD = "aap install DESTDIR=$PKGDIR"
</programlisting>
              Set INSTALLDIR to the directory inside $WRKDIR where the files
              are put.  Default is $WRKSRC.  $PKGDIR/$PREFIX is where files
              end up.
            </para>
          </listitem>
        </orderedlist>
     </para>
     <para>
       A packing list is generated with the files that exist in the package.
       Then "pkg_create" is executed to actually create the package.
       Arguments are given such that $PORTDESCR is used as the 
       description of the package and $PORTCOMMENT for a short explanation of
       what the package is for.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      install
    </term>
    <listitem>
      <para>
        Install the binary package.
     </para>
     <para>
       This executes the "pkg_add" command in a separate shell.
       You are asked to type the root password.
       This is reasonably safe, since the shell is only connected to Aap and
       it can only install a package.
     </para>
     <para>
        Exception: This updates the "rundepend" and "installtest" targets
        after updating the post-install target.  This allows doing "aap
        install", which is a lot more obvious than "aap installtest".
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      rundepend
    </term>
    <listitem>
      <para>
        Check runtime dependencies.
     </para>
     <para>
        Check if all required items specified with $DEPEND_RUN are present and
        tries to install them automatically, unless $AUTODEPEND is "no".
     </para>
     <para>
        This is skipped if $SKIPRUNTIME is "yes".  The pre-rundepend and
        post-rundepend are still done, they should check $SKIPRUNTIME
        themselves.
     </para>
     <para>
        "aap rundepend" will _not_ cause previous steps to be updated.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      installtest
    </term>
    <listitem>
      <para>
        Test if the installed package works.
     </para>
     <para>
        This is empty by default, specify a "do-installtest" target to
        actually do something.
     </para>
     <para>
        Note that when $SKIPRUNTIME is "yes" the dependencies have not been
        verified and running the application might not work.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      uninstall
    </term>
    <listitem>
      <para>
        Uninstall the binary package.
        Not implemented yet!
     </para>
     <para>
        Execute pkg_delete or equivalent.
        Does not depend on other steps.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      clean
    </term>
    <listitem>
      <para>
        Delete all generated, unpacked, patched and CVS files.
     </para>
     <para>
        Does not delete the downloaded files.
        Does not depend on other steps.
        Does not clean packages this one depends on.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      distclean
    </term>
    <listitem>
      <para>
        Delete everything except the toplevel recipe.
        After this all steps must be redone.
     </para>
     <para>
        Does not depend on other steps.
        Does not clean packages this one depends on.
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      makesum
    </term>
    <listitem>
     <para>
        Generates a "do-checksum" dependency that checks if the fetched files
        were not corrupted.
     </para>
     <para>
       If the recipe already contained a "do-checksum" dependency that was
       generated it is replaced.  Otherwise a new one is appended.
       Do not change the markers before and after the "do-checksum"
       dependency, otherwise you end up with two of these when doing "aap
       makesum" again.
     </para>
     <para>
        Does not depend on other steps.  The files must already be present.
        You can use "aap fetch --nofetch-recipe" to obtain the files, if
        needed (it obtains the files but not the recipes).
      </para>
    </listitem>
  </varlistentry>

  <varlistentry>
    <term>
      srcpackage
    </term>
    <listitem>
      <para>
        Generate a package with recipe and source files.
        Not implemented yet!
     </para>
     <para>
        Puts the  main recipe and all downloaded files into an archive.  The
        resulting archive can be installed without downloading.
     </para>
     <para>
        Depends on the "fetch" target.
      </para>
    </listitem>
  </varlistentry>

</variablelist>


<bridgehead>Port Description</bridgehead>

<para>
The text to describe the port is usually a page full of plain text.  Here is an
example:
</para>

<programlisting>
        PORTDESCR &lt;&lt; EOF
        This is the description of the port.
        A very important application indeed.

        See our website http://myport.org.
        EOF
</programlisting>

<para>
In the rare situation that "EOF" actually appears in the text you can use
anything else, such as "THEEND".
</para>
