path: root/doc/guide/files/components.xml

<!-- $NetBSD: components.xml,v 1.22 2006/03/17 19:45:30 wiz Exp $ -->

<!--
	TODO: after 2006Q1, "SITES_" should be replaced with "SITES.".
	(2 times)
-->

<chapter id="components"> <?dbhtml filename="components.html"?>
  <title>Package components - files, directories and contents</title>

  <para>  Whenever you're preparing a package, there are a number of
    files involved which are described in the following
    sections. </para>

  <sect1 id="components.Makefile">
    <title><filename>Makefile</filename></title>

    <para>Building, installation and creation of a binary package are all
      controlled by the package's <filename>Makefile</filename>.
      The <filename>Makefile</filename> describes various things about
      a package, for example from where to get it, how to configure,
      build, and install it.
    </para>

    <para>A package <filename>Makefile</filename> contains several
     sections that describe the package.</para>

    <para>In the first section there are the following variables, which
      should appear exactly in the order given here.
      <itemizedlist>

      <listitem><para><varname>DISTNAME</varname> is the basename of the
      distribution file to be downloaded from the package's
      website.</para></listitem>

      <listitem><para><varname>PKGNAME</varname> is the name of the
      package, as used by pkgsrc. You only need to provide it if it
      differs from <varname>DISTNAME</varname>. Usually it is the directory name together
      with the version number. It must match the regular expression
      <varname>^[A-Za-z0-9][A-Za-z0-9-_.+]*$</varname>, that is, it
      starts with a letter or digit, and contains only letters, digits,
      dashes, underscores, dots and plus signs.</para></listitem>

      <listitem><para><varname>CATEGORIES</varname> is a list of categories
	    which the package fits in. You can choose any of the top-level
	    directories of pkgsrc for it.</para>

	<para>Currently the following values are available for
	  <varname>CATEGORIES</varname>. If more than
	  one is used, they need to be separated by spaces:</para>

<programlisting>
    archivers     cross         geography     meta-pkgs     security
    audio         databases     graphics      misc          shells
    benchmarks    devel         ham           multimedia    sysutils
    biology       editors       inputmethod   net           textproc
    cad           emulators     lang          news          time
    chat          finance       mail          parallel      wm
    comms         fonts         math          pkgtools      www
    converters    games         mbone         print         x11
</programlisting>
	</listitem>

	<listitem><para><varname>MASTER_SITES</varname> is a list of URLs where
	    the distribution files can be downloaded. Each URL must end with a
	    slash.</para>
	  <para>The <varname>MASTER_SITES</varname> may make use of
	    the following predefined sites:</para>

<!-- sort bsd.sites.mk | sed -n 's/\(^MA[A-Z_]*\).*/        ${\1}/p' -->
<programlisting>
    ${MASTER_SITE_APACHE}
    ${MASTER_SITE_BACKUP}
    ${MASTER_SITE_CYGWIN}
    ${MASTER_SITE_DEBIAN}
    ${MASTER_SITE_FREEBSD}
    ${MASTER_SITE_FREEBSD_LOCAL}
    ${MASTER_SITE_GNOME}
    ${MASTER_SITE_GNU}
    ${MASTER_SITE_GNUSTEP}
    ${MASTER_SITE_IFARCHIVE}
    ${MASTER_SITE_MOZILLA}
    ${MASTER_SITE_OPENOFFICE}
    ${MASTER_SITE_PERL_CPAN}
    ${MASTER_SITE_R_CRAN}
    ${MASTER_SITE_SOURCEFORGE}
    ${MASTER_SITE_SUNSITE}
    ${MASTER_SITE_SUSE}
    ${MASTER_SITE_TEX_CTAN}
    ${MASTER_SITE_XCONTRIB}
    ${MASTER_SITE_XEMACS}
</programlisting>

	  <para>If one of these predefined sites is chosen, you may
	    want to specify a subdirectory of that
	    site.  Since these macros may expand to more than one
	    actual site, you <emphasis>must</emphasis> use the
	    following construct to specify a subdirectory:</para>

<programlisting>
    ${MASTER_SITE_GNU:=subdirectory/name/}
    ${MASTER_SITE_SOURCEFORGE:=project_name/}
</programlisting>

	  <para>Note the trailing slash after the subdirectory name.</para>

	  <para>If the package has multiple
	    <varname>DISTFILES</varname> or multiple
	    <varname>PATCHFILES</varname> from different
	    sites, set <varname>SITES_foo</varname> to a list of URIs
	    where file <quote>foo</quote> may be
	    found. <quote>foo</quote> includes the suffix, e.g.:</para>

<programlisting>
    DISTFILES=      ${DISTNAME}${EXTRACT_SUFX}
    DISTFILES+=     foo-file.tar.gz
    SITES_foo-file.tar.gz= \
            http://www.somewhere.com/somehow/ \
            http://www.somewhereelse.com/mirror/somehow/
</programlisting>
	</listitem>

	<listitem><para><varname>DISTFILES</varname>: Name(s)
	    of archive file(s) containing distribution. The default is
	    <filename>${DISTNAME}${EXTRACT_SUFX}</filename>. Should only
	    be set if you have more than one distfile.</para>
	  <para>Note that the normal default setting of
	    <varname>DISTFILES</varname> must be made explicit if you
	    want to add to it (rather than replace it), as you usually
	    would.</para>
	</listitem>

	<listitem><para><varname>EXTRACT_SUFX</varname>: Suffix of the
	    distribution file, will be appended to
	    <varname>DISTNAME</varname>. Defaults to
	    <filename>.tar.gz</filename>.
	  </para>
	</listitem>
      </itemizedlist>
    </para>

    <para>The second section contains information about separately
      downloaded patches, if any.
      <itemizedlist>
	<listitem><para><varname>PATCHFILES:</varname>
	  Name(s) of additional files that contain distribution patches.
	  There is no default. pkgsrc will look for them at
	  <varname>PATCH_SITES</varname>.
	  They will automatically be uncompressed before patching if
	  the names end with <filename>.gz</filename> or
	  <filename>.Z</filename>.</para>
	</listitem>
	<listitem><para><varname>PATCH_SITES</varname>:
	  Primary location(s) for distribution patch files (see
	  <varname>PATCHFILES</varname> below) if not found locally.</para>
	</listitem>
      </itemizedlist>
    </para>
    <para>The third section contains the following variables.
      <itemizedlist>

      <listitem><para><varname>MAINTAINER</varname> is the email address
      of the person who feels responsible for this package, and who is
      most likely to look at problems or questions regarding this
      package which have been reported with &man.send-pr.1;. Other
      developers should contact the <varname>MAINTAINER</varname> before
      making major changes to the package. When packaging a new program,
      set <varname>MAINTAINER</varname> to yourself. If you really can't
      maintain the package for future updates, set it to
      <email>pkgsrc-users@NetBSD.org</email>.</para></listitem>

      <listitem><para><varname>HOMEPAGE</varname> is a URL where users can
      find more information about the package.</para></listitem>

      <listitem><para><varname>COMMENT</varname> is a one-line
      description of the package (should not include the package
      name).</para></listitem>
      </itemizedlist>
    </para>

    <para>Other variables that affect the build:
      <itemizedlist>

	<listitem>

	  <para><varname>WRKSRC</varname>: The directory where the
	  interesting distribution files of the package are found. The
	  default is <filename>${WRKDIR}/${DISTNAME}</filename>, which
	  works for most packages.</para>

	  <para>If a package doesn't create a subdirectory for itself
	  (most GNU software does, for instance), but extracts itself in
	  the current directory, you should set <varname>WRKSRC=
	  ${WRKDIR}</varname>.</para>

	  <para>If a package doesn't create a subdirectory with the name
	  of <varname>DISTNAME</varname> but some different name, set
	  <varname>WRKSRC</varname> to point to the proper name in
	  <filename>${WRKDIR}</filename>, for example <varname>WRKSRC=
	  ${WRKDIR}/${DISTNAME}/unix</varname>. See <filename
	  role="pkg">lang/tcl</filename> and <filename
	  role="pkg">x11/tk</filename> for other examples.</para>

	  <para>The name of the working directory created by pkgsrc is
	  taken from the <varname>WRKDIR_BASENAME</varname> variable. By
	  default, its value is <filename>work</filename>. If you want
	  to use the same pkgsrc tree for building different kinds of
	  binary packages, you can change the variable according to your
	  needs. Two other variables handle common cases of setting
	  <varname>WRKDIR_BASENAME</varname> individually. If
	  <varname>OBJHOSTNAME</varname> is defined in
	  <filename>/etc/mk.conf</filename>, the first component of the
	  host's name is attached to the directory name. If
	  <varname>OBJMACHINE</varname> is defined, the platform name is
	  attached, which might look like <filename>work.i386</filename>
	  or <filename>work.sparc</filename>.</para>

	</listitem>
      </itemizedlist>
    </para>
    <para>Please pay attention to the following gotchas:</para>

    <itemizedlist>
      <listitem>
        <para>Add <varname>MANCOMPRESSED</varname> if man pages are installed in
          compressed form by the package; see comment in
          <filename>bsd.pkg.mk</filename>.</para>
      </listitem>

      <listitem>
        <para>Replace <filename>/usr/local</filename> with
          <quote>${PREFIX}</quote> in all files (see patches, below).</para>
      </listitem>

      <listitem>
        <para>If the package installs any info files, see
          <xref linkend="faq.info-files"/>.</para>
      </listitem>

    </itemizedlist>
  </sect1>

  <sect1 id="components.distinfo">
    <title><filename>distinfo</filename></title>

    <para>The <filename>distinfo</filename> file contains the message
    digest, or checksum, of each distfile needed for the package. This
    ensures that the distfiles retrieved from the Internet have not been
    corrupted during transfer or altered by a malign force to introduce
    a security hole. Due to recent rumor about weaknesses of digest
    algorithms, all distfiles are protected using both SHA1 and RMD160
    message digests, as well as the file size.</para>

    <para>The <filename>distinfo</filename> file also contains the
    checksums for all the patches found in the
    <filename>patches</filename> directory (see <xref
    linkend="components.patches"/>).</para>

    <para>To regenerate the <filename>distinfo</filename> file, use the
    <command>make makedistinfo</command> or <command>make mdi</command>
    command.</para>

    <para>Some packages have different sets of distfiles depending on
    the platform, for example <filename
    role="pkg">www/navigator</filename>). These are kept in the same
    <filename>distinfo</filename> file and care should be taken when
    upgrading such a package to ensure distfile information is not
    lost.</para>

  </sect1>

  <sect1 id="components.patches">
    <title>patches/*</title>

    <para>This directory contains files that are used by the
      &man.patch.1; command to
      modify the sources as distributed in the distribution file into a form
      that will compile and run perfectly on &os;. The files are applied
      successively in alphabetic order (as returned by a shell
      <quote>patches/patch-*</quote> glob expansion), so
      <filename>patch-aa</filename> is applied before
      <filename>patch-ab</filename>, etc.</para>

    <para>The <filename>patch-*</filename> files should be in
      <command>diff -bu</command> format, and apply without a fuzz to avoid
      problems. (To force patches to apply
      with fuzz you can set <varname>PATCH_FUZZ_FACTOR=-F2</varname>).
      Furthermore, do not put changes for more than one file into a single
      patch file, as this will make future modifications more difficult.</para>

    <para>Similar, a file should be patched at most once, not several times by
      several different patches. If a file needs several patches, they should
      be combined into one file.</para>

    <para>One important thing to mention is to pay attention that no RCS IDs
      get stored in the patch files, as these will cause problems when
      later checked into the &os; CVS tree. Use the
      <command>pkgdiff</command> from the
      <filename role="pkg">pkgtools/pkgdiff</filename> package to avoid
      these problems.</para>

    <para>For even more automation, we recommend using <command>mkpatches</command> from the same
      package to make a whole set of patches. You just have to backup files
      before you edit them to <filename>filename.orig</filename>, e.g. with
      <command>cp -p filename filename.orig</command> or, easier, by using
      <command>pkgvi</command> again from the same package. If you upgrade a package
      this way, you can easily compare the new set of patches with the
      previously existing one with <command>patchdiff</command>.</para>

    <para>When you have finished a package, remember to generate the checksums
      for the patch files by using the <command>make makepatchsum</command>
      command, see <xref linkend="components.distinfo"/>.</para>

    <para>When adding a patch that corrects a problem in the distfile (rather
      than e.g. enforcing pkgsrc's view of where man pages should go), send
      the patch as a bug report to the maintainer.  This benefits
      non-pkgsrc users of the package, and usually enables removing
      the patch in future version.</para>

    <para>Patch files that are distributed by the author or other
      maintainers can be listed in
      <varname>$PATCHFILES</varname>. </para>

    <para>If it is desired to store any patches that should not be committed into
      pkgsrc, they can be kept outside the pkgsrc tree in the
      <filename>$LOCALPATCHES</filename>
      directory. The directory tree there is expected to have the same
      <quote>category/package</quote> structure as pkgsrc, and patches are
      expected to be stored inside these dirs (also known as
      <filename>$LOCALPATCHES/$PKGPATH</filename>). For
      example, if you want to keep a private patch for
      <filename>pkgsrc/graphics/png</filename>, keep
      it in <filename>$LOCALPATCHES/graphics/png/mypatch</filename>. All
      files in the named directory are expected to be patch files, and
      <emphasis>they are applied after pkgsrc patches are applied</emphasis>.</para>
  </sect1>

  <sect1 id="other-mandatory-files">
    <title>Other mandatory files</title>

    <variablelist>
      <varlistentry>
        <term><filename>DESCR</filename></term>

        <listitem>
          <para>A multi-line description of the piece of software.  This should include
            any credits where they are due.  Please bear in mind that others do not
            share your sense of humour (or spelling idiosyncrasies), and that others
            will read everything that you write here.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><filename>PLIST</filename></term>

        <listitem>
          <para>
            This file governs the files that are installed on your system: all the
            binaries, manual pages, etc. There are other directives which may be
            entered in this file, to control the creation and deletion of
            directories, and the location of inserted files.
            See <xref linkend="plist"/> for more information. </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </sect1>

  <sect1 id="components.optional">
    <title>Optional files</title>

    <variablelist>
      <varlistentry>
        <term><filename>INSTALL</filename></term>

        <listitem>
          <para>This shell script is invoked twice by &man.pkg.add.1;.
            First time after package
            extraction and before files are moved in place, the second time after
            the files to install are moved in place. This can be used to do any
            custom procedures not possible with @exec commands in
            <filename>PLIST</filename>. See
            &man.pkg.add.1; and &man.pkg.create.1; for more information.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><filename>DEINSTALL</filename></term>

        <listitem>
          <para>This script is executed before and after any files are removed.  It is
            this script's responsibility to clean up any additional messy details
            around the package's installation, since all pkg_delete knows is how to
            delete the files created in the original distribution.
            See &man.pkg.delete.1;
            and &man.pkg.create.1; for more information.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><filename>MESSAGE</filename></term>

        <listitem>
          <para>This file is displayed after installation of the package.
            Useful for things like legal notices on almost-free
            software and hints for updating config files after
            installing modules for apache, PHP etc.
            Please note that you can modify variables in it easily by using
            <varname>MESSAGE_SUBST</varname> in the package's
            <filename>Makefile</filename>:</para>

<programlisting>
    MESSAGE_SUBST+=  SOMEVAR="somevalue"
</programlisting>

          <para>replaces "${SOMEVAR}" with <quote>somevalue</quote> in
            <filename>MESSAGE</filename>.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </sect1>

  <sect1 id="work-dir">
    <title><filename>work*</filename></title>

    <para>When you type <command>make</command>, the distribution files are
      unpacked into the directory denoted by
      <varname>WRKDIR</varname>. It can be removed by running
      <command>make clean</command>. Besides the sources, this
      directory is also used to keep various timestamp files.
      The directory gets <emphasis>removed completely</emphasis> on clean.
      The default is <filename>${.CURDIR}/work</filename>
      or <filename>${.CURDIR}/work.${MACHINE_ARCH}</filename>
      if <varname>OBJMACHINE</varname> is set.</para>
  </sect1>

  <sect1 id="files-dir">
    <title><filename>files/*</filename></title>

    <para>If you have any files that you wish to be placed in the package prior
      to configuration or building, you could place these files here and use
      a <quote>${CP}</quote> command in the
      <quote>pre-configure</quote> target to achieve
      this. Alternatively, you could simply diff the file against
      <filename>/dev/null</filename> and use the patch mechanism to manage
      the creation of this file.</para>
  </sect1>
</chapter>