[BACK]Return to pkgsrc.html CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / pkgsrc / doc

File: [cvs.NetBSD.org] / pkgsrc / doc / pkgsrc.html (download) (as text)

Revision 1.71, Fri Mar 17 19:49:19 2006 UTC (13 years, 7 months ago) by wiz
Branch: MAIN
CVS Tags: pkgsrc-2006Q1-base, pkgsrc-2006Q1
Changes since 1.70: +87 -82 lines

regen.

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta name="generator" content=
  "HTML Tidy for NetBSD (vers 1 September 2005), see www.w3.org" />
  <meta http-equiv="Content-Type" content=
  "text/html; charset=us-ascii" />

  <title>The pkgsrc guide</title>
  <link rel="stylesheet" href="/NetBSD.css" type="text/css" />
  <meta name="generator" content=
  "DocBook XSL Stylesheets VX.X.X" />
  <meta name="description" content=
  "Information about using the NetBSD package system (pkgsrc) from both a user view for installing packages as well as from a pkgsrc developers' view for creating new packages." />
  </head>

<body bgcolor="white" text="black" link="#0000FF" vlink="#840084"
alink="#0000FF">
  <div class="book" lang="en">
    <div class="titlepage">
      <div>
        <div>
          <h1 class="title"><a name="the-pkgsrc-guide"></a>The
          pkgsrc guide</h1>
        </div>

        <div>
          <h2 class="subtitle">Documentation on the NetBSD packages
          system</h2>
        </div>

        <div>
          <div class="authorgroup">
            <div class="author">
              <h3 class="author"><span class=
              "firstname">Alistair</span> <span class=
              "surname">Crooks</span></h3>

              <div class="affiliation">
                <div class="address">
                  <p><code class="email">&lt;<a href=
                  "mailto:agc@NetBSD.org">agc@NetBSD.org</a>&gt;</code></p>
                </div>
              </div>
            </div>

            <div class="author">
              <h3 class="author"><span class=
              "firstname">Hubert</span> <span class=
              "surname">Feyrer</span></h3>

              <div class="affiliation">
                <div class="address">
                  <p><code class="email">&lt;<a href=
                  "mailto:hubertf@NetBSD.org">hubertf@NetBSD.org</a>&gt;</code></p>
                </div>
              </div>
            </div>

            <h3 class="corpauthor">The pkgsrc Developers</h3>
          </div>
        </div>

        <div>
          <p class="copyright">Copyright &#169; 1994-2005 The
          NetBSD Foundation, Inc</p>
        </div>

        <div xmlns="http://www.w3.org/TR/xhtml1/transitional">
          <p xmlns="" class="pubdate">$NetBSD: pkgsrc.xml,v 1.12
          2006/02/18 01:46:43 rillig Exp $</p>
        </div>

        <div>
          <div class="abstract">
            <p class="title"><b>Abstract</b></p>

            <p>Information about using the NetBSD package system
            (pkgsrc) from both a user view for installing packages
            as well as from a pkgsrc developers' view for creating
            new packages.</p>
          </div>
        </div>
      </div>
      <hr />
    </div>

    <div class="toc">
      <p><b>Table of Contents</b></p>

      <dl>
        <dt><span class="chapter"><a href="#introduction">1. What
        is pkgsrc?</a></span></dt>

        <dd>
          <dl>
            <dt><span class="sect1"><a href=
            "#introduction-section">1.1.
            Introduction</a></span></dt>

            <dt><span class="sect1"><a href="#overview">1.2.
            Overview</a></span></dt>

            <dt><span class="sect1"><a href="#terminology">1.3.
            Terminology</a></span></dt>

            <dt><span class="sect1"><a href="#typography">1.4.
            Typography</a></span></dt>
          </dl>
        </dd>

        <dt><span class="part"><a href="#users-guide">I. The pkgsrc
        user's guide</a></span></dt>

        <dd>
          <dl>
            <dt><span class="chapter"><a href="#getting">2. Where
            to get pkgsrc and how to keep it
            up-to-date</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect1"><a href="#as-tar-file">2.1.
                As tar file</a></span></dt>

                <dt><span class="sect1"><a href="#via-sup">2.2. Via
                SUP</a></span></dt>

                <dt><span class="sect1"><a href="#via-cvs">2.3. Via
                CVS</a></span></dt>

                <dt><span class="sect1"><a href=
                "#uptodate-cvs">2.4. Keeping pkgsrc up-to-date via
                CVS</a></span></dt>
              </dl>
            </dd>

            <dt><span class="chapter"><a href="#platforms">3. Using
            pkgsrc on systems other than NetBSD</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect1"><a href=
                "#bootstrapping-pkgsrc">3.1. Bootstrapping
                pkgsrc</a></span></dt>

                <dt><span class="sect1"><a href=
                "#platform-specific-notes">3.2. Platform-specific
                notes</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#darwin">3.2.1. Darwin (Mac OS
                    X)</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#freebsd">3.2.2. FreeBSD</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#interix">3.2.3. Interix</a></span></dt>

                    <dt><span class="sect2"><a href="#irix">3.2.4.
                    IRIX</a></span></dt>

                    <dt><span class="sect2"><a href="#linux">3.2.5.
                    Linux</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#openbsd">3.2.6. OpenBSD</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#solaris">3.2.7. Solaris</a></span></dt>
                  </dl>
                </dd>
              </dl>
            </dd>

            <dt><span class="chapter"><a href="#using">4. Using
            pkgsrc</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect1"><a href="#using-pkg">4.1.
                Using binary packages</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#finding-binary-packages">4.1.1. Finding
                    binary packages</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#installing-binary-packages">4.1.2. Installing
                    binary packages</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#a-word-of-warning">4.1.3. A word of
                    warning</a></span></dt>
                  </dl>
                </dd>

                <dt><span class="sect1"><a href=
                "#building-packages-from-source">4.2. Building
                packages from source</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#requirements">4.2.1.
                    Requirements</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#fetching-distfiles">4.2.2. Fetching
                    distfiles</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#how-to-build-and-install">4.2.3. How to build
                    and install</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#selecting-the-compiler">4.2.4. Selecting the
                    compiler</a></span></dt>
                  </dl>
                </dd>
              </dl>
            </dd>

            <dt><span class="chapter"><a href="#configuring">5.
            Configuring pkgsrc</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect1"><a href=
                "#general-configuration">5.1. General
                configuration</a></span></dt>

                <dt><span class="sect1"><a href=
                "#variables-affecting-build">5.2. Variables
                affecting the build process</a></span></dt>

                <dt><span class="sect1"><a href=
                "#developer-advanced-settings">5.3.
                Developer/advanced settings</a></span></dt>

                <dt><span class="sect1"><a href=
                "#selecting-build-options">5.4. Selecting Build
                Options</a></span></dt>
              </dl>
            </dd>

            <dt><span class="chapter"><a href="#binary">6. Creating
            binary packages</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect1"><a href=
                "#building-a-single-binary-package">6.1. Building a
                single binary package</a></span></dt>

                <dt><span class="sect1"><a href=
                "#settings-for-creationg-of-binary-packages">6.2.
                Settings for creation of binary
                packages</a></span></dt>

                <dt><span class="sect1"><a href="#bulkbuild">6.3.
                Doing a bulk build of all packages</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#binary.configuration">6.3.1.
                    Configuration</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#other-environmental-considerations">6.3.2.
                    Other environmental
                    considerations</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#operation">6.3.3. Operation</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#what-it-does">6.3.4. What it
                    does</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#disk-space-requirements">6.3.5. Disk space
                    requirements</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#setting-up-a-sandbox">6.3.6. Setting up a
                    sandbox for chrooted builds</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#building-a-partial-set">6.3.7. Building a
                    partial set of packages</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#bulk-upload">6.3.8. Uploading results of a
                    bulk build</a></span></dt>
                  </dl>
                </dd>

                <dt><span class="sect1"><a href=
                "#creating-cdroms">6.4. Creating a multiple CD-ROM
                packages collection</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#cdpack-example">6.4.1. Example of
                    cdpack</a></span></dt>
                  </dl>
                </dd>
              </dl>
            </dd>

            <dt><span class="chapter"><a href="#faq">7. Frequently
            Asked Questions</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect1"><a href=
                "#mailing-list-pointers">7.1. Are there any mailing
                lists for pkg-related discussion?</a></span></dt>

                <dt><span class="sect1"><a href=
                "#pkgviews-docs">7.2. Where's the pkgviews
                documentation?</a></span></dt>

                <dt><span class="sect1"><a href=
                "#faq-pkgtools">7.3. Utilities for package
                management (pkgtools)</a></span></dt>

                <dt><span class="sect1"><a href=
                "#non-root-pkgsrc">7.4. How to use pkgsrc as
                non-root</a></span></dt>

                <dt><span class="sect1"><a href=
                "#resume-transfers">7.5. How to resume transfers
                when fetching distfiles?</a></span></dt>

                <dt><span class="sect1"><a href=
                "#XFree86-from-pkgsrc">7.6. How can I install/use
                XFree86 from pkgsrc?</a></span></dt>

                <dt><span class="sect1"><a href=
                "#x.org-from-pkgsrc">7.7. How can I install/use
                X.org from pkgsrc?</a></span></dt>

                <dt><span class="sect1"><a href=
                "#fetch-behind-firewall">7.8. How to fetch files
                from behind a firewall</a></span></dt>

                <dt><span class="sect1"><a href="#passive-ftp">7.9.
                How do I tell <span><strong class="command">make
                fetch</strong></span> to do passive
                FTP?</a></span></dt>

                <dt><span class="sect1"><a href=
                "#fetching-all-distfiles">7.10. How to fetch all
                distfiles at once</a></span></dt>

                <dt><span class="sect1"><a href=
                "#tmac.andoc-missing">7.11. What does
                &#8220;<span class="quote">Don't know how to make
                /usr/share/tmac/tmac.andoc</span>&#8221;
                mean?</a></span></dt>

                <dt><span class="sect1"><a href=
                "#bsd.own.mk-missing">7.12. What does
                &#8220;<span class="quote">Could not find
                bsd.own.mk</span>&#8221; mean?</a></span></dt>

                <dt><span class="sect1"><a href=
                "#using-sudo-with-pkgsrc">7.13. Using 'sudo' with
                pkgsrc</a></span></dt>

                <dt><span class="sect1"><a href="#faq.conf">7.14.
                How do I change the location of configuration
                files?</a></span></dt>

                <dt><span class="sect1"><a href=
                "#audit-packages">7.15. Automated security
                checks</a></span></dt>
              </dl>
            </dd>
          </dl>
        </dd>

        <dt><span class="part"><a href="#developers-guide">II. The
        pkgsrc developer's guide</a></span></dt>

        <dd>
          <dl>
            <dt><span class="chapter"><a href="#components">8.
            Package components - files, directories and
            contents</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect1"><a href=
                "#components.Makefile">8.1. <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">Makefile</code></a></span></dt>

                <dt><span class="sect1"><a href=
                "#components.distinfo">8.2. <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">distinfo</code></a></span></dt>

                <dt><span class="sect1"><a href=
                "#components.patches">8.3.
                patches/*</a></span></dt>

                <dt><span class="sect1"><a href=
                "#other-mandatory-files">8.4. Other mandatory
                files</a></span></dt>

                <dt><span class="sect1"><a href=
                "#components.optional">8.5. Optional
                files</a></span></dt>

                <dt><span class="sect1"><a href="#work-dir">8.6.
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">work*</code></a></span></dt>

                <dt><span class="sect1"><a href="#files-dir">8.7.
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">files/*</code></a></span></dt>
              </dl>
            </dd>

            <dt><span class="chapter"><a href="#makefile">9.
            Programming in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">Makefile</code>s</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect1"><a href=
                "#makefile.variables">9.1. <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">Makefile</code>
                variables</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#makefile.variables.names">9.1.1. Naming
                    conventions</a></span></dt>
                  </dl>
                </dd>

                <dt><span class="sect1"><a href=
                "#makefile.code">9.2. Code snippets</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#adding-to-list">9.2.1. Adding things to a
                    list</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#converting-internal-to-external">9.2.2.
                    Converting an internal list into an external
                    list</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#passing-variable-to-shell">9.2.3. Passing
                    variables to a shell command</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#quoting-guideline">9.2.4. Quoting
                    guideline</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#bsd-make-bug-workaround">9.2.5. Workaround
                    for a bug in BSD Make</a></span></dt>
                  </dl>
                </dd>
              </dl>
            </dd>

            <dt><span class="chapter"><a href="#plist">10. PLIST
            issues</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect1"><a href="#rcs-id">10.1. RCS
                ID</a></span></dt>

                <dt><span class="sect1"><a href=
                "#automatic-plist-generation">10.2. Semi-automatic
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">PLIST</code> generation</a></span></dt>

                <dt><span class="sect1"><a href=
                "#print-PLIST">10.3. Tweaking output of
                <span><strong class="command">make
                print-PLIST</strong></span></a></span></dt>

                <dt><span class="sect1"><a href="#plist.misc">10.4.
                Variable substitution in PLIST</a></span></dt>

                <dt><span class="sect1"><a href=
                "#manpage-compression">10.5. Man page
                compression</a></span></dt>

                <dt><span class="sect1"><a href=
                "#using-PLIST_SRC">10.6. Changing PLIST source with
                <code class=
                "varname">PLIST_SRC</code></a></span></dt>

                <dt><span class="sect1"><a href=
                "#platform-specific-plist">10.7. Platform-specific
                and differing PLISTs</a></span></dt>

                <dt><span class="sect1"><a href=
                "#faq.common-dirs">10.8. Sharing directories
                between packages</a></span></dt>
              </dl>
            </dd>

            <dt><span class="chapter"><a href="#buildlink">11.
            Buildlink methodology</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect1"><a href=
                "#converting-to-buildlink3">11.1. Converting
                packages to use buildlink3</a></span></dt>

                <dt><span class="sect1"><a href=
                "#creating-buildlink3.mk">11.2. Writing
                <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
                class="filename">buildlink3.mk</code>
                files</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#anatomy-of-bl3">11.2.1. Anatomy of a
                    buildlink3.mk file</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#updating-buildlink-depends">11.2.2. Updating
                    <code class=
                    "varname">BUILDLINK_DEPENDS.<em class=
                    "replaceable"><code>pkg</code></em></code> in
                    <code xmlns=
                    "http://www.w3.org/TR/xhtml1/transitional"
                    class="filename">buildlink3.mk</code>
                    files</a></span></dt>
                  </dl>
                </dd>

                <dt><span class="sect1"><a href=
                "#writing-builtin.mk">11.3. Writing <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">builtin.mk</code> files</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#anatomy-of-builtin.mk">11.3.1. Anatomy of a
                    <code xmlns=
                    "http://www.w3.org/TR/xhtml1/transitional"
                    class="filename">builtin.mk</code>
                    file</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#native-or-pkgsrc-preference">11.3.2. Global
                    preferences for native or pkgsrc
                    software</a></span></dt>
                  </dl>
                </dd>
              </dl>
            </dd>

            <dt><span class="chapter"><a href="#pkginstall">12. The
            pkginstall framework</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect1"><a href=
                "#files-and-dirs-outside-prefix">12.1. Files and
                directories outside the installation
                prefix</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#dirs-outside-prefix">12.1.1. Directory
                    manipulation</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#files-outside-prefix">12.1.2. File
                    manipulation</a></span></dt>
                  </dl>
                </dd>

                <dt><span class="sect1"><a href="#conf-files">12.2.
                Configuration files</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#conf-files-sysconfdir">12.2.1. How
                    <code class="varname">PKG_SYSCONFDIR</code> is
                    set</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#conf-files-configure">12.2.2. Telling the
                    software where configuration files
                    are</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#conf-files-patching">12.2.3. Patching
                    installations</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#conf-files-disable">12.2.4. Disabling
                    handling of configuration files</a></span></dt>
                  </dl>
                </dd>

                <dt><span class="sect1"><a href=
                "#rcd-scripts">12.3. System startup
                scripts</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#rcd-scripts-disable">12.3.1. Disabling
                    handling of system startup
                    scripts</a></span></dt>
                  </dl>
                </dd>

                <dt><span class="sect1"><a href=
                "#users-and-groups">12.4. System users and
                groups</a></span></dt>

                <dt><span class="sect1"><a href="#shells">12.5.
                System shells</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#shells-disable">12.5.1. Disabling shell
                    registration</a></span></dt>
                  </dl>
                </dd>

                <dt><span class="sect1"><a href="#fonts">12.6.
                Fonts</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#fonts-disable">12.6.1. Disabling automatic
                    update of the fonts databases</a></span></dt>
                  </dl>
                </dd>
              </dl>
            </dd>

            <dt><span class="chapter"><a href="#options">13.
            Options handling</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect1"><a href=
                "#global-default-options">13.1. Global default
                options</a></span></dt>

                <dt><span class="sect1"><a href=
                "#converting-to-options">13.2. Converting packages
                to use <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">bsd.options.mk</code></a></span></dt>

                <dt><span class="sect1"><a href=
                "#option-names">13.3. Option Names</a></span></dt>
              </dl>
            </dd>

            <dt><span class="chapter"><a href="#build">14. The
            build process</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect1"><a href=
                "#build.intro">14.1. Introduction</a></span></dt>

                <dt><span class="sect1"><a href=
                "#build.prefix">14.2. Program
                location</a></span></dt>

                <dt><span class="sect1"><a href=
                "#build.builddirs">14.3. Directories used during
                the build process</a></span></dt>

                <dt><span class="sect1"><a href=
                "#build.running">14.4. Running a
                phase</a></span></dt>

                <dt><span class="sect1"><a href=
                "#build.fetch">14.5. The <span class=
                "emphasis"><em>fetch</em></span>
                phase</a></span></dt>

                <dt><span class="sect1"><a href=
                "#build.checksum">14.6. The <span class=
                "emphasis"><em>checksum</em></span>
                phase</a></span></dt>

                <dt><span class="sect1"><a href=
                "#build.extract">14.7. The <span class=
                "emphasis"><em>extract</em></span>
                phase</a></span></dt>

                <dt><span class="sect1"><a href=
                "#build.patch">14.8. The <span class=
                "emphasis"><em>patch</em></span>
                phase</a></span></dt>

                <dt><span class="sect1"><a href=
                "#build.tools">14.9. The <span class=
                "emphasis"><em>tools</em></span>
                phase</a></span></dt>

                <dt><span class="sect1"><a href=
                "#build.wrapper">14.10. The <span class=
                "emphasis"><em>wrapper</em></span>
                phase</a></span></dt>

                <dt><span class="sect1"><a href=
                "#build.configure">14.11. The <span class=
                "emphasis"><em>configure</em></span>
                phase</a></span></dt>

                <dt><span class="sect1"><a href=
                "#build.build">14.12. The <span class=
                "emphasis"><em>build</em></span>
                phase</a></span></dt>

                <dt><span class="sect1"><a href=
                "#build.test">14.13. The <span class=
                "emphasis"><em>test</em></span>
                phase</a></span></dt>

                <dt><span class="sect1"><a href=
                "#build.install">14.14. The <span class=
                "emphasis"><em>install</em></span>
                phase</a></span></dt>

                <dt><span class="sect1"><a href=
                "#build.package">14.15. The <span class=
                "emphasis"><em>package</em></span>
                phase</a></span></dt>

                <dt><span class="sect1"><a href=
                "#build.helpful-targets">14.16. Other helpful
                targets</a></span></dt>
              </dl>
            </dd>

            <dt><span class="chapter"><a href="#tools">15. Tools
            needed for building or running</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect1"><a href=
                "#pkgsrc-tools">15.1. Tools for pkgsrc
                builds</a></span></dt>

                <dt><span class="sect1"><a href=
                "#package-tools">15.2. Tools needed by
                packages</a></span></dt>

                <dt><span class="sect1"><a href=
                "#platform-tools">15.3. Tools provided by
                platforms</a></span></dt>
              </dl>
            </dd>

            <dt><span class="chapter"><a href="#fixes">16. Making
            your package work</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect1"><a href=
                "#general-operation">16.1. General
                operation</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#pulling-vars-from-etc-mk.conf">16.1.1. How to
                    pull in variables from
                    /etc/mk.conf</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#where-to-install-documentation">16.1.2. Where
                    to install documentation</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#restricted-packages">16.1.3. Restricted
                    packages</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#dependencies">16.1.4. Handling
                    dependencies</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#conflicts">16.1.5. Handling conflicts with
                    other packages</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#not-building-packages">16.1.6. Packages that
                    cannot or should not be built</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#undeletable-packages">16.1.7. Packages which
                    should not be deleted, once
                    installed</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#security-handling">16.1.8. Handling packages
                    with security problems</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#compiler-bugs">16.1.9. How to handle compiler
                    bugs</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#bumping-pkgrevision">16.1.10. How to handle
                    incrementing versions when fixing an existing
                    package</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#portability-of-packages">16.1.11. Portability
                    of packages</a></span></dt>
                  </dl>
                </dd>

                <dt><span class="sect1"><a href=
                "#downloading-issues">16.2. Possible downloading
                issues</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#no-plain-download">16.2.1. Packages whose
                    distfiles aren't available for plain
                    downloading</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#modified-distfiles-same-name">16.2.2. How to
                    handle modified distfiles with the 'old'
                    name</a></span></dt>
                  </dl>
                </dd>

                <dt><span class="sect1"><a href=
                "#configuration-gotchas">16.3. Configuration
                gotchas</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#fixes.libtool">16.3.1. Shared libraries -
                    libtool</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#using-libtool">16.3.2. Using libtool on GNU
                    packages that already support
                    libtool</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#autoconf-automake">16.3.3. GNU
                    Autoconf/Automake</a></span></dt>
                  </dl>
                </dd>

                <dt><span class="sect1"><a href=
                "#fixes-build">16.4. Building the
                package</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#cpp-defines">16.4.1. CPP
                    defines</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#cpp-list-examples">16.4.2. Examples of CPP
                    defines for some platforms</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#cpp-list">16.4.3. Getting a list of CPP
                    defines</a></span></dt>
                  </dl>
                </dd>

                <dt><span class="sect1"><a href=
                "#package-specific-actions">16.5. Package specific
                actions</a></span></dt>

                <dd>
                  <dl>
                    <dt><span class="sect2"><a href=
                    "#user-interaction">16.5.1. User
                    interaction</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#handling-licenses">16.5.2. Handling
                    licenses</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#installing-score-files">16.5.3. Installing
                    score files</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#perl-scripts">16.5.4. Packages containing
                    perl scripts</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#hardcoded-paths">16.5.5. Packages with
                    hardcoded paths to other
                    interpreters</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#perl-modules">16.5.6. Packages installing
                    perl modules</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#faq.info-files">16.5.7. Packages installing
                    info files</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#manpages">16.5.8. Packages installing man
                    pages</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#gconf2-data-files">16.5.9. Packages
                    installing GConf2 data files</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#scrollkeeper-data-files">16.5.10. Packages
                    installing scrollkeeper data
                    files</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#x11-fonts">16.5.11. Packages installing X11
                    fonts</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#gtk2-modules">16.5.12. Packages installing
                    GTK2 modules</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#sgml-xml-data">16.5.13. Packages installing
                    SGML or XML data</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#mime-database">16.5.14. Packages installing
                    extensions to the MIME database</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#intltool">16.5.15. Packages using
                    intltool</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#startup-scripts">16.5.16. Packages installing
                    startup scripts</a></span></dt>

                    <dt><span class="sect2"><a href=
                    "#tex-packages">16.5.17. Packages installing
                    TeX modules</a></span></dt>
                  </dl>
                </dd>

                <dt><span class="sect1"><a href=
                "#feedback-to-author">16.6. Feedback to the
                author</a></span></dt>
              </dl>
            </dd>

            <dt><span class="chapter"><a href="#debug">17.
            Debugging</a></span></dt>

            <dt><span class="chapter"><a href="#submit">18.
            Submitting and Committing</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect1"><a href=
                "#submitting-your-package">18.1. Submitting your
                packages</a></span></dt>

                <dt><span class="sect1"><a href=
                "#general-notes-for-changes">18.2. General notes
                when adding, updating, or removing
                packages</a></span></dt>

                <dt><span class="sect1"><a href=
                "#committing-importing">18.3. Committing: Importing
                a package into CVS</a></span></dt>

                <dt><span class="sect1"><a href=
                "#updating-package">18.4. Updating a package to a
                newer version</a></span></dt>

                <dt><span class="sect1"><a href=
                "#moving-package">18.5. Moving a package in
                pkgsrc</a></span></dt>
              </dl>
            </dd>

            <dt><span class="chapter"><a href="#porting">19.
            Porting pkgsrc</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect1"><a href=
                "#porting.opsys">19.1. Porting pkgsrc to a new
                operating system</a></span></dt>

                <dt><span class="sect1"><a href=
                "#porting.compiler">19.2. Adding support for a new
                compiler</a></span></dt>
              </dl>
            </dd>
          </dl>
        </dd>

        <dt><span class="appendix"><a href="#examples">A. A simple
        example package: bison</a></span></dt>

        <dd>
          <dl>
            <dt><span class="sect1"><a href="#example-files">A.1.
            files</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#example-Makefile">A.1.1. Makefile</a></span></dt>

                <dt><span class="sect2"><a href=
                "#example-descr">A.1.2. DESCR</a></span></dt>

                <dt><span class="sect2"><a href=
                "#example-plist">A.1.3. PLIST</a></span></dt>

                <dt><span class="sect2"><a href=
                "#checking-package-with-pkglint">A.1.4. Checking a
                package with <span><strong class=
                "command">pkglint</strong></span></a></span></dt>
              </dl>
            </dd>

            <dt><span class="sect1"><a href="#steps-for-b-i-p">A.2.
            Steps for building, installing,
            packaging</a></span></dt>
          </dl>
        </dd>

        <dt><span class="appendix"><a href="#logs">B. Build
        logs</a></span></dt>

        <dd>
          <dl>
            <dt><span class="sect1"><a href="#logs.building">B.1.
            Building figlet</a></span></dt>

            <dt><span class="sect1"><a href="#logs.package">B.2.
            Packaging figlet</a></span></dt>
          </dl>
        </dd>

        <dt><span class="appendix"><a href="#ftp-layout">C. Layout
        of the FTP server's package archive</a></span></dt>

        <dt><span class="appendix"><a href="#editing">D. Editing
        guidelines for the pkgsrc guide</a></span></dt>

        <dd>
          <dl>
            <dt><span class="sect1"><a href="#targets">D.1.
            Targets</a></span></dt>

            <dt><span class="sect1"><a href="#procedure">D.2.
            Procedure</a></span></dt>
          </dl>
        </dd>
      </dl>
    </div>

    <div class="chapter" lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title"><a name=
            "introduction"></a>Chapter&nbsp;1.&nbsp;What is
            pkgsrc?</h2>
          </div>
        </div>
      </div>

      <div class="toc">
        <p><b>Table of Contents</b></p>

        <dl>
          <dt><span class="sect1"><a href=
          "#introduction-section">1.1. Introduction</a></span></dt>

          <dt><span class="sect1"><a href="#overview">1.2.
          Overview</a></span></dt>

          <dt><span class="sect1"><a href="#terminology">1.3.
          Terminology</a></span></dt>

          <dt><span class="sect1"><a href="#typography">1.4.
          Typography</a></span></dt>
        </dl>
      </div>

      <div class="sect1" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a name=
              "introduction-section"></a>1.1.&nbsp;Introduction</h2>
            </div>
          </div>
        </div>

        <p>There is a lot of software freely available for
        Unix-based systems, which usually runs on NetBSD and other
        Unix-flavoured systems, too, sometimes with some
        modifications. The NetBSD Packages Collection (pkgsrc)
        incorporates any such changes necessary to make that
        software run, and makes the installation (and
        de-installation) of the software package easy by means of a
        single command.</p>

        <p>Once the software has been built, it is manipulated with
        the <span><strong class="command">pkg_*</strong></span>
        tools so that installation and de-installation, printing of
        an inventory of all installed packages and retrieval of
        one-line comments or more verbose descriptions are all
        simple.</p>

        <p>pkgsrc currently contains several thousand packages,
        including:</p>

        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p><a xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" href=
              "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/apache/README.html"
              target="_top"><code xmlns="" class=
              "filename">www/apache</code></a> - The Apache web
              server</p>
            </li>

            <li>
              <p><a xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" href=
              "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/mozilla/README.html"
              target="_top"><code xmlns="" class=
              "filename">www/mozilla</code></a> - The Mozilla web
              browser</p>
            </li>

            <li>
              <p><a xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" href=
              "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/meta-pkgs/gnome/README.html"
              target="_top"><code xmlns="" class=
              "filename">meta-pkgs/gnome</code></a> - The GNOME
              Desktop Environment</p>
            </li>

            <li>
              <p><a xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" href=
              "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/meta-pkgs/kde3/README.html"
              target="_top"><code xmlns="" class=
              "filename">meta-pkgs/kde3</code></a> - The K Desktop
              Environment</p>
            </li>
          </ul>
        </div>

        <p>...just to name a few.</p>

        <p>pkgsrc has built-in support for handling varying
        dependencies, such as pthreads and X11, and extended
        features such as IPv6 support on a range of platforms.</p>

        <p>pkgsrc was derived from FreeBSD's ports system, and
        initially developed for NetBSD only. Since then, pkgsrc has
        grown a lot, and now supports the following platforms:</p>

        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p><a href="http://developer.apple.com/darwin/"
              target="_top">Darwin</a> (<a href=
              "http://www.apple.com/macosx/" target="_top">Mac OS
              X</a>)</p>
            </li>

            <li>
              <p><a href="http://www.DragonFlyBSD.org/" target=
              "_top">DragonFly BSD</a></p>
            </li>

            <li>
              <p><a href="http://www.FreeBSD.org/" target=
              "_top">FreeBSD</a></p>
            </li>

            <li>
              <p>Microsoft Windows, via <a href=
              "http://www.microsoft.com/windows/sfu/" target=
              "_top">Interix</a></p>
            </li>

            <li>
              <p><a href="http://www.sgi.com/software/irix6.5/"
              target="_top">IRIX</a></p>
            </li>

            <li>
              <p><a href="http://www.linux.org/" target=
              "_top">Linux</a></p>
            </li>

            <li>
              <p><a href="http://www.NetBSD.org/" target=
              "_top">NetBSD</a> (of course)</p>
            </li>

            <li>
              <p><a href="http://h30097.www3.hp.com/" target=
              "_top">Tru64</a> (Digital UNIX, OSF1)</p>
            </li>

            <li>
              <p><a href="http://www.openbsd.org/" target=
              "_top">OpenBSD</a></p>
            </li>

            <li>
              <p><a href="http://www.sun.com/solaris/" target=
              "_top">Solaris</a></p>
            </li>
          </ul>
        </div>
      </div>

      <div class="sect1" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a name=
              "overview"></a>1.2.&nbsp;Overview</h2>
            </div>
          </div>
        </div>

        <p>This document is divided into two parts. The first,
        <a href="#users-guide" title=
        "Part&nbsp;I.&nbsp;The pkgsrc user's guide">The pkgsrc
        user's guide</a>, describes how one can use one of the
        packages in the Package Collection, either by installing a
        precompiled binary package, or by building one's own copy
        using the NetBSD package system. The second part, <a href=
        "#developers-guide" title=
        "Part&nbsp;II.&nbsp;The pkgsrc developer's guide">The
        pkgsrc developer's guide</a>, explains how to prepare a
        package so it can be easily built by other NetBSD users
        without knowing about the package's building details.</p>

        <p>This document is available in various formats:</p>

        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p><a href="index.html" target="_top">HTML</a></p>
            </li>

            <li>
              <p><a href="pkgsrc.pdf" target="_top">PDF</a></p>
            </li>

            <li>
              <p><a href="pkgsrc.ps" target="_top">PS</a></p>
            </li>

            <li>
              <p><a href="pkgsrc.txt" target="_top">TXT</a></p>
            </li>
          </ul>
        </div>
      </div>

      <div class="sect1" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a name=
              "terminology"></a>1.3.&nbsp;Terminology</h2>
            </div>
          </div>
        </div>

        <p>There has been a lot of talk about &#8220;<span class=
        "quote">ports</span>&#8221;, &#8220;<span class=
        "quote">packages</span>&#8221;, etc. so far. Here is a
        description of all the terminology used within this
        document.</p>

        <div class="variablelist">
          <dl>
            <dt><span class="term">Package</span></dt>

            <dd>
              <p>A set of files and building instructions that
              describe what's necessary to build a certain piece of
              software using pkgsrc. Packages are traditionally
              stored under <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">/usr/pkgsrc</code>.</p>
            </dd>

            <dt><span class="term">The NetBSD package
            system</span></dt>

            <dd>
              <p>This is the former name of &#8220;<span class=
              "quote">pkgsrc</span>&#8221;. It is part of the
              NetBSD operating system and can be bootstrapped to
              run on non-NetBSD operating systems as well. It
              handles building (compiling), installing, and
              removing of packages.</p>
            </dd>

            <dt><span class="term">Distfile</span></dt>

            <dd>
              <p>This term describes the file or files that are
              provided by the author of the piece of software to
              distribute his work. All the changes necessary to
              build on NetBSD are reflected in the corresponding
              package. Usually the distfile is in the form of a
              compressed tar-archive, but other types are possible,
              too. Distfiles are usually stored below <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">/usr/pkgsrc/distfiles</code>.</p>
            </dd>

            <dt><span class="term">Port</span></dt>

            <dd>
              <p>This is the term used by FreeBSD and OpenBSD
              people for what we call a package. In NetBSD
              terminology, &#8220;<span class=
              "quote">port</span>&#8221; refers to a different
              architecture.</p>
            </dd>

            <dt><span class="term">Precompiled/binary
            package</span></dt>

            <dd>
              <p>A set of binaries built with pkgsrc from a
              distfile and stuffed together in a single
              <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
              class="filename">.tgz</code> file so it can be
              installed on machines of the same machine
              architecture without the need to recompile. Packages
              are usually generated in <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">/usr/pkgsrc/packages</code>; there is also
              an archive on <a href=
              "ftp://ftp.NetBSD.org/pub/NetBSD/packages/" target=
              "_top">ftp.NetBSD.org</a>.</p>

              <p>Sometimes, this is referred to by the term
              &#8220;<span class="quote">package</span>&#8221; too,
              especially in the context of precompiled
              packages.</p>
            </dd>

            <dt><span class="term">Program</span></dt>

            <dd>
              <p>The piece of software to be installed which will
              be constructed from all the files in the distfile by
              the actions defined in the corresponding package.</p>
            </dd>
          </dl>
        </div>
      </div>

      <div class="sect1" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a name=
              "typography"></a>1.4.&nbsp;Typography</h2>
            </div>
          </div>
        </div>

        <p>When giving examples for commands, shell prompts are
        used to show if the command should/can be issued as root,
        or if &#8220;<span class="quote">normal</span>&#8221; user
        privileges are sufficient. We use a <code class=
        "prompt">#</code> for root's shell prompt, and a
        <code class="prompt">%</code> for users' shell prompt,
        assuming they use the C-shell or tcsh.</p>
      </div>
    </div>

    <div class="part" lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h1 class="title"><a name=
            "users-guide"></a>Part&nbsp;I.&nbsp;The pkgsrc user's
            guide</h1>
          </div>
        </div>
      </div>

      <div class="toc">
        <p><b>Table of Contents</b></p>

        <dl>
          <dt><span class="chapter"><a href="#getting">2. Where to
          get pkgsrc and how to keep it up-to-date</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect1"><a href="#as-tar-file">2.1.
              As tar file</a></span></dt>

              <dt><span class="sect1"><a href="#via-sup">2.2. Via
              SUP</a></span></dt>

              <dt><span class="sect1"><a href="#via-cvs">2.3. Via
              CVS</a></span></dt>

              <dt><span class="sect1"><a href="#uptodate-cvs">2.4.
              Keeping pkgsrc up-to-date via CVS</a></span></dt>
            </dl>
          </dd>

          <dt><span class="chapter"><a href="#platforms">3. Using
          pkgsrc on systems other than NetBSD</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect1"><a href=
              "#bootstrapping-pkgsrc">3.1. Bootstrapping
              pkgsrc</a></span></dt>

              <dt><span class="sect1"><a href=
              "#platform-specific-notes">3.2. Platform-specific
              notes</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href="#darwin">3.2.1.
                  Darwin (Mac OS X)</a></span></dt>

                  <dt><span class="sect2"><a href="#freebsd">3.2.2.
                  FreeBSD</a></span></dt>

                  <dt><span class="sect2"><a href="#interix">3.2.3.
                  Interix</a></span></dt>

                  <dt><span class="sect2"><a href="#irix">3.2.4.
                  IRIX</a></span></dt>

                  <dt><span class="sect2"><a href="#linux">3.2.5.
                  Linux</a></span></dt>

                  <dt><span class="sect2"><a href="#openbsd">3.2.6.
                  OpenBSD</a></span></dt>

                  <dt><span class="sect2"><a href="#solaris">3.2.7.
                  Solaris</a></span></dt>
                </dl>
              </dd>
            </dl>
          </dd>

          <dt><span class="chapter"><a href="#using">4. Using
          pkgsrc</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect1"><a href="#using-pkg">4.1.
              Using binary packages</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#finding-binary-packages">4.1.1. Finding binary
                  packages</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#installing-binary-packages">4.1.2. Installing
                  binary packages</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#a-word-of-warning">4.1.3. A word of
                  warning</a></span></dt>
                </dl>
              </dd>

              <dt><span class="sect1"><a href=
              "#building-packages-from-source">4.2. Building
              packages from source</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#requirements">4.2.1.
                  Requirements</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#fetching-distfiles">4.2.2. Fetching
                  distfiles</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#how-to-build-and-install">4.2.3. How to build
                  and install</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#selecting-the-compiler">4.2.4. Selecting the
                  compiler</a></span></dt>
                </dl>
              </dd>
            </dl>
          </dd>

          <dt><span class="chapter"><a href="#configuring">5.
          Configuring pkgsrc</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect1"><a href=
              "#general-configuration">5.1. General
              configuration</a></span></dt>

              <dt><span class="sect1"><a href=
              "#variables-affecting-build">5.2. Variables affecting
              the build process</a></span></dt>

              <dt><span class="sect1"><a href=
              "#developer-advanced-settings">5.3.
              Developer/advanced settings</a></span></dt>

              <dt><span class="sect1"><a href=
              "#selecting-build-options">5.4. Selecting Build
              Options</a></span></dt>
            </dl>
          </dd>

          <dt><span class="chapter"><a href="#binary">6. Creating
          binary packages</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect1"><a href=
              "#building-a-single-binary-package">6.1. Building a
              single binary package</a></span></dt>

              <dt><span class="sect1"><a href=
              "#settings-for-creationg-of-binary-packages">6.2.
              Settings for creation of binary
              packages</a></span></dt>

              <dt><span class="sect1"><a href="#bulkbuild">6.3.
              Doing a bulk build of all packages</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#binary.configuration">6.3.1.
                  Configuration</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#other-environmental-considerations">6.3.2.
                  Other environmental
                  considerations</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#operation">6.3.3. Operation</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#what-it-does">6.3.4. What it
                  does</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#disk-space-requirements">6.3.5. Disk space
                  requirements</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#setting-up-a-sandbox">6.3.6. Setting up a
                  sandbox for chrooted builds</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#building-a-partial-set">6.3.7. Building a
                  partial set of packages</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#bulk-upload">6.3.8. Uploading results of a bulk
                  build</a></span></dt>
                </dl>
              </dd>

              <dt><span class="sect1"><a href=
              "#creating-cdroms">6.4. Creating a multiple CD-ROM
              packages collection</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#cdpack-example">6.4.1. Example of
                  cdpack</a></span></dt>
                </dl>
              </dd>
            </dl>
          </dd>

          <dt><span class="chapter"><a href="#faq">7. Frequently
          Asked Questions</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect1"><a href=
              "#mailing-list-pointers">7.1. Are there any mailing
              lists for pkg-related discussion?</a></span></dt>

              <dt><span class="sect1"><a href="#pkgviews-docs">7.2.
              Where's the pkgviews documentation?</a></span></dt>

              <dt><span class="sect1"><a href="#faq-pkgtools">7.3.
              Utilities for package management
              (pkgtools)</a></span></dt>

              <dt><span class="sect1"><a href=
              "#non-root-pkgsrc">7.4. How to use pkgsrc as
              non-root</a></span></dt>

              <dt><span class="sect1"><a href=
              "#resume-transfers">7.5. How to resume transfers when
              fetching distfiles?</a></span></dt>

              <dt><span class="sect1"><a href=
              "#XFree86-from-pkgsrc">7.6. How can I install/use
              XFree86 from pkgsrc?</a></span></dt>

              <dt><span class="sect1"><a href=
              "#x.org-from-pkgsrc">7.7. How can I install/use X.org
              from pkgsrc?</a></span></dt>

              <dt><span class="sect1"><a href=
              "#fetch-behind-firewall">7.8. How to fetch files from
              behind a firewall</a></span></dt>

              <dt><span class="sect1"><a href="#passive-ftp">7.9.
              How do I tell <span><strong class="command">make
              fetch</strong></span> to do passive
              FTP?</a></span></dt>

              <dt><span class="sect1"><a href=
              "#fetching-all-distfiles">7.10. How to fetch all
              distfiles at once</a></span></dt>

              <dt><span class="sect1"><a href=
              "#tmac.andoc-missing">7.11. What does
              &#8220;<span class="quote">Don't know how to make
              /usr/share/tmac/tmac.andoc</span>&#8221;
              mean?</a></span></dt>

              <dt><span class="sect1"><a href=
              "#bsd.own.mk-missing">7.12. What does
              &#8220;<span class="quote">Could not find
              bsd.own.mk</span>&#8221; mean?</a></span></dt>

              <dt><span class="sect1"><a href=
              "#using-sudo-with-pkgsrc">7.13. Using 'sudo' with
              pkgsrc</a></span></dt>

              <dt><span class="sect1"><a href="#faq.conf">7.14. How
              do I change the location of configuration
              files?</a></span></dt>

              <dt><span class="sect1"><a href=
              "#audit-packages">7.15. Automated security
              checks</a></span></dt>
            </dl>
          </dd>
        </dl>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "getting"></a>Chapter&nbsp;2.&nbsp;Where to get
              pkgsrc and how to keep it up-to-date</h2>
            </div>
          </div>
        </div>

        <div class="toc">
          <p><b>Table of Contents</b></p>

          <dl>
            <dt><span class="sect1"><a href="#as-tar-file">2.1. As
            tar file</a></span></dt>

            <dt><span class="sect1"><a href="#via-sup">2.2. Via
            SUP</a></span></dt>

            <dt><span class="sect1"><a href="#via-cvs">2.3. Via
            CVS</a></span></dt>

            <dt><span class="sect1"><a href="#uptodate-cvs">2.4.
            Keeping pkgsrc up-to-date via CVS</a></span></dt>
          </dl>
        </div>

        <p>There are three ways to get pkgsrc. Either as a tar
        file, via SUP, or via CVS. All three ways are described
        here.</p>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "as-tar-file"></a>2.1.&nbsp;As tar file</h2>
              </div>
            </div>
          </div>

          <p>To get pkgsrc going, you need to get the pkgsrc.tar.gz
          file from <a href=
          "ftp://ftp.NetBSD.org/pub/NetBSD/NetBSD-current/tar_files/pkgsrc.tar.gz"
          target="_top">ftp.NetBSD.org</a> and unpack it into
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">/usr/pkgsrc</code>.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "via-sup"></a>2.2.&nbsp;Via SUP</h2>
              </div>
            </div>
          </div>

          <p>As an alternative to the tar file, you can get pkgsrc
          via the Software Update Protocol, SUP. To do so, make
          sure your supfile has a line</p>
          <pre class="programlisting">
    release=pkgsrc
</pre>

          <p>in it, see the examples in <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/usr/share/examples/supfiles</code>, and that
          the <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/usr/pkgsrc</code> directory exists. Then,
          simply run <span><strong class="command">sup -v
          <em class="replaceable"><code>/path/to/your/supfile</code></em></strong></span>.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "via-cvs"></a>2.3.&nbsp;Via CVS</h2>
              </div>
            </div>
          </div>

          <p>To get pkgsrc via CVS, make sure you have
          &#8220;<span class="quote">cvs</span>&#8221; installed.
          To do an initial (full) checkout of pkgsrc, do the
          following steps:</p>
          <pre class="screen">
<code class="prompt">%</code> <strong class=
"userinput"><code>setenv CVSROOT anoncvs@anoncvs.NetBSD.org:/cvsroot</code></strong>
<code class="prompt">%</code> <strong class=
"userinput"><code>setenv CVS_RSH ssh</code></strong>
<code class="prompt">%</code> <strong class=
"userinput"><code>cd /usr</code></strong>
<code class="prompt">%</code> <strong class=
"userinput"><code>cvs checkout -P pkgsrc</code></strong>
</pre>

          <p>This will create the <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">pkgsrc</code> directory in your <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/usr</code>, and all the package source will
          be stored under <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/usr/pkgsrc</code>. To update pkgsrc after the
          initial checkout, make sure you have <code class=
          "varname">CVS_RSH</code> set as above, then do:</p>
          <pre class="screen">
<code class="prompt">%</code> <strong class=
"userinput"><code>cd /usr/pkgsrc</code></strong>
<code class="prompt">%</code> <strong class=
"userinput"><code>cvs -q update -dP</code></strong>
</pre>

          <p>Please also note that it is possible to have multiple
          copies of the pkgsrc hierarchy in use at any one time -
          all work is done relatively within the pkgsrc tree.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "uptodate-cvs"></a>2.4.&nbsp;Keeping pkgsrc
                up-to-date via CVS</h2>
              </div>
            </div>
          </div>

          <p>If your copy of pkgsrc contains a lot of <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">CVS</code> directories, you can update it
          using the <a href=
          "http://netbsd.gw.com/cgi-bin/man-cgi?cvs+1+NetBSD-current">
          <span class="citerefentry"><span class=
          "refentrytitle">cvs</span>(1)</span></a> program. First,
          <span><strong class="command">cd</strong></span> to the
          top level directory of pkgsrc. Then run
          <span><strong class="command">cvs -q update
          -dP</strong></span>, and you're done.</p>

          <p>If that doesn't work and the file <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">CVS/Root</code> contains the string
          &#8220;<span class="quote">:pserver:</span>&#8221;, you
          have to run <span><strong class="command">cvs
          login</strong></span> once to get known to the NetBSD CVS
          server. The <span><strong class=
          "command">cvs</strong></span> utility will then ask you
          for a password. Just enter &#8220;<span class=
          "quote">anoncvs</span>&#8221;. Then try again to
          update.</p>
        </div>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "platforms"></a>Chapter&nbsp;3.&nbsp;Using pkgsrc on
              systems other than NetBSD</h2>
            </div>
          </div>
        </div>

        <div class="toc">
          <p><b>Table of Contents</b></p>

          <dl>
            <dt><span class="sect1"><a href=
            "#bootstrapping-pkgsrc">3.1. Bootstrapping
            pkgsrc</a></span></dt>

            <dt><span class="sect1"><a href=
            "#platform-specific-notes">3.2. Platform-specific
            notes</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href="#darwin">3.2.1.
                Darwin (Mac OS X)</a></span></dt>

                <dt><span class="sect2"><a href="#freebsd">3.2.2.
                FreeBSD</a></span></dt>

                <dt><span class="sect2"><a href="#interix">3.2.3.
                Interix</a></span></dt>

                <dt><span class="sect2"><a href="#irix">3.2.4.
                IRIX</a></span></dt>

                <dt><span class="sect2"><a href="#linux">3.2.5.
                Linux</a></span></dt>

                <dt><span class="sect2"><a href="#openbsd">3.2.6.
                OpenBSD</a></span></dt>

                <dt><span class="sect2"><a href="#solaris">3.2.7.
                Solaris</a></span></dt>
              </dl>
            </dd>
          </dl>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "bootstrapping-pkgsrc"></a>3.1.&nbsp;Bootstrapping
                pkgsrc</h2>
              </div>
            </div>
          </div>

          <p>For operating systems other than NetBSD, we provide a
          bootstrap kit to build the required tools to use pkgsrc
          on your platform. Besides support for native NetBSD,
          pkgsrc and the bootstrap kit have support for the
          following operating systems:</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p>Darwin (Mac OS X)</p>
              </li>

              <li>
                <p>DragonFly BSD</p>
              </li>

              <li>
                <p>FreeBSD</p>
              </li>

              <li>
                <p>Interix (Windows 2000, XP, 2003)</p>
              </li>

              <li>
                <p>IRIX</p>
              </li>

              <li>
                <p>Linux</p>
              </li>

              <li>
                <p>OpenBSD</p>
              </li>

              <li>
                <p>Solaris</p>
              </li>

              <li>
                <p>Tru64 (Digital UNIX/OSF1)</p>
              </li>
            </ul>
          </div>

          <p>Support for other platforms is under development.</p>

          <p>Installing the bootstrap kit should be as simple
          as:</p>
          <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>env CVS_RSH=ssh cvs -d anoncvs@anoncvs.NetBSD.org:/cvsroot checkout pkgsrc</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>cd pkgsrc/bootstrap</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>./bootstrap</code></strong>
</pre>

          <p>See <a href="#getting" title=
          "Chapter&nbsp;2.&nbsp;Where to get pkgsrc and how to keep it up-to-date">
          Chapter&nbsp;2, <i>Where to get pkgsrc and how to keep it
          up-to-date</i></a> for other ways to get pkgsrc before
          bootstrapping. The given <span><strong class=
          "command">bootstrap</strong></span> command will use the
          defaults of <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/usr/pkg</code> for the <span class=
          "emphasis"><em>prefix</em></span> where programs will be
          installed in, and <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/var/db/pkg</code> for the package database
          directory where pkgsrc will do its internal bookkeeping.
          However, these can also be set using command-line
          arguments.</p>

          <p>Binary packages for the pkgsrc tools and an initial
          set of packages is available for supported platforms. An
          up-to-date list of these can be found on <a href=
          "http://www.pkgsrc.org/" target=
          "_top">www.pkgsrc.org</a>. Note that this only works for
          privileged builds that install into <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/usr/pkg</code>.</p>

          <div class="note" style=
          "margin-left: 0.5in; margin-right: 0.5in;">
            <h3 class="title">Note</h3>

            <p>The bootstrap installs a <span><strong class=
            "command">bmake</strong></span> tool. Use this
            <span><strong class="command">bmake</strong></span>
            when building via pkgsrc. For examples in this guide,
            use <span><strong class="command">bmake</strong></span>
            instead of &#8220;<span class=
            "quote">make</span>&#8221;.</p>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "platform-specific-notes"></a>3.2.&nbsp;Platform-specific
                notes</h2>
              </div>
            </div>
          </div>

          <p>Here are some platform-specific notes you should be
          aware of.</p>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "darwin"></a>3.2.1.&nbsp;Darwin (Mac OS X)</h3>
                </div>
              </div>
            </div>

            <p>Darwin 5.x and 6.x are supported. There are two
            methods of using pkgsrc on Mac OS X, by using a
            <a href="#platform.osx-image" title=
            "3.2.1.1.&nbsp;Using a disk image">disk image</a>, or a
            <a href="#platform.osx-ufs" title=
            "3.2.1.2.&nbsp;Using a UFS partition">UFS
            partition</a>.</p>

            <p>Before you start, you will need to download and
            install the Mac OS X Developer Tools from Apple's
            Developer Connection. See <a href=
            "http://developer.apple.com/macosx/" target=
            "_top">http://developer.apple.com/macosx/</a> for
            details. Also, make sure you install X11 for Mac OS X
            and the X11 SDK from <a href=
            "http://www.apple.com/macosx/x11/download/" target=
            "_top">http://www.apple.com/macosx/x11/download/</a> if
            you intend to build packages that use the X11 Window
            System.</p>

            <p>If you already have a UFS partition, or have a spare
            partition that you can format as UFS, it is recommended
            to use that instead of the disk image. It'll be
            somewhat faster and will mount automatically at boot
            time, where you must manually mount a disk image.</p>

            <div class="note" style=
            "margin-left: 0.5in; margin-right: 0.5in;">
              <h3 class="title">Note</h3>

              <p>You cannot use a HFS+ file system for pkgsrc,
              because pkgsrc currently requires the file system to
              be case-sensitive, and HFS+ is not.</p>
            </div>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "platform.osx-image"></a>3.2.1.1.&nbsp;Using a
                    disk image</h4>
                  </div>
                </div>
              </div>

              <p>Create the disk image:</p>
              <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>cd pkgsrc/bootstrap</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>./ufsdiskimage create ~/Documents/NetBSD 512</code></strong> # megabytes - season to taste
<code class="prompt">#</code> <strong class=
"userinput"><code>./ufsdiskimage mount ~/Documents/NetBSD</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>sudo chown `id -u`:`id -g` /Volumes/NetBSD</code></strong>
</pre>

              <p>That's it!</p>
            </div>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "platform.osx-ufs"></a>3.2.1.2.&nbsp;Using a
                    UFS partition</h4>
                  </div>
                </div>
              </div>

              <p>By default, <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">/usr</code> will be on your root file
              system, normally HFS+. It is possible to use the
              default <span class="emphasis"><em>prefix</em></span>
              of <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">/usr/pkg</code> by symlinking <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">/usr/pkg</code> to a directory on a UFS
              file system. Obviously, another symlink is required
              if you want to place the package database directory
              outside the <span class=
              "emphasis"><em>prefix</em></span>. e.g.</p>
              <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>./bootstrap --pkgdbdir /usr/pkg/pkgdb</code></strong>
</pre>

              <p>If you created your partitions at the time of
              installing Mac OS X and formatted the target
              partition as UFS, it should automatically mount on
              <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">/Volumes/&lt;volume name&gt;</code> when
              the machine boots. If you are (re)formatting a
              partition as UFS, you need to ensure that the
              partition map correctly reflects &#8220;<span class=
              "quote">Apple_UFS</span>&#8221; and not
              &#8220;<span class=
              "quote">Apple_HFS</span>&#8221;.</p>

              <p>The problem is that none of the disk tools will
              let you touch a disk that is booted from. You can
              unmount the partition, but even if you newfs it, the
              partition type will be incorrect and the automounter
              won't mount it. It can be mounted manually, but it
              won't appear in Finder.</p>

              <p>You'll need to boot off of the OS X Installation
              (User) CD. When the Installation program starts, go
              up to the menu and select Disk Utility. Now, you will
              be able to select the partition you want to be UFS,
              and Format it Apple UFS. Quit the Disk Utility, quit
              the installer which will reboot your machine. The new
              UFS file system will appear in Finder.</p>

              <p>Be aware that the permissions on the new file
              system will be writable by root only.</p>

              <p>This note is as of 10.2 (Jaguar) and applies to
              earlier versions. Hopefully Apple will fix Disk
              Utility in 10.3 (Panther).</p>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "freebsd"></a>3.2.2.&nbsp;FreeBSD</h3>
                </div>
              </div>
            </div>

            <p>FreeBSD 4.7 and 5.0 have been tested and are
            supported, other versions may work.</p>

            <p>Care should be taken so that the tools that this kit
            installs do not conflict with the FreeBSD userland
            tools. There are several steps:</p>

            <div class="orderedlist">
              <ol type="1">
                <li>
                  <p>FreeBSD stores its ports pkg database in
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/var/db/pkg</code>. It is therefore
                  recommended that you choose a different location
                  (e.g. <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/usr/pkgdb</code>) by using the
                  --pkgdbdir option to the bootstrap script.</p>
                </li>

                <li>
                  <p>If you do not intend to use the FreeBSD ports
                  tools, it's probably a good idea to move them out
                  of the way to avoid confusion, e.g.</p>
                  <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>cd /usr/sbin</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>mv pkg_add pkg_add.orig</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>mv pkg_create pkg_create.orig</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>mv pkg_delete pkg_delete.orig</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>mv pkg_info pkg_info.orig</code></strong>
</pre>
                </li>

                <li>
                  <p>An example <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/etc/mk.conf</code> file will be
                  placed in <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/etc/mk.conf.example</code> file when
                  you use the bootstrap script.</p>
                </li>
              </ol>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "interix"></a>3.2.3.&nbsp;Interix</h3>
                </div>
              </div>
            </div>

            <p>Interix is a POSIX-compatible subsystem for the
            Windows NT kernel, providing a Unix-like environment
            with a tighter kernel integration than available with
            Cygwin. It is part of the Windows Services for Unix
            package, available for free for any licensed copy of
            Windows 2000, XP (not including XP Home), or 2003. SFU
            can be downloaded from <a href=
            "http://www.microsoft.com/windows/sfu/" target=
            "_top">http://www.microsoft.com/windows/sfu/</a>.</p>

            <p>Services for Unix 3.5, current as of this writing,
            has been tested. 3.0 or 3.1 may work, but are not
            officially supported. (The main difference in 3.0/3.1
            is lack of pthreads.)</p>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "platform.interix-sfu-install"></a>3.2.3.1.&nbsp;When
                    installing Interix/SFU</h4>
                  </div>
                </div>
              </div>

              <p>At an absolute minimum, the following packages
              must be installed from the Windows Services for Unix
              3.5 distribution in order to use pkgsrc:</p>

              <div class="itemizedlist">
                <ul type="disc">
                  <li>
                    <p>Utilities -&gt; Base Utilities</p>
                  </li>

                  <li>
                    <p>Interix GNU Components -&gt; (all)</p>
                  </li>

                  <li>
                    <p>Remote Connectivity</p>
                  </li>

                  <li>
                    <p>Interix SDK</p>
                  </li>
                </ul>
              </div>

              <p>When using pkgsrc on Interix, DO NOT install the
              Utilities subcomponent "UNIX Perl". That is Perl 5.6
              without shared module support, installed to
              /usr/local, and will only cause confusion. Instead,
              install Perl 5.8 from pkgsrc (or from a binary
              package).</p>

              <p>The Remote Connectivity subcomponent "Windows
              Remote Shell Service" does not need to be installed,
              but Remote Connectivity itself should be installed in
              order to have a working inetd.</p>

              <p>During installation you may be asked whether to
              enable setuid behavior for Interix programs, and
              whether to make pathnames default to case-sensitive.
              Setuid should be enabled, and case-sensitivity MUST
              be enabled. (Without case-sensitivity, a large number
              of packages including perl will not build.)</p>

              <p>NOTE: Newer Windows service packs change the way
              binary execution works (via the Data Execution
              Prevention feature). In order to use pkgsrc and other
              gcc-compiled binaries reliably, a hotfix containing
              POSIX.EXE, PSXDLL.DLL, PSXRUN.EXE, and PSXSS.EXE
              (899522 or newer) must be installed. Hotfixes are
              available from Microsoft through a support contract;
              however, a NetBSD developer has made most Interix
              hotfixes available for personal use from <a href=
              "http://www.duh.org/interix/hotfixes.php" target=
              "_top">http://www.duh.org/interix/hotfixes.php</a>.</p>
            </div>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "platform.interix-sfu-postinstall"></a>3.2.3.2.&nbsp;What
                    to do if Interix/SFU is already installed</h4>
                  </div>
                </div>
              </div>

              <p>If SFU is already installed and you wish to alter
              these settings to work with pkgsrc, note the
              following things.</p>

              <div class="itemizedlist">
                <ul type="disc">
                  <li>
                    <p>To uninstall UNIX Perl, use Add/Remove
                    Programs, select Microsoft Windows Services for
                    UNIX, then click Change. In the installer,
                    choose Add or Remove, then uncheck
                    Utilities-&gt;UNIX Perl.</p>
                  </li>

                  <li>
                    <p>To enable case-sensitivity for the file
                    system, run REGEDIT.EXE, and change the
                    following registry key:</p>

                    <p>
                    HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session
                    Manager\kernel</p>

                    <p>Set the DWORD value "obcaseinsensitive" to
                    0; then reboot.</p>
                  </li>

                  <li>
                    <p>To enable setuid binaries (optional), run
                    REGEDIT.EXE, and change the following registry
                    key:</p>

                    <p>
                    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Services
                    for UNIX</p>

                    <p>Set the DWORD value "EnableSetuidBinaries"
                    to 1; then reboot.</p>
                  </li>
                </ul>
              </div>
            </div>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "platform.interix-notes"></a>3.2.3.3.&nbsp;Important
                    notes for using pkgsrc</h4>
                  </div>
                </div>
              </div>

              <p>The package manager (either the pkgsrc "su" user,
              or the user running "pkg_add") must be a member of
              the local Administrators group. Such a user must also
              be used to run the bootstrap. This is slightly
              relaxed from the normal pkgsrc requirement of
              "root".</p>

              <p>The package manager should use a umask of 002.
              "make install" will automatically complain if this is
              not the case. This ensures that directories written
              in /var/db/pkg are Administrators-group
              writeable.</p>

              <p>The popular Interix binary packages from
              http://www.interopsystems.com/ use an older version
              of pkgsrc's pkg_* tools. Ideally, these should NOT be
              used in conjunction with pkgsrc. If you choose to use
              them at the same time as the pkgsrc packages, ensure
              that you use the proper pkg_* tools for each type of
              binary package.</p>

              <p>The TERM setting used for DOS-type console windows
              (including those invoked by the csh and ksh startup
              shortcuts) is "interix". Most systems don't have a
              termcap/terminfo entry for it, but the following
              .termcap entry provides adequate emulation in most
              cases:</p>
              <pre class="programlisting">
    interix:kP=\E[S:kN=\E[T:kH=\E[U:dc@:DC@:tc=pcansi:
</pre>
            </div>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "platform.interix-limits"></a>3.2.3.4.&nbsp;Limitations
                    of the Interix platform</h4>
                  </div>
                </div>
              </div>

              <p>Though Interix suffices as a familiar and flexible
              substitute for a full Unix-like platform, it has some
              drawbacks that should be noted for those desiring to
              make the most of Interix.</p>

              <div class="itemizedlist">
                <ul type="disc">
                  <li>
                    <p><span class=
                    "strong"><strong>X11:</strong></span></p>

                    <p>Interix comes with the standard set of X11R6
                    client libraries, and can run X11 based
                    applications, but it does <span class=
                    "emphasis"><em>not</em></span> come with an X
                    server. Some options are <a href=
                    "http://www.starnet.com/products/xwin32/"
                    target="_top">StarNet X-Win32</a>, <a href=
                    "http://connectivity.hummingbird.com/products/nc/exceed/"
                    target="_top">Hummingbird Exceed</a> (available
                    in a trimmed version for Interix from Interop
                    Systems as the <a href=
                    "http://www.interopsystems.com/InteropXserver.htm"
                    target="_top">Interop X Server</a>), and the
                    free X11 server included with <a href=
                    "http://x.cygwin.com/" target=
                    "_top">Cygwin</a>.</p>

                    <p>Also, StarNet Communications has graciously
                    provided a free version of their X-Win32
                    product that accepts connections only from
                    localhost: <a href=
                    "http://www.starnet.com/xwin32LX/get_xwin32LX.htm"
                    target="_top">X-Win32 LX</a>, recommended by
                    the maintainer of Interix pkgsrc support.</p>
                  </li>

                  <li>
                    <p><span class="strong"><strong>X11
                    acceleration:</strong></span></p>

                    <p>Because Interix runs in a completely
                    different NT subsystem from Win32 applications,
                    it does not currently support various X11
                    protocol extensions for acceleration (such as
                    MIT-SHM or DGA). Most interactive applications
                    to a local X server will run reasonably fast,
                    but full motion video and other graphics
                    intensive applications may require a
                    faster-than-expected CPU.</p>
                  </li>

                  <li>
                    <p><span class=
                    "strong"><strong>Audio:</strong></span></p>

                    <p>Interix has no native support for audio
                    output. For audio support, pkgsrc uses the
                    <span><strong class=
                    "command">esound</strong></span> client/server
                    audio system on Interix. Unlike on most
                    platforms, the <a xmlns=
                    "http://www.w3.org/TR/xhtml1/transitional"
                    href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/audio/esound/README.html"
                    target="_top"><code xmlns="" class=
                    "filename">audio/esound</code></a> package does
                    <span class="emphasis"><em>not</em></span>
                    contain the <span><strong class=
                    "command">esd</strong></span> server component.
                    To output audio via an Interix host, the
                    <a xmlns=
                    "http://www.w3.org/TR/xhtml1/transitional"
                    href="ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/emulators/cygwin_esound/README.html"
                    target="_top"><code xmlns="" class=
                    "filename">emulators/cygwin_esound</code></a>
                    package must also be installed.</p>
                  </li>

                  <li>
                    <p><span class="strong"><strong>CD/DVDs, USB,
                    and SCSI:</strong></span></p>

                    <p>Direct device access is not currently
                    supported in Interix, so it is not currently
                    possible to access CD/DVD drives, USB devices,
                    or SCSI devices through non-filesystem means.
                    Among other things, this makes it impossible to
                    use Interix directly for CD/DVD burning.</p>
                  </li>

                  <li>
                    <p><span class="strong"><strong>Tape
                    drives:</strong></span></p>

                    <p>Due to the same limitations as for CD-ROMs
                    and SCSI devices, tape drives are also not
                    directly accessible in Interix. However,
                    support is in work to make tape drive access
                    possible by using Cygwin as a bridge (similarly
                    to audio bridged via Cygwin's esound
                    server).</p>
                  </li>
                </ul>
              </div>
            </div>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "platform.interix-knownissues"></a>3.2.3.5.&nbsp;Known
                    issues for pkgsrc on Interix</h4>
                  </div>
                </div>
              </div>

              <p>It is not necessary, in general, to have a "root"
              user on the Windows system; any member of the local
              Administrators group will suffice. However, some
              packages currently assume that the user named "root"
              is the privileged user. To accommodate these, you may
              create such a user; make sure it is in the local
              group Administrators (or your language
              equivalent).</p>

              <p>"pkg_add" creates directories of mode 0755, not
              0775, in $PKG_DBDIR. For the time being, install
              packages as the local Administrator (or your language
              equivalent), or run the following command after
              installing a package to work around the issue:</p>
              <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>chmod -R g+w $PKG_DBDIR</code></strong>
</pre>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "irix"></a>3.2.4.&nbsp;IRIX</h3>
                </div>
              </div>
            </div>

            <p>You will need a working C compiler, either gcc or
            SGI's MIPS and MIPSpro compiler (cc/c89). Please set
            the <code class="varname">CC</code> environment
            variable according to your preference. If you do not
            have a license for the MIPSpro compiler suite, you can
            download a gcc tardist file from <a href=
            "http://freeware.sgi.com/" target=
            "_top">http://freeware.sgi.com/</a>.</p>

            <p>Please note that you will need IRIX 6.5.17 or
            higher, as this is the earliest version of IRIX
            providing support for <a href=
            "http://netbsd.gw.com/cgi-bin/man-cgi?if_indextoname+3+NetBSD-current">
            <span class="citerefentry"><span class=
            "refentrytitle">if_indextoname</span>(3)</span></a>,
            <a href=
            "http://netbsd.gw.com/cgi-bin/man-cgi?if_nametoindex+3+NetBSD-current">
            <span class="citerefentry"><span class=
            "refentrytitle">if_nametoindex</span>(3)</span></a>,
            etc.</p>

            <p>At this point in time, pkgsrc only supports one ABI
            at a time. That is, you can not switch between the old
            32-bit ABI, the new 32-bit ABI and the 64-bit ABI. If
            you start out using "abi=n32", that's what all your
            packages will be built with.</p>

            <p>Therefore, please make sure that you have no
            conflicting <code class="varname">CFLAGS</code> in your
            environment or the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/etc/mk.conf</code>. Particularly, make sure
            that you do not try to link n32 object files with lib64
            or vice versa. Check your <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/etc/compiler.defaults</code>!</p>

            <p>If you have the actual pkgsrc tree mounted via NFS
            from a different host, please make sure to set
            <code class="varname">WRKOBJDIR</code> to a local
            directory, as it appears that IRIX linker occasionally
            runs into issues when trying to link over a
            network-mounted file system.</p>

            <p>The bootstrapping process should set all the right
            options for programs such as imake(1), but you may want
            to set some options depending on your local setup.
            Please see <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">pkgsrc/mk/defaults/mk.conf</code> and, of
            course, your compiler's man pages for details.</p>

            <p>If you are using SGI's MIPSPro compiler, please
            set</p>
            <pre class="programlisting">
    PKGSRC_COMPILER=        mipspro
</pre>

            <p>in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/etc/mk.conf</code>. Otherwise, pkgsrc will
            assume you are using gcc and may end up passing invalid
            flags to the compiler. Note that bootstrap should
            create an appropriate <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">mk.conf.example</code> by default.</p>

            <p>If you have both the MIPSPro compiler chain
            installed as well as gcc, but want to make sure that
            MIPRPro is used, please set your <code class=
            "varname">PATH</code> to <span class=
            "emphasis"><em>not</em></span> include the location of
            gcc (often <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/usr/freeware/bin</code>), and (important)
            pass the '--preserve-path' flag.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "linux"></a>3.2.5.&nbsp;Linux</h3>
                </div>
              </div>
            </div>

            <p>Some versions of Linux (for example Debian
            GNU/Linux) need either libtermcap or libcurses
            (libncurses). Installing the distributions
            libncurses-dev package (or equivalent) should fix the
            problem.</p>

            <p>pkgsrc supports both gcc (GNU Compiler Collection)
            and icc (Intel C++ Compiler). gcc is the default. icc
            8.0 and 8.1 on i386 have been tested.</p>

            <p>To bootstrap using icc, assuming the default icc
            installation directory:</p>
            <pre class="programlisting">
    env CC=/opt/intel_cc_80/bin/icc LDFLAGS=-static-libcxa \
            ac_cv___attribute__=yes ./bootstrap
</pre>

            <div class="note" style=
            "margin-left: 0.5in; margin-right: 0.5in;">
              <h3 class="title">Note</h3>

              <p>icc 8.1 needs the `-i-static' argument instead of
              -static-libcxa.</p>
            </div>

            <p>icc supports __attribute__, but the GNU configure
            test uses a nested function, which icc does not
            support. #undef'ing __attribute__ has the unfortunate
            side-effect of breaking many of the Linux header files,
            which cannot be compiled properly without
            __attribute__. The test must be overridden so that
            __attribute__ is assumed supported by the compiler.</p>

            <p>After bootstrapping, you should set <code class=
            "varname">PKGSRC_COMPILER</code> in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/etc/mk.conf</code>:</p>
            <pre class="programlisting">
    PKGSRC_COMPILER=        icc
</pre>

            <p>The default installation directory for icc is
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">/opt/intel_cc_80</code>, which is also
            the pkgsrc default. If you have installed it into a
            different directory, set <code class=
            "varname">ICCBASE</code> in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/etc/mk.conf</code>:</p>
            <pre class="programlisting">
    ICCBASE=                /opt/icc
</pre>

            <p>pkgsrc uses the static linking method of the runtime
            libraries provided by icc, so binaries can be run on
            other systems which do not have the shared libraries
            installed.</p>

            <p>Libtool, however, extracts a list of libraries from
            the <a href=
            "http://netbsd.gw.com/cgi-bin/man-cgi?ld+1+NetBSD-current">
            <span class="citerefentry"><span class=
            "refentrytitle">ld</span>(1)</span></a> command run
            when linking a C++ shared library and records it,
            throwing away the -Bstatic and -Bdynamic options
            interspersed between the libraries. This means that
            libtool-linked C++ shared libraries will have a runtime
            dependency on the icc libraries until this is fixed in
            libtool.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "openbsd"></a>3.2.6.&nbsp;OpenBSD</h3>
                </div>
              </div>
            </div>

            <p>OpenBSD 3.0 and 3.2 are tested and supported.</p>

            <p>Care should be taken so that the tools that this kit
            installs do not conflict with the OpenBSD userland
            tools. There are several steps:</p>

            <div class="orderedlist">
              <ol type="1">
                <li>
                  <p>OpenBSD stores its ports pkg database in
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/var/db/pkg</code>. It is therefore
                  recommended that you choose a different location
                  (e.g. <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/usr/pkgdb</code>) by using the
                  --pkgdbdir option to the bootstrap script.</p>
                </li>

                <li>
                  <p>If you do not intend to use the OpenBSD ports
                  tools, it's probably a good idea to move them out
                  of the way to avoid confusion, e.g.</p>
                  <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>cd /usr/sbin</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>mv pkg_add pkg_add.orig</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>mv pkg_create pkg_create.orig</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>mv pkg_delete pkg_delete.orig</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>mv pkg_info pkg_info.orig</code></strong>
</pre>
                </li>

                <li>
                  <p>An example <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/etc/mk.conf</code> file will be
                  placed in <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/etc/mk.conf.example</code> file when
                  you use the bootstrap script. OpenBSD's make
                  program uses <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/etc/mk.conf</code> as well. You can
                  work around this by enclosing all the
                  pkgsrc-specific parts of the file with:</p>
                  <pre class="programlisting">
    .ifdef BSD_PKG_MK
    # pkgsrc stuff, e.g. insert defaults/mk.conf or similar here
    .else
    # OpenBSD stuff
    .endif
</pre>
                </li>
              </ol>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "solaris"></a>3.2.7.&nbsp;Solaris</h3>
                </div>
              </div>
            </div>

            <p>Solaris 2.6 through 9 are supported on both x86 and
            sparc. You will need a working C compiler. Both gcc
            2.95.3 and Sun WorkShop 5 have been tested.</p>

            <p>The following packages are required on Solaris 8 for
            the bootstrap process and to build packages.</p>

            <div class="itemizedlist">
              <ul type="disc">
                <li>
                  <p>SUNWsprot</p>
                </li>

                <li>
                  <p>SUNWarc</p>
                </li>

                <li>
                  <p>SUNWbtool</p>
                </li>

                <li>
                  <p>SUNWtoo</p>
                </li>

                <li>
                  <p>SUNWlibm</p>
                </li>
              </ul>
            </div>

            <p>Please note the use of GNU binutils on Solaris is
            <span class="emphasis"><em>not</em></span>
            supported.</p>

            <p>Whichever compiler you use, please ensure the
            compiler tools and your $prefix are in your
            <code class="varname">PATH</code>. This includes
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">/usr/ccs/{bin,lib}</code> and e.g.
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">/usr/pkg/{bin,sbin}</code>.</p>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "solaris-gcc-note"></a>3.2.7.1.&nbsp;If you are
                    using gcc</h4>
                  </div>
                </div>
              </div>

              <p>It makes life much simpler if you only use the
              same gcc consistently for building all packages.</p>

              <p>It is recommended that an external gcc be used
              only for bootstrapping, then either build gcc from
              <a xmlns="http://www.w3.org/TR/xhtml1/transitional"
              href=
              "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/lang/gcc/README.html"
              target="_top"><code xmlns="" class=
              "filename">lang/gcc</code></a> or install a binary
              gcc package, then remove gcc used during
              bootstrapping.</p>

              <p>Binary packages of gcc can be found through
              <a href=
              "http://www.sun.com/bigadmin/common/freewareSearch.html"
              target=
              "_top">http://www.sun.com/bigadmin/common/freewareSearch.html</a>.</p>
            </div>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "solaris-sun-workshop-note"></a>3.2.7.2.&nbsp;If
                    you are using Sun WorkShop</h4>
                  </div>
                </div>
              </div>

              <p>You will need at least the following packages
              installed (from WorkShop 5.0)</p>

              <div class="itemizedlist">
                <ul type="disc">
                  <li>
                    <p>SPROcc - Sun WorkShop Compiler C 5.0</p>
                  </li>

                  <li>
                    <p>SPROcpl - Sun WorkShop Compiler C++ 5.0</p>
                  </li>

                  <li>
                    <p>SPROild - Sun WorkShop Incremental
                    Linker</p>
                  </li>

                  <li>
                    <p>SPROlang - Sun WorkShop Compilers common
                    components</p>
                  </li>
                </ul>
              </div>

              <p>You should set <code class="varname">CC</code>,
              <code class="varname">CXX</code> and optionally,
              <code class="varname">CPP</code> in <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">/etc/mk.conf</code>, e.g.:</p>
              <pre class="programlisting">
    CC=     cc
    CXX=    CC
    CPP=    /usr/ccs/lib/cpp
</pre>
            </div>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "solaris-sunpro-64"></a>3.2.7.3.&nbsp;Buildling
                    64-bit binaries with SunPro</h4>
                  </div>
                </div>
              </div>

              <p>Building 64-bit binaries is a little trickier.
              First, you need to bootstrap pkgsrc in 64-bit mode.
              One problem here is that while building one of the
              programs in the bootstrap kit (<code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">bmake</code>), the <code class=
              "varname">CFLAGS</code> variable is not honored, even
              if it is set in the environment. To work around this
              bug, you can create a simple shell script called
              <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">cc64</code> and put it somewhere in the
              <code class="varname">PATH</code>:</p>
              <pre class="programlisting">
    #! /bin/sh
    exec /opt/SUNWspro/bin/cc -xtarget=ultra -xarch=v9 ${1+"$@"}
</pre>

              <p>Then, pass the definition for <code class=
              "varname">CC</code> in the environment of the
              <span><strong class=
              "command">bootstrap</strong></span> command:</p>
              <pre class="programlisting">
    <code class="prompt">$</code> <strong class=
"userinput"><code>cd bootstrap</code></strong>
    <code class="prompt">$</code> <strong class=
"userinput"><code>CC=cc64 ./bootstrap</code></strong>
</pre>

              <p>After bootstrapping, there are two alternative
              ways, depending on whether you want to find bugs in
              packages or get your system ready quickly. If you
              just want a running system, add the following lines
              to your <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">mk.conf</code> file:</p>
              <pre class="programlisting">
    CC=                     cc64
    CXX=                    CC64
    PKGSRC_COMPILER=        sunpro
</pre>

              <p>This way, all calls to the compiler will be
              intercepted by the above wrapper and therefore get
              the necessary ABI options automatically. (Don't
              forget to create the shell script <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">CC64</code>, too.)</p>

              <p>To find packages that ignore the user-specified
              <code class="varname">CFLAGS</code> and <code class=
              "varname">CXXFLAGS</code>, add the following lines to
              your <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">mk.conf</code> file:</p>
              <pre class="programlisting">
    CC=                     cc
    CXX=                    CC
    PKGSRC_COMPILER=        sunpro
    CFLAGS=                 -xtarget=ultra -xarch=v9
    CXXFLAGS=               -xtarget=ultra -xarch=v9
    LDFLAGS=                -xtarget=ultra -xarch=v9
</pre>

              <p>Packages that don't use the flags provided in the
              configuration file will try to build 32-bit binaries
              and fail during linking. Detecting this is useful to
              prevent bugs on other platforms where the error would
              not show up but pass silently.</p>
            </div>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "plat.sunos.problems"></a>3.2.7.4.&nbsp;Common
                    problems</h4>
                  </div>
                </div>
              </div>

              <p>Sometimes, when using <span><strong class=
              "command">libtool</strong></span>, <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">/bin/ksh</code> crashes with a
              segmentation fault. The workaround is to use another
              shell for the configure scripts, for example by
              installing <a xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" href=
              "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/shells/bash/README.html"
              target="_top"><code xmlns="" class=
              "filename">shells/bash</code></a> and adding the
              following lines to your <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">mk.conf</code>:</p>
              <pre class="programlisting">
    CONFIG_SHELL=   ${LOCALBASE}/bin/bash
    WRAPPER_SHELL=  ${LOCALBASE}/bin/bash
</pre>

              <p>Then, rebuild the <a xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" href=
              "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/libtool-base/README.html"
              target="_top"><code xmlns="" class=
              "filename">devel/libtool-base</code></a> package.</p>
            </div>
          </div>
        </div>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "using"></a>Chapter&nbsp;4.&nbsp;Using pkgsrc</h2>
            </div>
          </div>
        </div>

        <div class="toc">
          <p><b>Table of Contents</b></p>

          <dl>
            <dt><span class="sect1"><a href="#using-pkg">4.1. Using
            binary packages</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#finding-binary-packages">4.1.1. Finding binary
                packages</a></span></dt>

                <dt><span class="sect2"><a href=
                "#installing-binary-packages">4.1.2. Installing
                binary packages</a></span></dt>

                <dt><span class="sect2"><a href=
                "#a-word-of-warning">4.1.3. A word of
                warning</a></span></dt>
              </dl>
            </dd>

            <dt><span class="sect1"><a href=
            "#building-packages-from-source">4.2. Building packages
            from source</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#requirements">4.2.1. Requirements</a></span></dt>

                <dt><span class="sect2"><a href=
                "#fetching-distfiles">4.2.2. Fetching
                distfiles</a></span></dt>

                <dt><span class="sect2"><a href=
                "#how-to-build-and-install">4.2.3. How to build and
                install</a></span></dt>

                <dt><span class="sect2"><a href=
                "#selecting-the-compiler">4.2.4. Selecting the
                compiler</a></span></dt>
              </dl>
            </dd>
          </dl>
        </div>

        <p>Basically, there are two ways of using pkgsrc. The first
        is to only install the package tools and to use binary
        packages that someone else has prepared. This is the
        &#8220;<span class="quote">pkg</span>&#8221; in pkgsrc. The
        second way is to install the &#8220;<span class=
        "quote">src</span>&#8221; of pkgsrc, too. Then you are able
        to build your own packages, and you can still use binary
        packages from someone else.</p>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "using-pkg"></a>4.1.&nbsp;Using binary
                packages</h2>
              </div>
            </div>
          </div>

          <p>To use binary packages, you need some tools to manage
          them. On NetBSD, these tools are already installed. On
          all other operating systems, you need to install them
          first. For the following platforms, prebuilt versions of
          the package tools are available and can simply be
          downloaded and unpacked in the <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/</code> directory:</p>

          <div class="informaltable">
            <a name="binary-bootstrap-kits"></a>

            <table border="1">
              <colgroup>
                <col />
                <col />
              </colgroup>

              <thead>
                <tr>
                  <th>Platform</th>

                  <th>URL</th>
                </tr>
              </thead>

              <tbody>
                <tr>
                  <td>Solaris 5.10</td>

                  <td><code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">http://public.enst.fr/pkgsrc/packages/bootstrap-pkgsrc/</code></td>
                </tr>
              </tbody>
            </table>
          </div>

          <p>These prebuilt package tools use <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/usr/pkg</code> for the base directory, and
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">/var/db/pkg</code> for the database of
          installed packages. If you cannot use these directories
          for whatever reasons (maybe because you're not root), you
          have to build the package tools yourself, which is
          explained in <a href="#bootstrapping-pkgsrc" title=
          "3.1.&nbsp;Bootstrapping pkgsrc">Section&nbsp;3.1,
          &#8220;Bootstrapping pkgsrc&#8221;</a>.</p>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "finding-binary-packages"></a>4.1.1.&nbsp;Finding
                  binary packages</h3>
                </div>
              </div>
            </div>

            <p>To install binary packages, you first need to know
            from where to get them. You can get them on CD-ROMs,
            DVDs, or via FTP or HTTP.</p>

            <p>For NetBSD, the binary packages are made available
            on <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">ftp.NetBSD.org</code> and its mirrors, in
            the directory <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/pub/NetBSD/packages/<em class=
            "replaceable"><code>OSVERSION</code></em>/<em class=
            "replaceable"><code>ARCH</code></em>/</code>. For
            <em class="replaceable"><code>OSVERSION</code></em>,
            you should insert the output of <span><strong class=
            "command">uname -r</strong></span>, and for <em class=
            "replaceable"><code>ARCH</code></em> the output of
            <span><strong class="command">uname
            -p</strong></span>.</p>

            <p>For some other platforms, binary packages can be
            found at the following locations:</p>

            <div class="informaltable">
              <a name="binary-packages"></a>

              <table border="1">
                <colgroup>
                  <col />
                  <col />
                </colgroup>

                <thead>
                  <tr>
                    <th>Platform</th>

                    <th>URL</th>
                  </tr>
                </thead>

                <tbody>
                  <tr>
                    <td>Solaris 5.10</td>

                    <td><code xmlns=
                    "http://www.w3.org/TR/xhtml1/transitional"
                    class=
                    "filename">http://public.enst.fr/pkgsrc/packages/</code></td>
                  </tr>
                </tbody>
              </table>
            </div>

            <p>In each of these directories, there is a
            subdirectory <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">All</code> that contains all the binary
            packages. Further, there are subdirectories for
            categories that contain symbolic links that point to
            the actual binary package in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">../All</code>. This directory layout is used
            for all package repositories, no matter if they are
            accessed via HTTP, FTP, NFS, CD-ROM, or the local
            filesystem.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "installing-binary-packages"></a>4.1.2.&nbsp;Installing
                  binary packages</h3>
                </div>
              </div>
            </div>

            <p>If you have the files on a CD-ROM or downloaded them
            to your hard disk, you can install them with the
            following command (be sure to <span><strong class=
            "command">su</strong></span> to root first):</p>
            <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>pkg_add /path/to/package.tgz</code></strong>
</pre>

            <p>If you have FTP access and you don't want to
            download the packages via FTP prior to installation,
            you can do this automatically by giving
            <span><strong class="command">pkg_add</strong></span>
            an FTP URL:</p>
            <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>pkg_add ftp://ftp.NetBSD.org/pub/NetBSD/packages/&lt;OSVERSION&gt;/&lt;ARCH&gt;/All/package.tgz</code></strong>
</pre>

            <p>Note that any prerequisite packages needed to run
            the package in question will be installed, too,
            assuming they are present where you install from.</p>

            <p>To save some typing, you can set the <code class=
            "varname">PKG_PATH</code> environment variable to a
            semicolon-separated list of paths (including remote
            URLs); trailing slashes are not allowed.</p>

            <p>Additionally to the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">All</code> directory there exists a
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">vulnerable</code> directory to which
            binary packages with known vulnerabilities are moved,
            since removing them could cause missing dependencies.
            To use these packages, add the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">vulnerable</code> directory to your
            <code class="varname">PKG_PATH</code>. However, you
            should run <a xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" href=
            "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/audit-packages/README.html"
            target="_top"><code xmlns="" class=
            "filename">security/audit-packages</code></a>
            regularly, especially after installing new packages,
            and verify that the vulnerabilities are acceptable for
            your configuration. An example <code class=
            "varname">PKG_PATH</code> would be: <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">ftp://ftp.NetBSD.org/pub/NetBSD/packages/&lt;OSVERSION&gt;/&lt;ARCH&gt;/All;ftp://ftp.NetBSD.org/pub/NetBSD/packages/&lt;OSVERSION&gt;/&lt;ARCH&gt;/vulnerable</code>
            Please note that semicolon (';') is a shell
            meta-character, so you'll probably have to quote
            it.</p>

            <p>After you've installed packages, be sure to have
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">/usr/pkg/bin</code> and <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/usr/pkg/sbin</code> in your <code class=
            "varname">PATH</code> so you can actually start the
            just installed program.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "a-word-of-warning"></a>4.1.3.&nbsp;A word of
                  warning</h3>
                </div>
              </div>
            </div>

            <p>Please pay very careful attention to the warnings
            expressed in the <a href=
            "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
            <span class="citerefentry"><span class=
            "refentrytitle">pkg_add</span>(1)</span></a> manual
            page about the inherent dangers of installing binary
            packages which you did not create yourself, and the
            security holes that can be introduced onto your system
            by indiscriminate adding of such files.</p>

            <p>The same warning of course applies to every package
            you install from source when you haven't completely
            read and understood the source code of the package, the
            compiler that is used to build the package and all the
            other tools that are involved.</p>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "building-packages-from-source"></a>4.2.&nbsp;Building
                packages from source</h2>
              </div>
            </div>
          </div>

          <p>This assumes that the package is already in pkgsrc. If
          it is not, see <a href="#developers-guide" title=
          "Part&nbsp;II.&nbsp;The pkgsrc developer's guide">Part&nbsp;II,
          &#8220;The pkgsrc developer's guide&#8221;</a> for
          instructions how to create your own packages.</p>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "requirements"></a>4.2.1.&nbsp;Requirements</h3>
                </div>
              </div>
            </div>

            <p>To build packages from source on a NetBSD system the
            &#8220;<span class="quote">comp</span>&#8221; and the
            &#8220;<span class="quote">text</span>&#8221;
            distribution sets must be installed. If you want to
            build X11-related packages the &#8220;<span class=
            "quote">xbase</span>&#8221; and &#8220;<span class=
            "quote">xcomp</span>&#8221; distribution sets are
            required, too.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "fetching-distfiles"></a>4.2.2.&nbsp;Fetching
                  distfiles</h3>
                </div>
              </div>
            </div>

            <p>The first step for building a package is downloading
            the distfiles (i.e. the unmodified source). If they
            have not yet been downloaded, pkgsrc will fetch them
            automatically.</p>

            <p>You can overwrite some of the major distribution
            sites to fit to sites that are close to your own. Have
            a look at <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">pkgsrc/mk/defaults/mk.conf</code> to find
            some examples &#8212; in particular, look for the
            <code class="varname">MASTER_SORT</code>, <code class=
            "varname">MASTER_SORT_REGEX</code> and <code class=
            "varname">INET_COUNTRY</code> definitions. This may
            save some of your bandwidth and time.</p>

            <p>You can change these settings either in your shell's
            environment, or, if you want to keep the settings, by
            editing the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/etc/mk.conf</code> file, and adding the
            definitions there.</p>

            <p>If you don't have a permanent Internet connection
            and you want to know which files to download,
            <span><strong class="command">make
            fetch-list</strong></span> will tell you what you'll
            need. Put these distfiles into <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/usr/pkgsrc/distfiles</code>.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "how-to-build-and-install"></a>4.2.3.&nbsp;How to
                  build and install</h3>
                </div>
              </div>
            </div>

            <p>Assuming that the distfile has been fetched (see
            previous section), become root and change into the
            relevant directory and run <span><strong class=
            "command">make</strong></span>.</p>

            <div class="note" style=
            "margin-left: 0.5in; margin-right: 0.5in;">
              <h3 class="title">Note</h3>

              <p>If using bootstrap or pkgsrc on a non-NetBSD
              system, use the pkgsrc <span><strong class=
              "command">bmake</strong></span> command instead of
              &#8220;<span class="quote">make</span>&#8221; in the
              examples in this guide.</p>
            </div>

            <p>For example, type</p>
            <pre class="screen">
<code class="prompt">%</code> <strong class=
"userinput"><code>cd misc/figlet</code></strong>
<code class="prompt">%</code> <strong class=
"userinput"><code>make</code></strong>
</pre>

            <p>at the shell prompt to build the various components
            of the package, and</p>
            <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>make install</code></strong>
</pre>

            <p>to install the various components into the correct
            places on your system. Installing the package on your
            system requires you to be root. However, pkgsrc has a
            <span class="emphasis"><em>just-in-time-su</em></span>
            feature, which allows you to only become root for the
            actual installation step</p>

            <p>Taking the figlet utility as an example, we can
            install it on our system by building as shown in
            <a href="#logs" title=
            "Appendix&nbsp;B.&nbsp;Build logs">Appendix&nbsp;B,
            <i>Build logs</i></a>.</p>

            <p>The program is installed under the default root of
            the packages tree - <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/usr/pkg</code>. Should this not conform to
            your tastes, set the <code class=
            "varname">LOCALBASE</code> variable in your
            environment, and it will use that value as the root of
            your packages tree. So, to use <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/usr/local</code>, set <code class=
            "varname">LOCALBASE=/usr/local</code> in your
            environment. Please note that you should use a
            directory which is dedicated to packages and not shared
            with other programs (i.e., do not try and use
            <code class="varname">LOCALBASE=/usr</code>). Also, you
            should not try to add any of your own files or
            directories (such as <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">src/</code>, <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">obj/</code>, or <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">pkgsrc/</code>) below the <code class=
            "varname">LOCALBASE</code> tree. This is to prevent
            possible conflicts between programs and other files
            installed by the package system and whatever else may
            have been installed there.</p>

            <p>Some packages look in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/etc/mk.conf</code> to alter some
            configuration options at build time. Have a look at
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">pkgsrc/mk/defaults/mk.conf</code> to
            get an overview of what will be set there by default.
            Environment variables such as <code class=
            "varname">LOCALBASE</code> can be set in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/etc/mk.conf</code> to save having to
            remember to set them each time you want to use
            pkgsrc.</p>

            <p>Occasionally, people want to &#8220;<span class=
            "quote">look under the covers</span>&#8221; to see what
            is going on when a package is building or being
            installed. This may be for debugging purposes, or out
            of simple curiosity. A number of utility values have
            been added to help with this.</p>

            <div class="orderedlist">
              <ol type="1">
                <li>
                  <p>If you invoke the <a href=
                  "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
                  <span class="citerefentry"><span class=
                  "refentrytitle">make</span>(1)</span></a> command
                  with <code class=
                  "varname">PKG_DEBUG_LEVEL=2</code>, then a huge
                  amount of information will be displayed. For
                  example,</p>
                  <pre class="screen">
<strong class=
"userinput"><code>make patch PKG_DEBUG_LEVEL=2</code></strong>
</pre>

                  <p>will show all the commands that are invoked,
                  up to and including the &#8220;<span class=
                  "quote">patch</span>&#8221; stage.</p>
                </li>

                <li>
                  <p>If you want to know the value of a certain
                  <a href=
                  "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
                  <span class="citerefentry"><span class=
                  "refentrytitle">make</span>(1)</span></a>
                  definition, then the <code class=
                  "varname">VARNAME</code> definition should be
                  used, in conjunction with the show-var target.
                  e.g. to show the expansion of the <a href=
                  "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
                  <span class="citerefentry"><span class=
                  "refentrytitle">make</span>(1)</span></a>
                  variable <code class=
                  "varname">LOCALBASE</code>:</p>
                  <pre class="screen">
<code class="prompt">%</code> <strong class=
"userinput"><code>make show-var VARNAME=LOCALBASE</code></strong>
/usr/pkg
<code class="prompt">%</code>
          
</pre>
                </li>
              </ol>
            </div>

            <p>If you want to install a binary package that you've
            either created yourself (see next section), that you
            put into pkgsrc/packages manually or that is located on
            a remote FTP server, you can use the "bin-install"
            target. This target will install a binary package - if
            available - via <a href=
            "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
            <span class="citerefentry"><span class=
            "refentrytitle">pkg_add</span>(1)</span></a>, else do a
            <span><strong class="command">make
            package</strong></span>. The list of remote FTP sites
            searched is kept in the variable <code class=
            "varname">BINPKG_SITES</code>, which defaults to
            ftp.NetBSD.org. Any flags that should be added to
            <a href=
            "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
            <span class="citerefentry"><span class=
            "refentrytitle">pkg_add</span>(1)</span></a> can be put
            into <code class="varname">BIN_INSTALL_FLAGS</code>.
            See <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">pkgsrc/mk/defaults/mk.conf</code> for more
            details.</p>

            <p>A final word of warning: If you set up a system that
            has a non-standard setting for <code class=
            "varname">LOCALBASE</code>, be sure to set that before
            any packages are installed, as you can not use several
            directories for the same purpose. Doing so will result
            in pkgsrc not being able to properly detect your
            installed packages, and fail miserably. Note also that
            precompiled binary packages are usually built with the
            default <code class="varname">LOCALBASE</code> of
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">/usr/pkg</code>, and that you should
            <span class="emphasis"><em>not</em></span> install any
            if you use a non-standard <code class=
            "varname">LOCALBASE</code>.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "selecting-the-compiler"></a>4.2.4.&nbsp;Selecting
                  the compiler</h3>
                </div>
              </div>
            </div>

            <p>By default, pkgsrc will use GCC to build packages.
            This may be overridden by setting the following
            variables in /etc/mk.conf:</p>

            <div class="variablelist">
              <dl>
                <dt><span class="term"><code class=
                "varname">PKGSRC_COMPILER</code>:</span></dt>

                <dd>
                  <p>This is a list of values specifying the chain
                  of compilers to invoke when building packages.
                  Valid values are:</p>

                  <div class="itemizedlist">
                    <ul type="disc">
                      <li>
                        <p><code class="varname">distcc</code>:
                        distributed C/C++ (chainable)</p>
                      </li>

                      <li>
                        <p><code class="varname">ccache</code>:
                        compiler cache (chainable)</p>
                      </li>

                      <li>
                        <p><code class="varname">gcc</code>: GNU
                        C/C++ Compiler</p>
                      </li>

                      <li>
                        <p><code class="varname">mipspro</code>:
                        Silicon Graphics, Inc. MIPSpro
                        (n32/n64)</p>
                      </li>

                      <li>
                        <p><code class="varname">mipspro</code>:
                        Silicon Graphics, Inc. MIPSpro (o32)</p>
                      </li>

                      <li>
                        <p><code class="varname">sunpro</code>: Sun
                        Microsystems, Inc. WorkShip/Forte/Sun ONE
                        Studio</p>
                      </li>
                    </ul>
                  </div>

                  <p>The default is &#8220;<span class=
                  "quote"><code class=
                  "varname">gcc</code></span>&#8221;. You can use
                  <code class="varname">ccache</code> and/or
                  <code class="varname">distcc</code> with an
                  appropriate <code class=
                  "varname">PKGSRC_COMPILER</code> setting, e.g.
                  &#8220;<span class="quote"><code class=
                  "varname">ccache gcc</code></span>&#8221;. This
                  variable should always be terminated with a value
                  for a real compiler.</p>
                </dd>

                <dt><span class="term"><code class=
                "varname">GCC_REQD</code>:</span></dt>

                <dd>
                  <p>This specifies the minimum version of GCC to
                  use when building packages. If the system GCC
                  doesn't satisfy this requirement, then pkgsrc
                  will build and install one of the GCC packages to
                  use instead.</p>
                </dd>
              </dl>
            </div>
          </div>
        </div>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "configuring"></a>Chapter&nbsp;5.&nbsp;Configuring
              pkgsrc</h2>
            </div>
          </div>
        </div>

        <div class="toc">
          <p><b>Table of Contents</b></p>

          <dl>
            <dt><span class="sect1"><a href=
            "#general-configuration">5.1. General
            configuration</a></span></dt>

            <dt><span class="sect1"><a href=
            "#variables-affecting-build">5.2. Variables affecting
            the build process</a></span></dt>

            <dt><span class="sect1"><a href=
            "#developer-advanced-settings">5.3. Developer/advanced
            settings</a></span></dt>

            <dt><span class="sect1"><a href=
            "#selecting-build-options">5.4. Selecting Build
            Options</a></span></dt>
          </dl>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "general-configuration"></a>5.1.&nbsp;General
                configuration</h2>
              </div>
            </div>
          </div>

          <p>In this section, you can find some variables that
          apply to all pkgsrc packages. The preferred method of
          setting these variables is by setting them in
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">/etc/mk.conf</code>.</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><code class="varname">LOCALBASE</code>: Where
                packages will be installed. The default is
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">/usr/pkg</code>. Do not mix binary
                packages with different <code class=
                "varname">LOCALBASE</code>s!</p>
              </li>

              <li>
                <p><code class="varname">CROSSBASE</code>: Where
                &#8220;<span class="quote">cross</span>&#8221;
                category packages will be installed. The default is
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${LOCALBASE}/cross</code>.</p>
              </li>

              <li>
                <p><code class="varname">X11BASE</code>: Where X11
                is installed on the system. The default is
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">/usr/X11R6</code>.</p>
              </li>

              <li>
                <p><code class="varname">DISTDIR</code>: Where to
                store the downloaded copies of the original source
                distributions used for building pkgsrc packages.
                The default is <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${PKGSRCDIR}/distfiles</code>.</p>
              </li>

              <li>
                <p><code class=
                "varname">MASTER_SITE_OVERRIDE</code>: If set,
                override the packages' <code class=
                "varname">MASTER_SITES</code> with this value.</p>
              </li>

              <li>
                <p><code class="varname">MASTER_SITE_BACKUP</code>:
                Backup location(s) for distribution files and patch
                files if not found locally or in <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${MASTER_SITES}</code> or <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${PATCH_SITES}</code> respectively. The
                defaults are <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/${DIST_SUBDIR}/</code>
                and <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/</code>.</p>
              </li>

              <li>
                <p><code class="varname">BINPKG_SITES</code>: List
                of sites carrying binary pkgs.</p>
              </li>
            </ul>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "variables-affecting-build"></a>5.2.&nbsp;Variables
                affecting the build process</h2>
              </div>
            </div>
          </div>

          <p>XXX</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><code class="varname">PACKAGES</code>: The top
                level directory for the binary packages. The
                default is <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${PKGSRCDIR}/packages</code>.</p>
              </li>

              <li>
                <p><code class="varname">WRKOBJDIR</code>: The top
                level directory where, if defined, the separate
                working directories will get created, and
                symbolically linked to from <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${WRKDIR}</code> (see below). This is
                useful for building packages on several
                architectures, then <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${PKGSRCDIR}</code> can be NFS-mounted
                while <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${WRKOBJDIR}</code> is local to every
                architecture. (It should be noted that <code class=
                "varname">PKGSRCDIR</code> should not be set by the
                user &#8212; it is an internal definition which
                refers to the root of the pkgsrc tree. It is
                possible to have many pkgsrc tree instances.)</p>
              </li>

              <li>
                <p><code class="varname">LOCALPATCHES</code>:
                Directory for local patches that aren't part of
                pkgsrc. See <a href="#components.patches" title=
                "8.3.&nbsp;patches/*">Section&nbsp;8.3,
                &#8220;patches/*&#8221;</a> for more information.
                <em class="replaceable"><code>rel</code></em> and
                <em class="replaceable"><code>arch</code></em> are
                replaced with OS release (&#8220;<span class=
                "quote">2.0</span>&#8221;, etc.) and architecture
                (&#8220;<span class="quote">mipsel</span>&#8221;,
                etc.).</p>
              </li>

              <li>
                <p><code class="varname">PKGMAKECONF</code>:
                Location of the <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">mk.conf</code> file used by a package's
                BSD-style Makefile. If this is not set,
                <code class="varname">MAKECONF</code> is set to
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">/dev/null</code> to avoid picking up
                settings used by builds in <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">/usr/src</code>.</p>
              </li>
            </ul>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "developer-advanced-settings"></a>5.3.&nbsp;Developer/advanced
                settings</h2>
              </div>
            </div>
          </div>

          <p>XXX</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><code class="varname">PKG_DEVELOPER</code>: Run
                some sanity checks that package developers
                want:</p>

                <div class="itemizedlist">
                  <ul type="circle">
                    <li>
                      <p>make sure patches apply with zero fuzz</p>
                    </li>

                    <li>
                      <p>run check-shlibs to see that all binaries
                      will find their shared libs.</p>
                    </li>
                  </ul>
                </div>
              </li>

              <li>
                <p><code class="varname">PKG_DEBUG_LEVEL</code>:
                The level of debugging output which is displayed
                whilst making and installing the package. The
                default value for this is 0, which will not display
                the commands as they are executed (normal, default,
                quiet operation); the value 1 will display all
                shell commands before their invocation, and the
                value 2 will display both the shell commands before
                their invocation, and their actual execution
                progress with <span><strong class="command">set
                -x</strong></span> will be displayed.</p>
              </li>

              <li>
                <p><code class=
                "varname">ALLOW_VULNERABILITIES.<em class=
                "replaceable"><code>pkgbase</code></em></code>: A
                space separated list of vulnerability IDs that may
                be ignored when performing the automated security
                checks. These IDs are listed in the
                pkg-vulnerabilities file and are displayed by
                <span><strong class=
                "command">audit-packages</strong></span> when it
                finds a vulnerable package.</p>
              </li>

              <li>
                <p><code class=
                "varname">SKIP_AUDIT_PACKAGES</code>: If this is
                set to &#8220;<span class=
                "quote">yes</span>&#8221;, the automated security
                checks (which use the <a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/audit-packages/README.html"
                target="_top"><code xmlns="" class=
                "filename">security/audit-packages</code></a>
                package) will be <span class=
                "strong"><strong>entirely</strong></span> skipped
                for <span class=
                "strong"><strong>all</strong></span> packages
                built. Normally you'll want to use
                ALLOW_VULNERABILITIES instead of this.</p>
              </li>
            </ul>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "selecting-build-options"></a>5.4.&nbsp;Selecting
                Build Options</h2>
              </div>
            </div>
          </div>

          <p>Some packages have build time options, usually to
          select between different dependencies, enable optional
          support for big dependencies or enable experimental
          features.</p>

          <p>To see which options, if any, a package supports, and
          which options are mutually exclusive, run
          <span><strong class="command">make
          show-options</strong></span>, for example:</p>
          <pre class="programlisting">
    The following options are supported by this package:
        ssl      Enable SSL support.
    Exactly one of the following gecko options is required:
        firefox  Use firefox as gecko rendering engine.
        mozilla  Use mozilla as gecko rendering engine.
    At most one of the following database options may be selected:
        mysql    Enable support for MySQL database.
        pgsql    Enable support for PostgreSQL database.

    These options are enabled by default: firefox
    These options are currently enabled: mozilla ssl
</pre>

          <p>The following variables can be defined in <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/etc/mk.conf</code> to select which options to
          enable for a package: <code class=
          "varname">PKG_DEFAULT_OPTIONS</code>, which can be used
          to select or disable options for all packages that
          support them, and <code class=
          "varname">PKG_OPTIONS.<em class=
          "replaceable"><code>pkgbase</code></em></code>, which can
          be used to select or disable options specifically for
          package <em class=
          "replaceable"><code>pkgbase</code></em>. Options listed
          in these variables are selected, options preceded by
          &#8220;<span class="quote">-</span>&#8221; are disabled.
          A few examples:</p>
          <pre class="screen">
<code class="prompt">$</code> <span><strong class=
"command">grep "PKG.*OPTION" /etc/mk.conf</strong></span>
PKG_DEFAULT_OPTIONS=    -arts -dvdread -esound
PKG_OPTIONS.kdebase=    debug -sasl
PKG_OPTIONS.apache=     suexec 
</pre>

          <p>The following settings are consulted in the order
          given, and the last setting that selects or disables an
          option is used:</p>

          <div class="orderedlist">
            <ol type="1">
              <li>
                <p>the default options as suggested by the package
                maintainer</p>
              </li>

              <li>
                <p>the options implied by the settings of legacy
                variables (see below)</p>
              </li>

              <li>
                <p><code class=
                "varname">PKG_DEFAULT_OPTIONS</code></p>
              </li>

              <li>
                <p><code class="varname">PKG_OPTIONS.<em class=
                "replaceable"><code>pkgbase</code></em></code></p>
              </li>
            </ol>
          </div>

          <p>For groups of mutually exclusive options, the last
          option selected is used, all others are automatically
          disabled. If an option of the group is explicitly
          disabled, the previously selected option, if any, is
          used. It is an error if no option from a required group
          of options is selected, and building the package will
          fail.</p>

          <p>Before the options framework was introduced, build
          options were selected by setting a variable (often named
          <code class="varname">USE_<em class=
          "replaceable"><code>FOO</code></em></code>) in
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">/etc/mk.conf</code> for each option. To
          ease transition to the options framework for the user,
          these legacy variables are converted to the appropriate
          options setting (<code class=
          "varname">PKG_OPTIONS.<em class=
          "replaceable"><code>pkgbase</code></em></code>)
          automatically. A warning is issued to prompt the user to
          update <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/etc/mk.conf</code> to use the options
          framework directly. Support for the legacy variables will
          be removed eventually.</p>
        </div>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "binary"></a>Chapter&nbsp;6.&nbsp;Creating binary
              packages</h2>
            </div>
          </div>
        </div>

        <div class="toc">
          <p><b>Table of Contents</b></p>

          <dl>
            <dt><span class="sect1"><a href=
            "#building-a-single-binary-package">6.1. Building a
            single binary package</a></span></dt>

            <dt><span class="sect1"><a href=
            "#settings-for-creationg-of-binary-packages">6.2.
            Settings for creation of binary
            packages</a></span></dt>

            <dt><span class="sect1"><a href="#bulkbuild">6.3. Doing
            a bulk build of all packages</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#binary.configuration">6.3.1.
                Configuration</a></span></dt>

                <dt><span class="sect2"><a href=
                "#other-environmental-considerations">6.3.2. Other
                environmental considerations</a></span></dt>

                <dt><span class="sect2"><a href="#operation">6.3.3.
                Operation</a></span></dt>

                <dt><span class="sect2"><a href=
                "#what-it-does">6.3.4. What it does</a></span></dt>

                <dt><span class="sect2"><a href=
                "#disk-space-requirements">6.3.5. Disk space
                requirements</a></span></dt>

                <dt><span class="sect2"><a href=
                "#setting-up-a-sandbox">6.3.6. Setting up a sandbox
                for chrooted builds</a></span></dt>

                <dt><span class="sect2"><a href=
                "#building-a-partial-set">6.3.7. Building a partial
                set of packages</a></span></dt>

                <dt><span class="sect2"><a href=
                "#bulk-upload">6.3.8. Uploading results of a bulk
                build</a></span></dt>
              </dl>
            </dd>

            <dt><span class="sect1"><a href="#creating-cdroms">6.4.
            Creating a multiple CD-ROM packages
            collection</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#cdpack-example">6.4.1. Example of
                cdpack</a></span></dt>
              </dl>
            </dd>
          </dl>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "building-a-single-binary-package"></a>6.1.&nbsp;Building
                a single binary package</h2>
              </div>
            </div>
          </div>

          <p>Once you have built and installed a package, you can
          create a <span class="emphasis"><em>binary
          package</em></span> which can be installed on another
          system with <a href=
          "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
          <span class="citerefentry"><span class=
          "refentrytitle">pkg_add</span>(1)</span></a>. This saves
          having to build the same package on a group of hosts and
          wasting CPU time. It also provides a simple means for
          others to install your package, should you distribute
          it.</p>

          <p>To create a binary package, change into the
          appropriate directory in pkgsrc, and run
          <span><strong class="command">make
          package</strong></span>:</p>
          <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>cd misc/figlet</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>make package</code></strong>
</pre>

          <p>This will build and install your package (if not
          already done), and then build a binary package from what
          was installed. You can then use the <span><strong class=
          "command">pkg_*</strong></span> tools to manipulate it.
          Binary packages are created by default in <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/usr/pkgsrc/packages</code>, in the form of a
          gzipped tar file. See <a href="#logs.package" title=
          "B.2.&nbsp;Packaging figlet">Section&nbsp;B.2,
          &#8220;Packaging figlet&#8221;</a> for a continuation of
          the above <a xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" href=
          "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/misc/figlet/README.html"
          target="_top"><code xmlns="" class=
          "filename">misc/figlet</code></a> example.</p>

          <p>See <a href="#submit" title=
          "Chapter&nbsp;18.&nbsp;Submitting and Committing">Chapter&nbsp;18,
          <i>Submitting and Committing</i></a> for information on
          how to submit such a binary package.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "settings-for-creationg-of-binary-packages"></a>6.2.&nbsp;Settings
                for creation of binary packages</h2>
              </div>
            </div>
          </div>

          <p>See <a href="#build.helpful-targets" title=
          "14.16.&nbsp;Other helpful targets">Section&nbsp;14.16,
          &#8220;Other helpful targets&#8221;</a>.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "bulkbuild"></a>6.3.&nbsp;Doing a bulk build of all
                packages</h2>
              </div>
            </div>
          </div>

          <p>If you want to get a full set of precompiled binary
          packages, this section describes how to get them. Beware
          that the bulk build will remove all currently installed
          packages from your system!</p>

          <p>Having an FTP server configured either on the machine
          doing the bulk builds or on a nearby NFS server can help
          to make the packages available to other machines that can
          then save time by installing only the binary packages.
          See <a href=
          "http://netbsd.gw.com/cgi-bin/man-cgi?ftpd+8+NetBSD-current">
          <span class="citerefentry"><span class=
          "refentrytitle">ftpd</span>(8)</span></a> for more
          information. If you use a remote NFS server's storage, be
          sure to not actually compile on NFS storage, as this
          slows things down a lot.</p>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "binary.configuration"></a>6.3.1.&nbsp;Configuration</h3>
                </div>
              </div>
            </div>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "binary.bulk.build.conf"></a>6.3.1.1.&nbsp;<code xmlns="http://www.w3.org/TR/xhtml1/transitional"
                    class="filename">build.conf</code></h4>
                  </div>
                </div>
              </div>

              <p>The <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">build.conf</code> file is the main
              configuration file for bulk builds. You can configure
              how your copy of pkgsrc is kept up to date, how the
              distfiles are downloaded, how the packages are built
              and how the report is generated. You can find an
              annotated example file in <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">pkgsrc/mk/bulk/build.conf-example</code>.
              To use it, copy <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">build.conf-example</code> to <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">build.conf</code> and edit it, following
              the comments in that file.</p>
            </div>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "binary.mk.conf"></a>6.3.1.2.&nbsp;/etc/mk.conf</h4>
                  </div>
                </div>
              </div>

              <p>You may want to set variables in <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">/etc/mk.conf</code>. Look at <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">pkgsrc/mk/defaults/mk.conf</code> for
              details of the default settings. You will want to
              ensure that <code class=
              "varname">ACCEPTABLE_LICENSES</code> meet your local
              policy. As used in this example, <code class=
              "varname">_ACCEPTABLE=yes</code> accepts <span class=
              "emphasis"><em>all</em></span> licenses.</p>
              <pre class="programlisting">
    PACKAGES?=      ${_PKGSRCDIR}/packages/${MACHINE_ARCH}
    WRKOBJDIR?=     /usr/tmp/pkgsrc   # build here instead of in pkgsrc
    BSDSRCDIR=      /usr/src
    BSDXSRCDIR=     /usr/xsrc         # for x11/xservers
    OBJHOSTNAME?=   yes               # use work.`hostname`
    FAILOVER_FETCH= yes               # insist on the correct checksum
    PKG_DEVELOPER?= yes
    _ACCEPTABLE=    yes
</pre>

              <p>Some options that are especially useful for bulk
              builds can be found at the top lines of the file
              <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">mk/bulk/bsd.bulk-pkg.mk</code>. The most
              useful options of these are briefly described
              here.</p>

              <div class="itemizedlist">
                <ul type="disc">
                  <li>
                    <p>If you are on a slow machine, you may want
                    to set <code class=
                    "varname">USE_BULK_BROKEN_CHECK</code> to
                    &#8220;<span class=
                    "quote">no</span>&#8221;.</p>
                  </li>

                  <li>
                    <p>If you are doing bulk builds from a
                    read-only copy of pkgsrc, you have to set
                    <code class="varname">BULKFILESDIR</code> to
                    the directory where all log files are created.
                    Otherwise the log files are created in the
                    pkgsrc directory.</p>
                  </li>

                  <li>
                    <p>Another important variable is <code class=
                    "varname">BULK_PREREQ</code>, which is a list
                    of packages that should be always available
                    while building other packages.</p>
                  </li>
                </ul>
              </div>

              <p>Some other options are scattered in the pkgsrc
              infrastructure:</p>

              <div class="itemizedlist">
                <ul type="disc">
                  <li>
                    <p><code class=
                    "varname">ALLOW_VULNERABLE_PACKAGES</code>
                    should be set to <code class=
                    "literal">yes</code>. The purpose of the bulk
                    builds is creating binary packages, no matter
                    if they are vulnerable or not. When uploading
                    the packages to a public server, the vulnerable
                    packages will be put into a directory of their
                    own. Leaving this variable unset would prevent
                    the bulk build system from even trying to build
                    them, so possible building errors would not
                    show up.</p>
                  </li>

                  <li>
                    <p><code class="varname">CHECK_FILES</code>
                    (<code xmlns=
                    "http://www.w3.org/TR/xhtml1/transitional"
                    class=
                    "filename">pkgsrc/mk/bsd.pkg.check.mk</code>)
                    can be set to &#8220;<span class=
                    "quote">yes</span>&#8221; to check that the
                    installed set of files matches the <code xmlns=
                    "http://www.w3.org/TR/xhtml1/transitional"
                    class="filename">PLIST</code>.</p>
                  </li>

                  <li>
                    <p><code class=
                    "varname">CHECK_INTERPRETER</code>
                    (<code xmlns="http://www.w3.org/TR/xhtml1/transitional"
                    class=
                    "filename">pkgsrc/mk/bsd.pkg.check.mk</code>)
                    can be set to &#8220;<span class=
                    "quote">yes</span>&#8221; to check that the
                    installed &#8220;<span class=
                    "quote">#!</span>&#8221;-scripts will find
                    their interpreter.</p>
                  </li>
                </ul>
              </div>
            </div>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "pre-build.local"></a>6.3.1.3.&nbsp;<code xmlns="http://www.w3.org/TR/xhtml1/transitional"
                    class="filename">pre-build.local</code></h4>
                  </div>
                </div>
              </div>

              <p>It is possible to configure the bulk build to
              perform certain site-specific tasks at the end of the
              pre-build stage. If the file <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">pre-build.local</code> exists in
              <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">/usr/pkgsrc/mk/bulk</code>, it will be
              executed (as a <a href=
              "http://netbsd.gw.com/cgi-bin/man-cgi?sh+1+NetBSD-current">
              <span class="citerefentry"><span class=
              "refentrytitle">sh</span>(1)</span></a> script) at
              the end of the usual pre-build stage. An example use
              of <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">pre-build.local</code> is to have the
              line:</p>
              <pre class="screen">
echo "I do not have enough disk space to build this pig." \
    &gt; misc/openoffice/$BROKENF
</pre>

              <p>to prevent the system from trying to build a
              particular package which requires nearly 3 GB of disk
              space.</p>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "other-environmental-considerations"></a>6.3.2.&nbsp;Other
                  environmental considerations</h3>
                </div>
              </div>
            </div>

            <p>As <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/usr/pkg</code> will be completely deleted
            at the start of bulk builds, make sure your login shell
            is placed somewhere else. Either drop it into
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">/usr/local/bin</code> (and adjust your
            login shell in the passwd file), or (re-)install it via
            <a href=
            "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
            <span class="citerefentry"><span class=
            "refentrytitle">pkg_add</span>(1)</span></a> from
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">/etc/rc.local</code>, so you can login
            after a reboot (remember that your current process
            won't die if the package is removed, you just can't
            start any new instances of the shell any more). Also,
            if you use NetBSD earlier than 1.5, or you still want
            to use the pkgsrc version of ssh for some reason, be
            sure to install ssh before starting it from
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">rc.local</code>:</p>
            <pre class="programlisting">
    ( cd /usr/pkgsrc/security/ssh ; make bulk-install )
    if [ -f /usr/pkg/etc/rc.d/sshd ]; then
        /usr/pkg/etc/rc.d/sshd
    fi
</pre>

            <p>Not doing so will result in you being not able to
            log in via ssh after the bulk build is finished or if
            the machine gets rebooted or crashes. You have been
            warned! :)</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "operation"></a>6.3.3.&nbsp;Operation</h3>
                </div>
              </div>
            </div>

            <p>Make sure you don't need any of the packages still
            installed.</p>

            <div class="warning" style=
            "margin-left: 0.5in; margin-right: 0.5in;">
              <h3 class="title">Warning</h3>

              <p>During the bulk build, <span class=
              "emphasis"><em>all packages will be
              removed!</em></span></p>
            </div>

            <p>Be sure to remove all other things that might
            interfere with builds, like some libs installed in
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">/usr/local</code>, etc. then become
            root and type:</p>
            <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>cd /usr/pkgsrc</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>sh mk/bulk/build</code></strong>
</pre>

            <p>If for some reason your last build didn't complete
            (power failure, system panic, ...), you can continue it
            by running:</p>
            <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>sh mk/bulk/build restart</code></strong>
</pre>

            <p>At the end of the bulk build, you will get a summary
            via mail, and find build logs in the directory
            specified by <code class="varname">FTP</code> in the
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">build.conf</code> file.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "what-it-does"></a>6.3.4.&nbsp;What it does</h3>
                </div>
              </div>
            </div>

            <p>The bulk builds consist of three steps:</p>

            <div class="variablelist">
              <dl>
                <dt><span class="term">1. pre-build</span></dt>

                <dd>
                  <p>The script updates your pkgsrc tree via
                  (anon)cvs, then cleans out any broken distfiles,
                  and removes all packages installed.</p>
                </dd>

                <dt><span class="term">2. the bulk
                build</span></dt>

                <dd>
                  <p>This is basically &#8220;<span class=
                  "quote">make bulk-package</span>&#8221; with an
                  optimised order in which packages will be built.
                  Packages that don't require other packages will
                  be built first, and packages with many
                  dependencies will be built later.</p>
                </dd>

                <dt><span class="term">3. post-build</span></dt>

                <dd>
                  <p>Generates a report that's placed in the
                  directory specified in the <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">build.conf</code> file named
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">broken.html</code>, a short version of
                  that report will also be mailed to the build's
                  admin.</p>
                </dd>
              </dl>
            </div>

            <p>During the build, a list of broken packages will be
            compiled in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/usr/pkgsrc/.broken</code> (or <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">.../.broken.${MACHINE}</code> if
            <code class="varname">OBJMACHINE</code> is set),
            individual build logs of broken builds can be found in
            the package's directory. These files are used by the
            bulk-targets to mark broken builds to not waste time
            trying to rebuild them, and they can be used to debug
            these broken package builds later.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "disk-space-requirements"></a>6.3.5.&nbsp;Disk
                  space requirements</h3>
                </div>
              </div>
            </div>

            <p>Currently, roughly the following requirements are
            valid for NetBSD 2.0/i386:</p>

            <div class="itemizedlist">
              <ul type="disc">
                <li>
                  <p>10 GB - distfiles (NFS ok)</p>
                </li>

                <li>
                  <p>8 GB - full set of all binaries (NFS ok)</p>
                </li>

                <li>
                  <p>5 GB - temp space for compiling (local disk
                  recommended)</p>
                </li>
              </ul>
            </div>

            <p>Note that all pkgs will be de-installed as soon as
            they are turned into a binary package, and that sources
            are removed, so there is no excessively huge demand to
            disk space. Afterwards, if the package is needed again,
            it will be installed via <a href=
            "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
            <span class="citerefentry"><span class=
            "refentrytitle">pkg_add</span>(1)</span></a> instead of
            building again, so there are no cycles wasted by
            recompiling.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "setting-up-a-sandbox"></a>6.3.6.&nbsp;Setting up
                  a sandbox for chrooted builds</h3>
                </div>
              </div>
            </div>

            <p>If you don't want all the packages nuked from a
            machine (rendering it useless for anything but pkg
            compiling), there is the possibility of doing the
            package bulk build inside a chroot environment.</p>

            <p>The first step is to set up a chroot sandbox, e.g.
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">/usr/sandbox</code>. This can be done
            by using null mounts, or manually.</p>

            <p>There is a shell script called <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">pkgsrc/mk/bulk/mksandbox</code> which will
            set up the sandbox environment using null mounts. It
            will also create a script called <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">sandbox</code> in the root of the sandbox
            environment, which will allow the null mounts to be
            activated using the <span><strong class=
            "command">sandbox mount</strong></span> command and
            deactivated using the <span><strong class=
            "command">sandbox umount</strong></span> command.</p>

            <p>To set up a sandbox environment by hand, after
            extracting all the sets from a NetBSD installation or
            doing a <span><strong class="command">make distribution
            DESTDIR=/usr/sandbox</strong></span> in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/usr/src/etc</code>, be sure the following
            items are present and properly configured:</p>

            <div class="procedure">
              <ol type="1">
                <li>
                  <p>Kernel</p>
                  <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>cp /netbsd /usr/sandbox</code></strong>
</pre>
                </li>

                <li>
                  <p><code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/dev/*</code></p>
                  <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>cd /usr/sandbox/dev ; sh MAKEDEV all</code></strong>
</pre>
                </li>

                <li>
                  <p><code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/etc/resolv.conf</code> (for <a xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" href=
                  "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/smtpd/README.html"
                  target="_top"><code xmlns="" class=
                  "filename">security/smtpd</code></a> and
                  mail):</p>
                  <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>cp /etc/resolv.conf /usr/sandbox/etc</code></strong>
</pre>
                </li>

                <li>
                  <p>Working(!) mail config (hostname,
                  sendmail.cf):</p>
                  <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>cp /etc/mail/sendmail.cf /usr/sandbox/etc/mail</code></strong>
</pre>
                </li>

                <li>
                  <p><code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/etc/localtime</code> (for <a xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" href=
                  "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/smtpd/README.html"
                  target="_top"><code xmlns="" class=
                  "filename">security/smtpd</code></a>):</p>
                  <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>ln -sf /usr/share/zoneinfo/UTC /usr/sandbox/etc/localtime</code></strong>
</pre>
                </li>

                <li>
                  <p><code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/usr/src</code> (system sources,
                  e.&nbsp;g. for <a xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" href=
                  "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/sysutils/aperture/README.html"
                  target="_top"><code xmlns="" class=
                  "filename">sysutils/aperture</code></a>):</p>
                  <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>ln -s ../disk1/cvs .</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>ln -s cvs/src-2.0 src</code></strong>
</pre>
                </li>

                <li>
                  <p>Create <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/var/db/pkg</code> (not part of
                  default install):</p>
                  <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>mkdir /usr/sandbox/var/db/pkg</code></strong>
</pre>
                </li>

                <li>
                  <p>Create <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/usr/pkg</code> (not part of default
                  install):</p>
                  <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>mkdir /usr/sandbox/usr/pkg</code></strong>
</pre>
                </li>

                <li>
                  <p>Checkout pkgsrc via cvs into <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/usr/sandbox/usr/pkgsrc</code>:</p>
                  <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>cd /usr/sandbox/usr</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>cvs -d anoncvs@anoncvs.NetBSD.org:/cvsroot checkout -d -P pkgsrc</code></strong>
</pre>

                  <p>Do not mount/link this to the copy of your
                  pkgsrc tree you do development in, as this will
                  likely cause problems!</p>
                </li>

                <li>
                  <p>Make <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/usr/sandbox/usr/pkgsrc/packages</code>
                  and <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">.../distfiles</code> point somewhere
                  appropriate. NFS- and/or nullfs-mounts may come
                  in handy!</p>
                </li>

                <li>
                  <p>Edit <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/etc/mk.conf</code>, see <a href=
                  "#binary.mk.conf" title=
                  "6.3.1.2.&nbsp;/etc/mk.conf">Section&nbsp;6.3.1.2,
                  &#8220;/etc/mk.conf&#8221;</a>.</p>
                </li>

                <li>
                  <p>Adjust <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">mk/bulk/build.conf</code> to suit your
                  needs.</p>
                </li>
              </ol>
            </div>

            <p>When the chroot sandbox is set up, you can start the
            build with the following steps:</p>
            <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>cd /usr/sandbox/usr/pkgsrc</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>sh mk/bulk/do-sandbox-build</code></strong>
</pre>

            <p>This will just jump inside the sandbox and start
            building. At the end of the build, mail will be sent
            with the results of the build. Created binary pkgs will
            be in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/usr/sandbox/usr/pkgsrc/packages</code>
            (wherever that points/mounts to/from).</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "building-a-partial-set"></a>6.3.7.&nbsp;Building
                  a partial set of packages</h3>
                </div>
              </div>
            </div>

            <p>In addition to building a complete set of all
            packages in pkgsrc, the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">pkgsrc/mk/bulk/build</code> script may be
            used to build a subset of the packages contained in
            pkgsrc. By setting <code class=
            "varname">SPECIFIC_PKGS</code> in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/etc/mk.conf</code>, the variables</p>

            <div class="itemizedlist">
              <ul type="disc">
                <li>
                  <p>SITE_SPECIFIC_PKGS</p>
                </li>

                <li>
                  <p>HOST_SPECIFIC_PKGS</p>
                </li>

                <li>
                  <p>GROUP_SPECIFIC_PKGS</p>
                </li>

                <li>
                  <p>USER_SPECIFIC_PKGS</p>
                </li>
              </ul>
            </div>

            <p>will define the set of packages which should be
            built. The bulk build code will also include any
            packages which are needed as dependencies for the
            explicitly listed packages.</p>

            <p>One use of this is to do a bulk build with
            <code class="varname">SPECIFIC_PKGS</code> in a chroot
            sandbox periodically to have a complete set of the
            binary packages needed for your site available without
            the overhead of building extra packages that are not
            needed.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "bulk-upload"></a>6.3.8.&nbsp;Uploading results
                  of a bulk build</h3>
                </div>
              </div>
            </div>

            <p>This section describes how pkgsrc developers can
            upload binary pkgs built by bulk builds to
            ftp.NetBSD.org.</p>

            <p>If you would like to automatically create checksum
            files for the binary packages you intend to upload,
            remember to set <code class="varname">MKSUMS=yes</code>
            in your <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">mk/bulk/build.conf</code>.</p>

            <p>If you would like to PGP sign the checksum files
            (highly recommended!), remember to set <code class=
            "varname">SIGN_AS=username@NetBSD.org</code> in your
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">mk/bulk/build.conf</code>. This will
            prompt you for your GPG password to sign the files
            before uploading everything.</p>

            <p>Then, make sure that you have <code class=
            "varname">RSYNC_DST</code> set properly in your
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">mk/bulk/build.conf</code> file, i.e.
            adjust it to something like one of the following:</p>
            <pre class="screen">
RSYNC_DST=ftp.NetBSD.org:/pub/NetBSD/packages/pkgsrc-200xQy/NetBSD-a.b.c/arch/upload 
</pre>

            <p>Please use appropriate values for "pkgsrc-200xQy",
            "NetBSD-a.b.c" and "arch" here. If your login on
            ftp.NetBSD.org is different from your local login,
            write your login directly into the variable, e.g. my
            local account is "feyrer", but for my login "hubertf",
            I use:</p>
            <pre class="screen">
RSYNC_DST=hubertf@ftp.NetBSD.org:/pub/NetBSD/packages/pkgsrc-200xQy/NetBSD-a.b.c/arch/upload 
</pre>

            <p>A separate <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">upload</code> directory is used here to
            allow "closing" the directory during upload. To do so,
            run the following command on ftp.NetBSD.org next:</p>
            <pre class="screen">
nbftp% <strong class=
"userinput"><code>mkdir -p -m 750 /pub/NetBSD/packages/pkgsrc-200xQy/NetBSD-a.b.c/arch/upload</code></strong>
</pre>

            <p>Please note that <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/pub/NetBSD/packages</code> is only
            appropriate for packages for the NetBSD operating
            system. Binary packages for other operating systems
            should go into <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/pub/pkgsrc</code>.</p>

            <p>Before uploading the binary pkgs, ssh authentication
            needs to be set up. This example shows how to set up
            temporary keys for the root account <span class=
            "emphasis"><em>inside the sandbox</em></span> (assuming
            that no keys should be present there usually):</p>
            <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>chroot /usr/sandbox</code></strong>
chroot-<code class="prompt">#</code> <strong class=
"userinput"><code>rm $HOME/.ssh/id-dsa*</code></strong>
chroot-<code class="prompt">#</code> <strong class=
"userinput"><code>ssh-keygen -t dsa</code></strong>
chroot-<code class="prompt">#</code> <strong class=
"userinput"><code>cat $HOME/.ssh/id-dsa.pub</code></strong> 
</pre>

            <p>Now take the output of <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">id-dsa.pub</code> and append it to your
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">~/.ssh/authorized_keys</code> file on
            ftp.NetBSD.org. You can remove the key after the upload
            is done!</p>

            <p>Next, test if your ssh connection really works:</p>
            <pre class="screen">
chroot-<code class="prompt">#</code> <strong class=
"userinput"><code>ssh ftp.NetBSD.org date</code></strong> 
</pre>

            <p>Use "-l yourNetBSDlogin" here as appropriate!</p>

            <p>Now after all this works, you can exit the sandbox
            and start the upload:</p>
            <pre class="screen">
chroot-<code class="prompt">#</code> <strong class=
"userinput"><code>exit</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>cd /usr/sandbox/usr/pkgsrc</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>sh mk/bulk/do-sandbox-upload</code></strong> 
</pre>

            <p>The upload process may take quite some time. Use
            <a href=
            "http://netbsd.gw.com/cgi-bin/man-cgi?ls+1+NetBSD-current">
            <span class="citerefentry"><span class=
            "refentrytitle">ls</span>(1)</span></a> or <a href=
            "http://netbsd.gw.com/cgi-bin/man-cgi?du+1+NetBSD-current">
            <span class="citerefentry"><span class=
            "refentrytitle">du</span>(1)</span></a> on the FTP
            server to monitor progress of the upload. The upload
            script will take care of not uploading restricted
            packages and putting vulnerable packages into the
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">vulnerable</code> subdirectory.</p>

            <p>After the upload has ended, first thing is to revoke
            ssh access:</p>
            <pre class="screen">
nbftp% <strong class=
"userinput"><code>vi ~/.ssh/authorized_keys</code></strong>
Gdd:x! 
</pre>

            <p>Use whatever is needed to remove the key you've
            entered before! Last, move the uploaded packages out of
            the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">upload</code> directory to have them
            accessible to everyone:</p>
            <pre class="screen">
nbftp% <strong class=
"userinput"><code>cd /pub/NetBSD/packages/pkgsrc-200xQy/NetBSD-a.b.c/arch</code></strong>
nbftp% <strong class=
"userinput"><code>mv upload/* .</code></strong>
nbftp% <strong class="userinput"><code>rmdir upload</code></strong>
nbftp% <strong class="userinput"><code>chmod 755 .</code></strong> 
</pre>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "creating-cdroms"></a>6.4.&nbsp;Creating a multiple
                CD-ROM packages collection</h2>
              </div>
            </div>
          </div>

          <p>After your pkgsrc bulk-build has completed, you may
          wish to create a CD-ROM set of the resulting binary
          packages to assist in installing packages on other
          machines. The <a xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" href=
          "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/cdpack/README.html"
          target="_top"><code xmlns="" class=
          "filename">pkgtools/cdpack</code></a> package provides a
          simple tool for creating the ISO 9660 images.
          <span><strong class="command">cdpack</strong></span>
          arranges the packages on the CD-ROMs in a way that keeps
          all the dependencies for a given package on the same CD
          as that package.</p>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "cdpack-example"></a>6.4.1.&nbsp;Example of
                  cdpack</h3>
                </div>
              </div>
            </div>

            <p>Complete documentation for cdpack is found in the
            cdpack(1) man page. The following short example assumes
            that the binary packages are left in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/usr/pkgsrc/packages/All</code> and that
            sufficient disk space exists in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/u2</code> to hold the ISO 9660 images.</p>
            <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>mkdir /u2/images</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>pkg_add /usr/pkgsrc/packages/All/cdpack</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>cdpack /usr/pkgsrc/packages/All /u2/images</code></strong>
</pre>

            <p>If you wish to include a common set of files
            (<code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">COPYRIGHT</code>, <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">README</code>, etc.) on each CD in the
            collection, then you need to create a directory which
            contains these files. e.g.</p>
            <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>mkdir /tmp/common</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>echo "This is a README" &gt; /tmp/common/README</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>echo "Another file" &gt; /tmp/common/COPYING</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>mkdir /tmp/common/bin</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>echo "#!/bin/sh" &gt; /tmp/common/bin/myscript</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>echo "echo Hello world" &gt;&gt; /tmp/common/bin/myscript</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>chmod 755 /tmp/common/bin/myscript</code></strong>
</pre>

            <p>Now create the images:</p>
            <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>cdpack -x /tmp/common /usr/pkgsrc/packages/All /u2/images</code></strong>
</pre>

            <p>Each image will contain <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">README</code>, <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">COPYING</code>, and <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">bin/myscript</code> in their root
            directories.</p>
          </div>
        </div>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "faq"></a>Chapter&nbsp;7.&nbsp;Frequently Asked
              Questions</h2>
            </div>
          </div>
        </div>

        <div class="toc">
          <p><b>Table of Contents</b></p>

          <dl>
            <dt><span class="sect1"><a href=
            "#mailing-list-pointers">7.1. Are there any mailing
            lists for pkg-related discussion?</a></span></dt>

            <dt><span class="sect1"><a href="#pkgviews-docs">7.2.
            Where's the pkgviews documentation?</a></span></dt>

            <dt><span class="sect1"><a href="#faq-pkgtools">7.3.
            Utilities for package management
            (pkgtools)</a></span></dt>

            <dt><span class="sect1"><a href="#non-root-pkgsrc">7.4.
            How to use pkgsrc as non-root</a></span></dt>

            <dt><span class="sect1"><a href=
            "#resume-transfers">7.5. How to resume transfers when
            fetching distfiles?</a></span></dt>

            <dt><span class="sect1"><a href=
            "#XFree86-from-pkgsrc">7.6. How can I install/use
            XFree86 from pkgsrc?</a></span></dt>

            <dt><span class="sect1"><a href=
            "#x.org-from-pkgsrc">7.7. How can I install/use X.org
            from pkgsrc?</a></span></dt>

            <dt><span class="sect1"><a href=
            "#fetch-behind-firewall">7.8. How to fetch files from
            behind a firewall</a></span></dt>

            <dt><span class="sect1"><a href="#passive-ftp">7.9. How
            do I tell <span><strong class="command">make
            fetch</strong></span> to do passive
            FTP?</a></span></dt>

            <dt><span class="sect1"><a href=
            "#fetching-all-distfiles">7.10. How to fetch all
            distfiles at once</a></span></dt>

            <dt><span class="sect1"><a href=
            "#tmac.andoc-missing">7.11. What does
            &#8220;<span class="quote">Don't know how to make
            /usr/share/tmac/tmac.andoc</span>&#8221;
            mean?</a></span></dt>

            <dt><span class="sect1"><a href=
            "#bsd.own.mk-missing">7.12. What does
            &#8220;<span class="quote">Could not find
            bsd.own.mk</span>&#8221; mean?</a></span></dt>

            <dt><span class="sect1"><a href=
            "#using-sudo-with-pkgsrc">7.13. Using 'sudo' with
            pkgsrc</a></span></dt>

            <dt><span class="sect1"><a href="#faq.conf">7.14. How
            do I change the location of configuration
            files?</a></span></dt>

            <dt><span class="sect1"><a href="#audit-packages">7.15.
            Automated security checks</a></span></dt>
          </dl>
        </div>

        <p>This section contains hints, tips &amp; tricks on
        special things in pkgsrc that we didn't find a better place
        for in the previous chapters, and it contains items for
        both pkgsrc users and developers.</p>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "mailing-list-pointers"></a>7.1.&nbsp;Are there any
                mailing lists for pkg-related discussion?</h2>
              </div>
            </div>
          </div>

          <p>The following mailing lists may be of interest to
          pkgsrc users:</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><a href=
                "http://www.NetBSD.org/MailingLists/index.html#pkgsrc-bugs"
                target="_top">pkgsrc-bugs</a>: All bug reports in
                category "pkg" sent with <a href=
                "http://netbsd.gw.com/cgi-bin/man-cgi?send-pr+1+NetBSD-current">
                <span class="citerefentry"><span class=
                "refentrytitle">send-pr</span>(1)</span></a> appear
                here. Please do not report your bugs here directly;
                use one of the other mailing lists. discussed.</p>
              </li>

              <li>
                <p><a href=
                "http://www.NetBSD.org/MailingLists/index.html#pkgsrc-bulk"
                target="_top">pkgsrc-bulk</a>: A list where the
                results of pkgsrc bulk builds are sent and
                discussed.</p>
              </li>

              <li>
                <p><a href=
                "http://www.NetBSD.org/MailingLists/index.html#pkgsrc-changes"
                target="_top">pkgsrc-changes</a>: This list is for
                those who are interested in getting a commit
                message for every change committed to pkgsrc. It is
                also available in digest form, meaning one daily
                message containing all commit messages for changes
                to the package source tree in that 24 hour
                period.</p>
              </li>

              <li>
                <p><a href=
                "http://www.NetBSD.org/MailingLists/index.html#tech-pkg"
                target="_top">pkgsrc-users</a>: This is a general
                purpose list for most issues regarding pkgsrc,
                regardless of platform, e.g. soliciting user help
                for pkgsrc configuration, unexpected build
                failures, using particular packages, upgrading
                pkgsrc installations, questions regarding the
                pkgsrc release branches, etc. General announcements
                or proposals for changes that impact the pkgsrc
                user community, e.g. major infrastructure changes,
                new features, package removals, etc., may also be
                posted.</p>
              </li>

              <li>
                <p><a href=
                "http://www.NetBSD.org/MailingLists/index.html#tech-pkg"
                target="_top">tech-pkg</a>: This is a list for
                technical discussions related to pkgsrc
                development, e.g. soliciting feedback for changes
                to pkgsrc infrastructure, proposed new features,
                questions related to porting pkgsrc to a new
                platform, advice for maintaining a package, patches
                that affect many packages, help requests moved from
                pkgsrc-users when an infrastructure bug is found,
                etc.</p>
              </li>
            </ul>
          </div>

          <p>To subscribe, do:</p>
          <pre class="programlisting">
    <code class="prompt">%</code> echo subscribe <em class=
"replaceable"><code>listname</code></em> | mail majordomo@NetBSD.org
</pre>

          <p>Archives for all these mailing lists are available
          from <a href="http://mail-index.NetBSD.org/" target=
          "_top">http://mail-index.NetBSD.org/</a>.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "pkgviews-docs"></a>7.2.&nbsp;Where's the pkgviews
                documentation?</h2>
              </div>
            </div>
          </div>

          <p>Pkgviews is tightly integrated with buildlink. You can
          find a pkgviews User's guide in <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">pkgsrc/mk/buildlink3/PKGVIEWS_UG</code>.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "faq-pkgtools"></a>7.3.&nbsp;Utilities for package
                management (pkgtools)</h2>
              </div>
            </div>
          </div>

          <p>The <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">pkgsrc/pkgtools</code> directory pkgtools
          contains a number of useful utilities for both users and
          developers of pkgsrc. This section attempts only to make
          the reader aware of the utilities and when they might be
          useful, and not to duplicate the documentation that comes
          with each package.</p>

          <p>Utilities used by pkgsrc (automatically installed when
          needed):</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/x11-links/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/x11-links</code></a>: Symlinks
                for use by buildlink.</p>
              </li>
            </ul>
          </div>

          <p>OS tool augmentation (automatically installed when
          needed):</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/digest/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/digest</code></a>: Calculates
                various kinds of checksums (including SHA1).</p>
              </li>

              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/libnbcompat/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/libnbcompat</code></a>:
                Compatibility library for pkgsrc tools.</p>
              </li>

              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/mtree/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/mtree</code></a>: Installed on
                non-BSD systems due to lack of native mtree.</p>
              </li>

              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_install/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/pkg_install</code></a>:
                Up-to-date replacement for <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">/usr/sbin/pkg_install</code>, or for use
                on operating systems where pkg_install is not
                present.</p>
              </li>
            </ul>
          </div>

          <p>Utilities used by pkgsrc (not automatically
          installed):</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_tarup/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/pkg_tarup</code></a>: Create a
                binary package from an already-installed package.
                Used by <span><strong class="command">make
                replace</strong></span> to save the old
                package.</p>
              </li>

              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/dfdisk/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/dfdisk</code></a>: Adds extra
                functionality to pkgsrc, allowing it to fetch
                distfiles from multiple locations. It currently
                supports the following methods: multiple CD-ROMs
                and network FTP/HTTP connections.</p>
              </li>

              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/xpkgwedge/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/xpkgwedge</code></a>: Put X11
                packages someplace else (enabled by default).</p>
              </li>

              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/cpuflags/README.html"
                target="_top"><code xmlns="" class=
                "filename">devel/cpuflags</code></a>: Determine the
                best compiler flags to optimise code for your
                current CPU and compiler.</p>
              </li>
            </ul>
          </div>

          <p>Utilities for keeping track of installed packages,
          being up to date, etc:</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_chk/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/pkg_chk</code></a>: Reports on
                packages whose installed versions do not match the
                latest pkgsrc entries.</p>
              </li>

              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdep/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/pkgdep</code></a>: Makes
                dependency graphs of packages, to aid in choosing a
                strategy for updating.</p>
              </li>

              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdepgraph/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/pkgdepgraph</code></a>: Makes
                graphs from the output of <a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdep/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/pkgdep</code></a> (uses
                graphviz).</p>
              </li>

              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkglint/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/pkglint</code></a>: The
                pkglint(1) program checks a pkgsrc entry for
                errors, lintpkgsrc(1) does various checks on the
                complete pkgsrc system.</p>
              </li>

              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgsurvey/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/pkgsurvey</code></a>: Report
                what packages you have installed.</p>
              </li>
            </ul>
          </div>

          <p>Utilities for people maintaining or creating
          individual packages:</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdiff/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/pkgdiff</code></a>: Automate
                making and maintaining patches for a package
                (includes pkgdiff, pkgvi, mkpatches, etc.).</p>
              </li>

              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/rpm2pkg/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/rpm2pkg</code></a>, <a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/url2pkg/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/url2pkg</code></a>: Aids in
                converting to pkgsrc.</p>
              </li>

              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/gensolpkg/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/gensolpkg</code></a>: Convert
                pkgsrc to a Solaris package.</p>
              </li>
            </ul>
          </div>

          <p>Utilities for people maintaining pkgsrc (or: more
          obscure pkg utilities)</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_comp/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/pkg_comp</code></a>: Build
                packages in a chrooted area.</p>
              </li>

              <li>
                <p><a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/libkver/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/libkver</code></a>: Spoof
                kernel version for chrooted cross builds.</p>
              </li>
            </ul>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "non-root-pkgsrc"></a>7.4.&nbsp;How to use pkgsrc
                as non-root</h2>
              </div>
            </div>
          </div>

          <p>If you want to use pkgsrc as non-root user, you can
          set some variables to make pkgsrc work under these
          conditions. At the very least, you need to set
          <code class="varname">UNPRIVILEGED</code> to
          &#8220;<span class="quote">yes</span>&#8221;; this will
          turn on unprivileged mode and set multiple related
          variables to allow installation of packages as
          non-root.</p>

          <p>In case the defaults are not enough, you may want to
          tune some other variables used. For example, if the
          automatic user/group detection leads to incorrect values
          (or not the ones you would like to use), you can change
          them by setting <code class=
          "varname">UNPRIVILEGED_USER</code> and <code class=
          "varname">UNPRIVILEGED_GROUP</code> respectively.</p>

          <p>As regards bootstrapping, please note that the
          <span><strong class="command">bootstrap</strong></span>
          script will ease non-root configuration when given the
          &#8220;<span class=
          "quote">--ignore-user-check</span>&#8221; flag, as it
          will choose and use multiple default directories under
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">~/pkg</code> as the installation
          targets. These directories can be overriden by the
          &#8220;<span class="quote">--prefix</span>&#8221; flag
          provided by the script, as well as some others that allow
          finer tuning of the tree layout.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "resume-transfers"></a>7.5.&nbsp;How to resume
                transfers when fetching distfiles?</h2>
              </div>
            </div>
          </div>

          <p>By default, resuming transfers in pkgsrc is disabled,
          but you can enable this feature by adding the option
          <code class="varname">PKG_RESUME_TRANSFERS=YES</code>
          into <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/etc/mk.conf</code>. If, during a fetch step,
          an incomplete distfile is found, pkgsrc will try to
          resume it.</p>

          <p>You can also use a different program than the default
          <a href=
          "http://netbsd.gw.com/cgi-bin/man-cgi?ftp+1+NetBSD-current">
          <span class="citerefentry"><span class=
          "refentrytitle">ftp</span>(1)</span></a> by changing the
          <code class="varname">FETCH_CMD</code> variable. Don't
          forget to set <code class=
          "varname">FETCH_RESUME_ARGS</code> and <code class=
          "varname">FETCH_OUTPUT_ARGS</code> if you are not using
          default values.</p>

          <p>For example, if you want to use <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">wget</code> to resume downloads, you'll have
          to use something like:</p>
          <pre class="programlisting">
    FETCH_CMD=             wget
    FETCH_BEFORE_ARGS=     --passive-ftp
    FETCH_RESUME_ARGS=     -c
    FETCH_OUTPUT_ARGS=     -O
</pre>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "XFree86-from-pkgsrc"></a>7.6.&nbsp;How can I
                install/use XFree86 from pkgsrc?</h2>
              </div>
            </div>
          </div>

          <p>If you want to use XFree86 from pkgsrc instead of your
          system's own X11 (<code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/usr/X11R6</code>, <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/usr/openwin</code>, ...), you will have to
          add the following line into <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/etc/mk.conf</code>:</p>
          <pre class="programlisting">
    X11_TYPE=XFree86
</pre>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "x.org-from-pkgsrc"></a>7.7.&nbsp;How can I
                install/use X.org from pkgsrc?</h2>
              </div>
            </div>
          </div>

          <p>If you want to use X.org from pkgsrc instead of your
          system's own X11 (<code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/usr/X11R6</code>, <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/usr/openwin</code>, ...) you will have to add
          the following line into <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/etc/mk.conf</code>:</p>
          <pre class="programlisting">
    X11_TYPE=xorg
</pre>

          <div class="note" style=
          "margin-left: 0.5in; margin-right: 0.5in;">
            <h3 class="title">Note</h3>

            <p>The DragonFly operating system defaults to using
            this X.org X11 implementation from pkgsrc.</p>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "fetch-behind-firewall"></a>7.8.&nbsp;How to fetch
                files from behind a firewall</h2>
              </div>
            </div>
          </div>

          <p>If you are sitting behind a firewall which does not
          allow direct connections to Internet hosts (i.e.
          non-NAT), you may specify the relevant proxy hosts. This
          is done using an environment variable in the form of a
          URL, e.g. in Amdahl, the machine &#8220;<span class=
          "quote">orpheus.amdahl.com</span>&#8221; is one of the
          firewalls, and it uses port 80 as the proxy port number.
          So the proxy environment variables are:</p>
          <pre class="programlisting">
    ftp_proxy=ftp://orpheus.amdahl.com:80/
    http_proxy=http://orpheus.amdahl.com:80/
</pre>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "passive-ftp"></a>7.9.&nbsp;How do I tell
                <span><strong class="command">make
                fetch</strong></span> to do passive FTP?</h2>
              </div>
            </div>
          </div>

          <p>This depends on which utility is used to retrieve
          distfiles. From <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">bsd.pkg.mk</code>, <code class=
          "varname">FETCH_CMD</code> is assigned the first
          available command from the following list:</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${LOCALBASE}/bin/ftp</code></p>
              </li>

              <li>
                <p><code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">/usr/bin/ftp</code></p>
              </li>
            </ul>
          </div>

          <p>On a default NetBSD installation, this will be
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">/usr/bin/ftp</code>, which automatically
          tries passive connections first, and falls back to active
          connections if the server refuses to do passive. For the
          other tools, add the following to your <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/etc/mk.conf</code> file: <code class=
          "varname">PASSIVE_FETCH=1</code>.</p>

          <p>Having that option present will prevent <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/usr/bin/ftp</code> from falling back to
          active transfers.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "fetching-all-distfiles"></a>7.10.&nbsp;How to
                fetch all distfiles at once</h2>
              </div>
            </div>
          </div>

          <p>You would like to download all the distfiles in a
          single batch from work or university, where you can't run
          a <span><strong class="command">make
          fetch</strong></span>. There is an archive of distfiles
          on <a href=
          "ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/"
          target="_top">ftp.NetBSD.org</a>, but downloading the
          entire directory may not be appropriate.</p>

          <p>The answer here is to do a <span><strong class=
          "command">make fetch-list</strong></span> in <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/usr/pkgsrc</code> or one of its
          subdirectories, carry the resulting list to your machine
          at work/school and use it there. If you don't have a
          NetBSD-compatible <a href=
          "http://netbsd.gw.com/cgi-bin/man-cgi?ftp+1+NetBSD-current">
          <span class="citerefentry"><span class=
          "refentrytitle">ftp</span>(1)</span></a> (like lukemftp)
          at work, don't forget to set <code class=
          "varname">FETCH_CMD</code> to something that fetches a
          URL:</p>

          <p>At home:</p>
          <pre class="screen">
<code class="prompt">%</code> <strong class=
"userinput"><code>cd /usr/pkgsrc</code></strong>
<code class="prompt">%</code> <strong class=
"userinput"><code>make fetch-list FETCH_CMD=wget DISTDIR=/tmp/distfiles &gt;/tmp/fetch.sh</code></strong>
<code class="prompt">%</code> <strong class=
"userinput"><code>scp /tmp/fetch.sh work:/tmp</code></strong>
</pre>

          <p>At work:</p>
          <pre class="screen">
<code class="prompt">%</code> <strong class=
"userinput"><code>sh /tmp/fetch.sh</code></strong>
</pre>

          <p>then tar up <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/tmp/distfiles</code> and take it home.</p>

          <p>If you have a machine running NetBSD, and you want to
          get <span class="emphasis"><em>all</em></span> distfiles
          (even ones that aren't for your machine architecture),
          you can do so by using the above-mentioned
          <span><strong class="command">make
          fetch-list</strong></span> approach, or fetch the
          distfiles directly by running:</p>
          <pre class="screen">
<code class="prompt">%</code> <strong class=
"userinput"><code>make mirror-distfiles</code></strong>
</pre>

          <p>If you even decide to ignore <code class=
          "varname">NO_{SRC,BIN}_ON_{FTP,CDROM}</code>, then you
          can get everything by running:</p>
          <pre class="screen">
<code class="prompt">%</code> <strong class=
"userinput"><code>make fetch NO_SKIP=yes</code></strong>
</pre>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "tmac.andoc-missing"></a>7.11.&nbsp;What does
                &#8220;<span class="quote">Don't know how to make
                /usr/share/tmac/tmac.andoc</span>&#8221; mean?</h2>
              </div>
            </div>
          </div>

          <p>When compiling the <a xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" href=
          "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_install/README.html"
          target="_top"><code xmlns="" class=
          "filename">pkgtools/pkg_install</code></a> package, you
          get the error from make that it doesn't know how to make
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">/usr/share/tmac/tmac.andoc</code>? This
          indicates that you don't have installed the
          &#8220;<span class="quote">text</span>&#8221; set (nroff,
          ...) from the NetBSD base distribution on your machine.
          It is recommended to do that to format man pages.</p>

          <p>In the case of the <a xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" href=
          "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkg_install/README.html"
          target="_top"><code xmlns="" class=
          "filename">pkgtools/pkg_install</code></a> package, you
          can get away with setting <code class=
          "varname">NOMAN=YES</code> either in the environment or
          in <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">/etc/mk.conf</code>.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "bsd.own.mk-missing"></a>7.12.&nbsp;What does
                &#8220;<span class="quote">Could not find
                bsd.own.mk</span>&#8221; mean?</h2>
              </div>
            </div>
          </div>

          <p>You didn't install the compiler set, <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">comp.tgz</code>, when you installed your
          NetBSD machine. Please get and install it, by extracting
          it in <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/</code>:</p>
          <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>cd /</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>tar --unlink -zxvpf .../comp.tgz</code></strong>
</pre>

          <p><code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">comp.tgz</code> is part of every NetBSD
          release. Get the one that corresponds to your release
          (determine via <span><strong class="command">uname
          -r</strong></span>).</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "using-sudo-with-pkgsrc"></a>7.13.&nbsp;Using
                'sudo' with pkgsrc</h2>
              </div>
            </div>
          </div>

          <p>When installing packages as non-root user and using
          the just-in-time <a href=
          "http://netbsd.gw.com/cgi-bin/man-cgi?su+1+NetBSD-current">
          <span class="citerefentry"><span class=
          "refentrytitle">su</span>(1)</span></a> feature of
          pkgsrc, it can become annoying to type in the root
          password for each required package installed. To avoid
          this, the sudo package can be used, which does password
          caching over a limited time. To use it, install sudo
          (either as binary package or from <a xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" href=
          "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/sudo/README.html"
          target="_top"><code xmlns="" class=
          "filename">security/sudo</code></a>) and then put the
          following into your <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/etc/mk.conf</code>:</p>
          <pre class="programlisting">
    .if exists(${LOCALBASE}/bin/sudo)
    SU_CMD=        ${LOCALBASE}/bin/sudo /bin/sh -c
    .endif
</pre>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "faq.conf"></a>7.14.&nbsp;How do I change the
                location of configuration files?</h2>
              </div>
            </div>
          </div>

          <p>As the system administrator, you can choose where
          configuration files are installed. The default settings
          make all these files go into <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">${PREFIX}/etc</code> or some of its
          subdirectories; this may be suboptimal depending on your
          expectations (e.g., a read-only, NFS-exported
          <code class="varname">PREFIX</code> with a need of
          per-machine configuration of the provided packages).</p>

          <p>In order to change the defaults, you can modify the
          <code class="varname">PKG_SYSCONFBASE</code> variable (in
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">/etc/mk.conf</code>) to point to your
          preferred configuration directory; some common examples
          include <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/etc</code> or <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/etc/pkg</code>.</p>

          <p>Furthermore, you can change this value on a
          per-package basis by setting the <code class=
          "varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code>
          variable. <code class="varname">PKG_SYSCONFVAR</code>'s
          value usually matches the name of the package you would
          like to modify, that is, the contents of <code class=
          "varname">PKGBASE</code>.</p>

          <p>Note that after changing these settings, you must
          rebuild and reinstall any affected packages.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "audit-packages"></a>7.15.&nbsp;Automated security
                checks</h2>
              </div>
            </div>
          </div>

          <p>Please be aware that there can often be bugs in
          third-party software, and some of these bugs can leave a
          machine vulnerable to exploitation by attackers. In an
          effort to lessen the exposure, the NetBSD packages team
          maintains a database of known-exploits to packages which
          have at one time been included in pkgsrc. The database
          can be downloaded automatically, and a security audit of
          all packages installed on a system can take place. To do
          this, install the <a xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" href=
          "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/audit-packages/README.html"
          target="_top"><code xmlns="" class=
          "filename">security/audit-packages</code></a> package. It
          has two components:</p>

          <div class="orderedlist">
            <ol type="1">
              <li>
                <p><span><strong class=
                "command">download-vulnerability-list</strong></span>,
                an easy way to download a list of the security
                vulnerabilities information. This list is kept up
                to date by the NetBSD security officer and the
                NetBSD packages team, and is distributed from the
                NetBSD ftp server:</p>

                <p><a href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/pkg-vulnerabilities"
                target=
                "_top">ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/pkg-vulnerabilities</a></p>
              </li>

              <li>
                <p><span><strong class=
                "command">audit-packages</strong></span>, an easy
                way to audit the current machine, checking each
                vulnerability which is known. If a vulnerable
                package is installed, it will be shown by output to
                stdout, including a description of the type of
                vulnerability, and a URL containing more
                information.</p>
              </li>
            </ol>
          </div>

          <p>Use of the <a xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" href=
          "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/security/audit-packages/README.html"
          target="_top"><code xmlns="" class=
          "filename">security/audit-packages</code></a> package is
          strongly recommended! After &#8220;<span class=
          "quote">audit-packages</span>&#8221; is installed, please
          read the package's message, which you can get by running
          <strong class="userinput"><code>pkg_info -D
          audit-packages</code></strong>.</p>

          <p>If this package is installed, pkgsrc builds will use
          it to perform a security check before building any
          package. See <a href="#variables-affecting-build" title=
          "5.2.&nbsp;Variables affecting the build process">Section&nbsp;5.2,
          &#8220;Variables affecting the build process&#8221;</a>
          for ways to control this check.</p>
        </div>
      </div>
    </div>

    <div class="part" lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h1 class="title"><a name=
            "developers-guide"></a>Part&nbsp;II.&nbsp;The pkgsrc
            developer's guide</h1>
          </div>
        </div>
      </div>

      <div class="toc">
        <p><b>Table of Contents</b></p>

        <dl>
          <dt><span class="chapter"><a href="#components">8.
          Package components - files, directories and
          contents</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect1"><a href=
              "#components.Makefile">8.1. <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">Makefile</code></a></span></dt>

              <dt><span class="sect1"><a href=
              "#components.distinfo">8.2. <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">distinfo</code></a></span></dt>

              <dt><span class="sect1"><a href=
              "#components.patches">8.3. patches/*</a></span></dt>

              <dt><span class="sect1"><a href=
              "#other-mandatory-files">8.4. Other mandatory
              files</a></span></dt>

              <dt><span class="sect1"><a href=
              "#components.optional">8.5. Optional
              files</a></span></dt>

              <dt><span class="sect1"><a href="#work-dir">8.6.
              <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">work*</code></a></span></dt>

              <dt><span class="sect1"><a href="#files-dir">8.7.
              <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">files/*</code></a></span></dt>
            </dl>
          </dd>

          <dt><span class="chapter"><a href="#makefile">9.
          Programming in <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">Makefile</code>s</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect1"><a href=
              "#makefile.variables">9.1. <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">Makefile</code> variables</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#makefile.variables.names">9.1.1. Naming
                  conventions</a></span></dt>
                </dl>
              </dd>

              <dt><span class="sect1"><a href="#makefile.code">9.2.
              Code snippets</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#adding-to-list">9.2.1. Adding things to a
                  list</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#converting-internal-to-external">9.2.2.
                  Converting an internal list into an external
                  list</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#passing-variable-to-shell">9.2.3. Passing
                  variables to a shell command</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#quoting-guideline">9.2.4. Quoting
                  guideline</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#bsd-make-bug-workaround">9.2.5. Workaround for
                  a bug in BSD Make</a></span></dt>
                </dl>
              </dd>
            </dl>
          </dd>

          <dt><span class="chapter"><a href="#plist">10. PLIST
          issues</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect1"><a href="#rcs-id">10.1. RCS
              ID</a></span></dt>

              <dt><span class="sect1"><a href=
              "#automatic-plist-generation">10.2. Semi-automatic
              <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">PLIST</code> generation</a></span></dt>

              <dt><span class="sect1"><a href="#print-PLIST">10.3.
              Tweaking output of <span><strong class="command">make
              print-PLIST</strong></span></a></span></dt>

              <dt><span class="sect1"><a href="#plist.misc">10.4.
              Variable substitution in PLIST</a></span></dt>

              <dt><span class="sect1"><a href=
              "#manpage-compression">10.5. Man page
              compression</a></span></dt>

              <dt><span class="sect1"><a href=
              "#using-PLIST_SRC">10.6. Changing PLIST source with
              <code class=
              "varname">PLIST_SRC</code></a></span></dt>

              <dt><span class="sect1"><a href=
              "#platform-specific-plist">10.7. Platform-specific
              and differing PLISTs</a></span></dt>

              <dt><span class="sect1"><a href=
              "#faq.common-dirs">10.8. Sharing directories between
              packages</a></span></dt>
            </dl>
          </dd>

          <dt><span class="chapter"><a href="#buildlink">11.
          Buildlink methodology</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect1"><a href=
              "#converting-to-buildlink3">11.1. Converting packages
              to use buildlink3</a></span></dt>

              <dt><span class="sect1"><a href=
              "#creating-buildlink3.mk">11.2. Writing <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">buildlink3.mk</code> files</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#anatomy-of-bl3">11.2.1. Anatomy of a
                  buildlink3.mk file</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#updating-buildlink-depends">11.2.2. Updating
                  <code class=
                  "varname">BUILDLINK_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
                  in <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">buildlink3.mk</code>
                  files</a></span></dt>
                </dl>
              </dd>

              <dt><span class="sect1"><a href=
              "#writing-builtin.mk">11.3. Writing <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">builtin.mk</code> files</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#anatomy-of-builtin.mk">11.3.1. Anatomy of a
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">builtin.mk</code> file</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#native-or-pkgsrc-preference">11.3.2. Global
                  preferences for native or pkgsrc
                  software</a></span></dt>
                </dl>
              </dd>
            </dl>
          </dd>

          <dt><span class="chapter"><a href="#pkginstall">12. The
          pkginstall framework</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect1"><a href=
              "#files-and-dirs-outside-prefix">12.1. Files and
              directories outside the installation
              prefix</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#dirs-outside-prefix">12.1.1. Directory
                  manipulation</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#files-outside-prefix">12.1.2. File
                  manipulation</a></span></dt>
                </dl>
              </dd>

              <dt><span class="sect1"><a href="#conf-files">12.2.
              Configuration files</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#conf-files-sysconfdir">12.2.1. How <code class=
                  "varname">PKG_SYSCONFDIR</code> is
                  set</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#conf-files-configure">12.2.2. Telling the
                  software where configuration files
                  are</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#conf-files-patching">12.2.3. Patching
                  installations</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#conf-files-disable">12.2.4. Disabling handling
                  of configuration files</a></span></dt>
                </dl>
              </dd>

              <dt><span class="sect1"><a href="#rcd-scripts">12.3.
              System startup scripts</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#rcd-scripts-disable">12.3.1. Disabling handling
                  of system startup scripts</a></span></dt>
                </dl>
              </dd>

              <dt><span class="sect1"><a href=
              "#users-and-groups">12.4. System users and
              groups</a></span></dt>

              <dt><span class="sect1"><a href="#shells">12.5.
              System shells</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#shells-disable">12.5.1. Disabling shell
                  registration</a></span></dt>
                </dl>
              </dd>

              <dt><span class="sect1"><a href="#fonts">12.6.
              Fonts</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#fonts-disable">12.6.1. Disabling automatic
                  update of the fonts databases</a></span></dt>
                </dl>
              </dd>
            </dl>
          </dd>

          <dt><span class="chapter"><a href="#options">13. Options
          handling</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect1"><a href=
              "#global-default-options">13.1. Global default
              options</a></span></dt>

              <dt><span class="sect1"><a href=
              "#converting-to-options">13.2. Converting packages to
              use <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">bsd.options.mk</code></a></span></dt>

              <dt><span class="sect1"><a href="#option-names">13.3.
              Option Names</a></span></dt>
            </dl>
          </dd>

          <dt><span class="chapter"><a href="#build">14. The build
          process</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect1"><a href="#build.intro">14.1.
              Introduction</a></span></dt>

              <dt><span class="sect1"><a href="#build.prefix">14.2.
              Program location</a></span></dt>

              <dt><span class="sect1"><a href=
              "#build.builddirs">14.3. Directories used during the
              build process</a></span></dt>

              <dt><span class="sect1"><a href=
              "#build.running">14.4. Running a
              phase</a></span></dt>

              <dt><span class="sect1"><a href="#build.fetch">14.5.
              The <span class="emphasis"><em>fetch</em></span>
              phase</a></span></dt>

              <dt><span class="sect1"><a href=
              "#build.checksum">14.6. The <span class=
              "emphasis"><em>checksum</em></span>
              phase</a></span></dt>

              <dt><span class="sect1"><a href=
              "#build.extract">14.7. The <span class=
              "emphasis"><em>extract</em></span>
              phase</a></span></dt>

              <dt><span class="sect1"><a href="#build.patch">14.8.
              The <span class="emphasis"><em>patch</em></span>
              phase</a></span></dt>

              <dt><span class="sect1"><a href="#build.tools">14.9.
              The <span class="emphasis"><em>tools</em></span>
              phase</a></span></dt>

              <dt><span class="sect1"><a href=
              "#build.wrapper">14.10. The <span class=
              "emphasis"><em>wrapper</em></span>
              phase</a></span></dt>

              <dt><span class="sect1"><a href=
              "#build.configure">14.11. The <span class=
              "emphasis"><em>configure</em></span>
              phase</a></span></dt>

              <dt><span class="sect1"><a href="#build.build">14.12.
              The <span class="emphasis"><em>build</em></span>
              phase</a></span></dt>

              <dt><span class="sect1"><a href="#build.test">14.13.
              The <span class="emphasis"><em>test</em></span>
              phase</a></span></dt>

              <dt><span class="sect1"><a href=
              "#build.install">14.14. The <span class=
              "emphasis"><em>install</em></span>
              phase</a></span></dt>

              <dt><span class="sect1"><a href=
              "#build.package">14.15. The <span class=
              "emphasis"><em>package</em></span>
              phase</a></span></dt>

              <dt><span class="sect1"><a href=
              "#build.helpful-targets">14.16. Other helpful
              targets</a></span></dt>
            </dl>
          </dd>

          <dt><span class="chapter"><a href="#tools">15. Tools
          needed for building or running</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect1"><a href="#pkgsrc-tools">15.1.
              Tools for pkgsrc builds</a></span></dt>

              <dt><span class="sect1"><a href=
              "#package-tools">15.2. Tools needed by
              packages</a></span></dt>

              <dt><span class="sect1"><a href=
              "#platform-tools">15.3. Tools provided by
              platforms</a></span></dt>
            </dl>
          </dd>

          <dt><span class="chapter"><a href="#fixes">16. Making
          your package work</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect1"><a href=
              "#general-operation">16.1. General
              operation</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#pulling-vars-from-etc-mk.conf">16.1.1. How to
                  pull in variables from
                  /etc/mk.conf</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#where-to-install-documentation">16.1.2. Where
                  to install documentation</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#restricted-packages">16.1.3. Restricted
                  packages</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#dependencies">16.1.4. Handling
                  dependencies</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#conflicts">16.1.5. Handling conflicts with
                  other packages</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#not-building-packages">16.1.6. Packages that
                  cannot or should not be built</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#undeletable-packages">16.1.7. Packages which
                  should not be deleted, once
                  installed</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#security-handling">16.1.8. Handling packages
                  with security problems</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#compiler-bugs">16.1.9. How to handle compiler
                  bugs</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#bumping-pkgrevision">16.1.10. How to handle
                  incrementing versions when fixing an existing
                  package</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#portability-of-packages">16.1.11. Portability
                  of packages</a></span></dt>
                </dl>
              </dd>

              <dt><span class="sect1"><a href=
              "#downloading-issues">16.2. Possible downloading
              issues</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#no-plain-download">16.2.1. Packages whose
                  distfiles aren't available for plain
                  downloading</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#modified-distfiles-same-name">16.2.2. How to
                  handle modified distfiles with the 'old'
                  name</a></span></dt>
                </dl>
              </dd>

              <dt><span class="sect1"><a href=
              "#configuration-gotchas">16.3. Configuration
              gotchas</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#fixes.libtool">16.3.1. Shared libraries -
                  libtool</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#using-libtool">16.3.2. Using libtool on GNU
                  packages that already support
                  libtool</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#autoconf-automake">16.3.3. GNU
                  Autoconf/Automake</a></span></dt>
                </dl>
              </dd>

              <dt><span class="sect1"><a href="#fixes-build">16.4.
              Building the package</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#cpp-defines">16.4.1. CPP
                  defines</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#cpp-list-examples">16.4.2. Examples of CPP
                  defines for some platforms</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#cpp-list">16.4.3. Getting a list of CPP
                  defines</a></span></dt>
                </dl>
              </dd>

              <dt><span class="sect1"><a href=
              "#package-specific-actions">16.5. Package specific
              actions</a></span></dt>

              <dd>
                <dl>
                  <dt><span class="sect2"><a href=
                  "#user-interaction">16.5.1. User
                  interaction</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#handling-licenses">16.5.2. Handling
                  licenses</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#installing-score-files">16.5.3. Installing
                  score files</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#perl-scripts">16.5.4. Packages containing perl
                  scripts</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#hardcoded-paths">16.5.5. Packages with
                  hardcoded paths to other
                  interpreters</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#perl-modules">16.5.6. Packages installing perl
                  modules</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#faq.info-files">16.5.7. Packages installing
                  info files</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#manpages">16.5.8. Packages installing man
                  pages</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#gconf2-data-files">16.5.9. Packages installing
                  GConf2 data files</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#scrollkeeper-data-files">16.5.10. Packages
                  installing scrollkeeper data
                  files</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#x11-fonts">16.5.11. Packages installing X11
                  fonts</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#gtk2-modules">16.5.12. Packages installing GTK2
                  modules</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#sgml-xml-data">16.5.13. Packages installing
                  SGML or XML data</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#mime-database">16.5.14. Packages installing
                  extensions to the MIME database</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#intltool">16.5.15. Packages using
                  intltool</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#startup-scripts">16.5.16. Packages installing
                  startup scripts</a></span></dt>

                  <dt><span class="sect2"><a href=
                  "#tex-packages">16.5.17. Packages installing TeX
                  modules</a></span></dt>
                </dl>
              </dd>

              <dt><span class="sect1"><a href=
              "#feedback-to-author">16.6. Feedback to the
              author</a></span></dt>
            </dl>
          </dd>

          <dt><span class="chapter"><a href="#debug">17.
          Debugging</a></span></dt>

          <dt><span class="chapter"><a href="#submit">18.
          Submitting and Committing</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect1"><a href=
              "#submitting-your-package">18.1. Submitting your
              packages</a></span></dt>

              <dt><span class="sect1"><a href=
              "#general-notes-for-changes">18.2. General notes when
              adding, updating, or removing
              packages</a></span></dt>

              <dt><span class="sect1"><a href=
              "#committing-importing">18.3. Committing: Importing a
              package into CVS</a></span></dt>

              <dt><span class="sect1"><a href=
              "#updating-package">18.4. Updating a package to a
              newer version</a></span></dt>

              <dt><span class="sect1"><a href=
              "#moving-package">18.5. Moving a package in
              pkgsrc</a></span></dt>
            </dl>
          </dd>

          <dt><span class="chapter"><a href="#porting">19. Porting
          pkgsrc</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect1"><a href=
              "#porting.opsys">19.1. Porting pkgsrc to a new
              operating system</a></span></dt>

              <dt><span class="sect1"><a href=
              "#porting.compiler">19.2. Adding support for a new
              compiler</a></span></dt>
            </dl>
          </dd>
        </dl>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "components"></a>Chapter&nbsp;8.&nbsp;Package
              components - files, directories and contents</h2>
            </div>
          </div>
        </div>

        <div class="toc">
          <p><b>Table of Contents</b></p>

          <dl>
            <dt><span class="sect1"><a href=
            "#components.Makefile">8.1. <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">Makefile</code></a></span></dt>

            <dt><span class="sect1"><a href=
            "#components.distinfo">8.2. <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">distinfo</code></a></span></dt>

            <dt><span class="sect1"><a href=
            "#components.patches">8.3. patches/*</a></span></dt>

            <dt><span class="sect1"><a href=
            "#other-mandatory-files">8.4. Other mandatory
            files</a></span></dt>

            <dt><span class="sect1"><a href=
            "#components.optional">8.5. Optional
            files</a></span></dt>

            <dt><span class="sect1"><a href="#work-dir">8.6.
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">work*</code></a></span></dt>

            <dt><span class="sect1"><a href="#files-dir">8.7.
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">files/*</code></a></span></dt>
          </dl>
        </div>

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

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "components.Makefile"></a>8.1.&nbsp;<code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">Makefile</code></h2>
              </div>
            </div>
          </div>

          <p>Building, installation and creation of a binary
          package are all controlled by the package's <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">Makefile</code>. The <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">Makefile</code> describes various things about
          a package, for example from where to get it, how to
          configure, build, and install it.</p>

          <p>A package <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">Makefile</code> contains several sections that
          describe the package.</p>

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

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><code class="varname">DISTNAME</code> is the
                basename of the distribution file to be downloaded
                from the package's website.</p>
              </li>

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

              <li>
                <p><code class="varname">CATEGORIES</code> is a
                list of categories which the package fits in. You
                can choose any of the top-level directories of
                pkgsrc for it.</p>

                <p>Currently the following values are available for
                <code class="varname">CATEGORIES</code>. If more
                than one is used, they need to be separated by
                spaces:</p>
                <pre class="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
</pre>
              </li>

              <li>
                <p><code class="varname">MASTER_SITES</code> is a
                list of URLs where the distribution files can be
                downloaded. Each URL must end with a slash.</p>

                <p>The <code class="varname">MASTER_SITES</code>
                may make use of the following predefined sites:</p>
                <pre class="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}
</pre>

                <p>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 <span class=
                "emphasis"><em>must</em></span> use the following
                construct to specify a subdirectory:</p>
                <pre class="programlisting">
    ${MASTER_SITE_GNU:=subdirectory/name/}
    ${MASTER_SITE_SOURCEFORGE:=project_name/}
</pre>

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

                <p>If the package has multiple <code class=
                "varname">DISTFILES</code> or multiple <code class=
                "varname">PATCHFILES</code> from different sites,
                set <code class="varname">SITES_foo</code> to a
                list of URIs where file &#8220;<span class=
                "quote">foo</span>&#8221; may be found.
                &#8220;<span class="quote">foo</span>&#8221;
                includes the suffix, e.g.:</p>
                <pre class="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/
</pre>
              </li>

              <li>
                <p><code class="varname">DISTFILES</code>: Name(s)
                of archive file(s) containing distribution. The
                default is <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${DISTNAME}${EXTRACT_SUFX}</code>.
                Should only be set if you have more than one
                distfile.</p>

                <p>Note that the normal default setting of
                <code class="varname">DISTFILES</code> must be made
                explicit if you want to add to it (rather than
                replace it), as you usually would.</p>
              </li>

              <li>
                <p><code class="varname">EXTRACT_SUFX</code>:
                Suffix of the distribution file, will be appended
                to <code class="varname">DISTNAME</code>. Defaults
                to <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">.tar.gz</code>.</p>
              </li>
            </ul>
          </div>

          <p>The second section contains information about
          separately downloaded patches, if any.</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><code class="varname">PATCHFILES:</code> Name(s)
                of additional files that contain distribution
                patches. There is no default. pkgsrc will look for
                them at <code class="varname">PATCH_SITES</code>.
                They will automatically be uncompressed before
                patching if the names end with <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">.gz</code> or <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">.Z</code>.</p>
              </li>

              <li>
                <p><code class="varname">PATCH_SITES</code>:
                Primary location(s) for distribution patch files
                (see <code class="varname">PATCHFILES</code> below)
                if not found locally.</p>
              </li>
            </ul>
          </div>

          <p>The third section contains the following
          variables.</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><code class="varname">MAINTAINER</code> 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 <a href=
                "http://netbsd.gw.com/cgi-bin/man-cgi?send-pr+1+NetBSD-current">
                <span class="citerefentry"><span class=
                "refentrytitle">send-pr</span>(1)</span></a>. Other
                developers should contact the <code class=
                "varname">MAINTAINER</code> before making major
                changes to the package. When packaging a new
                program, set <code class=
                "varname">MAINTAINER</code> to yourself. If you
                really can't maintain the package for future
                updates, set it to <code class="email">&lt;<a href=
                "mailto:pkgsrc-users@NetBSD.org">pkgsrc-users@NetBSD.org</a>&gt;</code>.</p>
              </li>

              <li>
                <p><code class="varname">HOMEPAGE</code> is a URL
                where users can find more information about the
                package.</p>
              </li>

              <li>
                <p><code class="varname">COMMENT</code> is a
                one-line description of the package (should not
                include the package name).</p>
              </li>
            </ul>
          </div>

          <p>Other variables that affect the build:</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><code class="varname">WRKSRC</code>: The
                directory where the interesting distribution files
                of the package are found. The default is
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${WRKDIR}/${DISTNAME}</code>, which
                works for most packages.</p>

                <p>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 <code class="varname">WRKSRC=
                ${WRKDIR}</code>.</p>

                <p>If a package doesn't create a subdirectory with
                the name of <code class="varname">DISTNAME</code>
                but some different name, set <code class=
                "varname">WRKSRC</code> to point to the proper name
                in <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${WRKDIR}</code>, for example
                <code class="varname">WRKSRC=
                ${WRKDIR}/${DISTNAME}/unix</code>. See <a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/lang/tcl/README.html"
                target="_top"><code xmlns="" class=
                "filename">lang/tcl</code></a> and <a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/x11/tk/README.html"
                target="_top"><code xmlns="" class=
                "filename">x11/tk</code></a> for other
                examples.</p>

                <p>The name of the working directory created by
                pkgsrc is taken from the <code class=
                "varname">WRKDIR_BASENAME</code> variable. By
                default, its value is <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">work</code>. 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 <code class=
                "varname">WRKDIR_BASENAME</code> individually. If
                <code class="varname">OBJHOSTNAME</code> is defined
                in <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">/etc/mk.conf</code>, the first component
                of the host's name is attached to the directory
                name. If <code class="varname">OBJMACHINE</code> is
                defined, the platform name is attached, which might
                look like <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">work.i386</code> or <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">work.sparc</code>.</p>
              </li>
            </ul>
          </div>

          <p>Please pay attention to the following gotchas:</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p>Add <code class="varname">MANCOMPRESSED</code>
                if man pages are installed in compressed form by
                the package; see comment in <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">bsd.pkg.mk</code>.</p>
              </li>

              <li>
                <p>Replace <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">/usr/local</code> with
                &#8220;<span class="quote">${PREFIX}</span>&#8221;
                in all files (see patches, below).</p>
              </li>

              <li>
                <p>If the package installs any info files, see
                <a href="#faq.info-files" title=
                "16.5.7.&nbsp;Packages installing info files">Section&nbsp;16.5.7,
                &#8220;Packages installing info
                files&#8221;</a>.</p>
              </li>
            </ul>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "components.distinfo"></a>8.2.&nbsp;<code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">distinfo</code></h2>
              </div>
            </div>
          </div>

          <p>The <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">distinfo</code> 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.</p>

          <p>The <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">distinfo</code> file also contains the
          checksums for all the patches found in the <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">patches</code> directory (see <a href=
          "#components.patches" title=
          "8.3.&nbsp;patches/*">Section&nbsp;8.3,
          &#8220;patches/*&#8221;</a>).</p>

          <p>To regenerate the <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">distinfo</code> file, use the
          <span><strong class="command">make
          makedistinfo</strong></span> or <span><strong class=
          "command">make mdi</strong></span> command.</p>

          <p>Some packages have different sets of distfiles
          depending on the platform, for example <a xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" href=
          "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/navigator/README.html"
          target="_top"><code xmlns="" class=
          "filename">www/navigator</code></a>). These are kept in
          the same <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">distinfo</code> file and care should be taken
          when upgrading such a package to ensure distfile
          information is not lost.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "components.patches"></a>8.3.&nbsp;patches/*</h2>
              </div>
            </div>
          </div>

          <p>This directory contains files that are used by the
          <a href=
          "http://netbsd.gw.com/cgi-bin/man-cgi?patch+1+NetBSD-current">
          <span class="citerefentry"><span class=
          "refentrytitle">patch</span>(1)</span></a> command to
          modify the sources as distributed in the distribution
          file into a form that will compile and run perfectly on
          NetBSD. The files are applied successively in alphabetic
          order (as returned by a shell &#8220;<span class=
          "quote">patches/patch-*</span>&#8221; glob expansion), so
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">patch-aa</code> is applied before
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">patch-ab</code>, etc.</p>

          <p>The <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">patch-*</code> files should be in
          <span><strong class="command">diff -bu</strong></span>
          format, and apply without a fuzz to avoid problems. (To
          force patches to apply with fuzz you can set <code class=
          "varname">PATCH_FUZZ_FACTOR=-F2</code>). Furthermore, do
          not put changes for more than one file into a single
          patch file, as this will make future modifications more
          difficult.</p>

          <p>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.</p>

          <p>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 NetBSD
          CVS tree. Use the <span><strong class=
          "command">pkgdiff</strong></span> from the <a xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" href=
          "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdiff/README.html"
          target="_top"><code xmlns="" class=
          "filename">pkgtools/pkgdiff</code></a> package to avoid
          these problems.</p>

          <p>For even more automation, we recommend using
          <span><strong class="command">mkpatches</strong></span>
          from the same package to make a whole set of patches. You
          just have to backup files before you edit them to
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">filename.orig</code>, e.g. with
          <span><strong class="command">cp -p filename
          filename.orig</strong></span> or, easier, by using
          <span><strong class="command">pkgvi</strong></span> 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 <span><strong class=
          "command">patchdiff</strong></span>.</p>

          <p>When you have finished a package, remember to generate
          the checksums for the patch files by using the
          <span><strong class="command">make
          makepatchsum</strong></span> command, see <a href=
          "#components.distinfo" title=
          "8.2.&nbsp;distinfo">Section&nbsp;8.2,
          &#8220;<code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">distinfo</code>&#8221;</a>.</p>

          <p>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.</p>

          <p>Patch files that are distributed by the author or
          other maintainers can be listed in <code class=
          "varname">$PATCHFILES</code>.</p>

          <p>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 <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">$LOCALPATCHES</code> directory. The directory
          tree there is expected to have the same
          &#8220;<span class="quote">category/package</span>&#8221;
          structure as pkgsrc, and patches are expected to be
          stored inside these dirs (also known as <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">$LOCALPATCHES/$PKGPATH</code>). For example,
          if you want to keep a private patch for <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">pkgsrc/graphics/png</code>, keep it in
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class=
          "filename">$LOCALPATCHES/graphics/png/mypatch</code>. All
          files in the named directory are expected to be patch
          files, and <span class="emphasis"><em>they are applied
          after pkgsrc patches are applied</em></span>.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "other-mandatory-files"></a>8.4.&nbsp;Other
                mandatory files</h2>
              </div>
            </div>
          </div>

          <div class="variablelist">
            <dl>
              <dt><span class="term"><code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">DESCR</code></span></dt>

              <dd>
                <p>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.</p>
              </dd>

              <dt><span class="term"><code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">PLIST</code></span></dt>

              <dd>
                <p>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 <a href="#plist" title=
                "Chapter&nbsp;10.&nbsp;PLIST issues">Chapter&nbsp;10,
                <i>PLIST issues</i></a> for more information.</p>
              </dd>
            </dl>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "components.optional"></a>8.5.&nbsp;Optional
                files</h2>
              </div>
            </div>
          </div>

          <div class="variablelist">
            <dl>
              <dt><span class="term"><code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">INSTALL</code></span></dt>

              <dd>
                <p>This shell script is invoked twice by <a href=
                "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
                <span class="citerefentry"><span class=
                "refentrytitle">pkg_add</span>(1)</span></a>. 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 <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">PLIST</code>. See <a href=
                "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
                <span class="citerefentry"><span class=
                "refentrytitle">pkg_add</span>(1)</span></a> and
                <a href=
                "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_create+1+NetBSD-current">
                <span class="citerefentry"><span class=
                "refentrytitle">pkg_create</span>(1)</span></a> for
                more information.</p>
              </dd>

              <dt><span class="term"><code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">DEINSTALL</code></span></dt>

              <dd>
                <p>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 <a href=
                "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1+NetBSD-current">
                <span class="citerefentry"><span class=
                "refentrytitle">pkg_delete</span>(1)</span></a> and
                <a href=
                "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_create+1+NetBSD-current">
                <span class="citerefentry"><span class=
                "refentrytitle">pkg_create</span>(1)</span></a> for
                more information.</p>
              </dd>

              <dt><span class="term"><code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">MESSAGE</code></span></dt>

              <dd>
                <p>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 <code class=
                "varname">MESSAGE_SUBST</code> in the package's
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">Makefile</code>:</p>
                <pre class="programlisting">
    MESSAGE_SUBST+=  SOMEVAR="somevalue"
</pre>

                <p>replaces "${SOMEVAR}" with &#8220;<span class=
                "quote">somevalue</span>&#8221; in <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">MESSAGE</code>.</p>
              </dd>
            </dl>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "work-dir"></a>8.6.&nbsp;<code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">work*</code></h2>
              </div>
            </div>
          </div>

          <p>When you type <span><strong class=
          "command">make</strong></span>, the distribution files
          are unpacked into the directory denoted by <code class=
          "varname">WRKDIR</code>. It can be removed by running
          <span><strong class="command">make clean</strong></span>.
          Besides the sources, this directory is also used to keep
          various timestamp files. The directory gets <span class=
          "emphasis"><em>removed completely</em></span> on clean.
          The default is <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">${.CURDIR}/work</code> or <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">${.CURDIR}/work.${MACHINE_ARCH}</code> if
          <code class="varname">OBJMACHINE</code> is set.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "files-dir"></a>8.7.&nbsp;<code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">files/*</code></h2>
              </div>
            </div>
          </div>

          <p>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 &#8220;<span class=
          "quote">${CP}</span>&#8221; command in the
          &#8220;<span class="quote">pre-configure</span>&#8221;
          target to achieve this. Alternatively, you could simply
          diff the file against <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/dev/null</code> and use the patch mechanism
          to manage the creation of this file.</p>
        </div>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "makefile"></a>Chapter&nbsp;9.&nbsp;Programming in
              <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">Makefile</code>s</h2>
            </div>
          </div>
        </div>

        <div class="toc">
          <p><b>Table of Contents</b></p>

          <dl>
            <dt><span class="sect1"><a href=
            "#makefile.variables">9.1. <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">Makefile</code> variables</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#makefile.variables.names">9.1.1. Naming
                conventions</a></span></dt>
              </dl>
            </dd>

            <dt><span class="sect1"><a href="#makefile.code">9.2.
            Code snippets</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#adding-to-list">9.2.1. Adding things to a
                list</a></span></dt>

                <dt><span class="sect2"><a href=
                "#converting-internal-to-external">9.2.2.
                Converting an internal list into an external
                list</a></span></dt>

                <dt><span class="sect2"><a href=
                "#passing-variable-to-shell">9.2.3. Passing
                variables to a shell command</a></span></dt>

                <dt><span class="sect2"><a href=
                "#quoting-guideline">9.2.4. Quoting
                guideline</a></span></dt>

                <dt><span class="sect2"><a href=
                "#bsd-make-bug-workaround">9.2.5. Workaround for a
                bug in BSD Make</a></span></dt>
              </dl>
            </dd>
          </dl>
        </div>

        <p>Pkgsrc consists of many <code xmlns=
        "http://www.w3.org/TR/xhtml1/transitional" class=
        "filename">Makefile</code> fragments, each of which forms a
        well-defined part of the pkgsrc system. Using the <a href=
        "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
        <span class="citerefentry"><span class=
        "refentrytitle">make</span>(1)</span></a> system as a
        programming language for a big system like pkgsrc requires
        some discipline to keep the code correct and
        understandable.</p>

        <p>The basic ingredients for <code xmlns=
        "http://www.w3.org/TR/xhtml1/transitional" class=
        "filename">Makefile</code> programming are variables (which
        are actually macros) and shell commands. Among these shell
        commands may even be more complex ones like <a href=
        "http://netbsd.gw.com/cgi-bin/man-cgi?awk+1+NetBSD-current">
        <span class="citerefentry"><span class=
        "refentrytitle">awk</span>(1)</span></a> programs. To make
        sure that every shell command runs as intended it is
        necessary to quote all variables correctly when they are
        used.</p>

        <p>This chapter describes some patterns, that appear quite
        often in <code xmlns=
        "http://www.w3.org/TR/xhtml1/transitional" class=
        "filename">Makefile</code>s, including the pitfalls that
        come along with them.</p>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "makefile.variables"></a>9.1.&nbsp;<code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">Makefile</code> variables</h2>
              </div>
            </div>
          </div>

          <p><code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">Makefile</code> variables contain
          strings that can be processed using the five operators
          ``='', ``+='', ``?='', ``:='', and ``!='', which are
          described in the <a href=
          "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
          <span class="citerefentry"><span class=
          "refentrytitle">make</span>(1)</span></a> man page.</p>

          <p>When a variable's value is parsed from a <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">Makefile</code>, the hash character ``#'' and
          the backslash character ``\'' are handled specially. If a
          backslash is followed by a newline, any whitespace
          immediately in front of the backslash, the backslash, the
          newline, and any whitespace immediately behind the
          newline are replaced with a single space. A backspace
          character and an immediately following hash character are
          replaced with a single hash character. Otherwise, the
          backslash is passed as is. In a variable assignment, any
          hash character that is not preceded by a backslash starts
          a comment that continues upto the end of the logical
          line.</p>

          <p><span class="emphasis"><em>Note:</em></span> Because
          of this parsing algorithm the only way to create a
          variable consisting of a single backslash is using the
          ``!='' operator, for example: <code class=
          "varname">BACKSLASH!=echo "\\"</code>.</p>

          <p>So far for defining variables. The other thing you can
          do with variables is evaluating them. A variable is
          evaluated when it is part of the right side of the ``:=''
          or the ``!='' operator, or directly before executing a
          shell command which the variable is part of. In all other
          cases, <a href=
          "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
          <span class="citerefentry"><span class=
          "refentrytitle">make</span>(1)</span></a> performs lazy
          evaluation, that is, variables are not evaluated until
          there's no other way. The ``modifiers'' mentioned in the
          man page also evaluate the variable.</p>

          <p>Some of the modifiers split the string into words and
          then operate on the words, others operate on the string
          as a whole. When a string is split into words, it is
          split as you would expect it from <a href=
          "http://netbsd.gw.com/cgi-bin/man-cgi?sh+1+NetBSD-current">
          <span class="citerefentry"><span class=
          "refentrytitle">sh</span>(1)</span></a>.</p>

          <p>No rule without exception&#8212;the
          <span><strong class="command">.for</strong></span> loop
          does not follow the shell quoting rules but splits at
          sequences of whitespace.</p>

          <p>There are several types of variables that should be
          handled differently. Strings and two types of lists.</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><span class="emphasis"><em>Strings</em></span>
                can contain arbitrary characters. Nevertheless, you
                should restrict yourself to only using printable
                characters. Examples are <code class=
                "varname">PREFIX</code> and <code class=
                "varname">COMMENT</code>.</p>
              </li>

              <li>
                <p><span class="emphasis"><em>Internal
                lists</em></span> are lists that are never exported
                to any shell command. Their elements are separated
                by whitespace. Therefore, the elements themselves
                cannot have embedded whitespace. Any other
                characters are allowed. Internal lists can be used
                in <span><strong class=
                "command">.for</strong></span> loops. Examples are
                <code class="varname">DEPENDS</code> and
                <code class="varname">BUILD_DEPENDS</code>.</p>
              </li>

              <li>
                <p><span class="emphasis"><em>External
                lists</em></span> are lists that may be exported to
                a shell command. Their elements can contain any
                characters, including whitespace. That's why they
                cannot be used in <span><strong class=
                "command">.for</strong></span> loops. Examples are
                <code class="varname">DISTFILES</code> and
                <code class="varname">MASTER_SITES</code>.</p>
              </li>
            </ul>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "makefile.variables.names"></a>9.1.1.&nbsp;Naming
                  conventions</h3>
                </div>
              </div>
            </div>

            <div class="itemizedlist">
              <ul type="disc">
                <li>
                  <p>All variable names starting with an underscore
                  are reserved for use by the pkgsrc
                  infrastructure. They shall not be used by package
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">Makefile</code>s.</p>
                </li>

                <li>
                  <p>In <span><strong class=
                  "command">.for</strong></span> loops you should
                  use lowercase variable names for the iteration
                  variables.</p>
                </li>

                <li>
                  <p>All list variables should have a ``plural''
                  name, e.g. <code class=
                  "varname">PKG_OPTIONS</code> or <code class=
                  "varname">DISTFILES</code>.</p>
                </li>
              </ul>
            </div>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "makefile.code"></a>9.2.&nbsp;Code snippets</h2>
              </div>
            </div>
          </div>

          <p>This section presents you with some code snippets you
          should use in your own code. If you don't find anything
          appropriate here, you should test your code and add it
          here.</p>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "adding-to-list"></a>9.2.1.&nbsp;Adding things to
                  a list</h3>
                </div>
              </div>
            </div>
            <pre class="programlisting">
    STRING=                 foo * bar `date`
    INT_LIST=               # empty
    ANOTHER_INT_LIST=       apache-[0-9]*:../../www/apache
    EXT_LIST=               # empty
    ANOTHER_EXT_LIST=       a=b c=d

    INT_LIST+=              ${STRING}               # 1
    INT_LIST+=              ${ANOTHER_INT_LIST}     # 2
    EXT_LIST+=              ${STRING:Q}             # 3
    EXT_LIST+=              ${ANOTHER_EXT_LIST}     # 4
</pre>

            <p>When you add a string to an external list (example
            3), it must be quoted. In all other cases, you must not
            add a quoting level. You must not merge internal and
            external lists, unless you are sure that all entries
            are correctly interpreted in both lists.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "converting-internal-to-external"></a>9.2.2.&nbsp;Converting
                  an internal list into an external list</h3>
                </div>
              </div>
            </div>
            <pre class="programlisting">
    EXT_LIST=       # empty
    .for i in ${INT_LIST}
    EXT_LIST+=      ${i:Q}""
    .endfor
</pre>

            <p>This code converts the internal list <code class=
            "varname">INT_LIST</code> into the external list
            <code class="varname">EXT_LIST</code>. As the elements
            of an internal list are unquoted they must be quoted
            here. The reason for appending <code class=
            "varname">""</code> is explained below.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "passing-variable-to-shell"></a>9.2.3.&nbsp;Passing
                  variables to a shell command</h3>
                </div>
              </div>
            </div>
            <pre class="programlisting">
    STRING=         foo bar &lt;    &gt; * `date` $$HOME ' "
    EXT_LIST=       string=${STRING:Q} x=second\ item

    all:
            echo ${STRING}                  # 1
            echo "${STRING}"                # 2
            echo "${STRING:Q}"              # 3
            echo ${STRING:Q}                # 4
            echo x${STRING:Q} | sed 1s,.,,  # 5
            env ${EXT_LIST} /bin/sh -c 'echo "$$string"; echo "$$x"'
</pre>

            <p>Example 1 leads to a syntax error in the shell, as
            the characters are just copied.</p>

            <p>Example 2 leads to a syntax error too, and if you
            leave out the last " character from <code class=
            "varname">${STRING}</code>, <a href=
            "http://netbsd.gw.com/cgi-bin/man-cgi?date+1+NetBSD-current">
            <span class="citerefentry"><span class=
            "refentrytitle">date</span>(1)</span></a> will be
            executed. The <code class="varname">$HOME</code> shell
            variable would be evaluated, too.</p>

            <p>Example 3 outputs each space character preceded by a
            backslash (or not), depending on the implementation of
            the <a href=
            "http://netbsd.gw.com/cgi-bin/man-cgi?echo+1+NetBSD-current">
            <span class="citerefentry"><span class=
            "refentrytitle">echo</span>(1)</span></a> command.</p>

            <p>Example 4 handles correctly every string that does
            not start with a dash. In that case, the result depends
            on the implementation of the <a href=
            "http://netbsd.gw.com/cgi-bin/man-cgi?echo+1+NetBSD-current">
            <span class="citerefentry"><span class=
            "refentrytitle">echo</span>(1)</span></a> command. As
            long as you can guarantee that your input does not
            start with a dash, this form is appropriate.</p>

            <p>Example 5 handles even the case of a leading dash
            correctly.</p>

            <p>The <code class="varname">EXT_LIST</code> does not
            need to be quoted because the quoting has already been
            done when adding elements to the list.</p>

            <p>As internal lists shall not be passed to the shell,
            there is no example for it.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "quoting-guideline"></a>9.2.4.&nbsp;Quoting
                  guideline</h3>
                </div>
              </div>
            </div>

            <p>There are many possible sources of wrongly quoted
            variables. This section lists some of the commonly
            known ones.</p>

            <div class="itemizedlist">
              <ul type="disc">
                <li>
                  <p>Whenever you use the value of a list, think
                  about what happens to leading or trailing
                  whitespace. If the list is a well-formed shell
                  expression, you can apply the <code class=
                  "varname">:M*</code> modifier to strip leading
                  and trailing whitespace from each word. The
                  <code class="varname">:M</code> operator first
                  splits its argument according to the rules of the
                  shell, and then creates a new list consisting of
                  all words that match the shell glob expression
                  <code class="varname">*</code>, that is: all. One
                  class of situations where this is needed is when
                  adding a variable like <code class=
                  "varname">CPPFLAGS</code> to <code class=
                  "varname">CONFIGURE_ARGS</code>. If the configure
                  script invokes other configure scripts, it strips
                  the leading and trailing whitespace from the
                  variable and then passes it to the other
                  configure scripts. But these configure scripts
                  expect the (child) <code class=
                  "varname">CPPFLAGS</code> variable to be the same
                  as the parent <code class=
                  "varname">CPPFLAGS</code>. That's why we better
                  pass the <code class="varname">CPPFLAGS</code>
                  value properly trimmed. And here is how we do
                  it:</p>
                  <pre class="programlisting">
    CPPFLAGS=               # empty
    CPPFLAGS+=              -Wundef -DPREFIX=\"${PREFIX:Q}\"
    CPPFLAGS+=              ${MY_CPPFLAGS}

    CONFIGURE_ARGS+=        CPPFLAGS=${CPPFLAGS:M*:Q}

    all:
            echo x${CPPFLAGS:Q}x            # leading and trailing whitespace
            echo x${CONFIGURE_ARGS}x        # properly trimmed
</pre>
                </li>

                <li>
                  <p>The example above contains one bug: The
                  <code class="varname">${PREFIX}</code> is a
                  properly quoted shell expression, but there is
                  the C compiler after it, which also expects a
                  properly quoted string (this time in C syntax).
                  The version above is therefore only correct if
                  <code class="varname">${PREFIX}</code> does not
                  have embedded backslashes or double quotes. If
                  you want to allow these, you have to add another
                  layer of quoting to each variable that is used as
                  a C string literal. You cannot use the
                  <code class="varname">:Q</code> operator for it,
                  as this operator only works for the shell.</p>
                </li>

                <li>
                  <p>Whenever a variable can be empty, the
                  <code class="varname">:Q</code> operator can have
                  surprising results. Here are two completely
                  different cases which can be solved with the same
                  trick.</p>
                  <pre class="programlisting">
    EMPTY=                  # empty
    empty_test:
            for i in a ${EMPTY:Q} c; do \
                    echo "$$i"; \
            done

    for_test:
    .for i in a:\ a:\test.txt
            echo ${i:Q}
            echo "foo"
    .endfor
</pre>

                  <p>The first example will only print two of the
                  three lines we might have expected. This is
                  because <code class="varname">${EMPTY:Q}</code>
                  expands to the empty string, which the shell
                  cannot see. The workaround is to write
                  <code class="varname">${EMPTY:Q}""</code>. This
                  pattern can be often found as <code class=
                  "varname">${TEST} -z ${VAR:Q}</code> or as
                  <code class="varname">${TEST} -f
                  ${FNAME:Q}</code> (both of these are wrong).</p>

                  <p>The second example will only print three lines
                  instead of four. The first line looks like
                  <code class="varname">a:\ echo foo</code>. This
                  is because the backslash of the value
                  <code class="varname">a:\</code> is interpreted
                  as a line-continuation by <a href=
                  "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
                  <span class="citerefentry"><span class=
                  "refentrytitle">make</span>(1)</span></a>, which
                  makes the second line the arguments of the
                  <a href=
                  "http://netbsd.gw.com/cgi-bin/man-cgi?echo+1+NetBSD-current">
                  <span class="citerefentry"><span class=
                  "refentrytitle">echo</span>(1)</span></a> command
                  from the first line. To avoid this, write
                  <code class="varname">${i:Q}""</code>.</p>
                </li>
              </ul>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "bsd-make-bug-workaround"></a>9.2.5.&nbsp;Workaround
                  for a bug in BSD Make</h3>
                </div>
              </div>
            </div>

            <p>The pkgsrc bmake program does not handle the
            following assignment correctly. In case <code class=
            "varname">_othervar_</code> contains a ``-'' character,
            one of the closing braces is included in <code class=
            "varname">${VAR}</code> after this code executes.</p>
            <pre class="programlisting">
    VAR:=   ${VAR:N${_othervar_:C/-//}}
</pre>

            <p>For a more complex code snippet and a workaround,
            see the package <a xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" href=
            "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/regress/make-quoting/README.html"
            target="_top"><code xmlns="" class=
            "filename">regress/make-quoting</code></a>, testcase
            <code class="varname">bug1</code>.</p>
          </div>
        </div>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "plist"></a>Chapter&nbsp;10.&nbsp;PLIST issues</h2>
            </div>
          </div>
        </div>

        <div class="toc">
          <p><b>Table of Contents</b></p>

          <dl>
            <dt><span class="sect1"><a href="#rcs-id">10.1. RCS
            ID</a></span></dt>

            <dt><span class="sect1"><a href=
            "#automatic-plist-generation">10.2. Semi-automatic
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">PLIST</code>
            generation</a></span></dt>

            <dt><span class="sect1"><a href="#print-PLIST">10.3.
            Tweaking output of <span><strong class="command">make
            print-PLIST</strong></span></a></span></dt>

            <dt><span class="sect1"><a href="#plist.misc">10.4.
            Variable substitution in PLIST</a></span></dt>

            <dt><span class="sect1"><a href=
            "#manpage-compression">10.5. Man page
            compression</a></span></dt>

            <dt><span class="sect1"><a href=
            "#using-PLIST_SRC">10.6. Changing PLIST source with
            <code class="varname">PLIST_SRC</code></a></span></dt>

            <dt><span class="sect1"><a href=
            "#platform-specific-plist">10.7. Platform-specific and
            differing PLISTs</a></span></dt>

            <dt><span class="sect1"><a href=
            "#faq.common-dirs">10.8. Sharing directories between
            packages</a></span></dt>
          </dl>
        </div>

        <p>The <code xmlns=
        "http://www.w3.org/TR/xhtml1/transitional" class=
        "filename">PLIST</code> file contains a package's
        &#8220;<span class="quote">packing list</span>&#8221;, i.e.
        a list of files that belong to the package (relative to the
        <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
        class="filename">${PREFIX}</code> directory it's been
        installed in) plus some additional statements - see the
        <a href=
        "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_create+1+NetBSD-current">
        <span class="citerefentry"><span class=
        "refentrytitle">pkg_create</span>(1)</span></a> man page
        for a full list. This chapter addresses some issues that
        need attention when dealing with the <code xmlns=
        "http://www.w3.org/TR/xhtml1/transitional" class=
        "filename">PLIST</code> file (or files, see below!).</p>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "rcs-id"></a>10.1.&nbsp;RCS ID</h2>
              </div>
            </div>
          </div>

          <p>Be sure to add a RCS ID line as the first thing in any
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">PLIST</code> file you write:</p>
          <pre class="programlisting">
    @comment $NetBSD$
</pre>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "automatic-plist-generation"></a>10.2.&nbsp;Semi-automatic
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">PLIST</code> generation</h2>
              </div>
            </div>
          </div>

          <p>You can use the <span><strong class="command">make
          print-PLIST</strong></span> command to output a PLIST
          that matches any new files since the package was
          extracted. See <a href="#build.helpful-targets" title=
          "14.16.&nbsp;Other helpful targets">Section&nbsp;14.16,
          &#8220;Other helpful targets&#8221;</a> for more
          information on this target.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "print-PLIST"></a>10.3.&nbsp;Tweaking output of
                <span><strong class="command">make
                print-PLIST</strong></span></h2>
              </div>
            </div>
          </div>

          <p>If you have used any of the *-dirs packages, as
          explained in <a href="#faq.common-dirs" title=
          "10.8.&nbsp;Sharing directories between packages">Section&nbsp;10.8,
          &#8220;Sharing directories between packages&#8221;</a>,
          you may have noticed that <span><strong class=
          "command">make print-PLIST</strong></span> outputs a set
          of <code class="varname">@comment</code>s instead of real
          <code class="varname">@dirrm</code> lines. You can also
          do this for specific directories and files, so that the
          results of that command are very close to reality. This
          helps <span class="emphasis"><em>a lot</em></span> during
          the update of packages.</p>

          <p>The <code class="varname">PRINT_PLIST_AWK</code>
          variable takes a set of AWK patterns and actions that are
          used to filter the output of print-PLIST. You can
          <span class="emphasis"><em>append</em></span> any chunk
          of AWK scripting you like to it, but be careful with
          quoting.</p>

          <p>For example, to get all files inside the <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">libdata/foo</code> directory removed from the
          resulting PLIST:</p>
          <pre class="programlisting">
    PRINT_PLIST_AWK+=       /^libdata\/foo/ { next; }
</pre>

          <p>And to get all the <code class="varname">@dirrm</code>
          lines referring to a specific (shared) directory
          converted to <code class="varname">@comment</code>s:</p>
          <pre class="programlisting">
    PRINT_PLIST_AWK+=       /^@dirrm share\/specific/ { print "@comment " $$0; next; }
</pre>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "plist.misc"></a>10.4.&nbsp;Variable substitution
                in PLIST</h2>
              </div>
            </div>
          </div>

          <p>A number of variables are substituted automatically in
          PLISTs when a package is installed on a system. This
          includes the following variables:</p>

          <div class="variablelist">
            <dl>
              <dt><span class="term"><code class=
              "varname">${MACHINE_ARCH}</code>, <code class=
              "varname">${MACHINE_GNU_ARCH}</code></span></dt>

              <dd>
                <p>Some packages like emacs and perl embed
                information about which architecture they were
                built on into the pathnames where they install
                their files. To handle this case, PLIST will be
                preprocessed before actually used, and the symbol
                &#8220;<span class="quote"><code class=
                "varname">${MACHINE_ARCH}</code></span>&#8221; will
                be replaced by what <span><strong class=
                "command">uname -p</strong></span> gives. The same
                is done if the string <code class=
                "varname">${MACHINE_GNU_ARCH}</code> is embedded in
                PLIST somewhere - use this on packages that have
                GNU autoconf-created configure scripts.</p>

                <div class="note" style=
                "margin-left: 0.5in; margin-right: 0.5in;">
                  <h3 class="title">Legacy note</h3>

                  <p>There used to be a symbol &#8220;<span class=
                  "quote"><code class=
                  "varname">$ARCH</code></span>&#8221; that was
                  replaced by the output of <span><strong class=
                  "command">uname -m</strong></span>, but that's no
                  longer supported and has been removed.</p>
                </div>
              </dd>

              <dt><span class="term"><code class=
              "varname">${OPSYS}</code>, <code class=
              "varname">${LOWER_OPSYS}</code>, <code class=
              "varname">${OS_VERSION}</code></span></dt>

              <dd>
                <p>Some packages want to embed the OS name and
                version into some paths. To do this, use these
                variables in the <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">PLIST</code>:</p>

                <div class="itemizedlist">
                  <ul type="disc">
                    <li>
                      <p><code class="varname">${OPSYS}</code> -
                      output of &#8220;<span class=
                      "quote"><span><strong class="command">uname
                      -s</strong></span></span>&#8221;</p>
                    </li>

                    <li>
                      <p><code class=
                      "varname">${LOWER_OPSYS}</code> - lowercase
                      common name (eg. &#8220;<span class=
                      "quote">solaris</span>&#8221;)</p>
                    </li>

                    <li>
                      <p><code class="varname">${OS_VERSION}</code>
                      - &#8220;<span class=
                      "quote"><span><strong class="command">uname
                      -r</strong></span></span>&#8221;</p>
                    </li>
                  </ul>
                </div>
              </dd>

              <dt><span class="term"><code class=
              "varname">${PKGLOCALEDIR}</code></span></dt>

              <dd>
                <p>Packages that install locale files should list
                them in the PLIST as &#8220;<span class=
                "quote">${PKGLOCALEDIR}/locale/de/LC_MESSAGES/...</span>&#8221;
                instead of &#8220;<span class=
                "quote">share/locale/de/LC_MESSAGES/...</span>&#8221;.
                This properly handles the fact that different
                operating systems expect locale files to be either
                in <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">share</code> or <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">lib</code> by default.</p>
              </dd>
            </dl>
          </div>

          <p>For a complete list of values which are replaced by
          default, please look in <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">bsd.pkg.mk</code> (and search for <span class=
          "emphasis"><em>PLIST_SUBST</em></span>).</p>

          <p>If you want to change other variables not listed
          above, you can add variables and their expansions to this
          variable in the following way, similar to <code class=
          "varname">MESSAGE_SUBST</code> (see <a href=
          "#components.optional" title=
          "8.5.&nbsp;Optional files">Section&nbsp;8.5,
          &#8220;Optional files&#8221;</a>):</p>
          <pre class="programlisting">
    PLIST_SUBST+=   SOMEVAR="somevalue"
</pre>

          <p>This replaces all occurrences of &#8220;<span class=
          "quote">${SOMEVAR}</span>&#8221; in the PLIST with
          &#8220;<span class="quote">somevalue</span>&#8221;.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "manpage-compression"></a>10.5.&nbsp;Man page
                compression</h2>
              </div>
            </div>
          </div>

          <p>Man pages should be installed in compressed form if
          <code class="varname">MANZ</code> is set (in <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">bsd.own.mk</code>), and uncompressed
          otherwise. To handle this in the <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">PLIST</code> file, the suffix
          &#8220;<span class="quote">.gz</span>&#8221; is
          appended/removed automatically for man pages according to
          <code class="varname">MANZ</code> and <code class=
          "varname">MANCOMPRESSED</code> being set or not, see
          above for details. This modification of the <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">PLIST</code> file is done on a copy of it, not
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">PLIST</code> itself.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "using-PLIST_SRC"></a>10.6.&nbsp;Changing PLIST
                source with <code class=
                "varname">PLIST_SRC</code></h2>
              </div>
            </div>
          </div>

          <p>To use one or more files as source for the
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">PLIST</code> used in generating the
          binary package, set the variable <code class=
          "varname">PLIST_SRC</code> to the names of that file(s).
          The files are later concatenated using <a href=
          "http://netbsd.gw.com/cgi-bin/man-cgi?cat+1+NetBSD-current">
          <span class="citerefentry"><span class=
          "refentrytitle">cat</span>(1)</span></a>, and order of
          things is important.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "platform-specific-plist"></a>10.7.&nbsp;Platform-specific
                and differing PLISTs</h2>
              </div>
            </div>
          </div>

          <p>Some packages decide to install a different set of
          files based on the operating system being used. These
          differences can be automatically handled by using the
          following files:</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">PLIST.common</code></p>
              </li>

              <li>
                <p><code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">PLIST.${OPSYS}</code></p>
              </li>

              <li>
                <p><code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">PLIST.${MACHINE_ARCH}</code></p>
              </li>

              <li>
                <p><code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">PLIST.${OPSYS}-${MACHINE_ARCH}</code></p>
              </li>

              <li>
                <p><code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">PLIST.common_end</code></p>
              </li>
            </ul>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "faq.common-dirs"></a>10.8.&nbsp;Sharing
                directories between packages</h2>
              </div>
            </div>
          </div>

          <p>A &#8220;<span class="quote">shared
          directory</span>&#8221; is a directory where multiple
          (and unrelated) packages install files. These directories
          are problematic because you have to add special tricks in
          the PLIST to conditionally remove them, or have some
          centralized package handle them.</p>

          <p>Within pkgsrc, you'll find both approaches. If a
          directory is shared by a few unrelated packages, it's
          often not worth to add an extra package to remove it.
          Therefore, one simply does:</p>
          <pre class="programlisting">
    @unexec ${RMDIR} %D/path/to/shared/directory 2&gt;/dev/null || ${TRUE}
</pre>

          <p>in the PLISTs of all affected packages, instead of the
          regular "@dirrm" line.</p>

          <p>However, if the directory is shared across many
          packages, two different solutions are available:</p>

          <div class="orderedlist">
            <ol type="1">
              <li>
                <p>If the packages have a common dependency, the
                directory can be removed in that. For example, see
                <a xmlns="http://www.w3.org/TR/xhtml1/transitional"
                href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/textproc/scrollkeeper/README.html"
                target="_top"><code xmlns="" class=
                "filename">textproc/scrollkeeper</code></a>, which
                removes the shared directory <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">share/omf</code>.</p>
              </li>

              <li>
                <p>If the packages using the directory are not
                related at all (they have no common dependencies),
                a *-dirs package is used.</p>
              </li>
            </ol>
          </div>

          <p>From now on, we'll discuss the second solution. To get
          an idea of the *-dirs packages available, issue:</p>
          <pre class="programlisting">
    <code class="prompt">%</code> cd .../pkgsrc
    <code class="prompt">%</code> ls -d */*-dirs
</pre>

          <p>Their use from other packages is very simple. The
          <code class="varname">USE_DIRS</code> variable takes a
          list of package names (without the &#8220;<span class=
          "quote">-dirs</span>&#8221; part) together with the
          required version number (always pick the latest one when
          writing new packages).</p>

          <p>For example, if a package installs files under
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">share/applications</code>, it should
          have the following line in it:</p>
          <pre class="programlisting">
    USE_DIRS+=      xdg-1.1
</pre>

          <p>After regenerating the PLIST using
          <span><strong class="command">make
          print-PLIST</strong></span>, you should get the right
          (commented out) lines.</p>

          <p>Note that even if your package is using <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">$X11BASE</code>, it must not depend on the
          *-x11-dirs packages. Just specify the name without that
          part and pkgsrc (in particular, <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">mk/dirs.mk</code>) will take care of it.</p>
        </div>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "buildlink"></a>Chapter&nbsp;11.&nbsp;Buildlink
              methodology</h2>
            </div>
          </div>
        </div>

        <div class="toc">
          <p><b>Table of Contents</b></p>

          <dl>
            <dt><span class="sect1"><a href=
            "#converting-to-buildlink3">11.1. Converting packages
            to use buildlink3</a></span></dt>

            <dt><span class="sect1"><a href=
            "#creating-buildlink3.mk">11.2. Writing <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">buildlink3.mk</code> files</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#anatomy-of-bl3">11.2.1. Anatomy of a
                buildlink3.mk file</a></span></dt>

                <dt><span class="sect2"><a href=
                "#updating-buildlink-depends">11.2.2. Updating
                <code class="varname">BUILDLINK_DEPENDS.<em class=
                "replaceable"><code>pkg</code></em></code> in
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">buildlink3.mk</code>
                files</a></span></dt>
              </dl>
            </dd>

            <dt><span class="sect1"><a href=
            "#writing-builtin.mk">11.3. Writing <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">builtin.mk</code> files</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#anatomy-of-builtin.mk">11.3.1. Anatomy of a
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">builtin.mk</code> file</a></span></dt>

                <dt><span class="sect2"><a href=
                "#native-or-pkgsrc-preference">11.3.2. Global
                preferences for native or pkgsrc
                software</a></span></dt>
              </dl>
            </dd>
          </dl>
        </div>

        <p>Buildlink is a framework in pkgsrc that controls what
        headers and libraries are seen by a package's configure and
        build processes. This is implemented in a two step
        process:</p>

        <div class="orderedlist">
          <ol type="1">
            <li>
              <p>Symlink headers and libraries for dependencies
              into <code class="varname">BUILDLINK_DIR</code>,
              which by default is a subdirectory of <code class=
              "varname">WRKDIR</code>.</p>
            </li>

            <li>
              <p>Create wrapper scripts that are used in place of
              the normal compiler tools that translate <code class=
              "option">-I${LOCALBASE}/include</code> and
              <code class="option">-L${LOCALBASE}/lib</code> into
              references to <code class=
              "varname">BUILDLINK_DIR</code>. The wrapper scripts
              also make native compiler on some operating systems
              look like GCC, so that packages that expect GCC won't
              require modifications to build with those native
              compilers.</p>
            </li>
          </ol>
        </div>

        <p>This normalizes the environment in which a package is
        built so that the package may be built consistently despite
        what other software may be installed. Please note that the
        normal system header and library paths, e.g. <code xmlns=
        "http://www.w3.org/TR/xhtml1/transitional" class=
        "filename">/usr/include</code>, <code xmlns=
        "http://www.w3.org/TR/xhtml1/transitional" class=
        "filename">/usr/lib</code>, etc., are always searched --
        buildlink3 is designed to insulate the package build from
        non-system-supplied software.</p>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "converting-to-buildlink3"></a>11.1.&nbsp;Converting
                packages to use buildlink3</h2>
              </div>
            </div>
          </div>

          <p>The process of converting packages to use the
          buildlink3 framework (&#8220;<span class=
          "quote">bl3ifying</span>&#8221;) is fairly
          straightforward. The things to keep in mind are:</p>

          <div class="orderedlist">
            <ol type="1">
              <li>
                <p>Ensure that the build always calls the wrapper
                scripts instead of the actual toolchain. Some
                packages are tricky, and the only way to know for
                sure is the check <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${WRKDIR}/.work.log</code> to see if the
                wrappers are being invoked.</p>
              </li>

              <li>
                <p>Don't override <code class=
                "varname">PREFIX</code> from within the package
                Makefile, e.g. Java VMs, standalone shells, etc.,
                because the code to symlink files into <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${BUILDLINK_DIR}</code> looks for files
                relative to &#8220;<span class="quote">pkg_info -qp
                <em class=
                "replaceable"><code>pkgname</code></em></span>&#8221;.</p>
              </li>

              <li>
                <p>Remember that <span class=
                "emphasis"><em>only</em></span> the <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">buildlink3.mk</code> files that you list
                in a package's Makefile are added as dependencies
                for that package.</p>
              </li>
            </ol>
          </div>

          <p>If a dependency on a particular package is required
          for its libraries and headers, then we replace:</p>
          <pre class="programlisting">
    DEPENDS+=   foo&gt;=1.1.0:../../category/foo
</pre>

          <p>with</p>
          <pre class="programlisting">
    .include "../../category/foo/buildlink3.mk"
</pre>

          <p>The buildlink3.mk files usually define the required
          dependencies. If you need a newer version of the
          dependency when using buildlink3.mk files, then you can
          define it in your Makefile; for example:</p>
          <pre class="programlisting">
    BUILDLINK_DEPENDS.foo+=   foo&gt;=1.1.0
    .include "../../category/foo/buildlink3.mk"
</pre>

          <p>There are several <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">buildlink3.mk</code> files in <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">pkgsrc/mk</code> that handle special package
          issues:</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">bdb.buildlink3.mk</code> chooses either
                the native or a pkgsrc Berkeley DB implementation
                based on the values of <code class=
                "varname">BDB_ACCEPTED</code> and <code class=
                "varname">BDB_DEFAULT</code>.</p>
              </li>

              <li>
                <p><code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">curses.buildlink3.mk</code>: If the
                system comes with neither Curses nor NCurses, this
                will take care to install the <a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/ncurses/README.html"
                target="_top"><code xmlns="" class=
                "filename">devel/ncurses</code></a> package.</p>
              </li>

              <li>
                <p><code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">krb5.buildlink3.mk</code> uses the value
                of <code class="varname">KRB5_ACCEPTED</code> to
                choose between adding a dependency on Heimdal or
                MIT-krb5 for packages that require a Kerberos 5
                implementation.</p>
              </li>

              <li>
                <p><code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">motif.buildlink3.mk</code> checks for a
                system-provided Motif installation or adds a
                dependency on <a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/x11/lesstif/README.html"
                target="_top"><code xmlns="" class=
                "filename">x11/lesstif</code></a> or <a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/x11/openmotif/README.html"
                target="_top"><code xmlns="" class=
                "filename">x11/openmotif</code></a>.</p>
              </li>

              <li>
                <p><code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">oss.buildlink3.mk</code> defines several
                variables that may be used by packages that use the
                Open Sound System (OSS) API.</p>
              </li>

              <li>
                <p><code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">pgsql.buildlink3.mk</code> will accept
                either Postgres 7.3 or 7.4, whichever is found
                installed. See the file for more information.</p>
              </li>

              <li>
                <p><code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">pthread.buildlink3.mk</code> uses the
                value of <code class="varname">PTHREAD_OPTS</code>
                and checks for native pthreads or adds a dependency
                on <a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/pth/README.html"
                target="_top"><code xmlns="" class=
                "filename">devel/pth</code></a> as needed.</p>
              </li>

              <li>
                <p><code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">xaw.buildlink3.mk</code> uses the value
                of <code class="varname">XAW_TYPE</code> to choose
                a particular Athena widgets library.</p>
              </li>
            </ul>
          </div>

          <p>The comments in those <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">buildlink3.mk</code> files provide a more
          complete description of how to use them properly.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "creating-buildlink3.mk"></a>11.2.&nbsp;Writing
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">buildlink3.mk</code> files</h2>
              </div>
            </div>
          </div>

          <p>A package's <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">buildlink3.mk</code> file is included by
          Makefiles to indicate the need to compile and link
          against header files and libraries provided by the
          package. A <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">buildlink3.mk</code> file should always
          provide enough information to add the correct type of
          dependency relationship and include any other
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">buildlink3.mk</code> files that it needs
          to find headers and libraries that it needs in turn.</p>

          <p>To generate an initial <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">buildlink3.mk</code> file for further editing,
          Rene Hexel's <a xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" href=
          "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/createbuildlink/README.html"
          target="_top"><code xmlns="" class=
          "filename">pkgtools/createbuildlink</code></a> package is
          highly recommended. For most packages, the following
          command will generate a good starting point for
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">buildlink3.mk</code> files:</p>
          <pre class="screen">
<code class="prompt">%</code> <strong class=
"userinput"><code>cd pkgsrc/<em class=
"replaceable"><code>category</code></em>/<em class=
"replaceable"><code>pkgdir</code></em>
<code class=
"prompt">%</code> createbuildlink &gt;buildlink3.mk</code></strong>
</pre>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "anatomy-of-bl3"></a>11.2.1.&nbsp;Anatomy of a
                  buildlink3.mk file</h3>
                </div>
              </div>
            </div>

            <p>The following real-life example <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">buildlink3.mk</code> is taken from
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">pkgsrc/graphics/tiff</code>:</p>
            <pre class="programlisting">
    # $NetBSD: buildlink3.mk,v 1.7 2004/03/18 09:12:12 jlam Exp $

    BUILDLINK_DEPTH:=       ${BUILDLINK_DEPTH}+
    TIFF_BUILDLINK3_MK:=    ${TIFF_BUILDLINK3_MK}+

    .if !empty(BUILDLINK_DEPTH:M+)
    BUILDLINK_DEPENDS+=     tiff
    .endif

    BUILDLINK_PACKAGES:=    ${BUILDLINK_PACKAGES:Ntiff}
    BUILDLINK_PACKAGES+=    tiff

    .if !empty(TIFF_BUILDLINK3_MK:M+)
    BUILDLINK_DEPENDS.tiff+=        tiff&gt;=3.6.1
    BUILDLINK_PKGSRCDIR.tiff?=      ../../graphics/tiff
    .endif  # TIFF_BUILDLINK3_MK

    .include "../../devel/zlib/buildlink3.mk"
    .include "../../graphics/jpeg/buildlink3.mk"

    BUILDLINK_DEPTH:=       ${BUILDLINK_DEPTH:S/+$//}
</pre>

            <p>The header and footer manipulate <code class=
            "varname">BUILDLINK_DEPTH</code>, which is common
            across all <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">buildlink3.mk</code> files and is used to
            track at what depth we are including <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">buildlink3.mk</code> files.</p>

            <p>The first section controls if the dependency on
            <em class="replaceable"><code>pkg</code></em> is added.
            <code class="varname">BUILDLINK_DEPENDS</code> is the
            global list of packages for which dependencies are
            added by buildlink3.</p>

            <p>The second section advises pkgsrc that the
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">buildlink3.mk</code> file for
            <em class="replaceable"><code>pkg</code></em> has been
            included at some point. <code class=
            "varname">BUILDLINK_PACKAGES</code> is the global list
            of packages for which <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">buildlink3.mk</code> files have been
            included. It must <span class=
            "emphasis"><em>always</em></span> be appended to within
            a <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">buildlink3.mk</code> file.</p>

            <p>The third section is protected from multiple
            inclusion and controls how the dependency on <em class=
            "replaceable"><code>pkg</code></em> is added. Several
            important variables are set in the section:</p>

            <div class="itemizedlist">
              <ul type="disc">
                <li>
                  <p><code class=
                  "varname">BUILDLINK_DEPENDS.<em class=
                  "replaceable"><code>pkg</code></em></code> is the
                  actual dependency recorded in the installed
                  package; this should always be set using
                  <span><strong class="command">+=</strong></span>
                  to ensure that we're appending to any
                  pre-existing list of values. This variable should
                  be set to the first version of the package that
                  had the last change in the major number of a
                  shared library or that had a major API
                  change.</p>
                </li>

                <li>
                  <p><code class=
                  "varname">BUILDLINK_PKGSRCDIR.<em class=
                  "replaceable"><code>pkg</code></em></code> is the
                  location of the <em class=
                  "replaceable"><code>pkg</code></em> pkgsrc
                  directory.</p>
                </li>

                <li>
                  <p><code class=
                  "varname">BUILDLINK_DEPMETHOD.<em class=
                  "replaceable"><code>pkg</code></em></code> (not
                  shown above) controls whether we use <code class=
                  "varname">BUILD_DEPENDS</code> or <code class=
                  "varname">DEPENDS</code> to add the dependency on
                  <em class="replaceable"><code>pkg</code></em>.
                  The build dependency is selected by setting
                  <code class=
                  "varname">BUILDLINK_DEPMETHOD.<em class=
                  "replaceable"><code>pkg</code></em></code> to
                  &#8220;<span class="quote">build</span>&#8221;.
                  By default, the full dependency is used.</p>
                </li>

                <li>
                  <p><code class=
                  "varname">BUILDLINK_INCDIRS.<em class=
                  "replaceable"><code>pkg</code></em></code> and
                  <code class=
                  "varname">BUILDLINK_LIBDIRS.<em class="replaceable"><code>pkg</code></em></code>
                  (not shown above) are lists of subdirectories of
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">${BUILDLINK_PREFIX.<em class=
                  "replaceable"><code>pkg</code></em>}</code> to
                  add to the header and library search paths. These
                  default to &#8220;<span class=
                  "quote">include</span>&#8221; and
                  &#8220;<span class="quote">lib</span>&#8221;
                  respectively.</p>
                </li>

                <li>
                  <p><code class=
                  "varname">BUILDLINK_CPPFLAGS.<em class=
                  "replaceable"><code>pkg</code></em></code> (not
                  shown above) is the list of preprocessor flags to
                  add to <code class="varname">CPPFLAGS</code>,
                  which are passed on to the configure and build
                  phases. The &#8220;<span class=
                  "quote">-I</span>&#8221; option should be avoided
                  and instead be handled using <code class=
                  "varname">BUILDLINK_INCDIRS.<em class=
                  "replaceable"><code>pkg</code></em></code> as
                  above.</p>
                </li>
              </ul>
            </div>

            <p>The following variables are all optionally defined
            within this second section (protected against multiple
            inclusion) and control which package files are
            symlinked into <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">${BUILDLINK_DIR}</code> and how their names
            are transformed during the symlinking:</p>

            <div class="itemizedlist">
              <ul type="disc">
                <li>
                  <p><code class=
                  "varname">BUILDLINK_FILES.<em class=
                  "replaceable"><code>pkg</code></em></code> (not
                  shown above) is a shell glob pattern relative to
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">${BUILDLINK_PREFIX.<em class=
                  "replaceable"><code>pkg</code></em>}</code> to be
                  symlinked into <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">${BUILDLINK_DIR}</code>, e.g.
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">include/*.h</code>.</p>
                </li>

                <li>
                  <p><code class=
                  "varname">BUILDLINK_FILES_CMD.<em class=
                  "replaceable"><code>pkg</code></em></code> (not
                  shown above) is a shell pipeline that outputs to
                  stdout a list of files relative to <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">${BUILDLINK_PREFIX.<em class=
                  "replaceable"><code>pkg</code></em>}</code>. The
                  resulting files are to be symlinked into
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">${BUILDLINK_DIR}</code>. By default,
                  this takes the <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">+CONTENTS</code> of a <em class=
                  "replaceable"><code>pkg</code></em> and filters
                  it through <code class=
                  "varname">${BUILDLINK_CONTENTS_FILTER.<em class=
                  "replaceable"><code>pkg</code></em>}</code>.</p>
                </li>

                <li>
                  <p><code class=
                  "varname">BUILDLINK_CONTENTS_FILTER.<em class=
                  "replaceable"><code>pkg</code></em></code> (not
                  shown above) is a filter command that filters
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">+CONTENTS</code> input into a list of
                  files relative to <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">${BUILDLINK_PREFIX.<em class=
                  "replaceable"><code>pkg</code></em>}</code> on
                  stdout. By default for overwrite packages,
                  <code class=
                  "varname">BUILDLINK_CONTENTS_FILTER.<em class=
                  "replaceable"><code>pkg</code></em></code>
                  outputs the contents of the <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">include</code> and <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">lib</code> directories in the package
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">+CONTENTS</code>, and for pkgviews
                  packages, it outputs any libtool archives in
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">lib</code> directories.</p>
                </li>

                <li>
                  <p><code class=
                  "varname">BUILDLINK_TRANSFORM.<em class=
                  "replaceable"><code>pkg</code></em></code> (not
                  shown above) is a list of sed arguments used to
                  transform the name of the source filename into a
                  destination filename, e.g. <span><strong class=
                  "command">-e
                  "s|/curses.h|/ncurses.h|g"</strong></span>.</p>
                </li>
              </ul>
            </div>

            <p>The last section includes any <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">buildlink3.mk</code> needed for <em class=
            "replaceable"><code>pkg</code></em>'s library
            dependencies. Including these <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">buildlink3.mk</code> files means that the
            headers and libraries for these dependencies are also
            symlinked into <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">${BUILDLINK_DIR}</code> whenever the
            <em class="replaceable"><code>pkg</code></em>
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">buildlink3.mk</code> file is
            included.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "updating-buildlink-depends"></a>11.2.2.&nbsp;Updating
                  <code class=
                  "varname">BUILDLINK_DEPENDS.<em class="replaceable"><code>pkg</code></em></code>
                  in <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">buildlink3.mk</code> files</h3>
                </div>
              </div>
            </div>

            <p>There are two situations that require increasing the
            dependency listed in <code class=
            "varname">BUILDLINK_DEPENDS.<em class=
            "replaceable"><code>pkg</code></em></code> after a
            package update:</p>

            <div class="orderedlist">
              <ol type="1">
                <li>
                  <p>if the sonames (major number of the library
                  version) of any installed shared libraries
                  change.</p>
                </li>

                <li>
                  <p>if the API or interface to the header files
                  change.</p>
                </li>
              </ol>
            </div>

            <p>In these cases, <code class=
            "varname">BUILDLINK_DEPENDS.<em class=
            "replaceable"><code>pkg</code></em></code> should be
            adjusted to require at least the new package version.
            In some cases, the packages that depend on this new
            version may need their <code class=
            "varname">PKGREVISION</code>s increased and, if they
            have <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">buildlink3.mk</code> files, their
            <code class="varname">BUILDLINK_DEPENDS.<em class=
            "replaceable"><code>pkg</code></em></code> adjusted,
            too. This is needed so that binary packages made using
            it will require the correct package dependency and not
            settle for an older one which will not contain the
            necessary shared libraries.</p>

            <p>Please take careful consideration before adjusting
            <code class="varname">BUILDLINK_DEPENDS.<em class=
            "replaceable"><code>pkg</code></em></code> as we don't
            want to cause unneeded package deletions and rebuilds.
            In many cases, new versions of packages work just fine
            with older dependencies. See <a href="#dependencies"
            title=
            "16.1.4.&nbsp;Handling dependencies">Section&nbsp;16.1.4,
            &#8220;Handling dependencies&#8221;</a> for more
            information about dependencies on other packages,
            including the <code class=
            "varname">BUILDLINK_RECOMMENDED</code> and <code class=
            "varname">RECOMMENDED</code> definitions.</p>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "writing-builtin.mk"></a>11.3.&nbsp;Writing
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">builtin.mk</code> files</h2>
              </div>
            </div>
          </div>

          <p>Some packages in pkgsrc install headers and libraries
          that coincide with headers and libraries present in the
          base system. Aside from a <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">buildlink3.mk</code> file, these packages
          should also include a <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">builtin.mk</code> file that includes the
          necessary checks to decide whether using the built-in
          software or the pkgsrc software is appropriate.</p>

          <p>The only requirements of a builtin.mk file for
          <em class="replaceable"><code>pkg</code></em> are:</p>

          <div class="orderedlist">
            <ol type="1">
              <li>
                <p>It should set <code class=
                "varname">USE_BUILTIN.<em class=
                "replaceable"><code>pkg</code></em></code> to
                either &#8220;<span class="quote">yes</span>&#8221;
                or &#8220;<span class="quote">no</span>&#8221;
                after it is included.</p>
              </li>

              <li>
                <p>It should <span class=
                "emphasis"><em>not</em></span> override any
                <code class="varname">USE_BUILTIN.<em class=
                "replaceable"><code>pkg</code></em></code> which is
                already set before the <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">builtin.mk</code> file is included.</p>
              </li>

              <li>
                <p>It should be written to allow multiple
                inclusion. This is <span class=
                "emphasis"><em>very</em></span> important and takes
                careful attention to <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">Makefile</code> coding.</p>
              </li>
            </ol>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "anatomy-of-builtin.mk"></a>11.3.1.&nbsp;Anatomy
                  of a <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">builtin.mk</code> file</h3>
                </div>
              </div>
            </div>

            <p>The following is the recommended template for
            builtin.mk files:</p>
            <pre class="programlisting">
    .if !defined(IS_BUILTIN.foo)
    #
    # IS_BUILTIN.foo is set to "yes" or "no" depending on whether "foo"
    # genuinely exists in the system or not.
    #
    IS_BUILTIN.foo?=        no

    # BUILTIN_PKG.foo should be set here if "foo" is built-in and its package
    # version can be determined.
    #
    .  if !empty(IS_BUILTIN.foo:M[yY][eE][sS])
    BUILTIN_PKG.foo?=       foo-1.0
    .  endif
    .endif  # IS_BUILTIN.foo

    .if !defined(USE_BUILTIN.foo)
    USE_BUILTIN.foo?=       ${IS_BUILTIN.foo}
    .  if defined(BUILTIN_PKG.foo)
    .    for _depend_ in ${BUILDLINK_DEPENDS.foo}
    .      if !empty(USE_BUILTIN.foo:M[yY][eE][sS])
    USE_BUILTIN.foo!=                                                       \
          if ${PKG_ADMIN} pmatch '${_depend_}' ${BUILTIN_PKG.foo}; then     \
                  ${ECHO} "yes";                                            \
          else                                                              \
                  ${ECHO} "no";                                             \
          fi
    .      endif
    .    endfor
    .  endif
    .endif  # USE_BUILTIN.foo

    CHECK_BUILTIN.foo?=     no
    .if !empty(CHECK_BUILTIN.foo:M[nN][oO])
    #
    # Here we place code that depends on whether USE_BUILTIN.foo is set to
    # "yes" or "no".
    #
    .endif  # CHECK_BUILTIN.foo
</pre>

            <p>The first section sets <code class=
            "varname">IS_BUILTIN.<em class=
            "replaceable"><code>pkg</code></em></code> depending on
            if <em class="replaceable"><code>pkg</code></em> really
            exists in the base system. This should not be a base
            system software with similar functionality to
            <em class="replaceable"><code>pkg</code></em>; it
            should only be &#8220;<span class=
            "quote">yes</span>&#8221; if the actual package is
            included as part of the base system. This variable is
            only used internally within the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">builtin.mk</code> file.</p>

            <p>The second section sets <code class=
            "varname">BUILTIN_PKG.<em class=
            "replaceable"><code>pkg</code></em></code> to the
            version of <em class=
            "replaceable"><code>pkg</code></em> in the base system
            if it exists (if <code class=
            "varname">IS_BUILTIN.<em class=
            "replaceable"><code>pkg</code></em></code> is
            &#8220;<span class="quote">yes</span>&#8221;). This
            variable is only used internally within the
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">builtin.mk</code> file.</p>

            <p>The third section sets <code class=
            "varname">USE_BUILTIN.<em class=
            "replaceable"><code>pkg</code></em></code> and is
            <span class="emphasis"><em>required</em></span> in all
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">builtin.mk</code> files. The code in
            this section must make the determination whether the
            built-in software is adequate to satisfy the
            dependencies listed in <code class=
            "varname">BUILDLINK_DEPENDS.<em class=
            "replaceable"><code>pkg</code></em></code>. This is
            typically done by comparing <code class=
            "varname">BUILTIN_PKG.<em class=
            "replaceable"><code>pkg</code></em></code> against each
            of the dependencies in <code class=
            "varname">BUILDLINK_DEPENDS.<em class=
            "replaceable"><code>pkg</code></em></code>.
            <code class="varname">USE_BUILTIN.<em class=
            "replaceable"><code>pkg</code></em></code> <span class=
            "emphasis"><em>must</em></span> be set to the correct
            value by the end of the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">builtin.mk</code> file. Note that
            <code class="varname">USE_BUILTIN.<em class=
            "replaceable"><code>pkg</code></em></code> may be
            &#8220;<span class="quote">yes</span>&#8221; even if
            <code class="varname">IS_BUILTIN.<em class=
            "replaceable"><code>pkg</code></em></code> is
            &#8220;<span class="quote">no</span>&#8221; because we
            may make the determination that the built-in version of
            the software is similar enough to be used as a
            replacement.</p>

            <p>The last section is guarded by <code class=
            "varname">CHECK_BUILTIN.<em class=
            "replaceable"><code>pkg</code></em></code>, and
            includes code that uses the value of <code class=
            "varname">USE_BUILTIN.<em class=
            "replaceable"><code>pkg</code></em></code> set in the
            previous section. This typically includes, e.g., adding
            additional dependency restrictions and listing
            additional files to symlink into <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">${BUILDLINK_DIR}</code> (via <code class=
            "varname">BUILDLINK_FILES.<em class=
            "replaceable"><code>pkg</code></em></code>).</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "native-or-pkgsrc-preference"></a>11.3.2.&nbsp;Global
                  preferences for native or pkgsrc software</h3>
                </div>
              </div>
            </div>

            <p>When building packages, it's possible to choose
            whether to set a global preference for using either the
            built-in (native) version or the pkgsrc version of
            software to satisfy a dependency. This is controlled by
            setting <code class="varname">PREFER_PKGSRC</code> and
            <code class="varname">PREFER_NATIVE</code>. These
            variables take values of either &#8220;<span class=
            "quote">yes</span>&#8221;, &#8220;<span class=
            "quote">no</span>&#8221;, or a list of packages.
            <code class="varname">PREFER_PKGSRC</code> tells pkgsrc
            to use the pkgsrc versions of software, while
            <code class="varname">PREFER_NATIVE</code> tells pkgsrc
            to use the built-in versions. Preferences are
            determined by the most specific instance of the package
            in either <code class="varname">PREFER_PKGSRC</code> or
            <code class="varname">PREFER_NATIVE</code>. If a
            package is specified in neither or in both variables,
            then <code class="varname">PREFER_PKGSRC</code> has
            precedence over <code class=
            "varname">PREFER_NATIVE</code>. For example, to require
            using pkgsrc versions of software for all but the most
            basic bits on a NetBSD system, you can set:</p>
            <pre class="programlisting">
    PREFER_PKGSRC=  yes
    PREFER_NATIVE=  getopt skey tcp_wrappers
</pre>

            <p>A package <span class=
            "emphasis"><em>must</em></span> have a <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">builtin.mk</code> file to be listed in
            <code class="varname">PREFER_NATIVE</code>, otherwise
            it is simply ignored in that list.</p>
          </div>
        </div>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "pkginstall"></a>Chapter&nbsp;12.&nbsp;The pkginstall
              framework</h2>
            </div>
          </div>
        </div>

        <div class="toc">
          <p><b>Table of Contents</b></p>

          <dl>
            <dt><span class="sect1"><a href=
            "#files-and-dirs-outside-prefix">12.1. Files and
            directories outside the installation
            prefix</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#dirs-outside-prefix">12.1.1. Directory
                manipulation</a></span></dt>

                <dt><span class="sect2"><a href=
                "#files-outside-prefix">12.1.2. File
                manipulation</a></span></dt>
              </dl>
            </dd>

            <dt><span class="sect1"><a href="#conf-files">12.2.
            Configuration files</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#conf-files-sysconfdir">12.2.1. How <code class=
                "varname">PKG_SYSCONFDIR</code> is
                set</a></span></dt>

                <dt><span class="sect2"><a href=
                "#conf-files-configure">12.2.2. Telling the
                software where configuration files
                are</a></span></dt>

                <dt><span class="sect2"><a href=
                "#conf-files-patching">12.2.3. Patching
                installations</a></span></dt>

                <dt><span class="sect2"><a href=
                "#conf-files-disable">12.2.4. Disabling handling of
                configuration files</a></span></dt>
              </dl>
            </dd>

            <dt><span class="sect1"><a href="#rcd-scripts">12.3.
            System startup scripts</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#rcd-scripts-disable">12.3.1. Disabling handling
                of system startup scripts</a></span></dt>
              </dl>
            </dd>

            <dt><span class="sect1"><a href=
            "#users-and-groups">12.4. System users and
            groups</a></span></dt>

            <dt><span class="sect1"><a href="#shells">12.5. System
            shells</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#shells-disable">12.5.1. Disabling shell
                registration</a></span></dt>
              </dl>
            </dd>

            <dt><span class="sect1"><a href="#fonts">12.6.
            Fonts</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#fonts-disable">12.6.1. Disabling automatic update
                of the fonts databases</a></span></dt>
              </dl>
            </dd>
          </dl>
        </div>

        <p>This chapter describes the framework known as
        <code class="literal">pkginstall</code>, whose key features
        are:</p>

        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p>Generic installation and manipulation of
              directories and files outside the pkgsrc-handled
              tree, <code class="varname">LOCALBASE</code>.</p>
            </li>

            <li>
              <p>Automatic handling of configuration files during
              installation, provided that packages are correctly
              designed.</p>
            </li>

            <li>
              <p>Generation and installation of system startup
              scripts.</p>
            </li>

            <li>
              <p>Registration of system users and groups.</p>
            </li>

            <li>
              <p>Registration of system shells.</p>
            </li>

            <li>
              <p>Automatic updating of fonts databases.</p>
            </li>
          </ul>
        </div>

        <p>The following sections inspect each of the above points
        in detail.</p>

        <p>You may be thinking that many of the things described
        here could be easily done with simple code in the package's
        post-installation target (<code class=
        "literal">post-install</code>). <span class=
        "emphasis"><em>This is incorrect</em></span>, as the code
        in them is only executed when building from source.
        Machines using binary packages could not benefit from it at
        all (as the code itself could be unavailable). Therefore,
        the only way to achieve any of the items described above is
        by means of the installation scripts, which are
        automatically generated by pkginstall.</p>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "files-and-dirs-outside-prefix"></a>12.1.&nbsp;Files
                and directories outside the installation
                prefix</h2>
              </div>
            </div>
          </div>

          <p>As you already know, the <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">PLIST</code> file holds a list of files and
          directories that belong to a package. The names used in
          it are relative to the installation prefix (<code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">${PREFIX}</code>), which means that it cannot
          register files outside this directory (absolute path
          names are not allowed). Despite this restriction, some
          packages need to install files outside this location;
          e.g., under <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">${VARBASE}</code> or <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">${PKG_SYSCONFDIR}</code>.</p>

          <p>The only way to achieve this is to create such files
          during installation time by using the installation
          scripts. These scripts can run arbitrary commands, so
          they have the potential to create and manage files
          anywhere in the file system. Here is where pkginstall
          comes into play: it provides generic scripts to abstract
          the manipulation of such files and directories based on
          variables set in the package's <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">Makefile</code>. The rest of this section
          describes these variables.</p>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "dirs-outside-prefix"></a>12.1.1.&nbsp;Directory
                  manipulation</h3>
                </div>
              </div>
            </div>

            <p>The following variables can be set to request the
            creation of directories anywhere in the file
            system:</p>

            <div class="itemizedlist">
              <ul type="disc">
                <li>
                  <p><code class="varname">MAKE_DIRS</code> and
                  <code class="varname">OWN_DIRS</code> contain a
                  list of directories that should be created and
                  should attempt to be destroyed by the
                  installation scripts. The difference between the
                  two is that the latter prompts the administrator
                  to remove any directories that may be left after
                  deinstallation (because they were not empty),
                  while the former does not.</p>
                </li>

                <li>
                  <p><code class="varname">MAKE_DIRS_PERMS</code>
                  and <code class="varname">OWN_DIRS_PERMS</code>
                  contain a list of tuples describing which
                  directories should be created and should attempt
                  to be destroyed by the installation scripts. Each
                  tuple holds the following values, separated by
                  spaces: the directory name, its owner, its group
                  and its numerical mode. For example:</p>
                  <pre class="programlisting">
    MAKE_DIRS_PERMS+=         ${VARBASE}/foo/private ${ROOT_USER} ${ROOT_GROUP} 0700
</pre>

                  <p>The difference between the two is exactly the
                  same as their non-<code class=
                  "varname">PERMS</code> counterparts.</p>
                </li>
              </ul>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "files-outside-prefix"></a>12.1.2.&nbsp;File
                  manipulation</h3>
                </div>
              </div>
            </div>

            <p>Creating non-empty files outside the installation
            prefix is tricky because the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">PLIST</code> forces all files to be inside
            it. To overcome this problem, the only solution is to
            extract the file in the known place (i.e., inside the
            installation prefix) and copy it to the appropriate
            location during installation (done by the installation
            scripts generated by pkginstall). We will call the
            former the <span class="emphasis"><em>master
            file</em></span> in the following paragraphs, which
            describe the variables that can be used to
            automatically and consistently handle files outside the
            installation prefix:</p>

            <div class="itemizedlist">
              <ul type="disc">
                <li>
                  <p><code class="varname">CONF_FILES</code> and
                  <code class="varname">SUPPORT_FILES</code> are
                  pairs of master and target files. During
                  installation time, the master file is copied to
                  the target one if and only if the latter does not
                  exist. Upon deinstallation, the target file is
                  removed provided that it was not modified by the
                  installation.</p>

                  <p>The difference between the two is that the
                  latter prompts the administrator to remove any
                  files that may be left after deinstallation
                  (because they were not empty), while the former
                  does not.</p>
                </li>

                <li>
                  <p><code class="varname">CONF_FILES_PERMS</code>
                  and <code class=
                  "varname">SUPPORT_FILES_PERMS</code> contain
                  tuples describing master files as well as their
                  target locations. For each of them, it also
                  specifies their owner, their group and their
                  numeric permissions, in this order. For
                  example:</p>
                  <pre class="programlisting">
    SUPPORT_FILES_PERMS+= ${PREFIX}/share/somefile ${VARBASE}/somefile ${ROOT_USER} ${ROOT_GROUP} 0700
</pre>

                  <p>The difference between the two is exactly the
                  same as their non-<code class=
                  "varname">PERMS</code> counterparts.</p>
                </li>
              </ul>
            </div>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "conf-files"></a>12.2.&nbsp;Configuration
                files</h2>
              </div>
            </div>
          </div>

          <p>Configuration files are special in the sense that they
          are installed in their own specific directory,
          <code class="varname">PKG_SYSCONFDIR</code>, and need
          special treatment during installation (most of which is
          automated by pkginstall). The main concept you must bear
          in mind is that files marked as configuration files are
          automatically copied to the right place (somewhere inside
          <code class="varname">PKG_SYSCONFDIR</code>) during
          installation <span class="emphasis"><em>if and only
          if</em></span> they didn't exist before. Similarly, they
          will not be removed if they have local modifications.
          This ensures that administrators never lose any custom
          changes they may have made.</p>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "conf-files-sysconfdir"></a>12.2.1.&nbsp;How
                  <code class="varname">PKG_SYSCONFDIR</code> is
                  set</h3>
                </div>
              </div>
            </div>

            <p>As said before, the <code class=
            "varname">PKG_SYSCONFDIR</code> variable specifies
            where configuration files shall be installed. Its
            contents are set based upon the following
            variables:</p>

            <div class="itemizedlist">
              <ul type="disc">
                <li>
                  <p><code class="varname">PKG_SYSCONFBASE</code>:
                  The configuration's root directory. Defaults to
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">${PREFIX}/etc</code> although it may
                  be overridden by the user to point to his
                  preferred location (e.g., <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/etc</code>, <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">/etc/pkg</code>, etc.). Packages must
                  not use it directly.</p>
                </li>

                <li>
                  <p><code class=
                  "varname">PKG_SYSCONFSUBDIR</code>: A
                  subdirectory of <code class=
                  "varname">PKG_SYSCONFBASE</code> under which the
                  configuration files for the package being built
                  shall be installed. The definition of this
                  variable only makes sense in the package's
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">Makefile</code> (i.e., it is not
                  user-customizable).</p>

                  <p>As an example, consider the Apache package,
                  <a xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" href=
                  "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/apache2/README.html"
                  target="_top"><code xmlns="" class=
                  "filename">www/apache2</code></a>, which places
                  its configuration files under the <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">httpd/</code> subdirectory of
                  <code class="varname">PKG_SYSCONFBASE</code>.
                  This should be set in the package Makefile.</p>
                </li>

                <li>
                  <p><code class="varname">PKG_SYSCONFVAR</code>:
                  Specifies the name of the variable that holds
                  this package's configuration directory (if
                  different from <code class=
                  "varname">PKG_SYSCONFBASE</code>). It defaults to
                  <code class="varname">PKGBASE</code>'s value, and
                  is always prefixed with <code class=
                  "literal">PKG_SYSCONFDIR</code>.</p>
                </li>

                <li>
                  <p><code class=
                  "varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code>:
                  Holds the directory where the configuration files
                  for the package identified by <code class=
                  "varname">PKG_SYSCONFVAR</code>'s shall be
                  placed.</p>
                </li>
              </ul>
            </div>

            <p>Based on the above variables, pkginstall determines
            the value of <code class=
            "varname">PKG_SYSCONFDIR</code>, which is the
            <span class="emphasis"><em>only</em></span> variable
            that can be used within a package to refer to its
            configuration directory. The algorithm used to set its
            value is basically the following:</p>

            <div class="orderedlist">
              <ol type="1">
                <li>
                  <p>If <code class=
                  "varname">PKG_SYSCONFDIR.${PKG_SYSCONFVAR}</code>
                  is set, its value is used.</p>
                </li>

                <li>
                  <p>If the previous variable is not defined but
                  <code class="varname">PKG_SYSCONFSUBDIR</code> is
                  set in the package's <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">Makefile</code>, the resulting value
                  is <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">${PKG_SYSCONFBASE}/${PKG_SYSCONFSUBDIR}</code>.</p>
                </li>

                <li>
                  <p>Otherwise, it is set to <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">${PKG_SYSCONFBASE}</code>.</p>
                </li>
              </ol>
            </div>

            <p>It is worth mentioning that <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">${PKG_SYSCONFDIR}</code> is automatically
            added to <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">OWN_DIRS</code>. See <a href=
            "#dirs-outside-prefix" title=
            "12.1.1.&nbsp;Directory manipulation">Section&nbsp;12.1.1,
            &#8220;Directory manipulation&#8221;</a> what this
            means.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "conf-files-configure"></a>12.2.2.&nbsp;Telling
                  the software where configuration files are</h3>
                </div>
              </div>
            </div>

            <p>Given that pkgsrc (and users!) expect configuration
            files to be in a known place, you need to teach each
            package where it shall install its files. In some cases
            you will have to patch the package Makefiles to achieve
            it. If you are lucky, though, it may be as easy as
            passing an extra flag to the configuration script; this
            is the case of GNU Autoconf- generated files:</p>
            <pre class="programlisting">
    CONFIGURE_ARGS+= --sysconfdir=${PKG_SYSCONFDIR}
</pre>

            <p>Note that this specifies where the package has to
            <span class="emphasis"><em>look for</em></span> its
            configuration files, not where they will be originally
            installed (although the difference is never explicit,
            unfortunately).</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "conf-files-patching"></a>12.2.3.&nbsp;Patching
                  installations</h3>
                </div>
              </div>
            </div>

            <p>As said before, pkginstall automatically handles
            configuration files. This means that <span class=
            "strong"><strong>the packages themselves must not touch
            the contents of <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">${PKG_SYSCONFDIR}</code>
            directly</strong></span>. Bad news is that many
            software installation scripts will, out of the box,
            mess with the contents of that directory. So what is
            the correct procedure to fix this issue?</p>

            <p>You must teach the package (usually by manually
            patching it) to install any configuration files under
            the examples hierarchy, <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">share/examples/${PKGBASE}/</code>. This way,
            the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">PLIST</code> registers them and the
            administrator always has the original copies
            available.</p>

            <p>Once the required configuration files are in place
            (i.e., under the examples hierarchy), the pkginstall
            framework can use them as master copies during the
            package installation to update what is in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">${PKG_SYSCONFDIR}</code>. To achieve this,
            the variables <code class="varname">CONF_FILES</code>
            and <code class="varname">CONF_FILES_PERMS</code> are
            used. Check out <a href="#files-outside-prefix" title=
            "12.1.2.&nbsp;File manipulation">Section&nbsp;12.1.2,
            &#8220;File manipulation&#8221;</a> for information
            about their syntax and their purpose. Here is an
            example, taken from the <a xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" href=
            "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/mail/mutt/README.html"
            target="_top"><code xmlns="" class=
            "filename">mail/mutt</code></a> package:</p>
            <pre class="programlisting">
    EGDIR=        ${PREFIX}/share/doc/mutt/samples
    CONF_FILES=   ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc
</pre>

            <p>Note that the <code class="varname">EGDIR</code>
            variable is specific to that package and has no meaning
            outside it.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "conf-files-disable"></a>12.2.4.&nbsp;Disabling
                  handling of configuration files</h3>
                </div>
              </div>
            </div>

            <p>The automatic copying of config files can be toggled
            by setting the environment variable <code class=
            "varname">PKG_CONFIG</code> prior to package
            installation.</p>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "rcd-scripts"></a>12.3.&nbsp;System startup
                scripts</h2>
              </div>
            </div>
          </div>

          <p>System startup scripts are special files because they
          must be installed in a place known by the underlying OS,
          usually outside the installation prefix. Therefore, the
          same rules described in <a href=
          "#files-and-dirs-outside-prefix" title=
          "12.1.&nbsp;Files and directories outside the installation prefix">
          Section&nbsp;12.1, &#8220;Files and directories outside
          the installation prefix&#8221;</a> apply, and the same
          solutions can be used. However, pkginstall provides a
          special mechanism to handle these files.</p>

          <p>In order to provide system startup scripts, the
          package has to:</p>

          <div class="orderedlist">
            <ol type="1">
              <li>
                <p>Store the script inside <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${FILESDIR}</code>, with the
                <code class="literal">.sh</code> suffix appended.
                Considering the <a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/print/cups/README.html"
                target="_top"><code xmlns="" class=
                "filename">print/cups</code></a> package as an
                example, it has a <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">cupsd.sh</code> in its files
                directory.</p>
              </li>

              <li>
                <p>Tell pkginstall to handle it, appending the name
                of the script, without its extension, to the
                <code class="varname">RCD_SCRIPTS</code> variable.
                Continuing the previous example:</p>
                <pre class="programlisting">
    RCD_SCRIPTS+=   cupsd
</pre>
              </li>
            </ol>
          </div>

          <p>Once this is done, pkginstall will do the following
          steps for each script in an automated fashion:</p>

          <div class="orderedlist">
            <ol type="1">
              <li>
                <p>Process the file found in the files directory
                applying all the substitutions described in the
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">FILES_SUBST</code> variable.</p>
              </li>

              <li>
                <p>Copy the script from the files directory to the
                examples hierarchy, <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${PREFIX}/share/examples/rc.d/</code>.
                Note that this master file must be explicitly
                registered in the <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">PLIST</code>.</p>
              </li>

              <li>
                <p>Add code to the installation scripts to copy the
                startup script from the examples hierarchy into the
                system-wide startup scripts directory.</p>
              </li>
            </ol>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "rcd-scripts-disable"></a>12.3.1.&nbsp;Disabling
                  handling of system startup scripts</h3>
                </div>
              </div>
            </div>

            <p>The automatic copying of config files can be toggled
            by setting the environment variable <code class=
            "varname">PKG_RCD_SCRIPTS</code> prior to package
            installation. Note that the scripts will be always
            copied inside the examples hierarchy, <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">${PREFIX}/share/examples/rc.d/</code>, no
            matter what the value of this variable is.</p>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "users-and-groups"></a>12.4.&nbsp;System users and
                groups</h2>
              </div>
            </div>
          </div>

          <p>If a package needs to create special users and/or
          groups during installation, it can do so by using the
          pkginstall framework.</p>

          <p>Users can be created by adding entries to the
          <code class="varname">PKG_USERS</code> variable. Each
          entry has the following syntax, which mimics <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/etc/passwd</code>:</p>
          <pre class="programlisting">
    user:group[:[userid][:[descr][:[home][:shell]]]]
</pre>

          <p>Only the user and group are required; everything else
          is optional, but the colons must be in the right places
          when specifying optional bits. By default, a new user
          will have home directory <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/nonexistent</code>, and login shell
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">/sbin/nologin</code> unless they are
          specified as part of the user element. Note that if the
          description contains spaces, then spaces should be
          backslash-escaped, as in:</p>
          <pre class="programlisting">
    foo:foogrp::The\ Foomister
</pre>

          <p>Similarly, groups can be created using the
          <code class="varname">PKG_GROUPS</code> variable, whose
          syntax is:</p>
          <pre class="programlisting">
    group[:groupid]
</pre>

          <p>As before, only the group name is required; the
          numeric identifier is optional.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "shells"></a>12.5.&nbsp;System shells</h2>
              </div>
            </div>
          </div>

          <p>Packages that install system shells should register
          them in the shell database, <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/etc/shells</code>, to make things easier to
          the administrator. This must be done from the
          installation scripts to keep binary packages working on
          any system. pkginstall provides an easy way to accomplish
          this task.</p>

          <p>When a package provides a shell interpreter, it has to
          set the <code class="varname">PKG_SHELL</code> variable
          to its absolute file name. This will add some hooks to
          the installation scripts to handle it. Consider the
          following example, taken from <a xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" href=
          "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/shells/zsh/README.html"
          target="_top"><code xmlns="" class=
          "filename">shells/zsh</code></a>:</p>
          <pre class="programlisting">
    PKG_SHELL=      ${PREFIX}/bin/zsh
</pre>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "shells-disable"></a>12.5.1.&nbsp;Disabling shell
                  registration</h3>
                </div>
              </div>
            </div>

            <p>The automatic registration of shell interpreters can
            be disabled by the administrator by setting the
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">PKG_REGISTER_SHELLS</code> environment
            variable to <code class="literal">NO</code>.</p>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "fonts"></a>12.6.&nbsp;Fonts</h2>
              </div>
            </div>
          </div>

          <p>Packages that install X11 fonts should update the
          database files that index the fonts within each fonts
          directory. This can easily be accomplished within the
          pkginstall framework.</p>

          <p>When a package installs X11 fonts, it must list the
          directories in which fonts are installed in the
          <code class="varname">FONTS_DIRS.<em class=
          "replaceable"><code>type</code></em></code> variables,
          where <em class="replaceable"><code>type</code></em> can
          be one of &#8220;<span class="quote">ttf</span>&#8221;,
          &#8220;<span class="quote">type1</span>&#8221; or
          &#8220;<span class="quote">x11</span>&#8221;. This will
          add hooks to the installation scripts to run the
          appropriate commands to update the fonts database files
          within each of those directories. For convenience, if the
          directory path is relative, it is taken to be relative to
          the package's installation prefix. Consider the following
          example, taken from <a xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" href=
          "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/fonts/dbz-ttf/README.html"
          target="_top"><code xmlns="" class=
          "filename">fonts/dbz-ttf</code></a>:</p>
          <pre class="programlisting">
    FONTS_DIRS.ttf= ${PREFIX}/lib/X11/fonts/TTF
</pre>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "fonts-disable"></a>12.6.1.&nbsp;Disabling
                  automatic update of the fonts databases</h3>
                </div>
              </div>
            </div>

            <p>The automatic update of fonts databases can be
            disabled by the administrator by setting the
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">PKG_UPDATE_FONTS_DB</code> environment
            variable to <code class="literal">NO</code>.</p>
          </div>
        </div>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "options"></a>Chapter&nbsp;13.&nbsp;Options
              handling</h2>
            </div>
          </div>
        </div>

        <div class="toc">
          <p><b>Table of Contents</b></p>

          <dl>
            <dt><span class="sect1"><a href=
            "#global-default-options">13.1. Global default
            options</a></span></dt>

            <dt><span class="sect1"><a href=
            "#converting-to-options">13.2. Converting packages to
            use <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">bsd.options.mk</code></a></span></dt>

            <dt><span class="sect1"><a href="#option-names">13.3.
            Option Names</a></span></dt>
          </dl>
        </div>

        <p>Many packages have the ability to be built to support
        different sets of features. <code xmlns=
        "http://www.w3.org/TR/xhtml1/transitional" class=
        "filename">bsd.options.mk</code> is a framework in pkgsrc
        that provides generic handling of those options that
        determine different ways in which the packages can be
        built. It's possible for the user to specify exactly which
        sets of options will be built into a package or to allow a
        set of global default options apply.</p>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "global-default-options"></a>13.1.&nbsp;Global
                default options</h2>
              </div>
            </div>
          </div>

          <p>Global default options are listed in <code class=
          "varname">PKG_DEFAULT_OPTIONS</code>, which is a list of
          the options that should be built into every package if
          that option is supported. This variable should be set in
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">/etc/mk.conf</code>.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "converting-to-options"></a>13.2.&nbsp;Converting
                packages to use <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">bsd.options.mk</code></h2>
              </div>
            </div>
          </div>

          <p>The following example shows how <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">bsd.options.mk</code> should be used by the
          hypothetical ``wibble'' package, either in the package
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">Makefile</code>, or in a file, e.g.
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">options.mk</code>, that is included by
          the main package <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">Makefile</code>.</p>
          <pre class="programlisting">
    PKG_OPTIONS_VAR=            PKG_OPTIONS.wibble
    PKG_SUPPORTED_OPTIONS=              wibble-foo ldap
    PKG_OPTIONS_OPTIONAL_GROUPS=        database
    PKG_OPTIONS_GROUP.database= mysql pgsql
    PKG_SUGGESTED_OPTIONS=              wibble-foo
    PKG_OPTIONS_LEGACY_VARS+=   WIBBLE_USE_OPENLDAP:ldap
    PKG_OPTIONS_LEGACY_OPTS+=   foo:wibble-foo

    .include "../../mk/bsd.prefs.mk"

    # this package was previously named wibble2
    .if defined(PKG_OPTIONS.wibble2)
    PKG_LEGACY_OPTIONS+=  ${PKG_OPTIONS.wibble2}
    PKG_OPTIONS_DEPRECATED_WARNINGS+= \
            "Deprecated variable PKG_OPTIONS.wibble2 used, use "${PKG_OPTIONS_VAR:Q}" instead."
    .endif

    .include "../../mk/bsd.options.mk"

    # Package-specific option-handling

    ###
    ### FOO support
    ###
    .if !empty(PKG_OPTIONS:Mwibble-foo)
    CONFIGURE_ARGS+=    --enable-foo
    .endif

    ###
    ### LDAP support
    ###
    .if !empty(PKG_OPTIONS:Mldap)
    .  include "../../databases/openldap/buildlink3.mk"
    CONFIGURE_ARGS+=    --enable-ldap=${BUILDLINK_PREFIX.openldap}
    .endif

    ###
    ### database support
    ###
    .if !empty(PKG_OPTIONS:Mmysql)
    .  include "../../mk/mysql.buildlink3.mk"
    .endif
    .if !empty(PKG_OPTIONS:Mpgsql)
    .  include "../../mk/pgsql.buildlink3.mk"
    .endif
</pre>

          <p>The first section contains the information about which
          build options are supported by the package, and any
          default options settings if needed.</p>

          <div class="orderedlist">
            <ol type="1">
              <li>
                <p><code class="varname">PKG_OPTIONS_VAR</code> is
                the name of the <a href=
                "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
                <span class="citerefentry"><span class=
                "refentrytitle">make</span>(1)</span></a> variable
                that the user can set to override the default
                options. It should be set to PKG_OPTIONS.<em class=
                "replaceable"><code>pkgbase</code></em>. Do not set
                it to PKG_OPTIONS.${PKGBASE}, since <code class=
                "varname">PKGBASE</code> is set after <code class=
                "varname">PKG_OPTIONS_VAR</code> is used.</p>
              </li>

              <li>
                <p><code class=
                "varname">PKG_SUPPORTED_OPTIONS</code> is a list of
                build options supported by the package.</p>
              </li>

              <li>
                <p><code class=
                "varname">PKG_OPTIONS_OPTIONAL_GROUPS</code> is a
                list of names of groups of mutually exclusive
                options. The options in each group are listed in
                <code class="varname">PKG_OPTIONS_GROUP.<em class=
                "replaceable"><code>groupname</code></em></code>.
                The most specific setting of any option from the
                group takes precedence over all other options in
                the group. Options from the groups will be
                automatically added to <code class=
                "varname">PKG_SUPPORTED_OPTIONS</code>.</p>
              </li>

              <li>
                <p><code class=
                "varname">PKG_OPTIONS_REQUIRED_GROUPS</code> is
                like <code class=
                "varname">PKG_OPTIONS_OPTIONAL_GROUPS</code>, but
                building the packages will fail if no option from
                the group is selected.</p>
              </li>

              <li>
                <p><code class=
                "varname">PKG_OPTIONS_NONEMPTY_SETS</code> is a
                list of names of sets of options. At least one
                option from each set must be selected. The options
                in each set are listed in <code class=
                "varname">PKG_OPTIONS_SET.<em class=
                "replaceable"><code>setname</code></em></code>.
                Options from the sets will be automatically added
                to <code class=
                "varname">PKG_SUPPORTED_OPTIONS</code>. Building
                the package will fail if no option from the set is
                selected.</p>
              </li>

              <li>
                <p><code class=
                "varname">PKG_SUGGESTED_OPTIONS</code> is a list of
                build options which are enabled by default.</p>
              </li>

              <li>
                <p><code class=
                "varname">PKG_OPTIONS_LEGACY_VARS</code> is a list
                of &#8220;<span class="quote"><em class=
                "replaceable"><code>USE_VARIABLE</code></em>:<em class="replaceable"><code>option</code></em></span>&#8221;
                pairs that map legacy <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">/etc/mk.conf</code> variables to their
                option counterparts. Pairs should be added with
                &#8220;<span class="quote">+=</span>&#8221; to keep
                the listing of global legacy variables. A warning
                will be issued if the user uses a legacy
                variable.</p>
              </li>

              <li>
                <p><code class=
                "varname">PKG_OPTIONS_LEGACY_OPTS</code> is a list
                of &#8220;<span class="quote"><em class=
                "replaceable"><code>old-option</code></em>:<em class="replaceable"><code>new-option</code></em></span>&#8221;
                pairs that map options that have been renamed to
                their new counterparts. Pairs should be added with
                &#8220;<span class="quote">+=</span>&#8221; to keep
                the listing of global legacy options. A warning
                will be issued if the user uses a legacy
                option.</p>
              </li>

              <li>
                <p><code class="varname">PKG_LEGACY_OPTIONS</code>
                is a list of options implied by deprecated
                variables used. This can be used for cases that
                neither <code class=
                "varname">PKG_OPTIONS_LEGACY_VARS</code> nor
                <code class=
                "varname">PKG_OPTIONS_LEGACY_OPTS</code> can
                handle, e. g. when <code class=
                "varname">PKG_OPTIONS_VAR</code> is renamed.</p>
              </li>

              <li>
                <p><code class=
                "varname">PKG_OPTIONS_DEPRECATED_WARNINGS</code> is
                a list of warnings about deprecated variables or
                options used, and what to use instead.</p>
              </li>
            </ol>
          </div>

          <p>A package should never modify <code class=
          "varname">PKG_DEFAULT_OPTIONS</code> or the variable
          named in <code class="varname">PKG_OPTIONS_VAR</code>.
          These are strictly user-settable. To suggest a default
          set of options, use <code class=
          "varname">PKG_SUGGESTED_OPTIONS</code>.</p>

          <p><code class="varname">PKG_OPTIONS_VAR</code> must be
          defined before including <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">bsd.options.mk</code>. If none of <code class=
          "varname">PKG_SUPPORTED_OPTIONS</code>, <code class=
          "varname">PKG_OPTIONS_OPTIONAL_GROUPS</code>, and
          <code class="varname">PKG_OPTIONS_REQUIRED_GROUPS</code>
          are defined (as can happen with platform-specific options
          if none of them is supported on the current platform),
          <code class="varname">PKG_OPTIONS</code> is set to the
          empty list and the package is otherwise treated as not
          using the options framework.</p>

          <p>After the inclusion of <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">bsd.options.mk</code>, the variable
          <code class="varname">PKG_OPTIONS</code> contains the
          list of selected build options, properly filtered to
          remove unsupported and duplicate options.</p>

          <p>The remaining sections contain the logic that is
          specific to each option. The correct way to check for an
          option is to check whether it is listed in <code class=
          "varname">PKG_OPTIONS</code>:</p>
          <pre class="programlisting">
    .if !empty(PKG_OPTIONS:M<em class=
"replaceable"><code>option</code></em>)
</pre>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "option-names"></a>13.3.&nbsp;Option Names</h2>
              </div>
            </div>
          </div>

          <p>Options that enable similar features in different
          packages (like optional support for a library) should use
          a common name in all packages that support it (like the
          name of the library). If another package already has an
          option with the same meaning, use the same name.</p>

          <p>Options that enable features specific to one package,
          where it's unlikely that another (unrelated) package has
          the same (or a similar) optional feature, should use a
          name prefixed with <code class="varname"><em class=
          "replaceable"><code>pkgname</code></em>-</code>.</p>

          <p>If a group of related packages share an optional
          feature specific to that group, prefix it with the name
          of the &#8220;<span class="quote">main</span>&#8221;
          package (e. g. <code class=
          "varname">djbware-errno-hack</code>).</p>

          <p>For new options, add a line to <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">mk/defaults/options.description</code>. Lines
          have two fields, separated by tab. The first field is the
          option name, the second its description. The description
          should be a whole sentence (starting with an uppercase
          letter and ending with a period) that describes what
          enabling the option does. E. g. &#8220;<span class=
          "quote">Enable ispell support.</span>&#8221; The file is
          sorted by option names.</p>
        </div>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "build"></a>Chapter&nbsp;14.&nbsp;The build
              process</h2>
            </div>
          </div>
        </div>

        <div class="toc">
          <p><b>Table of Contents</b></p>

          <dl>
            <dt><span class="sect1"><a href="#build.intro">14.1.
            Introduction</a></span></dt>

            <dt><span class="sect1"><a href="#build.prefix">14.2.
            Program location</a></span></dt>

            <dt><span class="sect1"><a href=
            "#build.builddirs">14.3. Directories used during the
            build process</a></span></dt>

            <dt><span class="sect1"><a href="#build.running">14.4.
            Running a phase</a></span></dt>

            <dt><span class="sect1"><a href="#build.fetch">14.5.
            The <span class="emphasis"><em>fetch</em></span>
            phase</a></span></dt>

            <dt><span class="sect1"><a href="#build.checksum">14.6.
            The <span class="emphasis"><em>checksum</em></span>
            phase</a></span></dt>

            <dt><span class="sect1"><a href="#build.extract">14.7.
            The <span class="emphasis"><em>extract</em></span>
            phase</a></span></dt>

            <dt><span class="sect1"><a href="#build.patch">14.8.
            The <span class="emphasis"><em>patch</em></span>
            phase</a></span></dt>

            <dt><span class="sect1"><a href="#build.tools">14.9.
            The <span class="emphasis"><em>tools</em></span>
            phase</a></span></dt>

            <dt><span class="sect1"><a href="#build.wrapper">14.10.
            The <span class="emphasis"><em>wrapper</em></span>
            phase</a></span></dt>

            <dt><span class="sect1"><a href=
            "#build.configure">14.11. The <span class=
            "emphasis"><em>configure</em></span>
            phase</a></span></dt>

            <dt><span class="sect1"><a href="#build.build">14.12.
            The <span class="emphasis"><em>build</em></span>
            phase</a></span></dt>

            <dt><span class="sect1"><a href="#build.test">14.13.
            The <span class="emphasis"><em>test</em></span>
            phase</a></span></dt>

            <dt><span class="sect1"><a href="#build.install">14.14.
            The <span class="emphasis"><em>install</em></span>
            phase</a></span></dt>

            <dt><span class="sect1"><a href="#build.package">14.15.
            The <span class="emphasis"><em>package</em></span>
            phase</a></span></dt>

            <dt><span class="sect1"><a href=
            "#build.helpful-targets">14.16. Other helpful
            targets</a></span></dt>
          </dl>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "build.intro"></a>14.1.&nbsp;Introduction</h2>
              </div>
            </div>
          </div>

          <p>This chapter gives a detailed description on how a
          package is built. Building a package is separated into
          different <span class="emphasis"><em>phases</em></span>
          (for example <code class="varname">fetch</code>,
          <code class="varname">build</code>, <code class=
          "varname">install</code>), all of which are described in
          the following sections. Each phase is splitted into
          so-called <span class="emphasis"><em>stages</em></span>,
          which take the name of the containing phase, prefixed by
          one of <code class="varname">pre-</code>, <code class=
          "varname">do-</code> or <code class=
          "varname">post-</code>. (Examples are <code class=
          "varname">pre-configure</code>, <code class=
          "varname">post-build</code>.) Most of the actual work is
          done in the <code class="varname">do-*</code> stages.</p>

          <p>The basic steps for building a program are always the
          same. First the program's source (<span class=
          "emphasis"><em>distfile</em></span>) must be brought to
          the local system and then extracted. After any
          pkgsrc-specific patches to compile properly are applied,
          the software can be configured, then built (usually by
          compiling), and finally the generated binaries, etc. can
          be put into place on the system.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "build.prefix"></a>14.2.&nbsp;Program location</h2>
              </div>
            </div>
          </div>

          <p>Before outlining the process performed by the NetBSD
          package system in the next section, here's a brief
          discussion on where programs are installed, and which
          variables influence this.</p>

          <p>The automatic variable <code class=
          "varname">PREFIX</code> indicates where all files of the
          final program shall be installed. It is usually set to
          <code class="varname">LOCALBASE</code> (<code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/usr/pkg</code>), or <code class=
          "varname">CROSSBASE</code> for pkgs in the
          &#8220;<span class="quote">cross</span>&#8221; category.
          The value of <code class="varname">PREFIX</code> needs to
          be put into the various places in the program's source
          where paths to these files are encoded. See <a href=
          "#components.patches" title=
          "8.3.&nbsp;patches/*">Section&nbsp;8.3,
          &#8220;patches/*&#8221;</a> and <a href="#fixes.libtool"
          title=
          "16.3.1.&nbsp;Shared libraries - libtool">Section&nbsp;16.3.1,
          &#8220;Shared libraries - libtool&#8221;</a> for more
          details.</p>

          <p>When choosing which of these variables to use, follow
          the following rules:</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><code class="varname">PREFIX</code> always
                points to the location where the current pkg will
                be installed. When referring to a pkg's own
                installation path, use &#8220;<span class=
                "quote">${PREFIX}</span>&#8221;.</p>
              </li>

              <li>
                <p><code class="varname">LOCALBASE</code> is where
                all non-X11 pkgs are installed. If you need to
                construct a -I or -L argument to the compiler to
                find includes and libraries installed by another
                non-X11 pkg, use &#8220;<span class=
                "quote">${LOCALBASE}</span>&#8221;.</p>
              </li>

              <li>
                <p><code class="varname">X11BASE</code> is where
                the actual X11 distribution (from xsrc, etc.) is
                installed. When looking for <span class=
                "emphasis"><em>standard</em></span> X11 includes
                (not those installed by a pkg), use
                &#8220;<span class=
                "quote">${X11BASE}</span>&#8221;.</p>
              </li>

              <li>
                <p>X11-based packages are special in that they may
                be installed in either <code class=
                "varname">X11BASE</code> or <code class=
                "varname">LOCALBASE</code>.</p>

                <p>Usually, X11 packages should be installed under
                <code class="varname">LOCALBASE</code> whenever
                possible. Note that you will need to include
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">../../mk/x11.buildlink3.mk</code> in
                them to request the presence of X11 and to get the
                right compilation flags.</p>

                <p>Even though, there are some packages that cannot
                be installed under <code class=
                "varname">LOCALBASE</code>: those that come with
                app-defaults files. These packages are special and
                they must be placed under <code class=
                "varname">X11BASE</code>. To accomplish this, set
                either <code class="varname">USE_X11BASE</code> or
                <code class="varname">USE_IMAKE</code> in your
                package.</p>

                <p>Some notes: If you need to find includes or
                libraries installed by a pkg that has <code class=
                "varname">USE_IMAKE</code> or <code class=
                "varname">USE_X11BASE</code> in its pkg
                <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
                class="filename">Makefile</code>, you need to look
                in <span class="emphasis"><em>both</em></span>
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${X11BASE}</code> and <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${LOCALBASE}</code>. To force
                installation of all X11 packages in <code class=
                "varname">LOCALBASE</code>, the <a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/xpkgwedge/README.html"
                target="_top"><code xmlns="" class=
                "filename">pkgtools/xpkgwedge</code></a> package is
                enabled by default.</p>
              </li>

              <li>
                <p><code class="varname">X11PREFIX</code> should be
                used to refer to the installed location of an X11
                package. <code class="varname">X11PREFIX</code>
                will be set to <code class="varname">X11BASE</code>
                if xpkgwedge is not installed, and to <code class=
                "varname">LOCALBASE</code> if xpkgwedge is
                installed.</p>
              </li>

              <li>
                <p>If xpkgwedge is installed, it is possible to
                have some packages installed in <code class=
                "varname">X11BASE</code> and some in <code class=
                "varname">LOCALBASE</code>. To determine the prefix
                of an installed package, the <code class=
                "varname">EVAL_PREFIX</code> definition can be
                used. It takes pairs in the format
                &#8220;<span class=
                "quote">DIRNAME=&lt;package&gt;</span>&#8221;, and
                the <a href=
                "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
                <span class="citerefentry"><span class=
                "refentrytitle">make</span>(1)</span></a> variable
                <code class="varname">DIRNAME</code> will be set to
                the prefix of the installed package
                &lt;package&gt;, or &#8220;<span class=
                "quote">${X11PREFIX}</span>&#8221; if the package
                is not installed.</p>

                <p>This is best illustrated by example.</p>

                <p>The following lines are taken from <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">pkgsrc/wm/scwm/Makefile</code>:</p>
                <pre class="programlisting">
    EVAL_PREFIX+=           GTKDIR=gtk+
    CONFIGURE_ARGS+=        --with-guile-prefix=${LOCALBASE:Q}
    CONFIGURE_ARGS+=        --with-gtk-prefix=${GTKDIR:Q}
    CONFIGURE_ARGS+=        --enable-multibyte
</pre>

                <p>Specific defaults can be defined for the
                packages evaluated using <code class=
                "varname">EVAL_PREFIX</code>, by using a definition
                of the form:</p>
                <pre class="programlisting">
    GTKDIR_DEFAULT= ${LOCALBASE}
</pre>

                <p>where <code class="varname">GTKDIR</code>
                corresponds to the first definition in the
                <code class="varname">EVAL_PREFIX</code> pair.</p>
              </li>

              <li>
                <p>Within <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${PREFIX}</code>, packages should
                install files according to <a href=
                "http://netbsd.gw.com/cgi-bin/man-cgi?hier+7+NetBSD-current">
                <span class="citerefentry"><span class=
                "refentrytitle">hier</span>(7)</span></a>, with the
                exception that manual pages go into <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${PREFIX}/man</code>, not <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">${PREFIX}/share/man</code>.</p>
              </li>
            </ul>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "build.builddirs"></a>14.3.&nbsp;Directories used
                during the build process</h2>
              </div>
            </div>
          </div>

          <p>When building a package, a number of directories is
          used to store source files, temporary files,
          pkgsrc-internal files, and so on. These directories are
          explained here.</p>

          <p>Some of the directory variables contain relative
          pathnames. There are two common base directories for
          these relative directories: <code class=
          "varname">PKGSRCDIR/PKGPATH</code> is used for
          directories that are pkgsrc-specific. <code class=
          "varname">WRKSRC</code> is used for directories inside
          the package itself.</p>

          <div class="variablelist">
            <dl>
              <dt><span class="term"><code class=
              "varname">PKGSRCDIR</code></span></dt>

              <dd>
                <p>This is an absolute pathname that points to the
                pkgsrc root directory. Generally, you don't need
                it.</p>
              </dd>

              <dt><span class="term"><code class=
              "varname">PKGPATH</code></span></dt>

              <dd>
                <p>This is a pathname relative to <code class=
                "varname">PKGSRCDIR</code> that points to the
                current package.</p>
              </dd>

              <dt><span class="term"><code class=
              "varname">WRKDIR</code></span></dt>

              <dd>
                <p>This is an absolute pathname pointing to the
                directory where all work takes place. The distfiles
                are extraced to this directory. It also contains
                temporary directories and log files used by the
                various pkgsrc frameworks, like <span class=
                "emphasis"><em>buildlink</em></span> or the
                <span class=
                "emphasis"><em>wrappers</em></span>.</p>
              </dd>

              <dt><span class="term"><code class=
              "varname">WRKSRC</code></span></dt>

              <dd>
                <p>This is an absolute pathname pointing to the
                directory where the distfiles are extracted. It is
                usually a direct subdirectory of <code class=
                "varname">WRKDIR</code>, and often it's the only
                directory entry that isn't hidden. This variable
                may be changed by a package <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">Makefile</code>.</p>
              </dd>
            </dl>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "build.running"></a>14.4.&nbsp;Running a phase</h2>
              </div>
            </div>
          </div>

          <p>You can run a particular phase by typing
          <span><strong class="command">make phase</strong></span>,
          where <span class="emphasis"><em>phase</em></span> is the
          name of the phase. This will automatically run all phases
          that are required for this phase. The default phase is
          <code class="varname">build</code>, that is, when you run
          <span><strong class="command">make</strong></span>
          without parameters in a package directory, the package
          will be built, but not installed.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "build.fetch"></a>14.5.&nbsp;The <span class=
                "emphasis"><em>fetch</em></span> phase</h2>
              </div>
            </div>
          </div>

          <p>This will check if the file(s) given in the variables
          <code class="varname">DISTFILES</code> and <code class=
          "varname">PATCHFILES</code> (as defined in the package's
          Makefile) are present on the local system in <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/usr/pkgsrc/distfiles</code>. If they are not
          present, an attempt will be made to fetch them using
          commands of the form:</p>
          <pre class="programlisting">
    ${FETCH_CMD} ${FETCH_BEFORE_ARGS} ${site}${file} ${FETCH_AFTER_ARGS}
</pre>

          <p>where ${site} varies through several possibilities in
          turn: first, <code class=
          "varname">MASTER_SITE_OVERRIDE</code> is tried, then the
          sites specified in either <code class=
          "varname">SITES_file</code> if defined, else <code class=
          "varname">MASTER_SITES</code> or <code class=
          "varname">PATCH_SITES</code>, as applies, then finally
          the value of <code class=
          "varname">MASTER_SITE_BACKUP</code>. The order of all
          except the first can be optionally sorted by the user,
          via setting either <code class=
          "varname">MASTER_SORT_AWK</code> or <code class=
          "varname">MASTER_SORT_REGEX</code>.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "build.checksum"></a>14.6.&nbsp;The <span class=
                "emphasis"><em>checksum</em></span> phase</h2>
              </div>
            </div>
          </div>

          <p>After the distfile(s) are fetched, their checksum is
          generated and compared with the checksums stored in the
          distinfo file. If the checksums don't match, the build is
          aborted. This is to ensure the same distfile is used for
          building, and that the distfile wasn't changed, e.g. by
          some malign force, deliberately changed distfiles on the
          master distribution site or network lossage.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "build.extract"></a>14.7.&nbsp;The <span class=
                "emphasis"><em>extract</em></span> phase</h2>
              </div>
            </div>
          </div>

          <p>When the distfiles are present on the local system,
          they need to be extracted, as they usually come in the
          form of some compressed archive format.</p>

          <p>By default, all <code class="varname">DISTFILES</code>
          are extracted. If you only need some of them, you can set
          the <code class="varname">EXTRACT_ONLY</code> variable to
          the list of those files.</p>

          <p>Extracting the files is usually done by a little
          program, <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">mk/scripts/extract</code>, which already knows
          how to extract various archive formats, so most likely
          you will not need to change anything here. But if you
          need, the following variables may help you:</p>

          <div class="variablelist">
            <dl>
              <dt><span class="term"><code class=
              "varname">EXTRACT_OPTS_{BIN,LHA,PAX,RAR,TAR,ZIP,ZOO}</code></span></dt>

              <dd>
                <p>Use these variables to override the default
                options for an extract command, which are defined
                in <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">mk/scripts/extract</code>.</p>
              </dd>

              <dt><span class="term"><code class=
              "varname">EXTRACT_USING</code></span></dt>

              <dd>
                <p>This variable can be set to <code class=
                "literal">pax</code>, <code class=
                "literal">tar</code> or an absolute pathname
                pointing to the command with which tar archives
                should be extracted.</p>
              </dd>
            </dl>
          </div>

          <p>If the <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">extract</code> program doesn't serve your
          needs, you can also override the <code class=
          "varname">EXTRACT_CMD</code> variable, which holds the
          command used for extracting the files. This command is
          executed in the <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">${WRKSRC}</code> directory. During execution
          of this command, the shell variable <code class=
          "varname">extract_file</code> holds the absolute pathname
          of the file that is going to be extracted.</p>

          <p>And if that still does not suffice, you can override
          the <code class="varname">do-extract</code> target in the
          package Makefile.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "build.patch"></a>14.8.&nbsp;The <span class=
                "emphasis"><em>patch</em></span> phase</h2>
              </div>
            </div>
          </div>

          <p>After extraction, all the patches named by the
          <code class="varname">PATCHFILES</code>, those present in
          the patches subdirectory of the package as well as in
          $LOCALPATCHES/$PKGPATH (e.g. <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">/usr/local/patches/graphics/png</code>) are
          applied. Patchfiles ending in <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">.Z</code> or <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">.gz</code> are uncompressed before they are
          applied, files ending in <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">.orig</code> or <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">.rej</code> are ignored. Any special options
          to <a href=
          "http://netbsd.gw.com/cgi-bin/man-cgi?patch+1+NetBSD-current">
          <span class="citerefentry"><span class=
          "refentrytitle">patch</span>(1)</span></a> can be handed
          in <code class="varname">PATCH_DIST_ARGS</code>. See
          <a href="#components.patches" title=
          "8.3.&nbsp;patches/*">Section&nbsp;8.3,
          &#8220;patches/*&#8221;</a> for more details.</p>

          <p>By default <a href=
          "http://netbsd.gw.com/cgi-bin/man-cgi?patch+1+NetBSD-current">
          <span class="citerefentry"><span class=
          "refentrytitle">patch</span>(1)</span></a> is given
          special args to make it fail if the patches apply with
          some lines of fuzz. Please fix (regen) the patches so
          that they apply cleanly. The rationale behind this is
          that patches that don't apply cleanly may end up being
          applied in the wrong place, and cause severe harm
          there.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "build.tools"></a>14.9.&nbsp;The <span class=
                "emphasis"><em>tools</em></span> phase</h2>
              </div>
            </div>
          </div>

          <p>This is covered in <a href="#tools" title=
          "Chapter&nbsp;15.&nbsp;Tools needed for building or running">
          Chapter&nbsp;15, <i>Tools needed for building or
          running</i></a>.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "build.wrapper"></a>14.10.&nbsp;The <span class=
                "emphasis"><em>wrapper</em></span> phase</h2>
              </div>
            </div>
          </div>

          <p>[TODO]</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "build.configure"></a>14.11.&nbsp;The <span class=
                "emphasis"><em>configure</em></span> phase</h2>
              </div>
            </div>
          </div>

          <p>Most pieces of software need information on the header
          files, system calls, and library routines which are
          available on the platform they run on. The process of
          determining this information is known as configuration,
          and is usually automated. In most cases, a script is
          supplied with the distfiles, and its invocation results
          in generation of header files, Makefiles, etc.</p>

          <p>If the package contains a configure script, this can
          be invoked by setting <code class=
          "varname">HAS_CONFIGURE</code> to &#8220;<span class=
          "quote">yes</span>&#8221;. If the configure script is a
          GNU autoconf script, you should set <code class=
          "varname">GNU_CONFIGURE</code> to &#8220;<span class=
          "quote">yes</span>&#8221; instead. What happens in the
          <span class="emphasis"><em>configure</em></span> phase is
          roughly:</p>
          <pre class="programlisting">
    .for d in ${CONFIGURE_DIRS}
            cd ${WRKSRC} &amp;&amp; cd ${d} &amp;&amp; env ${CONFIGURE_ENV} \
                ${CONFIGURE_SCRIPT} ${CONFIGURE_ARGS}
    .endfor
</pre>

          <p><code class="varname">CONFIGURE_DIRS</code> (default:
          &#8220;<span class="quote">.</span>&#8221;) is a list of
          pathnames relative to <code class=
          "varname">WRKSRC</code>. In each of these directories,
          the configure script is run with the environment
          <code class="varname">CONFIGURE_ENV</code> and arguments
          <code class="varname">CONFIGURE_ARGS</code>. The
          variables <code class="varname">CONFIGURE_ENV</code>,
          <code class="varname">CONFIGURE_SCRIPT</code> (default:
          &#8220;<span class="quote">./configure</span>&#8221;) and
          <code class="varname">CONFIGURE_ARGS</code> may all be
          changed by the package.</p>

          <p>If the program uses an <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">Imakefile</code> for configuration, the
          appropriate steps can be invoked by setting <code class=
          "varname">USE_IMAKE</code> to &#8220;<span class=
          "quote">yes</span>&#8221;. (If you only want the package
          installed in <code class="varname">${X11PREFIX}</code>
          but xmkmf not being run, set <code class=
          "varname">USE_X11BASE</code> instead.)</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "build.build"></a>14.12.&nbsp;The <span class=
                "emphasis"><em>build</em></span> phase</h2>
              </div>
            </div>
          </div>

          <p>For building a package, a rough equivalent of the
          following code is executed.</p>
          <pre class="programlisting">
    .for d in ${BUILD_DIRS}
            cd ${WRKSRC} &amp;&amp; cd ${d} &amp;&amp; env ${MAKE_ENV} \
                ${MAKE_PROGRAM} ${BUILD_MAKE_FLAGS} \
                    -f ${MAKEFILE} ${BUILD_TARGET}
    .endfor
</pre>

          <p><code class="varname">BUILD_DIRS</code> (default:
          &#8220;<span class="quote">.</span>&#8221;) is a list of
          pathnames relative to <code class=
          "varname">WRKSRC</code>. In each of these directories,
          <code class="varname">MAKE_PROGRAM</code> is run with the
          environment <code class="varname">MAKE_ENV</code> and
          arguments <code class="varname">BUILD_MAKE_FLAGS</code>.
          The variables <code class="varname">MAKE_ENV</code>,
          <code class="varname">BUILD_MAKE_FLAGS</code>,
          <code class="varname">MAKEFILE</code> and <code class=
          "varname">BUILD_TARGET</code> may all be changed by the
          package.</p>

          <p>The default value of <code class=
          "varname">MAKE_PROGRAM</code> is &#8220;<span class=
          "quote">gmake</span>&#8221; if <code class=
          "varname">USE_TOOLS</code> contains &#8220;<span class=
          "quote">gmake</span>&#8221;, &#8220;<span class=
          "quote">make</span>&#8221; otherwise. The default value
          of <code class="varname">MAKEFILE</code> is
          &#8220;<span class="quote">Makefile</span>&#8221;, and
          <code class="varname">BUILD_TARGET</code> defaults to
          &#8220;<span class="quote">all</span>&#8221;.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "build.test"></a>14.13.&nbsp;The <span class=
                "emphasis"><em>test</em></span> phase</h2>
              </div>
            </div>
          </div>

          <p>[TODO]</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "build.install"></a>14.14.&nbsp;The <span class=
                "emphasis"><em>install</em></span> phase</h2>
              </div>
            </div>
          </div>

          <p>Once the build stage has completed, the final step is
          to install the software in public directories, so users
          can access the programs and files.</p>

          <p>In the <span class="emphasis"><em>install</em></span>
          phase, a rough equivalent of the following code is
          executed. Additionally, before and after this code, much
          magic is performed to do consistency checks, registering
          the package, and so on.</p>
          <pre class="programlisting">
    .for d in ${INSTALL_DIRS}
            cd ${WRKSRC} &amp;&amp; cd ${d} &amp;&amp; env ${MAKE_ENV} \
                ${MAKE_PROGRAM} ${INSTALL_MAKE_FLAGS} \
                    -f ${MAKEFILE} ${BUILD_TARGET}
    .endfor
</pre>

          <p>The variable's meanings are analogous to the ones in
          the <span class="emphasis"><em>build</em></span> phase.
          <code class="varname">INSTALL_DIRS</code> defaults to
          <code class="varname">BUILD_DIRS</code>. <code class=
          "varname">INSTALL_TARGET</code> is &#8220;<span class=
          "quote">install</span>&#8221; by default, plus
          &#8220;<span class="quote">install.man</span>&#8221; if
          <code class="varname">USE_IMAKE</code> is defined.</p>

          <p>In the <span class="emphasis"><em>install</em></span>
          phase, the following variables are useful. They are all
          variations of the <a href=
          "http://netbsd.gw.com/cgi-bin/man-cgi?install+1+NetBSD-current">
          <span class="citerefentry"><span class=
          "refentrytitle">install</span>(1)</span></a> command that
          have the owner, group and permissions preset.
          <code class="varname">INSTALL</code> is the plain install
          command. The specialized variants, together with their
          intended use, are:</p>

          <div class="variablelist">
            <dl>
              <dt><span class="term"><code class=
              "varname">INSTALL_PROGRAM_DIR</code></span></dt>

              <dd>
                <p>directories that contain binaries</p>
              </dd>

              <dt><span class="term"><code class=
              "varname">INSTALL_SCRIPT_DIR</code></span></dt>

              <dd>
                <p>directories that contain scripts</p>
              </dd>

              <dt><span class="term"><code class=
              "varname">INSTALL_LIB_DIR</code></span></dt>

              <dd>
                <p>directories that contain shared and static
                libraries</p>
              </dd>

              <dt><span class="term"><code class=
              "varname">INSTALL_DATA_DIR</code></span></dt>

              <dd>
                <p>directories that contain data files</p>
              </dd>

              <dt><span class="term"><code class=
              "varname">INSTALL_MAN_DIR</code></span></dt>

              <dd>
                <p>directories that contain man pages</p>
              </dd>

              <dt><span class="term"><code class=
              "varname">INSTALL_PROGRAM</code></span></dt>

              <dd>
                <p>binaries that can be stripped from debugging
                symbols</p>
              </dd>

              <dt><span class="term"><code class=
              "varname">INSTALL_SCRIPT</code></span></dt>

              <dd>
                <p>binaries that cannot be stripped</p>
              </dd>

              <dt><span class="term"><code class=
              "varname">INSTALL_GAME</code></span></dt>

              <dd>
                <p>game binaries</p>
              </dd>

              <dt><span class="term"><code class=
              "varname">INSTALL_LIB</code></span></dt>

              <dd>
                <p>shared and static libraries</p>
              </dd>

              <dt><span class="term"><code class=
              "varname">INSTALL_DATA</code></span></dt>

              <dd>
                <p>data files</p>
              </dd>

              <dt><span class="term"><code class=
              "varname">INSTALL_GAME_DATA</code></span></dt>

              <dd>
                <p>data files for games</p>
              </dd>

              <dt><span class="term"><code class=
              "varname">INSTALL_MAN</code></span></dt>

              <dd>
                <p>man pages</p>
              </dd>
            </dl>
          </div>

          <p>Some other variables are:</p>

          <div class="variablelist">
            <dl>
              <dt><span class="term"><code class=
              "varname">INSTALLATION_DIRS</code></span></dt>

              <dd>
                <p>A list of directories relative to <code class=
                "varname">PREFIX</code> that are created by pkgsrc
                at the beginning of the <span class=
                "emphasis"><em>install</em></span> phase. If this
                variable is set, <code class=
                "varname">NO_MTREE</code>=&#8220;<span class=
                "quote">yes</span>&#8221; is assumed, which means
                that the package claims to create all needed
                directories itself before installing files to it.
                Therefore this variable should only be set in
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">Makefile</code>s that are under control
                of the package's author.</p>
              </dd>
            </dl>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "build.package"></a>14.15.&nbsp;The <span class=
                "emphasis"><em>package</em></span> phase</h2>
              </div>
            </div>
          </div>

          <p>[TODO]</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "build.helpful-targets"></a>14.16.&nbsp;Other
                helpful targets</h2>
              </div>
            </div>
          </div>

          <div class="variablelist">
            <dl>
              <dt><span class="term">pre/post-*</span></dt>

              <dd>
                <p>For any of the main targets described in the
                previous section, two auxiliary targets exist with
                &#8220;<span class="quote">pre-</span>&#8221; and
                &#8220;<span class="quote">post-</span>&#8221; used
                as a prefix for the main target's name. These
                targets are invoked before and after the main
                target is called, allowing extra configuration or
                installation steps be performed from a package's
                Makefile, for example, which a program's configure
                script or install target omitted.</p>
              </dd>

              <dt><span class="term">do-*</span></dt>

              <dd>
                <p>Should one of the main targets do the wrong
                thing, and should there be no variable to fix this,
                you can redefine it with the do-* target. (Note
                that redefining the target itself instead of the
                do-* target is a bad idea, as the pre-* and post-*
                targets won't be called anymore, etc.) You will not
                usually need to do this.</p>
              </dd>

              <dt><span class="term">reinstall</span></dt>

              <dd>
                <p>If you did a <span><strong class="command">make
                install</strong></span> and you noticed some file
                was not installed properly, you can repeat the
                installation with this target, which will ignore
                the &#8220;<span class="quote">already
                installed</span>&#8221; flag.</p>
              </dd>

              <dt><span class="term">deinstall</span></dt>

              <dd>
                <p>This target does a <a href=
                "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1+NetBSD-current">
                <span class="citerefentry"><span class=
                "refentrytitle">pkg_delete</span>(1)</span></a> in
                the current directory, effectively de-installing
                the package. The following variables can be used to
                tune the behaviour:</p>

                <div class="variablelist">
                  <dl>
                    <dt><span class="term"><code class=
                    "varname">PKG_VERBOSE</code></span></dt>

                    <dd>
                      <p>Add a "-v" to the <a href=
                      "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1+NetBSD-current">
                      <span class="citerefentry"><span class=
                      "refentrytitle">pkg_delete</span>(1)</span></a>
                      command.</p>
                    </dd>

                    <dt><span class="term"><code class=
                    "varname">DEINSTALLDEPENDS</code></span></dt>

                    <dd>
                      <p>Remove all packages that require (depend
                      on) the given package. This can be used to
                      remove any packages that may have been pulled
                      in by a given package, e.g. if
                      <span><strong class="command">make deinstall
                      DEINSTALLDEPENDS=1</strong></span> is done in
                      <code xmlns=
                      "http://www.w3.org/TR/xhtml1/transitional"
                      class="filename">pkgsrc/x11/kde</code>, this
                      is likely to remove whole KDE. Works by
                      adding &#8220;<span class=
                      "quote">-R</span>&#8221; to the <a href=
                      "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1+NetBSD-current">
                      <span class="citerefentry"><span class=
                      "refentrytitle">pkg_delete</span>(1)</span></a>
                      command line.</p>
                    </dd>
                  </dl>
                </div>
              </dd>

              <dt><span class="term">update</span></dt>

              <dd>
                <p>This target causes the current package to be
                updated to the latest version. The package and all
                depending packages first get de-installed, then
                current versions of the corresponding packages get
                compiled and installed. This is similar to manually
                noting which packages are currently installed, then
                performing a series of <span><strong class=
                "command">make deinstall</strong></span> and
                <span><strong class="command">make
                install</strong></span> (or whatever <code class=
                "varname">UPDATE_TARGET</code> is set to) for these
                packages.</p>

                <p>You can use the &#8220;<span class=
                "quote">update</span>&#8221; target to resume
                package updating in case a previous
                <span><strong class="command">make
                update</strong></span> was interrupted for some
                reason. However, in this case, make sure you don't
                call <span><strong class="command">make
                clean</strong></span> or otherwise remove the list
                of dependent packages in <code class=
                "varname">WRKDIR</code>. Otherwise, you lose the
                ability to automatically update the current package
                along with the dependent packages you have
                installed.</p>

                <p>Resuming an interrupted <span><strong class=
                "command">make update</strong></span> will only
                work as long as the package tree remains unchanged.
                If the source code for one of the packages to be
                updated has been changed, resuming
                <span><strong class="command">make
                update</strong></span> will most certainly
                fail!</p>

                <p>The following variables can be used either on
                the command line or in <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">/etc/mk.conf</code> to alter the
                behaviour of <span><strong class="command">make
                update</strong></span>:</p>

                <div class="variablelist">
                  <dl>
                    <dt><span class="term"><code class=
                    "varname">UPDATE_TARGET</code></span></dt>

                    <dd>
                      <p>Install target to recursively use for the
                      updated package and the dependent packages.
                      Defaults to <code class=
                      "varname">DEPENDS_TARGET</code> if set,
                      &#8220;<span class=
                      "quote">install</span>&#8221; otherwise for
                      <span><strong class="command">make
                      update</strong></span>. e.g.
                      <span><strong class="command">make update
                      UPDATE_TARGET=package</strong></span></p>
                    </dd>

                    <dt><span class="term"><code class=
                    "varname">NOCLEAN</code></span></dt>

                    <dd>
                      <p>Don't clean up after updating. Useful if
                      you want to leave the work sources of the
                      updated packages around for inspection or
                      other purposes. Be sure you eventually clean
                      up the source tree (see the
                      &#8220;<span class=
                      "quote">clean-update</span>&#8221; target
                      below) or you may run into troubles with old
                      source code still lying around on your next
                      <span><strong class=
                      "command">make</strong></span> or
                      <span><strong class="command">make
                      update</strong></span>.</p>
                    </dd>

                    <dt><span class="term"><code class=
                    "varname">REINSTALL</code></span></dt>

                    <dd>
                      <p>Deinstall each package before installing
                      (making <code class=
                      "varname">DEPENDS_TARGET</code>). This may be
                      necessary if the &#8220;<span class=
                      "quote">clean-update</span>&#8221; target
                      (see below) was called after interrupting a
                      running <span><strong class="command">make
                      update</strong></span>.</p>
                    </dd>

                    <dt><span class="term"><code class=
                    "varname">DEPENDS_TARGET</code></span></dt>

                    <dd>
                      <p>Allows you to disable recursion and
                      hardcode the target for packages. The default
                      is &#8220;<span class=
                      "quote">update</span>&#8221; for the update
                      target, facilitating a recursive update of
                      prerequisite packages. Only set <code class=
                      "varname">DEPENDS_TARGET</code> if you want
                      to disable recursive updates. Use
                      <code class="varname">UPDATE_TARGET</code>
                      instead to just set a specific target for
                      each package to be installed during
                      <span><strong class="command">make
                      update</strong></span> (see above).</p>
                    </dd>
                  </dl>
                </div>
              </dd>

              <dt><span class="term">clean-update</span></dt>

              <dd>
                <p>Clean the source tree for all packages that
                would get updated if <span><strong class=
                "command">make update</strong></span> was called
                from the current directory. This target should not
                be used if the current package (or any of its
                depending packages) have already been de-installed
                (e.g., after calling <span><strong class=
                "command">make update</strong></span>) or you may
                lose some packages you intended to update. As a
                rule of thumb: only use this target <span class=
                "emphasis"><em>before</em></span> the first time
                you run <span><strong class="command">make
                update</strong></span> and only if you have a dirty
                package tree (e.g., if you used <code class=
                "varname">NOCLEAN</code>).</p>

                <p>If you are unsure about whether your tree is
                clean, you can either perform a
                <span><strong class="command">make
                clean</strong></span> at the top of the tree, or
                use the following sequence of commands from the
                directory of the package you want to update
                (<span class="emphasis"><em>before</em></span>
                running <span><strong class="command">make
                update</strong></span> for the first time,
                otherwise you lose all the packages you wanted to
                update!):</p>
                <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>make clean-update</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>make clean CLEANDEPENDS=YES</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>make update</code></strong>
</pre>

                <p>The following variables can be used either on
                the command line or in <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">/etc/mk.conf</code> to alter the
                behaviour of <span><strong class="command">make
                clean-update</strong></span>:</p>

                <div class="variablelist">
                  <dl>
                    <dt><span class="term"><code class=
                    "varname">CLEAR_DIRLIST</code></span></dt>

                    <dd>
                      <p>After <span><strong class="command">make
                      clean</strong></span>, do not reconstruct the
                      list of directories to update for this
                      package. Only use this if
                      <span><strong class="command">make
                      update</strong></span> successfully installed
                      all packages you wanted to update. Normally,
                      this is done automatically on
                      <span><strong class="command">make
                      update</strong></span>, but may have been
                      suppressed by the <code class=
                      "varname">NOCLEAN</code> variable (see
                      above).</p>
                    </dd>
                  </dl>
                </div>
              </dd>

              <dt><span class="term">info</span></dt>

              <dd>
                <p>This target invokes <a href=
                "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_info+1+NetBSD-current">
                <span class="citerefentry"><span class=
                "refentrytitle">pkg_info</span>(1)</span></a> for
                the current package. You can use this to check
                which version of a package is installed.</p>
              </dd>

              <dt><span class="term">readme</span></dt>

              <dd>
                <p>This target generates a <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">README.html</code> file, which can be
                viewed using a browser such as <a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/mozilla/README.html"
                target="_top"><code xmlns="" class=
                "filename">www/mozilla</code></a> or <a xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" href=
                "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/www/links/README.html"
                target="_top"><code xmlns="" class=
                "filename">www/links</code></a>. The generated
                files contain references to any packages which are
                in the <code class="varname">PACKAGES</code>
                directory on the local host. The generated files
                can be made to refer to URLs based on <code class=
                "varname">FTP_PKG_URL_HOST</code> and <code class=
                "varname">FTP_PKG_URL_DIR</code>. For example, if I
                wanted to generate <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">README.html</code> files which pointed
                to binary packages on the local machine, in the
                directory <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">/usr/packages</code>, set <code class=
                "varname">FTP_PKG_URL_HOST=file://localhost</code>
                and <code class=
                "varname">FTP_PKG_URL_DIR=/usr/packages</code>. The
                <code class="varname">${PACKAGES}</code> directory
                and its subdirectories will be searched for all the
                binary packages.</p>
              </dd>

              <dt><span class="term">readme-all</span></dt>

              <dd>
                <p>Use this target to create a file <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">README-all.html</code> which contains a
                list of all packages currently available in the
                NetBSD Packages Collection, together with the
                category they belong to and a short description.
                This file is compiled from the <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">pkgsrc/*/README.html</code> files, so be
                sure to run this <span class=
                "emphasis"><em>after</em></span> a
                <span><strong class="command">make
                readme</strong></span>.</p>
              </dd>

              <dt><span class="term">cdrom-readme</span></dt>

              <dd>
                <p>This is very much the same as the
                &#8220;<span class="quote">readme</span>&#8221;
                target (see above), but is to be used when
                generating a pkgsrc tree to be written to a CD-ROM.
                This target also produces <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">README.html</code> files, and can be
                made to refer to URLs based on <code class=
                "varname">CDROM_PKG_URL_HOST</code> and
                <code class="varname">CDROM_PKG_URL_DIR</code>.</p>
              </dd>

              <dt><span class="term">show-distfiles</span></dt>

              <dd>
                <p>This target shows which distfiles and patchfiles
                are needed to build the package. (<code class=
                "varname">DISTFILES</code> and <code class=
                "varname">PATCHFILES</code>, but not <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">patches/*</code>)</p>
              </dd>

              <dt><span class="term">show-downlevel</span></dt>

              <dd>
                <p>This target shows nothing if the package is not
                installed. If a version of this package is
                installed, but is not the version provided in this
                version of pkgsrc, then a warning message is
                displayed. This target can be used to show which of
                your installed packages are downlevel, and so the
                old versions can be deleted, and the current ones
                added.</p>
              </dd>

              <dt><span class="term">show-pkgsrc-dir</span></dt>

              <dd>
                <p>This target shows the directory in the pkgsrc
                hierarchy from which the package can be built and
                installed. This may not be the same directory as
                the one from which the package was installed. This
                target is intended to be used by people who may
                wish to upgrade many packages on a single host, and
                can be invoked from the top-level pkgsrc Makefile
                by using the &#8220;<span class=
                "quote">show-host-specific-pkgs</span>&#8221;
                target.</p>
              </dd>

              <dt><span class=
              "term">show-installed-depends</span></dt>

              <dd>
                <p>This target shows which installed packages match
                the current package's <code class=
                "varname">DEPENDS</code>. Useful if out of date
                dependencies are causing build problems.</p>
              </dd>

              <dt><span class="term">check-shlibs</span></dt>

              <dd>
                <p>After a package is installed, check all its
                binaries and (on ELF platforms) shared libraries to
                see if they find the shared libs they need. Run by
                default if <code class=
                "varname">PKG_DEVELOPER</code> is set in
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">/etc/mk.conf</code>.</p>
              </dd>

              <dt><span class="term">print-PLIST</span></dt>

              <dd>
                <p>After a &#8220;<span class="quote">make
                install</span>&#8221; from a new or upgraded pkg,
                this prints out an attempt to generate a new
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">PLIST</code> from a <span><strong class=
                "command">find -newer
                work/.extract_done</strong></span>. An attempt is
                made to care for shared libs etc., but it is
                <span class="emphasis"><em>strongly</em></span>
                recommended to review the result before putting it
                into <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">PLIST</code>. On upgrades, it's useful
                to diff the output of this command against an
                already existing <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">PLIST</code> file.</p>

                <p>If the package installs files via <a href=
                "http://netbsd.gw.com/cgi-bin/man-cgi?tar+1+NetBSD-current">
                <span class="citerefentry"><span class=
                "refentrytitle">tar</span>(1)</span></a> or other
                methods that don't update file access times, be
                sure to add these files manually to your
                <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">PLIST</code>, as the &#8220;<span class=
                "quote">find -newer</span>&#8221; command used by
                this target won't catch them!</p>

                <p>See <a href="#print-PLIST" title=
                "10.3.&nbsp;Tweaking output of make print-PLIST">Section&nbsp;10.3,
                &#8220;Tweaking output of <span><strong class=
                "command">make
                print-PLIST</strong></span>&#8221;</a> for more
                information on this target.</p>
              </dd>

              <dt><span class="term">bulk-package</span></dt>

              <dd>
                <p>Used to do bulk builds. If an appropriate binary
                package already exists, no action is taken. If not,
                this target will compile, install and package it
                (and its depends, if <code class=
                "varname">PKG_DEPENDS</code> is set properly. See
                <a href="#binary.configuration" title=
                "6.3.1.&nbsp;Configuration">Section&nbsp;6.3.1,
                &#8220;Configuration&#8221;</a>). After creating
                the binary package, the sources, the just-installed
                package and its required packages are removed,
                preserving free disk space.</p>

                <p><span class="emphasis"><em>Beware that this
                target may deinstall all packages installed on a
                system!</em></span></p>
              </dd>

              <dt><span class="term">bulk-install</span></dt>

              <dd>
                <p>Used during bulk-installs to install required
                packages. If an up-to-date binary package is
                available, it will be installed via <a href=
                "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
                <span class="citerefentry"><span class=
                "refentrytitle">pkg_add</span>(1)</span></a>. If
                not, <span><strong class="command">make
                bulk-package</strong></span> will be executed, but
                the installed binary won't be removed.</p>

                <p>A binary package is considered
                &#8220;<span class="quote">up-to-date</span>&#8221;
                to be installed via <a href=
                "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_add+1+NetBSD-current">
                <span class="citerefentry"><span class=
                "refentrytitle">pkg_add</span>(1)</span></a>
                if:</p>

                <div class="itemizedlist">
                  <ul type="disc">
                    <li>
                      <p>None of the package's files (<code xmlns=
                      "http://www.w3.org/TR/xhtml1/transitional"
                      class="filename">Makefile</code>, ...) were
                      modified since it was built.</p>
                    </li>

                    <li>
                      <p>None of the package's required (binary)
                      packages were modified since it was
                      built.</p>
                    </li>
                  </ul>
                </div>

                <p><span class="emphasis"><em>Beware that this
                target may deinstall all packages installed on a
                system!</em></span></p>
              </dd>
            </dl>
          </div>
        </div>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "tools"></a>Chapter&nbsp;15.&nbsp;Tools needed for
              building or running</h2>
            </div>
          </div>
        </div>

        <div class="toc">
          <p><b>Table of Contents</b></p>

          <dl>
            <dt><span class="sect1"><a href="#pkgsrc-tools">15.1.
            Tools for pkgsrc builds</a></span></dt>

            <dt><span class="sect1"><a href="#package-tools">15.2.
            Tools needed by packages</a></span></dt>

            <dt><span class="sect1"><a href="#platform-tools">15.3.
            Tools provided by platforms</a></span></dt>
          </dl>
        </div>

        <p>The <code class="varname">USE_TOOLS</code> definition is
        used both internally by pkgsrc and also for individual
        packages to define what commands are needed for building a
        package (like <code class="varname">BUILD_DEPENDS</code>)
        or for later run-time of an installed packaged (such as
        <code class="varname">DEPENDS</code>). If the native system
        provides an adequate tool, then in many cases, a pkgsrc
        package will not be used.</p>

        <p>When building a package, the replacement tools are made
        available in a directory (as symlinks or wrapper scripts)
        that is early in the executable search path. Just like the
        buildlink system, this helps with consistent builds.</p>

        <p>A tool may be needed to help build a specific package.
        For example, perl, GNU make (gmake) or yacc may be
        needed.</p>

        <p>Also a tool may be needed, for example, because the
        native system's supplied tool may be inefficient for
        building a package with pkgsrc. For example, a package may
        need GNU awk, bison (instead of yacc) or a better sed.</p>

        <p>The tools used by a package can be listed by running
        <span><strong class="command">make
        show-tools</strong></span>.</p>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "pkgsrc-tools"></a>15.1.&nbsp;Tools for pkgsrc
                builds</h2>
              </div>
            </div>
          </div>

          <p>The default set of tools used by pkgsrc is defined in
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">bsd.pkg.mk</code>. This includes
          standard Unix tools, such as: <span><strong class=
          "command">cat</strong></span>, <span><strong class=
          "command">awk</strong></span>, <span><strong class=
          "command">chmod</strong></span>, <span><strong class=
          "command">test</strong></span>, and so on. These can be
          seen by running: <span><strong class="command">make
          show-var VARNAME=USE_TOOLS</strong></span>.</p>

          <p>If a package needs a specific program to build then
          the <code class="varname">USE_TOOLS</code> variable can
          be used to define the tools needed.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "package-tools"></a>15.2.&nbsp;Tools needed by
                packages</h2>
              </div>
            </div>
          </div>

          <p>In the following examples, the :pkgsrc means to use
          the pkgsrc version and not the native version for a build
          dependency. And the :run means that it is used for a
          run-time dependencies also (and becomes a DEPENDS). The
          default is a build dependency which can be set with
          :build. (So in this example, it is the same as
          gmake:build and pkg-config:build.)</p>
          <pre class="programlisting">
USE_TOOLS+=     mktemp:pkgsrc
USE_TOOLS+=     gmake perl:run pkg-config
</pre>

          <p>When using the tools framework, a <code class=
          "varname">TOOLS_PATH.foo</code> variable is defined which
          contains the full path to the appropriate tool. For
          example, <code class="varname">TOOLS_PATH.bash</code>
          could be &#8220;<span class=
          "quote">/bin/bash</span>&#8221; on Linux systems.</p>

          <p>If you always need a pkgsrc version of the tool at
          run-time, then just use <code class=
          "varname">DEPENDS</code> instead.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "platform-tools"></a>15.3.&nbsp;Tools provided by
                platforms</h2>
              </div>
            </div>
          </div>

          <p>When improving or porting pkgsrc to a new platform,
          have a look at (or create) the corresponding platform
          specific make file fragment under <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">pkgsrc/mk/tools/tools.${OPSYS}.mk</code> which
          defines the name of the common tools. For example:</p>
          <pre class="programlisting">
.if exists(/usr/bin/bzcat)
TOOLS_PLATFORM.bzcat?=          /usr/bin/bzcat
.elif exists(/usr/bin/bzip2)
TOOLS_PLATFORM.bzcat?=          /usr/bin/bzip2 -cd
.endif

TOOLS_PLATFORM.true?=           true                    # shell builtin
</pre>
        </div>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "fixes"></a>Chapter&nbsp;16.&nbsp;Making your package
              work</h2>
            </div>
          </div>
        </div>

        <div class="toc">
          <p><b>Table of Contents</b></p>

          <dl>
            <dt><span class="sect1"><a href=
            "#general-operation">16.1. General
            operation</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#pulling-vars-from-etc-mk.conf">16.1.1. How to
                pull in variables from /etc/mk.conf</a></span></dt>

                <dt><span class="sect2"><a href=
                "#where-to-install-documentation">16.1.2. Where to
                install documentation</a></span></dt>

                <dt><span class="sect2"><a href=
                "#restricted-packages">16.1.3. Restricted
                packages</a></span></dt>

                <dt><span class="sect2"><a href=
                "#dependencies">16.1.4. Handling
                dependencies</a></span></dt>

                <dt><span class="sect2"><a href=
                "#conflicts">16.1.5. Handling conflicts with other
                packages</a></span></dt>

                <dt><span class="sect2"><a href=
                "#not-building-packages">16.1.6. Packages that
                cannot or should not be built</a></span></dt>

                <dt><span class="sect2"><a href=
                "#undeletable-packages">16.1.7. Packages which
                should not be deleted, once
                installed</a></span></dt>

                <dt><span class="sect2"><a href=
                "#security-handling">16.1.8. Handling packages with
                security problems</a></span></dt>

                <dt><span class="sect2"><a href=
                "#compiler-bugs">16.1.9. How to handle compiler
                bugs</a></span></dt>

                <dt><span class="sect2"><a href=
                "#bumping-pkgrevision">16.1.10. How to handle
                incrementing versions when fixing an existing
                package</a></span></dt>

                <dt><span class="sect2"><a href=
                "#portability-of-packages">16.1.11. Portability of
                packages</a></span></dt>
              </dl>
            </dd>

            <dt><span class="sect1"><a href=
            "#downloading-issues">16.2. Possible downloading
            issues</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#no-plain-download">16.2.1. Packages whose
                distfiles aren't available for plain
                downloading</a></span></dt>

                <dt><span class="sect2"><a href=
                "#modified-distfiles-same-name">16.2.2. How to
                handle modified distfiles with the 'old'
                name</a></span></dt>
              </dl>
            </dd>

            <dt><span class="sect1"><a href=
            "#configuration-gotchas">16.3. Configuration
            gotchas</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#fixes.libtool">16.3.1. Shared libraries -
                libtool</a></span></dt>

                <dt><span class="sect2"><a href=
                "#using-libtool">16.3.2. Using libtool on GNU
                packages that already support
                libtool</a></span></dt>

                <dt><span class="sect2"><a href=
                "#autoconf-automake">16.3.3. GNU
                Autoconf/Automake</a></span></dt>
              </dl>
            </dd>

            <dt><span class="sect1"><a href="#fixes-build">16.4.
            Building the package</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#cpp-defines">16.4.1. CPP defines</a></span></dt>

                <dt><span class="sect2"><a href=
                "#cpp-list-examples">16.4.2. Examples of CPP
                defines for some platforms</a></span></dt>

                <dt><span class="sect2"><a href="#cpp-list">16.4.3.
                Getting a list of CPP defines</a></span></dt>
              </dl>
            </dd>

            <dt><span class="sect1"><a href=
            "#package-specific-actions">16.5. Package specific
            actions</a></span></dt>

            <dd>
              <dl>
                <dt><span class="sect2"><a href=
                "#user-interaction">16.5.1. User
                interaction</a></span></dt>

                <dt><span class="sect2"><a href=
                "#handling-licenses">16.5.2. Handling
                licenses</a></span></dt>

                <dt><span class="sect2"><a href=
                "#installing-score-files">16.5.3. Installing score
                files</a></span></dt>

                <dt><span class="sect2"><a href=
                "#perl-scripts">16.5.4. Packages containing perl
                scripts</a></span></dt>

                <dt><span class="sect2"><a href=
                "#hardcoded-paths">16.5.5. Packages with hardcoded
                paths to other interpreters</a></span></dt>

                <dt><span class="sect2"><a href=
                "#perl-modules">16.5.6. Packages installing perl
                modules</a></span></dt>

                <dt><span class="sect2"><a href=
                "#faq.info-files">16.5.7. Packages installing info
                files</a></span></dt>

                <dt><span class="sect2"><a href="#manpages">16.5.8.
                Packages installing man pages</a></span></dt>

                <dt><span class="sect2"><a href=
                "#gconf2-data-files">16.5.9. Packages installing
                GConf2 data files</a></span></dt>

                <dt><span class="sect2"><a href=
                "#scrollkeeper-data-files">16.5.10. Packages
                installing scrollkeeper data files</a></span></dt>

                <dt><span class="sect2"><a href=
                "#x11-fonts">16.5.11. Packages installing X11
                fonts</a></span></dt>

                <dt><span class="sect2"><a href=
                "#gtk2-modules">16.5.12. Packages installing GTK2
                modules</a></span></dt>

                <dt><span class="sect2"><a href=
                "#sgml-xml-data">16.5.13. Packages installing SGML
                or XML data</a></span></dt>

                <dt><span class="sect2"><a href=
                "#mime-database">16.5.14. Packages installing
                extensions to the MIME database</a></span></dt>

                <dt><span class="sect2"><a href=
                "#intltool">16.5.15. Packages using
                intltool</a></span></dt>

                <dt><span class="sect2"><a href=
                "#startup-scripts">16.5.16. Packages installing
                startup scripts</a></span></dt>

                <dt><span class="sect2"><a href=
                "#tex-packages">16.5.17. Packages installing TeX
                modules</a></span></dt>
              </dl>
            </dd>

            <dt><span class="sect1"><a href=
            "#feedback-to-author">16.6. Feedback to the
            author</a></span></dt>
          </dl>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "general-operation"></a>16.1.&nbsp;General
                operation</h2>
              </div>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "pulling-vars-from-etc-mk.conf"></a>16.1.1.&nbsp;How
                  to pull in variables from /etc/mk.conf</h3>
                </div>
              </div>
            </div>

            <p>The problem with package-defined variables that can
            be overridden via <code class="varname">MAKECONF</code>
            or <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/etc/mk.conf</code> is that <a href=
            "http://netbsd.gw.com/cgi-bin/man-cgi?make+1+NetBSD-current">
            <span class="citerefentry"><span class=
            "refentrytitle">make</span>(1)</span></a> expands a
            variable as it is used, but evaluates preprocessor-like
            statements (.if, .ifdef and .ifndef) as they are read.
            So, to use any variable (which may be set in
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">/etc/mk.conf</code>) in one of the
            .if* statements, the file <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/etc/mk.conf</code> must be included before
            that .if* statement.</p>

            <p>Rather than having a number of ad-hoc ways of
            including <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/etc/mk.conf</code>, should it exist, or
            <code class="varname">MAKECONF</code>, should it exist,
            include the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">pkgsrc/mk/bsd.prefs.mk</code> file in the
            package Makefile before any preprocessor-like .if,
            .ifdef, or .ifndef statements:</p>
            <pre class="programlisting">
    .include "../../mk/bsd.prefs.mk"

    .if defined(USE_MENUS)
    # ...
    .endif
</pre>

            <p>If you wish to set the <code class=
            "varname">CFLAGS</code> variable in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/etc/mk.conf</code>, please make sure to
            use:</p>
            <pre class="programlisting">
    CFLAGS+=  -your -flags
</pre>

            <p>Using <code class="varname">CFLAGS=</code> (i.e.
            without the &#8220;<span class="quote">+</span>&#8221;)
            may lead to problems with packages that need to add
            their own flags. Also, you may want to take a look at
            the <a xmlns="http://www.w3.org/TR/xhtml1/transitional"
            href=
            "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/cpuflags/README.html"
            target="_top"><code xmlns="" class=
            "filename">devel/cpuflags</code></a> package if you're
            interested in optimization for the current CPU.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "where-to-install-documentation"></a>16.1.2.&nbsp;Where
                  to install documentation</h3>
                </div>
              </div>
            </div>

            <p>Documentation should be installed into <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">${PREFIX}/share/doc/${PKGBASE}</code> or
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">${PREFIX}/share/doc/${PKGNAME}</code>
            (the latter includes the version number of the
            package).</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "restricted-packages"></a>16.1.3.&nbsp;Restricted
                  packages</h3>
                </div>
              </div>
            </div>

            <p>Some licenses restrict how software may be
            re-distributed. In order to satisfy these restrictions,
            the package system defines five make variables that can
            be set to note these restrictions:</p>

            <div class="itemizedlist">
              <ul type="disc">
                <li>
                  <p><code class="varname">RESTRICTED</code></p>

                  <p>This variable should be set whenever a
                  restriction exists (regardless of its kind). Set
                  this variable to a string containing the reason
                  for the restriction.</p>
                </li>

                <li>
                  <p><code class=
                  "varname">NO_BIN_ON_CDROM</code></p>

                  <p>Binaries may not be placed on CD-ROM. Set this
                  variable to <code class=
                  "varname">${RESTRICTED}</code> whenever a binary
                  package may not be included on a CD-ROM.</p>
                </li>

                <li>
                  <p><code class="varname">NO_BIN_ON_FTP</code></p>

                  <p>Binaries may not be placed on an FTP server.
                  Set this variable to <code class=
                  "varname">${RESTRICTED}</code> whenever a binary
                  package may not not be made available on the
                  Internet.</p>
                </li>

                <li>
                  <p><code class=
                  "varname">NO_SRC_ON_CDROM</code></p>

                  <p>Distfiles may not be placed on CD-ROM. Set
                  this variable to <code class=
                  "varname">${RESTRICTED}</code> if re-distribution
                  of the source code or other distfile(s) is not
                  allowed on CD-ROMs.</p>
                </li>

                <li>
                  <p><code class="varname">NO_SRC_ON_FTP</code></p>

                  <p>Distfiles may not be placed on FTP. Set this
                  variable to <code class=
                  "varname">${RESTRICTED}</code> if re-distribution
                  of the source code or other distfile(s) via the
                  Internet is not allowed.</p>
                </li>
              </ul>
            </div>

            <p>Please note that the use of <code class=
            "varname">NO_PACKAGE</code>, <code class=
            "varname">IGNORE</code>, <code class=
            "varname">NO_CDROM</code>, or other generic make
            variables to denote restrictions is deprecated, because
            they unconditionally prevent users from generating
            binary packages!</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "dependencies"></a>16.1.4.&nbsp;Handling
                  dependencies</h3>
                </div>
              </div>
            </div>

            <p>Your package may depend on some other package being
            present - and there are various ways of expressing this
            dependency. pkgsrc supports the <code class=
            "varname">BUILD_DEPENDS</code> and <code class=
            "varname">DEPENDS</code> definitions, the <code class=
            "varname">USE_TOOLS</code> definition, as well as
            dependencies via <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">buildlink3.mk</code>, which is the preferred
            way to handle dependencies, and which uses the
            variables named above. See <a href="#buildlink" title=
            "Chapter&nbsp;11.&nbsp;Buildlink methodology">Chapter&nbsp;11,
            <i>Buildlink methodology</i></a> for more
            information.</p>

            <p>The basic difference between the two variables is as
            follows: The <code class="varname">DEPENDS</code>
            definition registers that pre-requisite in the binary
            package so it will be pulled in when the binary package
            is later installed, whilst the <code class=
            "varname">BUILD_DEPENDS</code> definition does not,
            marking a dependency that is only needed for building
            the package.</p>

            <p>This means that if you only need a package present
            whilst you are building, it should be noted as a
            <code class="varname">BUILD_DEPENDS</code>.</p>

            <p>The format for a <code class=
            "varname">BUILD_DEPENDS</code> and a <code class=
            "varname">DEPENDS</code> definition is:</p>
            <pre class="programlisting">
    &lt;pre-req-package-name&gt;:../../&lt;category&gt;/&lt;pre-req-package&gt;
</pre>

            <p>Please note that the &#8220;<span class=
            "quote">pre-req-package-name</span>&#8221; may include
            any of the wildcard version numbers recognized by
            <a href=
            "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_info+1+NetBSD-current">
            <span class="citerefentry"><span class=
            "refentrytitle">pkg_info</span>(1)</span></a>.</p>

            <div class="orderedlist">
              <ol type="1">
                <li>
                  <p>If your package needs another package's
                  binaries or libraries to build or run, and if
                  that package has a <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">buildlink3.mk</code> file available,
                  use it:</p>
                  <pre class="programlisting">
    .include "../../graphics/jpeg/buildlink3.mk"
</pre>
                </li>

                <li>
                  <p>If your package needs to use another package
                  to build itself and there is no <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">buildlink3.mk</code> file available,
                  use the <code class=
                  "varname">BUILD_DEPENDS</code> definition:</p>
                  <pre class="programlisting">
    BUILD_DEPENDS+= autoconf-2.13:../../devel/autoconf
</pre>
                </li>

                <li>
                  <p>If your package needs a library with which to
                  link and again there is no <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">buildlink3.mk</code> file available,
                  this is specified using the <code class=
                  "varname">DEPENDS</code> definition. For
                  example:</p>
                  <pre class="programlisting">
    DEPENDS+=       xpm-3.4j:../../graphics/xpm
</pre>

                  <p>You can also use wildcards in package
                  dependences:</p>
                  <pre class="programlisting">
    DEPENDS+=       xpm-[0-9]*:../../graphics/xpm
</pre>

                  <p>Note that such wildcard dependencies are
                  retained when creating binary packages. The
                  dependency is checked when installing the binary
                  package and any package which matches the pattern
                  will be used. Wildcard dependencies should be
                  used with care.</p>

                  <p>The &#8220;<span class=
                  "quote">-[0-9]*</span>&#8221; should be used
                  instead of &#8220;<span class=
                  "quote">-*</span>&#8221; to avoid potentially
                  ambiguous matches such as &#8220;<span class=
                  "quote">tk-postgresql</span>&#8221; matching a
                  &#8220;<span class="quote">tk-*</span>&#8221;
                  <code class="varname">DEPENDS</code>.</p>

                  <p>Wildcards can also be used to specify that a
                  package will only build against a certain minimum
                  version of a pre-requisite:</p>
                  <pre class="programlisting">
    DEPENDS+=       tiff&gt;=3.5.4:../../graphics/tiff
</pre>

                  <p>This means that the package will build against
                  version 3.5.4 of the tiff library or newer. Such
                  a dependency may be warranted if, for example,
                  the API of the library has changed with version
                  3.5.4 and a package would not compile against an
                  earlier version of tiff.</p>

                  <p>Please note that such dependencies should only
                  be updated if a package requires a newer
                  pre-requisite, but not to denote recommendations
                  such as security updates or ABI changes that do
                  not prevent a package from building correctly.
                  Such recommendations can be expressed using
                  <code class="varname">RECOMMENDED</code>:</p>
                  <pre class="programlisting">
    RECOMMENDED+=   tiff&gt;=3.6.1:../../graphics/tiff
</pre>

                  <p>In addition to the above <code class=
                  "varname">DEPENDS</code> line, this denotes that
                  while a package will build against
                  tiff&gt;=3.5.4, at least version 3.6.1 is
                  recommended. <code class=
                  "varname">RECOMMENDED</code> entries will be
                  turned into dependencies unless explicitly
                  ignored (in which case a warning will be
                  printed).</p>

                  <p>To ignore these dependency recommendations and
                  just use the required <code class=
                  "varname">DEPENDS</code>, set <code class=
                  "varname">IGNORE_RECOMMENDED=YES</code>. This may
                  make it easier and faster to update packages
                  built using pkgsrc, since older compatible
                  dependencies can continue to be used. This is
                  useful for people who watch their rebuilds very
                  carefully; it is not very good as a
                  general-purpose hammer. If you use it, you need
                  to be mindful of possible ABI changes, including
                  those from the underlying OS.</p>

                  <p>Packages that are built with recommendations
                  ignored may not be uploaded to ftp.NetBSD.org by
                  developers and should not be used across
                  different systems that may have different
                  versions of binary packages installed.</p>

                  <p>For security fixes, please update the package
                  vulnerabilities file as well as setting
                  <code class="varname">RECOMMENDED</code>, see
                  <a href="#security-handling" title=
                  "16.1.8.&nbsp;Handling packages with security problems">
                  Section&nbsp;16.1.8, &#8220;Handling packages
                  with security problems&#8221;</a> for more
                  information.</p>
                </li>

                <li>
                  <p>If your package needs some executable to be
                  able to run correctly and if there's no
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">buildlink3.mk</code> file, this is
                  specified using the <code class=
                  "varname">DEPENDS</code> variable. The <a xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" href=
                  "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/print/lyx/README.html"
                  target="_top"><code xmlns="" class=
                  "filename">print/lyx</code></a> package needs to
                  be able to execute the latex binary from the
                  teTeX package when it runs, and that is
                  specified:</p>
                  <pre class="programlisting">
    DEPENDS+=        teTeX-[0-9]*:../../print/teTeX
</pre>

                  <p>The comment about wildcard dependencies from
                  previous paragraph applies here, too.</p>
                </li>
              </ol>
            </div>

            <p>If your package needs files from another package to
            build, add the relevant distribution files to
            <code class="varname">DISTFILES</code>, so they will be
            extracted automatically. See the <a xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" href=
            "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/print/ghostscript/README.html"
            target="_top"><code xmlns="" class=
            "filename">print/ghostscript</code></a> package for an
            example. (It relies on the jpeg sources being present
            in source form during the build.)</p>

            <p>Please also note the <code class=
            "varname">BUILD_USES_MSGFMT</code> and <code class=
            "varname">BUILD_USES_GETTEXT_M4</code> definitions,
            which are provided as convenience definitions. The
            former works out whether <a href=
            "http://netbsd.gw.com/cgi-bin/man-cgi?msgfmt+1+NetBSD-current">
            <span class="citerefentry"><span class=
            "refentrytitle">msgfmt</span>(1)</span></a> is part of
            the base system, and, if it isn't, installs the
            <a xmlns="http://www.w3.org/TR/xhtml1/transitional"
            href=
            "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/gettext/README.html"
            target="_top"><code xmlns="" class=
            "filename">devel/gettext</code></a> package. The latter
            adds a build dependency on either an installed version
            of an older gettext package, or if it isn't, installs
            the <a xmlns="http://www.w3.org/TR/xhtml1/transitional"
            href=
            "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/gettext-m4/README.html"
            target="_top"><code xmlns="" class=
            "filename">devel/gettext-m4</code></a> package.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "conflicts"></a>16.1.5.&nbsp;Handling conflicts
                  with other packages</h3>
                </div>
              </div>
            </div>

            <p>Your package may conflict with other packages a user
            might already have installed on his system, e.g. if
            your package installs the same set of files like
            another package in our pkgsrc tree.</p>

            <p>In this case you can set <code class=
            "varname">CONFLICTS</code> to a space-separated list of
            packages (including version string) your package
            conflicts with.</p>

            <p>For example, <a xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" href=
            "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/x11/Xaw3d/README.html"
            target="_top"><code xmlns="" class=
            "filename">x11/Xaw3d</code></a> and <a xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" href=
            "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/x11/Xaw-Xpm/README.html"
            target="_top"><code xmlns="" class=
            "filename">x11/Xaw-Xpm</code></a> install the same
            shared library, thus you set in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">pkgsrc/x11/Xaw3d/Makefile</code>:</p>
            <pre class="programlisting">
    CONFLICTS=      Xaw-Xpm-[0-9]*
</pre>

            <p>and in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">pkgsrc/x11/Xaw-Xpm/Makefile</code>:</p>
            <pre class="programlisting">
    CONFLICTS=      Xaw3d-[0-9]*
</pre>

            <p>Packages will automatically conflict with other
            packages with the name prefix and a different version
            string. &#8220;<span class=
            "quote">Xaw3d-1.5</span>&#8221; e.g. will automatically
            conflict with the older version &#8220;<span class=
            "quote">Xaw3d-1.3</span>&#8221;.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "not-building-packages"></a>16.1.6.&nbsp;Packages
                  that cannot or should not be built</h3>
                </div>
              </div>
            </div>

            <p>There are several reasons why a package might be
            instructed to not build under certain circumstances. If
            the package builds and runs on most platforms, the
            exceptions should be noted with <code class=
            "varname">NOT_FOR_PLATFORM</code>. If the package
            builds and runs on a small handful of platforms, set
            <code class="varname">ONLY_FOR_PLATFORM</code> instead.
            Both <code class="varname">ONLY_FOR_PLATFORM</code> and
            <code class="varname">NOT_FOR_PLATFORM</code> are OS
            triples (OS-version-platform) that can use glob-style
            wildcards.</p>

            <p>If the package should be skipped (for example,
            because it provides functionality already provided by
            the system), set <code class=
            "varname">PKG_SKIP_REASON</code> to a descriptive
            message. If the package should fail because some
            preconditions are not met, set <code class=
            "varname">PKG_FAIL_REASON</code> to a descriptive
            message.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "undeletable-packages"></a>16.1.7.&nbsp;Packages
                  which should not be deleted, once installed</h3>
                </div>
              </div>
            </div>

            <p>To ensure that a package may not be deleted, once it
            has been installed, the <code class=
            "varname">PKG_PRESERVE</code> definition should be set
            in the package Makefile. This will be carried into any
            binary package that is made from this pkgsrc entry. A
            &#8220;<span class="quote">preserved</span>&#8221;
            package will not be deleted using <a href=
            "http://netbsd.gw.com/cgi-bin/man-cgi?pkg_delete+1+NetBSD-current">
            <span class="citerefentry"><span class=
            "refentrytitle">pkg_delete</span>(1)</span></a> unless
            the &#8220;<span class="quote">-f</span>&#8221; option
            is used.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "security-handling"></a>16.1.8.&nbsp;Handling
                  packages with security problems</h3>
                </div>
              </div>
            </div>

            <p>When a vulnerability is found, this should be noted
            in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">localsrc/security/advisories/pkg-vulnerabilities</code>,
            and after committing that file, use
            <span><strong class="command">make
            upload</strong></span> in the same directory to update
            the file on ftp.NetBSD.org.</p>

            <p>After fixing the vulnerability by a patch, its
            <code class="varname">PKGREVISION</code> should be
            increased (this is of course not necessary if the
            problem is fixed by using a newer release of the
            software). In addition, if a <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">buildlink3.mk</code> file exists for an
            affected package, a corresponding <code class=
            "varname">BUILDLINK_RECOMMENDED.<em class=
            "replaceable"><code>pkg</code></em></code> entry should
            be added or updated in it.</p>

            <p>Also, if the fix should be applied to the stable
            pkgsrc branch, be sure to submit a pullup request!</p>

            <p>Binary packages already on ftp.NetBSD.org will be
            handled semi-automatically by a weekly cron job.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "compiler-bugs"></a>16.1.9.&nbsp;How to handle
                  compiler bugs</h3>
                </div>
              </div>
            </div>

            <p>Some source files trigger bugs in the compiler,
            based on combinations of compiler version and
            architecture and almost always relation to optimisation
            being enabled. Common symptoms are gcc internal errors
            or never finishing compiling a file.</p>

            <p>Typically, a workaround involves testing the
            <code class="varname">MACHINE_ARCH</code> and compiler
            version, disabling optimisation for that
            file/<code class="varname">MACHINE_ARCH</code>/compiler
            combination, and documenting it in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">pkgsrc/doc/HACKS</code>. See that file for a
            number of examples!</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "bumping-pkgrevision"></a>16.1.10.&nbsp;How to
                  handle incrementing versions when fixing an
                  existing package</h3>
                </div>
              </div>
            </div>

            <p>When making fixes to an existing package it can be
            useful to change the version number in <code class=
            "varname">PKGNAME</code>. To avoid conflicting with
            future versions by the original author, a
            &#8220;<span class="quote">nb1</span>&#8221;,
            &#8220;<span class="quote">nb2</span>&#8221;, ...
            suffix can be used on package versions by setting
            <code class="varname">PKGREVISION=1</code> (2, ...).
            The &#8220;<span class="quote">nb</span>&#8221; is
            treated like a &#8220;<span class=
            "quote">.</span>&#8221; by the pkg tools. e.g.</p>
            <pre class="programlisting">
    DISTNAME=       foo-17.42
    PKGREVISION=    9
</pre>

            <p>will result in a <code class=
            "varname">PKGNAME</code> of &#8220;<span class=
            "quote">foo-17.42nb9</span>&#8221;.</p>

            <p>When a new release of the package is released, the
            <code class="varname">PKGREVISION</code> should be
            removed, e.g. on a new minor release of the above
            package, things should be like:</p>
            <pre class="programlisting">
    DISTNAME=       foo-17.43
</pre>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "portability-of-packages"></a>16.1.11.&nbsp;Portability
                  of packages</h3>
                </div>
              </div>
            </div>

            <p>One appealing feature of pkgsrc is that it runs on
            many different platforms. As a result, it is important
            to ensure, where possible, that packages in pkgsrc are
            portable. There are some particular details you should
            pay attention to while working on pkgsrc.</p>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "install-scripts"></a>16.1.11.1.&nbsp;${INSTALL},
                    ${INSTALL_DATA_DIR}, ...</h4>
                  </div>
                </div>
              </div>

              <p>The BSD-compatible <span><strong class=
              "command">install</strong></span> supplied with some
              operating systems will not perform more than one
              operation at a time. As such, you should call
              &#8220;<span class="quote">${INSTALL}</span>&#8221;,
              etc. like this:</p>
              <pre class="programlisting">
    ${INSTALL_DATA_DIR} ${PREFIX}/dir1
    ${INSTALL_DATA_DIR} ${PREFIX}/dir2
</pre>
            </div>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "downloading-issues"></a>16.2.&nbsp;Possible
                downloading issues</h2>
              </div>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "no-plain-download"></a>16.2.1.&nbsp;Packages
                  whose distfiles aren't available for plain
                  downloading</h3>
                </div>
              </div>
            </div>

            <p>If you need to download from a dynamic URL you can
            set <code class="varname">DYNAMIC_MASTER_SITES</code>
            and a <span><strong class="command">make
            fetch</strong></span> will call <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">files/getsite.sh</code> with the name of
            each file to download as an argument, expecting it to
            output the URL of the directory from which to download
            it. <a xmlns="http://www.w3.org/TR/xhtml1/transitional"
            href=
            "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/graphics/ns-cult3d/README.html"
            target="_top"><code xmlns="" class=
            "filename">graphics/ns-cult3d</code></a> is an example
            of this usage.</p>

            <p>If the download can't be automated, because the user
            must submit personal information to apply for a
            password, or must pay for the source, or whatever, you
            can set <code class="varname">_FETCH_MESSAGE</code> to
            a macro which displays a message explaining the
            situation. <code class="varname">_FETCH_MESSAGE</code>
            must be executable shell commands, not just a message.
            (Generally, it executes <code class=
            "varname">${ECHO}</code>). See one of the following
            packages for an example: <a xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" href=
            "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/fonts/acroread-jpnfont/README.html"
            target="_top"><code xmlns="" class=
            "filename">fonts/acroread-jpnfont</code></a>, <a xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" href=
            "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/sysutils/storage-manager/README.html"
            target="_top"><code xmlns="" class=
            "filename">sysutils/storage-manager</code></a>.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "modified-distfiles-same-name"></a>16.2.2.&nbsp;How
                  to handle modified distfiles with the 'old'
                  name</h3>
                </div>
              </div>
            </div>

            <p>Sometimes authors of a software package make some
            modifications after the software was released, and they
            put up a new distfile without changing the package's
            version number. If a package is already in pkgsrc at
            that time, the checksum will no longer match. The
            contents of the new distfile should be compared against
            the old one before changing anything, to make sure the
            distfile was really updated on purpose, and that no
            trojan horse or so crept in. Then, the correct way to
            work around this is to set <code class=
            "varname">DIST_SUBDIR</code> to a unique directory
            name, usually based on <code class=
            "varname">PKGNAME_NOREV</code>. In case this happens
            more often, <code class="varname">PKGNAME</code> can be
            used (thus including the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">nbX</code> suffix) or a date stamp can be
            appended, like <code class=
            "varname">${PKGNAME_NOREV}-YYYYMMDD</code>. Do not
            forget regenerating the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">distinfo</code> file after that, since it
            contains the <code class="varname">DIST_SUBDIR</code>
            path in the filenames. Furthermore, a mail to the
            package's authors seems appropriate telling them that
            changing distfiles after releases without changing the
            file names is not good practice.</p>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "configuration-gotchas"></a>16.3.&nbsp;Configuration
                gotchas</h2>
              </div>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "fixes.libtool"></a>16.3.1.&nbsp;Shared libraries
                  - libtool</h3>
                </div>
              </div>
            </div>

            <p>pkgsrc supports many different machines, with
            different object formats like a.out and ELF, and
            varying abilities to do shared library and dynamic
            loading at all. To accompany this, varying commands and
            options have to be passed to the compiler, linker, etc.
            to get the Right Thing, which can be pretty annoying
            especially if you don't have all the machines at your
            hand to test things. The <a xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" href=
            "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/libtool/README.html"
            target="_top"><code xmlns="" class=
            "filename">devel/libtool</code></a> pkg can help here,
            as it just &#8220;<span class=
            "quote">knows</span>&#8221; how to build both static
            and dynamic libraries from a set of source files, thus
            being platform-independent.</p>

            <p>Here's how to use libtool in a pkg in seven simple
            steps:</p>

            <div class="orderedlist">
              <ol type="1">
                <li>
                  <p>Add <code class=
                  "varname">USE_LIBTOOL=yes</code> to the package
                  Makefile.</p>
                </li>

                <li>
                  <p>For library objects, use &#8220;<span class=
                  "quote">${LIBTOOL} --mode=compile
                  ${CC}</span>&#8221; in place of
                  &#8220;<span class="quote">${CC}</span>&#8221;.
                  You could even add it to the definition of
                  <code class="varname">CC</code>, if only
                  libraries are being built in a given Makefile.
                  This one command will build both PIC and non-PIC
                  library objects, so you need not have separate
                  shared and non-shared library rules.</p>
                </li>

                <li>
                  <p>For the linking of the library, remove any
                  &#8220;<span class="quote">ar</span>&#8221;,
                  &#8220;<span class="quote">ranlib</span>&#8221;,
                  and &#8220;<span class="quote">ld
                  -Bshareable</span>&#8221; commands, and instead
                  use:</p>
                  <pre class="programlisting">
    ${LIBTOOL} --mode=link ${CC} -o ${.TARGET:.a=.la} ${OBJS:.o=.lo} \
        -rpath ${PREFIX}/lib -version-info major:minor
</pre>

                  <p>Note that the library is changed to have a
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">.la</code> extension, and the objects
                  are changed to have a <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">.lo</code> extension. Change
                  <code class="varname">OBJS</code> as necessary.
                  This automatically creates all of the
                  <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
                  class="filename">.a</code>, <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">.so.major.minor</code>, and ELF
                  symlinks (if necessary) in the build directory.
                  Be sure to include &#8220;<span class=
                  "quote">-version-info</span>&#8221;, especially
                  when major and minor are zero, as libtool will
                  otherwise strip off the shared library
                  version.</p>

                  <p>From the libtool manual:</p>
                  <pre class="programlisting">
    So, libtool library versions are described by three integers:

    CURRENT
        The most recent interface number that this library implements.

    REVISION
        The implementation number of the CURRENT interface.

    AGE
        The difference between the newest and oldest interfaces that
        this library implements.  In other words, the library implements
        all the interface numbers in the range from number `CURRENT -
        AGE' to `CURRENT'.

    If two libraries have identical CURRENT and AGE numbers, then the
    dynamic linker chooses the library with the greater REVISION number.
</pre>

                  <p>The &#8220;<span class=
                  "quote">-release</span>&#8221; option will
                  produce different results for a.out and ELF
                  (excluding symlinks) in only one case. An ELF
                  library of the form &#8220;<span class=
                  "quote">libfoo-release.so.<span class=
                  "emphasis"><em>x</em></span>.<span class=
                  "emphasis"><em>y</em></span></span>&#8221; will
                  have a symlink of &#8220;<span class=
                  "quote">libfoo.so.<span class=
                  "emphasis"><em>x</em></span>.<span class=
                  "emphasis"><em>y</em></span></span>&#8221; on an
                  a.out platform. This is handled
                  automatically.</p>

                  <p>The &#8220;<span class="quote">-rpath
                  argument</span>&#8221; is the install directory
                  of the library being built.</p>

                  <p>In the <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">PLIST</code>, include only the
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">.la</code> file, the other files will
                  be added automatically.</p>
                </li>

                <li>
                  <p>When linking shared object (<code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">.so</code>) files, i.e. files that are
                  loaded via <a href=
                  "http://netbsd.gw.com/cgi-bin/man-cgi?dlopen+3+NetBSD-current">
                  <span class="citerefentry"><span class=
                  "refentrytitle">dlopen</span>(3)</span></a>, NOT
                  shared libraries, use &#8220;<span class=
                  "quote">-module -avoid-version</span>&#8221; to
                  prevent them getting version tacked on.</p>

                  <p>The <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">PLIST</code> file gets the
                  <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
                  class="filename">foo.so</code> entry.</p>
                </li>

                <li>
                  <p>When linking programs that depend on these
                  libraries <span class=
                  "emphasis"><em>before</em></span> they are
                  installed, preface the <a href=
                  "http://netbsd.gw.com/cgi-bin/man-cgi?cc+1+NetBSD-current">
                  <span class="citerefentry"><span class=
                  "refentrytitle">cc</span>(1)</span></a> or
                  <a href=
                  "http://netbsd.gw.com/cgi-bin/man-cgi?ld+1+NetBSD-current">
                  <span class="citerefentry"><span class=
                  "refentrytitle">ld</span>(1)</span></a> line with
                  &#8220;<span class="quote">${LIBTOOL}
                  --mode=link</span>&#8221;, and it will find the
                  correct libraries (static or shared), but please
                  be aware that libtool will not allow you to
                  specify a relative path in -L (such as
                  &#8220;<span class=
                  "quote">-L../somelib</span>&#8221;), because it
                  expects you to change that argument to be the
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">.la</code> file. e.g.</p>
                  <pre class="programlisting">
    ${LIBTOOL} --mode=link ${CC} -o someprog -L../somelib -lsomelib
</pre>

                  <p>should be changed to:</p>
                  <pre class="programlisting">
    ${LIBTOOL} --mode=link ${CC} -o <em class=
"replaceable"><code>someprog</code></em> <em class=
"replaceable"><code>../somelib/somelib.la</code></em>
</pre>

                  <p>and it will do the right thing with the
                  libraries.</p>
                </li>

                <li>
                  <p>When installing libraries, preface the
                  <a href="http://netbsd.gw.com/cgi-bin/man-cgi?install+1+NetBSD-current">
                  <span class="citerefentry"><span class=
                  "refentrytitle">install</span>(1)</span></a> or
                  <a href=
                  "http://netbsd.gw.com/cgi-bin/man-cgi?cp+1+NetBSD-current">
                  <span class="citerefentry"><span class=
                  "refentrytitle">cp</span>(1)</span></a> command
                  with &#8220;<span class="quote">${LIBTOOL}
                  --mode=install</span>&#8221;, and change the
                  library name to <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">.la</code>. e.g.</p>
                  <pre class="programlisting">
    ${LIBTOOL} --mode=install ${BSD_INSTALL_DATA} ${SOMELIB:.a=.la} ${PREFIX}/lib
</pre>

                  <p>This will install the static <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">.a</code>, shared library, any needed
                  symlinks, and run <a href=
                  "http://netbsd.gw.com/cgi-bin/man-cgi?ldconfig+8+NetBSD-current">
                  <span class="citerefentry"><span class=
                  "refentrytitle">ldconfig</span>(8)</span></a>.</p>
                </li>

                <li>
                  <p>In your <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">PLIST</code>, include only the
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">.la</code> file (this is a change from
                  previous behaviour).</p>
                </li>
              </ol>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "using-libtool"></a>16.3.2.&nbsp;Using libtool on
                  GNU packages that already support libtool</h3>
                </div>
              </div>
            </div>

            <p>Add <code class="varname">USE_LIBTOOL=yes</code> to
            the package Makefile. This will override the package's
            own libtool in most cases. For older libtool using
            packages, libtool is made by ltconfig script during the
            do-configure step; you can check the libtool script
            location by doing <span><strong class="command">make
            configure; find work*/ -name
            libtool</strong></span>.</p>

            <p><code class="varname">LIBTOOL_OVERRIDE</code>
            specifies which libtool scripts, relative to
            <code class="varname">WRKSRC</code>, to override. By
            default, it is set to &#8220;<span class=
            "quote">libtool */libtool */*/libtool</span>&#8221;. If
            this does not match the location of the package's
            libtool script(s), set it as appropriate.</p>

            <p>If you do not need <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">*.a</code> static libraries built and
            installed, then use <code class=
            "varname">SHLIBTOOL_OVERRIDE</code> instead.</p>

            <p>If your package makes use of the
            platform-independent library for loading dynamic shared
            objects, that comes with libtool (libltdl), you should
            include devel/libltdl/buildlink3.mk.</p>

            <p>Some packages use libtool incorrectly so that the
            package may not work or build in some circumstances.
            Some of the more common errors are:</p>

            <div class="itemizedlist">
              <ul type="disc">
                <li>
                  <p>The inclusion of a shared object (-module) as
                  a dependent library in an executable or library.
                  This in itself isn't a problem if one of two
                  things has been done:</p>

                  <div class="orderedlist">
                    <ol type="1">
                      <li>
                        <p>The shared object is named correctly,
                        i.e. <code xmlns=
                        "http://www.w3.org/TR/xhtml1/transitional"
                        class="filename">libfoo.la</code>, not
                        <code xmlns=
                        "http://www.w3.org/TR/xhtml1/transitional"
                        class="filename">foo.la</code></p>
                      </li>

                      <li>
                        <p>The -dlopen option is used when linking
                        an executable.</p>
                      </li>
                    </ol>
                  </div>
                </li>

                <li>
                  <p>The use of libltdl without the correct calls
                  to initialisation routines. The function
                  lt_dlinit() should be called and the macro
                  <code class=
                  "varname">LTDL_SET_PRELOADED_SYMBOLS</code>
                  included in executables.</p>
                </li>
              </ul>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "autoconf-automake"></a>16.3.3.&nbsp;GNU
                  Autoconf/Automake</h3>
                </div>
              </div>
            </div>

            <p>If a package needs GNU autoconf or automake to be
            executed to regenerate the configure script and
            Makefile.in makefile templates, then they should be
            executed in a pre-configure target.</p>

            <p>For packages that need only autoconf:</p>
            <pre class="programlisting">
    AUTOCONF_REQD=  2.50            # if default version is not good enough
    USE_TOOLS+=     autoconf        # use "autoconf213" for autoconf-2.13
    ...

    pre-configure:
            cd ${WRKSRC}; autoconf

    ...
</pre>

            <p>and for packages that need automake and
            autoconf:</p>
            <pre class="programlisting">
    AUTOMAKE_REQD=  1.7.1           # if default version is not good enough
    USE_TOOLS+=     automake        # use "automake14" for automake-1.4
    ...

    pre-configure:
            cd ${WRKSRC};                          \
            aclocal; autoheader;                   \
            automake -a --foreign -i; autoconf

    ...
</pre>

            <p>Packages which use GNU Automake will almost
            certainly require GNU Make.</p>

            <p>There are times when the configure process makes
            additional changes to the generated files, which then
            causes the build process to try to re-execute the
            automake sequence. This is prevented by touching
            various files in the configure stage. If this causes
            problems with your package you can set <code class=
            "varname">AUTOMAKE_OVERRIDE=NO</code> in the package
            Makefile.</p>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "fixes-build"></a>16.4.&nbsp;Building the
                package</h2>
              </div>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "cpp-defines"></a>16.4.1.&nbsp;CPP defines</h3>
                </div>
              </div>
            </div>

            <p>Sometimes you need to compile different code
            depending on the target platform. The C preprocessor
            has a set of predefined macros that can be queried by
            using <code class="varname">#ifdef FOO</code> or
            <code class="varname">#if defined(FOO)</code>. Among
            these macros are usually ones that describe the target
            CPU and operating system. Depending of which of the
            macros are defined, you can write code that uses
            features unique to a specific platform. Generally you
            should rather use the GNU autotools (automake,
            autoconf, etc.) to check for specific features (like
            the existence of a header file, a function or a
            library), but sometimes this is not possible or
            desired.</p>

            <p>In that case you can use the predefined macros below
            to configure your code to the platform it runs on.
            Almost every operating system, hardware architecture
            and compiler has its own macro. For example, if the
            macros <code class="varname">__GNUC__</code>,
            <code class="varname">__i386__</code> and <code class=
            "varname">__NetBSD__</code> are all defined, you know
            that you are using NetBSD on an i386 compatible CPU,
            and your compiler is GCC.</p>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "fixes-build-cpp-opsys"></a>16.4.1.1.&nbsp;CPP
                    defines for operating systems</h4>
                  </div>
                </div>
              </div>

              <p>To distinguish between 4.4 BSD-derived systems and
              the rest of the world, you should use the following
              code.</p>
              <pre class="programlisting">
    #include &lt;sys/param.h&gt;
    #if (defined(BSD) &amp;&amp; BSD &gt;= 199306)
      /* BSD-specific code goes here */
    #else
      /* non-BSD-specific code goes here */
    #endif
</pre>

              <p>If this distinction is not fine enough, you can
              also use the following defines.</p>
              <pre class="programlisting">
    FreeBSD     __FreeBSD__
    DragonFly   __DragonFly__
    Interix     __INTERIX
    Linux       linux, __linux, __linux__
    NetBSD      __NetBSD__
    OpenBSD     __OpenBSD__
    Solaris     sun, __sun
</pre>
            </div>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "fixes-build-cpp-cpu"></a>16.4.1.2.&nbsp;CPP
                    defines for CPUs</h4>
                  </div>
                </div>
              </div>
              <pre class="programlisting">
    i386        i386, __i386, __i386__
    MIPS        __mips
    SPARC       sparc, __sparc
</pre>
            </div>

            <div class="sect3" lang="en">
              <div class="titlepage">
                <div>
                  <div>
                    <h4 class="title"><a name=
                    "fixes-build-cpp-compiler"></a>16.4.1.3.&nbsp;CPP
                    defines for compilers</h4>
                  </div>
                </div>
              </div>
              <pre class="programlisting">
    GCC         __GNUC__ (major version), __GNUC_MINOR__
    SunPro      __SUNPRO_C (0x570 for version 5.7)
</pre>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "cpp-list-examples"></a>16.4.2.&nbsp;Examples of
                  CPP defines for some platforms</h3>
                </div>
              </div>
            </div>

            <p>The list of the CPP identification macros for
            hardware and operating system may depend on the
            compiler that is used. The following list contains some
            examples that may help you to choose the right ones.
            For example, if you want to conditionally compile code
            on Solaris, don't use <code class=
            "varname">__sun__</code>, as the SunPro compiler does
            not define it. Use <code class="varname">__sun</code>
            instead.</p>

            <div class="variablelist">
              <dl>
                <dt><span class="term">GCC 3.3.3 + SuSE Linux 9.1 +
                i386</span></dt>

                <dd>
                  <p>__ELF__, __gnu_linux__, __i386, __i386__,
                  __linux, __linux__, __unix, __unix__, i386,
                  linux, unix.</p>
                </dd>

                <dt><span class="term">GCC 2.95 + NetBSD 1.6.2 +
                i386</span></dt>

                <dd>
                  <p>__ELF__, __NetBSD__, __i386, __i386__,
                  i386.</p>
                </dd>

                <dt><span class="term">GCC 3.3.3 + NetBSD 2.0 +
                i386</span></dt>

                <dd>
                  <p>__ELF__, __NetBSD__, __i386, __i386__,
                  i386.</p>
                </dd>

                <dt><span class="term">GCC 4 + Solaris 8 +
                SPARC</span></dt>

                <dd>
                  <p>__ELF__, __sparc, __sparc__, __sun, __sun__,
                  __SVR4, __svr4__, __unix, __unix__, sparc, sun,
                  unix.</p>
                </dd>

                <dt><span class="term">SunPro 5.7 + Solaris 8 +
                SPARC</span></dt>

                <dd>
                  <p>__SVR4, __sparc, __sun, __unix, sparc, sun,
                  unix.</p>
                </dd>
              </dl>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "cpp-list"></a>16.4.3.&nbsp;Getting a list of CPP
                  defines</h3>
                </div>
              </div>
            </div>

            <p>If your system uses the GNU C Compiler, you can get
            a list of symbols that are defined by default, e.g. to
            identify the platform, with the following command:</p>
            <pre class="programlisting">
    gcc -E -dM - &lt; /dev/null 
</pre>

            <p>On other systems you may get the list by using the
            system's syscall trace utility (ktrace, truss, strace)
            to have a look which arguments are passed to the actual
            compiler.</p>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "package-specific-actions"></a>16.5.&nbsp;Package
                specific actions</h2>
              </div>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "user-interaction"></a>16.5.1.&nbsp;User
                  interaction</h3>
                </div>
              </div>
            </div>

            <p>Occasionally, packages require interaction from the
            user, and this can be in a number of ways:</p>

            <div class="itemizedlist">
              <ul type="disc">
                <li>
                  <p>help in fetching the distfiles</p>
                </li>

                <li>
                  <p>help to configure the package before it is
                  built</p>
                </li>

                <li>
                  <p>help during the build process</p>
                </li>

                <li>
                  <p>help during the installation of a package</p>
                </li>
              </ul>
            </div>

            <p>The <code class="varname">INTERACTIVE_STAGE</code>
            definition is provided to notify the pkgsrc mechanism
            of an interactive stage which will be needed, and this
            should be set in the package's <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">Makefile</code>, e.g.:</p>
            <pre class="programlisting">
    INTERACTIVE_STAGE=      build
</pre>

            <p>Multiple interactive stages can be specified:</p>
            <pre class="programlisting">
    INTERACTIVE_STAGE=      configure install
</pre>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "handling-licenses"></a>16.5.2.&nbsp;Handling
                  licenses</h3>
                </div>
              </div>
            </div>

            <p>A package may be covered by a license which the user
            has or has not agreed to accept. For these cases,
            pkgsrc contains a mechanism to note that a package is
            covered by a particular license, and the package cannot
            be built unless the user has accepted the license.
            (Installation of binary packages are not currently
            subject to this mechanism.) Packages with licenses that
            are either Open Source according to the Open Source
            Initiative or Free according to the Free Software
            Foundation will not be marked with a license tag.
            Packages with licenses that have not been determined to
            meet either definition will be marked with a license
            tag referring to the license. This will prevent
            building unless pkgsrc is informed that the license is
            acceptable, and enables displaying the license.</p>

            <p>The license tag mechanism is intended to address
            copyright-related issues surrounding building,
            installing and using a package, and not to address
            redistribution issues (see <code class=
            "varname">RESTRICTED</code> and <code class=
            "varname">NO_SRC_ON_FTP</code>, etc.). However, the
            above definition of licenses for which tags are not
            needed implies that packages with redistribution
            restrictions should have tags.</p>

            <p>Denoting that a package is covered by a particular
            license is done by placing the license in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">pkgsrc/licenses</code> and setting the
            <code class="varname">LICENSE</code> variable to a
            string identifying the license, e.g. in <a xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" href=
            "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/graphics/xv/README.html"
            target="_top"><code xmlns="" class=
            "filename">graphics/xv</code></a>:</p>
            <pre class="programlisting">
    LICENSE=        xv-license
</pre>

            <p>When trying to build, the user will get a notice
            that the package is covered by a license which has not
            been accepted:</p>
            <pre class="programlisting">
    <code class="prompt">%</code> <strong class=
"userinput"><code>make</code></strong>
    ===&gt; xv-3.10anb9 has an unacceptable license: xv-license.
    ===&gt;     To view the license, enter "/usr/bin/make show-license".
    ===&gt;     To indicate acceptance, add this line to your /etc/mk.conf:
    ===&gt;     ACCEPTABLE_LICENSES+=xv-license
    *** Error code 1
</pre>

            <p>The license can be viewed with <span><strong class=
            "command">make show-license</strong></span>, and if it
            is considered appropriate, the line printed above can
            be added to <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/etc/mk.conf</code> to indicate acceptance
            of the particular license:</p>
            <pre class="programlisting">
    ACCEPTABLE_LICENSES+=xv-license
</pre>

            <p>When adding a package with a new license, the
            license text should be added to <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">pkgsrc/licenses</code> for displaying. A
            list of known licenses can be seen in this directory as
            well as by looking at the list of (commented out)
            <code class="varname">ACCEPTABLE_LICENSES</code>
            variable settings in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">pkgsrc/mk/defaults/mk.conf</code>.</p>

            <p>The use of <code class=
            "varname">LICENSE=shareware</code>, <code class=
            "varname">LICENSE=no-commercial-use</code>, and similar
            language is deprecated because it does not crisply
            refer to a particular license text. Another problem
            with such usage is that it does not enable a user to
            denote acceptance of the license for a single package
            without accepting the same license text for another
            package. In particular, this can be inappropriate when
            e.g. one accepts a particular license to indicate to
            pkgsrc that a fee has been paid.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "installing-score-files"></a>16.5.3.&nbsp;Installing
                  score files</h3>
                </div>
              </div>
            </div>

            <p>Certain packages, most of them in the games
            category, install a score file that allows all users on
            the system to record their highscores. In order for
            this to work, the binaries need to be installed setgid
            and the score files owned by the appropriate group
            and/or owner (traditionally the "games" user/group).
            The following variables, documented in more detail in
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">mk/defaults/mk.conf</code>, control
            this behaviour: <code class=
            "varname">SETGIDGAME</code>, <code class=
            "varname">GAMEDATAMODE</code>, <code class=
            "varname">GAMEGRP</code>, <code class=
            "varname">GAMEMODE</code>, <code class=
            "varname">GAMEOWN</code>.</p>

            <p>Note that per default, setgid installation of games
            is disabled; setting <code class=
            "varname">SETGIDGAME=YES</code> will set all the other
            variables accordingly.</p>

            <p>A package should therefor never hard code file
            ownership or access permissions but rely on
            <code class="varname">INSTALL_GAME</code> and
            <code class="varname">INSTALL_GAME_DATA</code> to set
            these correctly.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "perl-scripts"></a>16.5.4.&nbsp;Packages
                  containing perl scripts</h3>
                </div>
              </div>
            </div>

            <p>If your package contains interpreted perl scripts,
            set <code class="varname">REPLACE_PERL</code> to ensure
            that the proper interpreter path is set. <code class=
            "varname">REPLACE_PERL</code> should contain a list of
            scripts, relative to <code class=
            "varname">WRKSRC</code>, that you want adjusted.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "hardcoded-paths"></a>16.5.5.&nbsp;Packages with
                  hardcoded paths to other interpreters</h3>
                </div>
              </div>
            </div>

            <p>Your package may also contain scripts with hardcoded
            paths to other interpreters besides (or as well as)
            perl. To correct the full pathname to the script
            interpreter, you need to set the following definitions
            in your <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">Makefile</code> (we shall use
            <span><strong class="command">tclsh</strong></span> in
            this example):</p>
            <pre class="programlisting">
    REPLACE_INTERPRETER+=   tcl
    REPLACE.tcl.old=        .*/bin/tclsh
    REPLACE.tcl.new=        ${PREFIX}/bin/tclsh
    REPLACE_FILES.tcl=      # list of tcl scripts which need to be fixed,
                            # relative to ${WRKSRC}, just as in REPLACE_PERL
</pre>

            <div class="note" style=
            "margin-left: 0.5in; margin-right: 0.5in;">
              <h3 class="title">Note</h3>

              <p>Before March 2006, these variables were called
              <code class="varname">_REPLACE.*</code> and
              <code class="varname">_REPLACE_FILES.*</code>.</p>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "perl-modules"></a>16.5.6.&nbsp;Packages
                  installing perl modules</h3>
                </div>
              </div>
            </div>

            <p>Makefiles of packages providing perl5 modules should
            include the Makefile fragment <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">../../lang/perl5/module.mk</code>. It
            provides a <span><strong class=
            "command">do-configure</strong></span> target for the
            standard perl configuration for such modules as well as
            various hooks to tune this configuration. See comments
            in this file for details.</p>

            <p>Perl5 modules will install into different places
            depending on the version of perl used during the build
            process. To address this, pkgsrc will append lines to
            the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">PLIST</code> corresponding to the files
            listed in the installed <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">.packlist</code> file generated by most
            perl5 modules. This is invoked by defining <code class=
            "varname">PERL5_PACKLIST</code> to a space-separated
            list of paths to packlist files, e.g.:</p>
            <pre class="programlisting">
    PERL5_PACKLIST= ${PERL5_SITEARCH}/auto/Pg/.packlist
</pre>

            <p>The variables <code class=
            "varname">PERL5_SITELIB</code>, <code class=
            "varname">PERL5_SITEARCH</code>, and <code class=
            "varname">PERL5_ARCHLIB</code> represent the three
            locations in which perl5 modules may be installed, and
            may be used by perl5 packages that don't have a
            packlist. These three variables are also substituted
            for in the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">PLIST</code>.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "faq.info-files"></a>16.5.7.&nbsp;Packages
                  installing info files</h3>
                </div>
              </div>
            </div>

            <p>Some packages install info files or use the
            &#8220;<span class="quote">makeinfo</span>&#8221; or
            &#8220;<span class="quote">install-info</span>&#8221;
            commands. Each of the info files:</p>

            <div class="itemizedlist">
              <ul type="disc">
                <li>
                  <p>is considered to be installed in the directory
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">${PREFIX}/${INFO_DIR}</code>,</p>
                </li>

                <li>
                  <p>is registered in the Info directory file
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">${PREFIX}/${INFO_DIR}/dir</code>,</p>
                </li>

                <li>
                  <p>and must be listed as a filename in the
                  <code class="varname">INFO_FILES</code> variable
                  in the package Makefile.</p>
                </li>
              </ul>
            </div>

            <p><code class="varname">INFO_DIR</code> defaults to
            &#8220;<span class="quote">info</span>&#8221; and can
            be overridden in the package Makefile. <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">INSTALL</code> and <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">DEINSTALL</code> scripts will be generated
            to handle registration of the info files in the Info
            directory file. The &#8220;<span class=
            "quote">install-info</span>&#8221; command used for the
            info files registration is either provided by the
            system, or by a special purpose package automatically
            added as dependency if needed.</p>

            <p>A package which needs the &#8220;<span class=
            "quote">makeinfo</span>&#8221; command at build time
            must define the variable <code class=
            "varname">USE_MAKEINFO</code> in its Makefile. If a
            minimum version of the &#8220;<span class=
            "quote">makeinfo</span>&#8221; command is needed it
            should be noted with the <code class=
            "varname">TEXINFO_REQD</code> variable in the package
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">Makefile</code>. By default, a minimum
            version of 3.12 is required. If the system does not
            provide a <span><strong class=
            "command">makeinfo</strong></span> command or if it
            does not match the required minimum, a build dependency
            on the <a xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" href=
            "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/devel/gtexinfo/README.html"
            target="_top"><code xmlns="" class=
            "filename">devel/gtexinfo</code></a> package will be
            added automatically.</p>

            <p>The build and installation process of the software
            provided by the package should not use the
            <span><strong class=
            "command">install-info</strong></span> command as the
            registration of info files is the task of the package
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">INSTALL</code> script, and it must use
            the appropriate <span><strong class=
            "command">makeinfo</strong></span> command.</p>

            <p>To achieve this goal, the pkgsrc infrastructure
            creates overriding scripts for the <span><strong class=
            "command">install-info</strong></span> and
            <span><strong class="command">makeinfo</strong></span>
            commands in a directory listed early in <code class=
            "varname">PATH</code>.</p>

            <p>The script overriding <span><strong class=
            "command">install-info</strong></span> has no effect
            except the logging of a message. The script overriding
            <span><strong class="command">makeinfo</strong></span>
            logs a message and according to the value of
            <code class="varname">USE_MAKEINFO</code> and
            <code class="varname">TEXINFO_REQD</code> either run
            the appropriate <span><strong class=
            "command">makeinfo</strong></span> command or exit on
            error.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "manpages"></a>16.5.8.&nbsp;Packages installing
                  man pages</h3>
                </div>
              </div>
            </div>

            <p>Many packages install manual pages. The man pages
            are installed under <code class=
            "varname">${PREFIX}/${PKGMANDIR}</code> which is
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">/usr/pkg/man</code> by default.
            <code class="varname">PKGMANDIR</code> defaults to
            &#8220;<span class="quote">man</span>&#8221;. For
            example, you can set <code class=
            "varname">PKGMANDIR</code> to &#8220;<span class=
            "quote">share/man</span>&#8221; to have man pages
            install under <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/usr/pkg/share/man/</code> by default.</p>

            <div class="note" style=
            "margin-left: 0.5in; margin-right: 0.5in;">
              <h3 class="title">Note</h3>

              <p>The support for a custom <code class=
              "varname">PKGMANDIR</code> is not complete.</p>
            </div>

            <p>The <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">PLIST</code> files can just use <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">man/</code> as the top level directory for
            the man page file entries and the pkgsrc framework will
            convert as needed.</p>

            <p>Packages that are configured with <code class=
            "varname">GNU_CONFIGURE</code> set as
            &#8220;<span class="quote">yes</span>&#8221;, by
            default will use the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">./configure</code> --mandir switch to set
            where the man pages should be installed. The path is
            <code class="varname">GNU_CONFIGURE_MANDIR</code> which
            defaults to <code class=
            "varname">${PREFIX}/${PKGMANDIR}</code>.</p>

            <p>Packages that use <code class=
            "varname">GNU_CONFIGURE</code> but do not use --mandir,
            can set <code class=
            "varname">CONFIGURE_HAS_MANDIR</code> to
            &#8220;<span class="quote">no</span>&#8221;. Or if the
            <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
            class="filename">./configure</code> script uses a
            non-standard use of --mandir, you can set <code class=
            "varname">GNU_CONFIGURE_MANDIR</code> as needed.</p>

            <p>See <a href="#manpage-compression" title=
            "10.5.&nbsp;Man page compression">Section&nbsp;10.5,
            &#8220;Man page compression&#8221;</a> for information
            on installation of compressed manual pages.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "gconf2-data-files"></a>16.5.9.&nbsp;Packages
                  installing GConf2 data files</h3>
                </div>
              </div>
            </div>

            <p>If a package installs <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">.schemas</code> or <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">.entries</code> files, used by GConf2, you
            need to take some extra steps to make sure they get
            registered in the database:</p>

            <div class="orderedlist">
              <ol type="1">
                <li>
                  <p>Include <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">../../devel/GConf2/schemas.mk</code>
                  instead of its <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">buildlink3.mk</code> file. This takes
                  care of rebuilding the GConf2 database at
                  installation and deinstallation time, and tells
                  the package where to install GConf2 data files
                  using some standard configure arguments. It also
                  disallows any access to the database directly
                  from the package.</p>
                </li>

                <li>
                  <p>Ensure that the package installs its
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">.schemas</code> files under
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">${PREFIX}/share/gconf/schemas</code>.
                  If they get installed under <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">${PREFIX}/etc</code>, you will need to
                  manually patch the package.</p>
                </li>

                <li>
                  <p>Check the PLIST and remove any entries under
                  the etc/gconf directory, as they will be handled
                  automatically. See <a href="#faq.conf" title=
                  "7.14.&nbsp;How do I change the location of configuration files?">
                  Section&nbsp;7.14, &#8220;How do I change the
                  location of configuration files?&#8221;</a> for
                  more information.</p>
                </li>

                <li>
                  <p>Define the <code class=
                  "varname">GCONF2_SCHEMAS</code> variable in your
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">Makefile</code> with a list of all
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">.schemas</code> files installed by the
                  package, if any. Names must not contain any
                  directories in them.</p>
                </li>

                <li>
                  <p>Define the <code class=
                  "varname">GCONF2_ENTRIES</code> variable in your
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">Makefile</code> with a list of all
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">.entries</code> files installed by the
                  package, if any. Names must not contain any
                  directories in them.</p>
                </li>
              </ol>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "scrollkeeper-data-files"></a>16.5.10.&nbsp;Packages
                  installing scrollkeeper data files</h3>
                </div>
              </div>
            </div>

            <p>If a package installs <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">.omf</code> files, used by scrollkeeper, you
            need to take some extra steps to make sure they get
            registered in the database:</p>

            <div class="orderedlist">
              <ol type="1">
                <li>
                  <p>Include <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">../../textproc/scrollkeeper/omf.mk</code>
                  instead of its <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">buildlink3.mk</code> file. This takes
                  care of rebuilding the scrollkeeper database at
                  installation and deinstallation time, and
                  disallows any access to it directly from the
                  package.</p>
                </li>

                <li>
                  <p>Check the PLIST and remove any entries under
                  the <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">libdata/scrollkeeper</code> directory,
                  as they will be handled automatically.</p>
                </li>

                <li>
                  <p>Remove the <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">share/omf</code> directory from the
                  PLIST. It will be handled by scrollkeeper.</p>
                </li>
              </ol>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "x11-fonts"></a>16.5.11.&nbsp;Packages installing
                  X11 fonts</h3>
                </div>
              </div>
            </div>

            <p>If a package installs font files, you will need to
            rebuild the fonts database in the directory where they
            get installed at installation and deinstallation time.
            This can be automatically done by using the pkginstall
            framework.</p>

            <p>You can list the directories where fonts are
            installed in the <code class=
            "varname">FONTS_DIRS.<em class=
            "replaceable"><code>type</code></em></code> variables,
            where <em class="replaceable"><code>type</code></em>
            can be one of &#8220;<span class=
            "quote">ttf</span>&#8221;, &#8220;<span class=
            "quote">type1</span>&#8221; or &#8220;<span class=
            "quote">x11</span>&#8221;. Also make sure that the
            database file <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">fonts.dir</code> is not listed in the
            PLIST.</p>

            <p>Note that you should not create new directories for
            fonts; instead use the standard ones to avoid that the
            user needs to manually configure his X server to find
            them.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "gtk2-modules"></a>16.5.12.&nbsp;Packages
                  installing GTK2 modules</h3>
                </div>
              </div>
            </div>

            <p>If a package installs GTK2 immodules or loaders, you
            need to take some extra steps to get them registered in
            the GTK2 database properly:</p>

            <div class="orderedlist">
              <ol type="1">
                <li>
                  <p>Include <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">../../x11/gtk2/modules.mk</code>
                  instead of its <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">buildlink3.mk</code> file. This takes
                  care of rebuilding the database at installation
                  and deinstallation time.</p>
                </li>

                <li>
                  <p>Set <code class=
                  "varname">GTK2_IMMODULES=YES</code> if your
                  package installs GTK2 immodules.</p>
                </li>

                <li>
                  <p>Set <code class=
                  "varname">GTK2_LOADERS=YES</code> if your package
                  installs GTK2 loaders.</p>
                </li>

                <li>
                  <p>Patch the package to not touch any of the GTK2
                  databases directly. These are:</p>

                  <div class="itemizedlist">
                    <ul type="disc">
                      <li>
                        <p><code xmlns=
                        "http://www.w3.org/TR/xhtml1/transitional"
                        class=
                        "filename">libdata/gtk-2.0/gdk-pixbuf.loaders</code></p>
                      </li>

                      <li>
                        <p><code xmlns=
                        "http://www.w3.org/TR/xhtml1/transitional"
                        class=
                        "filename">libdata/gtk-2.0/gtk.immodules</code></p>
                      </li>
                    </ul>
                  </div>
                </li>

                <li>
                  <p>Check the PLIST and remove any entries under
                  the <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">libdata/gtk-2.0</code> directory, as
                  they will be handled automatically.</p>
                </li>
              </ol>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "sgml-xml-data"></a>16.5.13.&nbsp;Packages
                  installing SGML or XML data</h3>
                </div>
              </div>
            </div>

            <p>If a package installs SGML or XML data files that
            need to be registered in system-wide catalogs (like
            DTDs, sub-catalogs, etc.), you need to take some extra
            steps:</p>

            <div class="orderedlist">
              <ol type="1">
                <li>
                  <p>Include <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">../../textproc/xmlcatmgr/catalogs.mk</code>
                  in your <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">Makefile</code>, which takes care of
                  registering those files in system-wide catalogs
                  at installation and deinstallation time.</p>
                </li>

                <li>
                  <p>Set <code class="varname">SGML_CATALOGS</code>
                  to the full path of any SGML catalogs installed
                  by the package.</p>
                </li>

                <li>
                  <p>Set <code class="varname">XML_CATALOGS</code>
                  to the full path of any XML catalogs installed by
                  the package.</p>
                </li>

                <li>
                  <p>Set <code class="varname">SGML_ENTRIES</code>
                  to individual entries to be added to the SGML
                  catalog. These come in groups of three strings;
                  see xmlcatmgr(1) for more information
                  (specifically, arguments recognized by the 'add'
                  action). Note that you will normally not use this
                  variable.</p>
                </li>

                <li>
                  <p>Set <code class="varname">XML_ENTRIES</code>
                  to individual entries to be added to the XML
                  catalog. These come in groups of three strings;
                  see xmlcatmgr(1) for more information
                  (specifically, arguments recognized by the 'add'
                  action). Note that you will normally not use this
                  variable.</p>
                </li>
              </ol>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "mime-database"></a>16.5.14.&nbsp;Packages
                  installing extensions to the MIME database</h3>
                </div>
              </div>
            </div>

            <p>If a package provides extensions to the MIME
            database by installing <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">.xml</code> files inside <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">${PREFIX}/share/mime/packages</code>, you
            need to take some extra steps to ensure that the
            database is kept consistent with respect to these new
            files:</p>

            <div class="orderedlist">
              <ol type="1">
                <li>
                  <p>Include <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">../../databases/shared-mime-info/mimedb.mk</code>
                  (avoid using the <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">buildlink3.mk</code> file from this
                  same directory, which is reserved for inclusion
                  from other <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">buildlink3.mk</code> files). It takes
                  care of rebuilding the MIME database at
                  installation and deinstallation time, and
                  disallows any access to it directly from the
                  package.</p>
                </li>

                <li>
                  <p>Check the PLIST and remove any entries under
                  the <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">share/mime</code> directory,
                  <span class="emphasis"><em>except</em></span> for
                  files saved under <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">share/mime/packages</code>. The former
                  are handled automatically by the
                  update-mime-database program, but the latter are
                  package-dependent and must be removed by the
                  package that installed them in the first
                  place.</p>
                </li>

                <li>
                  <p>Remove any <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">share/mime/*</code> directories from
                  the PLIST. They will be handled by the
                  shared-mime-info package.</p>
                </li>
              </ol>
            </div>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "intltool"></a>16.5.15.&nbsp;Packages using
                  intltool</h3>
                </div>
              </div>
            </div>

            <p>If a package uses intltool during its build, include
            the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">../../textproc/intltool/buildlink3.mk</code>
            file, which forces it to use the intltool package
            provided by pkgsrc, instead of the one bundled with the
            distribution file.</p>

            <p>This tracks intltool's build-time dependencies and
            uses the latest available version; this way, the
            package benefits of any bug fixes that may have
            appeared since it was released.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "startup-scripts"></a>16.5.16.&nbsp;Packages
                  installing startup scripts</h3>
                </div>
              </div>
            </div>

            <p>If a package contains a rc.d script, it won't be
            copied into the startup directory by default, but you
            can enable it, by adding the option <code class=
            "varname">PKG_RCD_SCRIPTS=YES</code> in <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/etc/mk.conf</code>. This option will copy
            the scripts into <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">/etc/rc.d</code> when a package is
            installed, and it will automatically remove the scripts
            when the package is deinstalled.</p>
          </div>

          <div class="sect2" lang="en">
            <div class="titlepage">
              <div>
                <div>
                  <h3 class="title"><a name=
                  "tex-packages"></a>16.5.17.&nbsp;Packages
                  installing TeX modules</h3>
                </div>
              </div>
            </div>

            <p>If a package installs TeX packages into the texmf
            tree, the <code xmlns=
            "http://www.w3.org/TR/xhtml1/transitional" class=
            "filename">ls-R</code> database of the tree needs to be
            updated.</p>

            <div class="note" style=
            "margin-left: 0.5in; margin-right: 0.5in;">
              <h3 class="title">Note</h3>

              <p>Except the main TeX packages such as teTeX-texmf,
              packages should install files into <code class=
              "varname">PKG_LOCALTEXMFPREFIX</code>, not
              <code class="varname">PKG_TEXMFPREFIX</code>.</p>
            </div>

            <div class="orderedlist">
              <ol type="1">
                <li>
                  <p>Include <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">../../print/teTeX/module.mk</code>
                  instead of <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">../../mk/tex.buildlink3.mk</code>.
                  This takes care of rebuilding the <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">ls-R</code> database at installation
                  and deinstallation time.</p>
                </li>

                <li>
                  <p>If your package installs files into a texmf
                  tree other than the one at <code class=
                  "varname">PKG_LOCALTEXMFPREFIX</code>, set
                  <code class="varname">TEXMFDIRS</code> to the
                  list of all texmf trees that need database
                  update.</p>

                  <p>If your package also installs font map files
                  that need to be registered using
                  <span><strong class=
                  "command">updmap</strong></span>, set
                  <code class="varname">TEX_FONTMAPS</code> to the
                  list of all such font map files. Then
                  <span><strong class=
                  "command">updmap</strong></span> will be run
                  automatically at installation/deinstallation to
                  enable/disable font map files for TeX output
                  drivers.</p>
                </li>

                <li>
                  <p>Make sure that none of <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">ls-R</code> databases are included in
                  <code xmlns=
                  "http://www.w3.org/TR/xhtml1/transitional" class=
                  "filename">PLIST</code>, as they will be removed
                  only by the teTeX-bin package.</p>
                </li>
              </ol>
            </div>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "feedback-to-author"></a>16.6.&nbsp;Feedback to the
                author</h2>
              </div>
            </div>
          </div>

          <p>If you have found any bugs in the package you make
          available, if you had to do special steps to make it run
          under NetBSD or if you enhanced the software in various
          other ways, be sure to report these changes back to the
          original author of the program! With that kind of
          support, the next release of the program can incorporate
          these fixes, and people not using the NetBSD packages
          system can win from your efforts.</p>

          <p>Support the idea of free software!</p>
        </div>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "debug"></a>Chapter&nbsp;17.&nbsp;Debugging</h2>
            </div>
          </div>
        </div>

        <p>To check out all the gotchas when building a package,
        here are the steps that I do in order to get a package
        working. Please note this is basically the same as what was
        explained in the previous sections, only with some
        debugging aids.</p>

        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p>Be sure to set <code class=
              "varname">PKG_DEVELOPER=1</code> in <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">/etc/mk.conf</code></p>
            </li>

            <li>
              <p>Install <a xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" href=
              "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/url2pkg/README.html"
              target="_top"><code xmlns="" class=
              "filename">pkgtools/url2pkg</code></a>, create a
              directory for a new package, change into it, then run
              <span><strong class=
              "command">url2pkg</strong></span>:</p>
              <pre class="screen">
<code class="prompt">%</code> <strong class=
"userinput"><code>mkdir /usr/pkgsrc/<em class=
"replaceable"><code>category</code></em>/<em class=
"replaceable"><code>examplepkg</code></em></code></strong>
<code class="prompt">%</code> <strong class=
"userinput"><code>cd /usr/pkgsrc/<em class=
"replaceable"><code>category</code></em>/<em class=
"replaceable"><code>examplepkg</code></em></code></strong>
<code class="prompt">%</code> <strong class=
"userinput"><code>url2pkg http://www.example.com/path/to/distfile.tar.gz</code></strong>
</pre>
            </li>

            <li>
              <p>Edit the <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">Makefile</code> as requested.</p>
            </li>

            <li>
              <p>Fill in the <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">DESCR</code> file</p>
            </li>

            <li>
              <p>Run <span><strong class="command">make
              configure</strong></span></p>
            </li>

            <li>
              <p>Add any dependencies glimpsed from documentation
              and the configure step to the package's <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">Makefile</code>.</p>
            </li>

            <li>
              <p>Make the package compile, doing multiple rounds
              of</p>
              <pre class="screen">
<code class="prompt">%</code> <strong class=
"userinput"><code>make</code></strong>
<code class="prompt">%</code> <strong class=
"userinput"><code>pkgvi ${WRKSRC}/some/file/that/does/not/compile</code></strong>
<code class="prompt">%</code> <strong class=
"userinput"><code>mkpatches</code></strong>
<code class="prompt">%</code> <strong class=
"userinput"><code>patchdiff</code></strong>
<code class="prompt">%</code> <strong class=
"userinput"><code>mv ${WRKDIR}/.newpatches/* patches</code></strong>
<code class="prompt">%</code> <strong class=
"userinput"><code>make mps</code></strong>
<code class="prompt">%</code> <strong class=
"userinput"><code>make clean</code></strong>
</pre>

              <p>Doing as non-root user will ensure that no files
              are modified that shouldn't be, especially during the
              build phase. <span><strong class=
              "command">mkpatches</strong></span>,
              <span><strong class=
              "command">patchdiff</strong></span> and
              <span><strong class="command">pkgvi</strong></span>
              are from the <a xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" href=
              "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkgdiff/README.html"
              target="_top"><code xmlns="" class=
              "filename">pkgtools/pkgdiff</code></a> package.</p>
            </li>

            <li>
              <p>Look at the <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">Makefile</code>, fix if necessary; see
              <a href="#components.Makefile" title=
              "8.1.&nbsp;Makefile">Section&nbsp;8.1,
              &#8220;<code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">Makefile</code>&#8221;</a>.</p>
            </li>

            <li>
              <p>Generate a <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">PLIST</code>:</p>
              <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>make install</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>make print-PLIST &gt;PLIST</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>make deinstall</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>make install</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>make deinstall</code></strong>
</pre>

              <p>You usually need to be <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "username">root</code> to do this. Look if there are
              any files left:</p>
              <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>make print-PLIST</code></strong>
</pre>

              <p>If this reveals any files that are missing in
              <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">PLIST</code>, add them.</p>
            </li>

            <li>
              <p>Now that the <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">PLIST</code> is OK, install the package
              again and make a binary package:</p>
              <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>make reinstall</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>make package</code></strong>
</pre>
            </li>

            <li>
              <p>Delete the installed package:</p>
              <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>pkg_delete blub</code></strong>
</pre>
            </li>

            <li>
              <p>Repeat the above <span><strong class=
              "command">make print-PLIST</strong></span> command,
              which shouldn't find anything now:</p>
              <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>make print-PLIST</code></strong>
</pre>
            </li>

            <li>
              <p>Reinstall the binary package:</p>
              <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>pkgadd .../blub.tgz</code></strong>
</pre>
            </li>

            <li>
              <p>Play with it. Make sure everything works.</p>
            </li>

            <li>
              <p>Run <span><strong class=
              "command">pkglint</strong></span> from <a xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" href=
              "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkglint/README.html"
              target="_top"><code xmlns="" class=
              "filename">pkgtools/pkglint</code></a>, and fix the
              problems it reports:</p>
              <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>pkglint</code></strong>
</pre>
            </li>

            <li>
              <p>Submit (or commit, if you have cvs access); see
              <a href="#submit" title=
              "Chapter&nbsp;18.&nbsp;Submitting and Committing">Chapter&nbsp;18,
              <i>Submitting and Committing</i></a>.</p>
            </li>
          </ul>
        </div>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "submit"></a>Chapter&nbsp;18.&nbsp;Submitting and
              Committing</h2>
            </div>
          </div>
        </div>

        <div class="toc">
          <p><b>Table of Contents</b></p>

          <dl>
            <dt><span class="sect1"><a href=
            "#submitting-your-package">18.1. Submitting your
            packages</a></span></dt>

            <dt><span class="sect1"><a href=
            "#general-notes-for-changes">18.2. General notes when
            adding, updating, or removing packages</a></span></dt>

            <dt><span class="sect1"><a href=
            "#committing-importing">18.3. Committing: Importing a
            package into CVS</a></span></dt>

            <dt><span class="sect1"><a href=
            "#updating-package">18.4. Updating a package to a newer
            version</a></span></dt>

            <dt><span class="sect1"><a href="#moving-package">18.5.
            Moving a package in pkgsrc</a></span></dt>
          </dl>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "submitting-your-package"></a>18.1.&nbsp;Submitting
                your packages</h2>
              </div>
            </div>
          </div>

          <p>You have to separate between binary and
          &#8220;<span class="quote">normal</span>&#8221; (source)
          packages here:</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p>precompiled binary packages</p>

                <p>Our policy is that we accept binaries only from
                pkgsrc developers to guarantee that the packages
                don't contain any trojan horses etc. This is not to
                annoy anyone but rather to protect our users!
                You're still free to put up your home-made binary
                packages and tell the world where to get them.
                NetBSD developers doing bulk builds and wanting to
                upload them please see <a href="#bulk-upload"
                title="6.3.8.&nbsp;Uploading results of a bulk build">
                Section&nbsp;6.3.8, &#8220;Uploading results of a
                bulk build&#8221;</a>.</p>
              </li>

              <li>
                <p>packages</p>

                <p>First, check that your package is complete,
                compiles and runs well; see <a href="#debug" title=
                "Chapter&nbsp;17.&nbsp;Debugging">Chapter&nbsp;17,
                <i>Debugging</i></a> and the rest of this document.
                Next, generate an uuencoded gzipped <a href=
                "http://netbsd.gw.com/cgi-bin/man-cgi?tar+1+NetBSD-current">
                <span class="citerefentry"><span class=
                "refentrytitle">tar</span>(1)</span></a> archive,
                preferably with all files in a single directory.
                Finally, <span><strong class=
                "command">send-pr</strong></span> with category
                &#8220;<span class="quote">pkg</span>&#8221;, a
                synopsis which includes the package name and
                version number, a short description of your package
                (contents of the COMMENT variable or DESCR file are
                OK) and attach the archive to your PR.</p>

                <p>If you want to submit several packages, please
                send a separate PR for each one, it's easier for us
                to track things that way.</p>

                <p>Alternatively, you can also import new packages
                into pkgsrc-wip (&#8220;<span class="quote">pkgsrc
                work-in-progress</span>&#8221;); see the homepage
                at <a href="http://pkgsrc-wip.sourceforge.net/"
                target=
                "_top">http://pkgsrc-wip.sourceforge.net/</a> for
                details.</p>
              </li>
            </ul>
          </div>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "general-notes-for-changes"></a>18.2.&nbsp;General
                notes when adding, updating, or removing
                packages</h2>
              </div>
            </div>
          </div>

          <p>Please note all package additions, updates, moves, and
          removals in <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">pkgsrc/doc/CHANGES</code>. It's very important
          to keep this file up to date and conforming to the
          existing format, because it will be used by scripts to
          automatically update pages on <a href=
          "http://www.NetBSD.org/" target="_top">www.NetBSD.org</a>
          and other sites. Additionally, check the <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">pkgsrc/doc/TODO</code> file and remove the
          entry for the package you updated or removed, in case it
          was mentioned there.</p>

          <p>When the <code class="varname">PKGREVISION</code> of a
          package is bumped, the change should appear in
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">pkgsrc/doc/CHANGES</code> if it is
          security related or otherwise relevant. Mass bumps that
          result from a dependency being updated should not be
          mentioned. In all other cases it's the developer's
          decision.</p>

          <p>There is a make target that helps in creating proper
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">CHANGES</code> entries:
          <span><strong class="command">make
          changes-entry</strong></span>. It uses the optional
          <code class="varname">CTYPE</code> and <code class=
          "varname">NETBSD_LOGIN_NAME</code> variables. The general
          usage is to first make sure that your <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">CHANGES</code> file is up-to-date (to avoid
          having to resolve conflicts later-on) and then to
          <span><strong class="command">cd</strong></span> to the
          package directory. For package updates,
          <span><strong class="command">make
          changes-entry</strong></span> is enough. For new
          packages, or package moves or removals, set the
          <code class="varname">CTYPE</code> variable on the
          command line to "Added", "Moved", or "Removed". You can
          set <code class="varname">NETBSD_LOGIN_NAME</code> in
          <code xmlns="http://www.w3.org/TR/xhtml1/transitional"
          class="filename">/etc/mk.conf</code> if your local login
          name is not the same as your NetBSD login name. Don't
          forget to commit the changes to <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">pkgsrc/doc/CHANGES</code>!</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "committing-importing"></a>18.3.&nbsp;Committing:
                Importing a package into CVS</h2>
              </div>
            </div>
          </div>

          <p>This section is only of interest for pkgsrc developers
          with write access to the pkgsrc repository. Please
          remember that cvs imports files relative to the current
          working directory, and that the pathname that you give
          the <span><strong class="command">cvs
          import</strong></span> command is so that it knows where
          to place the files in the repository. Newly created
          packages should be imported with a vendor tag of
          &#8220;<span class="quote">TNF</span>&#8221; and a
          release tag of &#8220;<span class=
          "quote">pkgsrc-base</span>&#8221;, e.g:</p>
          <pre class="programlisting">
    <code class="prompt">$</code> cd .../pkgsrc/category/pkgname
    <code class=
"prompt">$</code> cvs import pkgsrc/category/pkgname TNF pkgsrc-base
</pre>

          <p>Remember to move the directory from which you imported
          out of the way, or cvs will complain the next time you
          &#8220;<span class="quote">cvs update</span>&#8221; your
          source tree. Also don't forget to add the new package to
          the category's <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">Makefile</code>.</p>

          <p>The commit message of the initial import should
          include part of the <code xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" class=
          "filename">DESCR</code> file, so people reading the
          mailing lists know what the package is/does.</p>

          <p>For new packages, &#8220;<span class="quote">cvs
          import</span>&#8221; is preferred to &#8220;<span class=
          "quote">cvs add</span>&#8221; because the former gets
          everything with a single command, and provides a
          consistent tag.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "updating-package"></a>18.4.&nbsp;Updating a
                package to a newer version</h2>
              </div>
            </div>
          </div>

          <p>Please always put a concise, appropriate and relevant
          summary of the changes between old and new versions into
          the commit log when updating a package. There are various
          reasons for this:</p>

          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p>A URL is volatile, and can change over time. It
                may go away completely or its information may be
                overwritten by newer information.</p>
              </li>

              <li>
                <p>Having the change information between old and
                new versions in our CVS repository is very useful
                for people who use either cvs or anoncvs.</p>
              </li>

              <li>
                <p>Having the change information between old and
                new versions in our CVS repository is very useful
                for people who read the pkgsrc-changes mailing
                list, so that they can make tactical decisions
                about when to upgrade the package.</p>
              </li>
            </ul>
          </div>

          <p>Please also recognize that, just because a new version
          of a package has been released, it should not
          automatically be upgraded in the CVS repository. We
          prefer to be conservative in the packages that are
          included in pkgsrc - development or beta packages are not
          really the best thing for most places in which pkgsrc is
          used. Please use your judgement about what should go into
          pkgsrc, and bear in mind that stability is to be
          preferred above new and possibly untested features.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "moving-package"></a>18.5.&nbsp;Moving a package in
                pkgsrc</h2>
              </div>
            </div>
          </div>

          <div class="orderedlist">
            <ol type="1">
              <li>
                <p>Make a copy of the directory somewhere else.</p>
              </li>

              <li>
                <p>Remove all CVS dirs.</p>

                <p>Alternatively to the first two steps you can
                also do:</p>
                <pre class="screen">
<code class="prompt">%</code> <strong class=
"userinput"><code>cvs -d user@cvs.NetBSD.org:/cvsroot export -D today pkgsrc/category/package</code></strong>
</pre>

                <p>and use that for further work.</p>
              </li>

              <li>
                <p>Fix <code class="varname">CATEGORIES</code> and
                any <code class="varname">DEPENDS</code> paths that
                just did &#8220;<span class=
                "quote">../package</span>&#8221; instead of
                &#8220;<span class=
                "quote">../../category/package</span>&#8221;.</p>
              </li>

              <li>
                <p><span><strong class="command">cvs
                import</strong></span> the modified package in the
                new place.</p>
              </li>

              <li>
                <p>Check if any package depends on it:</p>
                <pre class="screen">
<code class="prompt">%</code> <strong class=
"userinput"><code>cd /usr/pkgsrc</code></strong>
<code class="prompt">%</code> <strong class=
"userinput"><code>grep /package */*/Makefile* */*/buildlink*</code></strong>
</pre>
              </li>

              <li>
                <p>Fix paths in packages from step 5 to point to
                new location.</p>
              </li>

              <li>
                <p><span><strong class="command">cvs rm
                (-f)</strong></span> the package at the old
                location.</p>
              </li>

              <li>
                <p>Remove from <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">oldcategory/Makefile</code>.</p>
              </li>

              <li>
                <p>Add to <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename">newcategory/Makefile</code>.</p>
              </li>

              <li>
                <p>Commit the changed and removed files:</p>
                <pre class="screen">
<code class="prompt">%</code> <strong class=
"userinput"><code>cvs commit oldcategory/package oldcategory/Makefile newcategory/Makefile</code></strong>
</pre>

                <p>(and any packages from step 5, of course).</p>
              </li>
            </ol>
          </div>
        </div>
      </div>

      <div class="chapter" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title"><a name=
              "porting"></a>Chapter&nbsp;19.&nbsp;Porting
              pkgsrc</h2>
            </div>
          </div>
        </div>

        <div class="toc">
          <p><b>Table of Contents</b></p>

          <dl>
            <dt><span class="sect1"><a href="#porting.opsys">19.1.
            Porting pkgsrc to a new operating
            system</a></span></dt>

            <dt><span class="sect1"><a href=
            "#porting.compiler">19.2. Adding support for a new
            compiler</a></span></dt>
          </dl>
        </div>

        <p>The pkgsrc system has already been ported to many
        operating systems, hardware architectures and compilers.
        This chapter explains the necessary steps to make pkgsrc
        even more portable.</p>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "porting.opsys"></a>19.1.&nbsp;Porting pkgsrc to a
                new operating system</h2>
              </div>
            </div>
          </div>

          <p>To port pkgsrc to a new operating system (called
          <code class="literal">MyOS</code> in this example), you
          need to touch the following files:</p>

          <div class="variablelist">
            <dl>
              <dt><span class="term"><code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">bootstrap/mods/mk/<em class=
              "replaceable"><code>MyOS</code></em>.sys.mk</code></span></dt>

              <dd>
                <p>This file contains some basic definitions, for
                example the name of the C compiler.</p>
              </dd>

              <dt><span class="term"><code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">mk/bsd.prefs.mk</code></span></dt>

              <dd>
                <p>Insert code that defines the variables
                <code class="varname">OPSYS</code>, <code class=
                "varname">OS_VERSION</code>, <code class=
                "varname">LOWER_OS_VERSION</code>, <code class=
                "varname">LOWER_VENDOR</code>, <code class=
                "varname">MACHINE_ARCH</code>, <code class=
                "varname">OBJECT_FMT</code>, <code class=
                "varname">APPEND_ELF</code>, and the other
                variables that appear in this file.</p>
              </dd>

              <dt><span class="term"><code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">mk/platform/MyOS.mk</code></span></dt>

              <dd>
                <p>This file contains the platform-specific
                definitions that are used by pkgsrc. Start by
                copying one of the other files and edit it to your
                needs.</p>
              </dd>

              <dt><span class="term"><code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">mk/platform/MyOS.pkg.dist</code></span></dt>

              <dd>
                <p>This file contains a list of directories,
                together with their permission bits and ownership.
                These directories will be created automatically
                with every package that does not explicitly set
                <code class="varname">NO_MTREE</code>. There have
                been some discussions about whether this file is
                needed at all, but with no result.</p>
              </dd>

              <dt><span class="term"><code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">mk/platform/MyOS.x11.dist</code></span></dt>

              <dd>
                <p>Just copy one of the pre-existing x11.dist files
                to your <code xmlns=
                "http://www.w3.org/TR/xhtml1/transitional" class=
                "filename"><em class=
                "replaceable"><code>MyOS</code></em>.x11.dist</code>.</p>
              </dd>

              <dt><span class="term"><code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">mk/tools/bootstrap.mk</code></span></dt>

              <dd>
                <p>On some operating systems, the tools that are
                provided with the base system are not good enough
                for pkgsrc. For example, there are many versions of
                <a href=
                "http://netbsd.gw.com/cgi-bin/man-cgi?sed+1+NetBSD-current">
                <span class="citerefentry"><span class=
                "refentrytitle">sed</span>(1)</span></a> that have
                a narrow limit on the line length they can process.
                Therefore pkgsrc brings its own tools, which can be
                enabled here.</p>
              </dd>

              <dt><span class="term"><code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">mk/tools/<em class=
              "replaceable"><code>MyOS</code></em>.mk</code></span></dt>

              <dd>
                <p>This file defines the paths to all the tools
                that are needed by one or the other package in
                pkgsrc, as well as by pkgsrc itself. Find out where
                these tools are on your platform and add them.</p>
              </dd>
            </dl>
          </div>

          <p>Now, you should be able to build some basic packages,
          like <a xmlns="http://www.w3.org/TR/xhtml1/transitional"
          href=
          "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/lang/perl5/README.html"
          target="_top"><code xmlns="" class=
          "filename">lang/perl5</code></a>, <a xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" href=
          "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/shells/bash/README.html"
          target="_top"><code xmlns="" class=
          "filename">shells/bash</code></a>.</p>
        </div>

        <div class="sect1" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h2 class="title" style="clear: both"><a name=
                "porting.compiler"></a>19.2.&nbsp;Adding support
                for a new compiler</h2>
              </div>
            </div>
          </div>

          <p>TODO</p>
        </div>
      </div>
    </div>

    <div class="appendix" lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title"><a name=
            "examples"></a>Appendix&nbsp;A.&nbsp;A simple example
            package: bison</h2>
          </div>
        </div>
      </div>

      <div class="toc">
        <p><b>Table of Contents</b></p>

        <dl>
          <dt><span class="sect1"><a href="#example-files">A.1.
          files</a></span></dt>

          <dd>
            <dl>
              <dt><span class="sect2"><a href=
              "#example-Makefile">A.1.1. Makefile</a></span></dt>

              <dt><span class="sect2"><a href=
              "#example-descr">A.1.2. DESCR</a></span></dt>

              <dt><span class="sect2"><a href=
              "#example-plist">A.1.3. PLIST</a></span></dt>

              <dt><span class="sect2"><a href=
              "#checking-package-with-pkglint">A.1.4. Checking a
              package with <span><strong class=
              "command">pkglint</strong></span></a></span></dt>
            </dl>
          </dd>

          <dt><span class="sect1"><a href="#steps-for-b-i-p">A.2.
          Steps for building, installing, packaging</a></span></dt>
        </dl>
      </div>

      <p>We checked to find a piece of software that wasn't in the
      packages collection, and picked GNU bison. Quite why someone
      would want to have <span><strong class=
      "command">bison</strong></span> when Berkeley
      <span><strong class="command">yacc</strong></span> is already
      present in the tree is beyond us, but it's useful for the
      purposes of this exercise.</p>

      <div class="sect1" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a name=
              "example-files"></a>A.1.&nbsp;files</h2>
            </div>
          </div>
        </div>

        <div class="sect2" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h3 class="title"><a name=
                "example-Makefile"></a>A.1.1.&nbsp;Makefile</h3>
              </div>
            </div>
          </div>
          <pre class="programlisting">
    # $NetBSD$
    #

    DISTNAME=       bison-1.25
    CATEGORIES=     devel
    MASTER_SITES=   ${MASTER_SITE_GNU}

    MAINTAINER=     thorpej@NetBSD.org
    HOMEPAGE=       http://www.gnu.org/software/bison/bison.html
    COMMENT=        GNU yacc clone

    GNU_CONFIGURE=  yes
    INFO_FILES=     bison.info

    .include "../../mk/bsd.pkg.mk"
</pre>
        </div>

        <div class="sect2" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h3 class="title"><a name=
                "example-descr"></a>A.1.2.&nbsp;DESCR</h3>
              </div>
            </div>
          </div>
          <pre class="programlisting">
    GNU version of yacc.  Can make re-entrant parsers, and numerous other
    improvements.  Why you would want this when Berkeley <a href=
"http://netbsd.gw.com/cgi-bin/man-cgi?yacc+1+NetBSD-current"><span class="citerefentry"><span class="refentrytitle">yacc</span>(1)</span></a> is part
    of the NetBSD source tree is beyond me.
</pre>
        </div>

        <div class="sect2" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h3 class="title"><a name=
                "example-plist"></a>A.1.3.&nbsp;PLIST</h3>
              </div>
            </div>
          </div>
          <pre class="programlisting">
    @comment $NetBSD$
    bin/bison
    man/man1/bison.1.gz
    share/bison.simple
    share/bison.hairy
</pre>
        </div>

        <div class="sect2" lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h3 class="title"><a name=
                "checking-package-with-pkglint"></a>A.1.4.&nbsp;Checking
                a package with <span><strong class=
                "command">pkglint</strong></span></h3>
              </div>
            </div>
          </div>

          <p>The NetBSD package system comes with <a xmlns=
          "http://www.w3.org/TR/xhtml1/transitional" href=
          "ftp://ftp.NetBSD.org/pub/NetBSD/packages/pkgsrc/pkgtools/pkglint/README.html"
          target="_top"><code xmlns="" class=
          "filename">pkgtools/pkglint</code></a> which helps to
          check the contents of these files. After installation it
          is quite easy to use, just change to the directory of the
          package you wish to examine and execute
          <span><strong class=
          "command">pkglint</strong></span>:</p>
          <pre class="screen">
<code class="prompt">$</code> <strong class=
"userinput"><code>pkglint</code></strong>
looks fine.
</pre>

          <p>Depending on the supplied command line arguments (see
          pkglint(1)), more checks will be performed. Use e.g.
          <span><strong class="command">pkglint -Call
          -Wall</strong></span> for a very thorough check.</p>
        </div>
      </div>

      <div class="sect1" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a name=
              "steps-for-b-i-p"></a>A.2.&nbsp;Steps for building,
              installing, packaging</h2>
            </div>
          </div>
        </div>

        <p>Create the directory where the package lives, plus any
        auxiliary directories:</p>
        <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>cd /usr/pkgsrc/lang</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>mkdir bison</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>cd bison</code></strong>
<code class="prompt">#</code> <strong class=
"userinput"><code>mkdir patches</code></strong>
</pre>

        <p>Create <code xmlns=
        "http://www.w3.org/TR/xhtml1/transitional" class=
        "filename">Makefile</code>, <code xmlns=
        "http://www.w3.org/TR/xhtml1/transitional" class=
        "filename">DESCR</code> and <code xmlns=
        "http://www.w3.org/TR/xhtml1/transitional" class=
        "filename">PLIST</code> (see <a href="#components" title=
        "Chapter&nbsp;8.&nbsp;Package components - files, directories and contents">
        Chapter&nbsp;8, <i>Package components - files, directories
        and contents</i></a>) then continue with fetching the
        distfile:</p>
        <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>make fetch</code></strong>
&gt;&gt; bison-1.25.tar.gz doesn't seem to exist on this system.
&gt;&gt; Attempting to fetch from ftp://prep.ai.mit.edu/pub/gnu//.
Requesting ftp://prep.ai.mit.edu/pub/gnu//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/)
ftp: Error retrieving file: 500 Internal error

&gt;&gt; Attempting to fetch from ftp://wuarchive.wustl.edu/systems/gnu//.
Requesting ftp://wuarchive.wustl.edu/systems/gnu//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/)
ftp: Error retrieving file: 500 Internal error

&gt;&gt; Attempting to fetch from ftp://ftp.freebsd.org/pub/FreeBSD/distfiles//.
Requesting ftp://ftp.freebsd.org/pub/FreeBSD/distfiles//bison-1.25.tar.gz (via ftp://orpheus.amdahl.com:80/)
Successfully retrieved file.
</pre>

        <p>Generate the checksum of the distfile into <code xmlns=
        "http://www.w3.org/TR/xhtml1/transitional" class=
        "filename">distinfo</code>:</p>
        <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>make makesum</code></strong>
</pre>

        <p>Now compile:</p>
        <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>make</code></strong>
&gt;&gt; Checksum OK for bison-1.25.tar.gz.
===&gt;  Extracting for bison-1.25
===&gt;  Patching for bison-1.25
===&gt;   Ignoring empty patch directory
===&gt;  Configuring for bison-1.25
creating cache ./config.cache
checking for gcc... cc
checking whether we are using GNU C... yes
checking for a BSD compatible install... /usr/bin/install -c -o bin -g bin
checking how to run the C preprocessor... cc -E
checking for minix/config.h... no
checking for POSIXized ISC... no
checking whether cross-compiling... no
checking for ANSI C header files... yes
checking for string.h... yes
checking for stdlib.h... yes
checking for memory.h... yes
checking for working const... yes
checking for working alloca.h... no
checking for alloca... yes
checking for strerror... yes
updating cache ./config.cache
creating ./config.status
creating Makefile
===&gt;  Building for bison-1.25
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g LR0.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g allocate.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g closure.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g conflicts.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g derives.c
cc -c -DXPFILE=\"/usr/pkg/share/bison.simple\"  -DXPFILE1=\"/usr/pkg/share/bison.hairy\" -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1  -g  ./files.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g getargs.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g gram.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g lalr.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g lex.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g main.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g nullable.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g output.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g print.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g reader.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g reduce.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g symtab.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g warshall.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g version.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g getopt.c
cc -c -DSTDC_HEADERS=1 -DHAVE_STRING_H=1 -DHAVE_STDLIB_H=1 -DHAVE_MEMORY_H=1 -DHAVE_ALLOCA=1 -DHAVE_STRERROR=1 -I./../include  -g getopt1.c
cc  -g -o bison LR0.o allocate.o closure.o conflicts.o derives.o files.o         getargs.o gram.o lalr.o lex.o                                   main.o nullable.o output.o print.o reader.o reduce.o symtab.o   warshall.o version.o getopt.o getopt1.o
./files.c:240: warning: mktemp() possibly used unsafely, consider using mkstemp()
rm -f bison.s1
sed -e "/^#line/ s|bison|/usr/pkg/share/bison|" &lt; ./bison.simple &gt; bison.s1
</pre>

        <p>Everything seems OK, so install the files:</p>
        <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>make install</code></strong>
&gt;&gt; Checksum OK for bison-1.25.tar.gz.
===&gt;  Installing for bison-1.25
sh ./mkinstalldirs /usr/pkg/bin /usr/pkg/share  /usr/pkg/info /usr/pkg/man/man1
rm -f /usr/pkg/bin/bison
cd /usr/pkg/share; rm -f bison.simple bison.hairy
rm -f /usr/pkg/man/man1/bison.1 /usr/pkg/info/bison.info*
install -c  -o bin -g bin -m 555 bison /usr/pkg/bin/bison
/usr/bin/install -c -o bin -g bin -m 644 bison.s1 /usr/pkg/share/bison.simple
/usr/bin/install -c -o bin -g bin -m 644 ./bison.hairy /usr/pkg/share/bison.hairy
cd .; for f in bison.info*;  do /usr/bin/install -c -o bin -g bin -m 644 $f /usr/pkg/info/$f; done
/usr/bin/install -c -o bin -g bin -m 644 ./bison.1 /usr/pkg/man/man1/bison.1
===&gt;  Registering installation for bison-1.25
</pre>

        <p>You can now use bison, and also - if you decide so -
        remove it with <span><strong class="command">pkg_delete
        bison</strong></span>. Should you decide that you want a
        binary package, do this now:</p>
        <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>make package</code></strong>
&gt;&gt; Checksum OK for bison-1.25.tar.gz.
===&gt;  Building package for bison-1.25
Creating package bison-1.25.tgz
Registering depends:.
Creating gzip'd tar ball in '/u/pkgsrc/lang/bison/bison-1.25.tgz'
</pre>

        <p>Now that you don't need the source and object files any
        more, clean up:</p>
        <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>make clean</code></strong>
===&gt;  Cleaning for bison-1.25
</pre>
      </div>
    </div>

    <div class="appendix" lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title"><a name=
            "logs"></a>Appendix&nbsp;B.&nbsp;Build logs</h2>
          </div>
        </div>
      </div>

      <div class="toc">
        <p><b>Table of Contents</b></p>

        <dl>
          <dt><span class="sect1"><a href="#logs.building">B.1.
          Building figlet</a></span></dt>

          <dt><span class="sect1"><a href="#logs.package">B.2.
          Packaging figlet</a></span></dt>
        </dl>
      </div>

      <div class="sect1" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a name=
              "logs.building"></a>B.1.&nbsp;Building figlet</h2>
            </div>
          </div>
        </div>
        <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>make</code></strong>
===&gt; Checking for vulnerabilities in figlet-2.2.1nb2
=&gt; figlet221.tar.gz doesn't seem to exist on this system.
=&gt; Attempting to fetch figlet221.tar.gz from ftp://ftp.figlet.org/pub/figlet/program/unix/.
=&gt; [172219 bytes]
Connected to ftp.plig.net.
220 ftp.plig.org NcFTPd Server (licensed copy) ready.
331 Guest login ok, send your complete e-mail address as password.
230-You are user #5 of 500 simultaneous users allowed.
230-
230-  ___ _             _ _
230- |  _| |_ ___   ___| |_|___   ___ ___ ___
230- |  _|  _| . |_| . | | | . |_| . |  _| . |
230- |_| |_| |  _|_|  _|_|_|_  |_|___|_| |_  |
230-         |_|   |_|     |___|         |___|
230-
230-** Welcome to ftp.plig.org **
230-
230-Please note that all transfers from this FTP site are logged. If you
230-do not like this, please disconnect now.
230-
230-This arhive is available via
230-
230-HTTP:  http://ftp.plig.org/
230-FTP:   ftp://ftp.plig.org/     (max 500 connections)
230-RSYNC: rsync://ftp.plig.org/   (max  30 connections)
230-
230-Please email comments, bug reports and requests for packages to be
230-mirrored to ftp-admin@plig.org.
230-
230-
230 Logged in anonymously.
Remote system type is UNIX.
Using binary mode to transfer files.
200 Type okay.
250 "/pub" is new cwd.
250-"/pub/figlet" is new cwd.
250-
250-Welcome to the figlet archive at ftp.figlet.org
250-
250-    ftp://ftp.figlet.org/pub/figlet/
250-
250-The official FIGlet web page is:
250-    http://www.figlet.org/
250-
250-If you have questions, please mailto:info@figlet.org. If you want to
250-contribute a font or something else, you can email us.
250
250 "/pub/figlet/program" is new cwd.
250 "/pub/figlet/program/unix" is new cwd.
local: figlet221.tar.gz remote: figlet221.tar.gz
502 Unimplemented command.
227 Entering Passive Mode (195,40,6,41,246,104)
150 Data connection accepted from 84.128.86.72:65131; transfer starting for figlet221.tar.gz (172219 bytes).
38% |**************                       | 65800      64.16 KB/s    00:01 ETA
226 Transfer completed.
172219 bytes received in 00:02 (75.99 KB/s)
221 Goodbye.
=&gt; Checksum OK for figlet221.tar.gz.
===&gt; Extracting for figlet-2.2.1nb2
===&gt; Required installed package ccache-[0-9]*: ccache-2.3nb1 found
===&gt; Patching for figlet-2.2.1nb2
===&gt; Applying pkgsrc patches for figlet-2.2.1nb2
===&gt; Overriding tools for figlet-2.2.1nb2
===&gt; Creating toolchain wrappers for figlet-2.2.1nb2
===&gt; Configuring for figlet-2.2.1nb2
===&gt; Building for figlet-2.2.1nb2
gcc -O2 -DDEFAULTFONTDIR=\"/usr/pkg/share/figlet\"  -DDEFAULTFONTFILE=\"standard.flf\"  figlet.c zipio.c crc.c inflate.c -o figlet
chmod a+x figlet
gcc -O2 -o chkfont chkfont.c
=&gt; Unwrapping files-to-be-installed.
<code class="prompt">#</code>
<code class="prompt">#</code> <strong class=
"userinput"><code>make install</code></strong>
===&gt; Checking for vulnerabilities in figlet-2.2.1nb2
===&gt; Installing for figlet-2.2.1nb2
install -d -o root -g wheel -m 755 /usr/pkg/bin
install -d -o root -g wheel -m 755 /usr/pkg/man/man6
mkdir -p /usr/pkg/share/figlet
cp figlet /usr/pkg/bin
cp chkfont /usr/pkg/bin
chmod 555 figlist showfigfonts
cp figlist /usr/pkg/bin
cp showfigfonts /usr/pkg/bin
cp fonts/*.flf /usr/pkg/share/figlet
cp fonts/*.flc /usr/pkg/share/figlet
cp figlet.6 /usr/pkg/man/man6
===&gt; Registering installation for figlet-2.2.1nb2
<code class="prompt">#</code>
</pre>
      </div>

      <div class="sect1" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a name=
              "logs.package"></a>B.2.&nbsp;Packaging figlet</h2>
            </div>
          </div>
        </div>
        <pre class="screen">
<code class="prompt">#</code> <strong class=
"userinput"><code>make package</code></strong>
===&gt; Checking for vulnerabilities in figlet-2.2.1nb2
===&gt; Packaging figlet-2.2.1nb2
===&gt; Building binary package for figlet-2.2.1nb2
Creating package /home/cvs/pkgsrc/packages/i386/All/figlet-2.2.1nb2.tgz
Using SrcDir value of /usr/pkg
Registering depends:.
<code class="prompt">#</code>
</pre>
      </div>
    </div>

    <div class="appendix" lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title"><a name=
            "ftp-layout"></a>Appendix&nbsp;C.&nbsp;Layout of the
            FTP server's package archive</h2>
          </div>
        </div>
      </div>

      <p>Layout for precompiled binary packages on
      ftp.NetBSD.org:</p>
      <pre class="programlisting">
    /pub/NetBSD/packages/
        distfiles/

        # Unpacked pkgsrc trees
        pkgsrc-current -&gt; /pub/NetBSD/NetBSD-current/pkgsrc
        pkgsrc-2003Q4 -&gt; N/A
        pkgsrc-2004Q1/pkgsrc

        # pkgsrc archives
        pkgsrc-current.tar.gz -&gt; ../NetBSD-current/tar_files/pkgsrc.tar.gz
        pkgsrc-2003Q4.tar.gz -&gt; N/A
        pkgsrc-2004Q1.tar.gz -&gt; N/A

        # Per pkgsrc-release/OS-release/arch package archives
        pkgsrc-2003Q4/
            NetBSD-1.6.2/
                i386/
                    All/
                    archivers/
                        foo -&gt; ../All/foo
                    ...
        pkgsrc-2004Q1/
            NetBSD-1.6.2/
                i386/
                    All/
                    ...
            NetBSD-2.0/
                i386/
                    All/
                    ...
            SunOS-5.9/
                sparc/
                    All/
                    ...
                x86/
                    All/
                    ...

        # Per os-release package archive convenience links
        NetBSD-1.6.2 -&gt; 1.6.2
        1.6.2/
            i386 -&gt; ../pkgsrc-2004Q1/NetBSD-1.6.2/i386
            m68k/
                All/
                archivers/
                    foo -&gt; ../All/foo
                ...
            amiga -&gt; m68k
            atari -&gt; m68k
            ...

        2.0 -&gt; NetBSD-2.0       # backward compat, historic
        NetBSD-2.0/
            i386 -&gt; ../pkgsrc-2004Q1/NetBSD-2.0/i386
        SunOS-5.9/
            sparc -&gt; ../pkgsrc-2004Q1/SunOS-5.9/sparc
            x86 -&gt; ../pkgsrc-2004Q1/SunOS-5.9/x86
</pre>

      <p>To create:</p>

      <div class="orderedlist">
        <ol type="1">
          <li>
            <p>Run bulk build, see <a href="#bulkbuild" title=
            "6.3.&nbsp;Doing a bulk build of all packages">Section&nbsp;6.3,
            &#8220;Doing a bulk build of all
            packages&#8221;</a></p>
          </li>

          <li>
            <p>Upload /usr/pkgsrc/packages to</p>
            <pre class="programlisting">
    ftp://ftp.NetBSD.org/pub/NetBSD/packages/\
        pkgsrc-2004Q4/\             # pkgsrc-branch
        `uname -s`-`uname -r`/\     # OS &amp; version
        `uname -p`                  # architecture
</pre>
          </li>

          <li>
            <p>If necessary, create a symlink <span><strong class=
            "command">ln -s `uname -m` `uname -p`</strong></span>
            (amiga -&gt; m68k, ...)</p>
          </li>
        </ol>
      </div>
    </div>

    <div class="appendix" lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title"><a name=
            "editing"></a>Appendix&nbsp;D.&nbsp;Editing guidelines
            for the pkgsrc guide</h2>
          </div>
        </div>
      </div>

      <div class="toc">
        <p><b>Table of Contents</b></p>

        <dl>
          <dt><span class="sect1"><a href="#targets">D.1.
          Targets</a></span></dt>

          <dt><span class="sect1"><a href="#procedure">D.2.
          Procedure</a></span></dt>
        </dl>
      </div>

      <p>This section contains information on editing the pkgsrc
      guide itself.</p>

      <div class="sect1" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a name=
              "targets"></a>D.1.&nbsp;Targets</h2>
            </div>
          </div>
        </div>

        <p>The pkgsrc guide's source code is stored in <code xmlns=
        "http://www.w3.org/TR/xhtml1/transitional" class=
        "filename">pkgsrc/doc/guide/files</code>, and several files
        are created from it:</p>

        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p><code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">pkgsrc/doc/pkgsrc.txt</code></p>
            </li>

            <li>
              <p><code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">pkgsrc/doc/pkgsrc.html</code></p>
            </li>

            <li>
              <p><code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">http://www.NetBSD.org/Documentation/pkgsrc/</code>:
              the documentation on the NetBSD website will be built
              from pkgsrc and kept up to date on the web server
              itself. This means you <span class=
              "emphasis"><em>must</em></span> make sure that your
              changes haven't broken the build!</p>
            </li>

            <li>
              <p><code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">http://www.NetBSD.org/Documentation/pkgsrc/pkgsrc.pdf</code>:
              PDF version of the pkgsrc guide.</p>
            </li>

            <li>
              <p><code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">http://www.NetBSD.org/Documentation/pkgsrc/pkgsrc.ps</code>:
              PostScript version of the pkgsrc guide.</p>
            </li>
          </ul>
        </div>
      </div>

      <div class="sect1" lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a name=
              "procedure"></a>D.2.&nbsp;Procedure</h2>
            </div>
          </div>
        </div>

        <p>The procedure to edit the pkgsrc guide is:</p>

        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p>Make sure you have the packages needed to
              re-generate the pkgsrc guide (and other XML-based
              NetBSD documentation) installed. These are
              &#8220;<span class="quote">netbsd-doc</span>&#8221;
              for creating the ASCII and HTML versions, and
              &#8220;<span class=
              "quote">netbsd-doc-print</span>&#8221; for the
              PostScript and PDF versions. You will need both
              packages installed, to make sure documentation is
              consistent across all formats. The packages can be
              found in <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">pkgsrc/meta-pkgs/netbsd-doc</code> and
              <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">pkgsrc/meta-pkgs/netbsd-doc-print</code>.</p>
            </li>

            <li>
              <p>Edit the XML file(s) in <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">pkgsrc/doc/guide/files</code>.</p>
            </li>

            <li>
              <p>Run <span><strong class="command">make extract
              &amp;&amp; make do-lint</strong></span> in
              <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">pkgsrc/doc/guide</code> to check the XML
              syntax, and fix it if needed.</p>
            </li>

            <li>
              <p>Run <span><strong class=
              "command">make</strong></span> in <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">pkgsrc/doc/guide</code> to build the HTML
              and ASCII version.</p>
            </li>

            <li>
              <p>If all is well, run <span><strong class=
              "command">make install-doc</strong></span> to put the
              generated files into <code xmlns=
              "http://www.w3.org/TR/xhtml1/transitional" class=
              "filename">pkgsrc/doc</code>.</p>
            </li>

            <li>
              <p><span><strong class="command">cvs commit
              pkgsrc/doc/guide/files</strong></span></p>
            </li>

            <li>
              <p><span><strong class="command">cvs commit -m
              re-generate
              pkgsrc/doc/pkgsrc.{html,txt}</strong></span></p>
            </li>

            <li>
              <p>Until the webserver on www.NetBSD.org is really
              updated automatically to pick up changes to the
              pkgsrc guide automatically, also run
              <span><strong class="command">make install-htdocs
              HTDOCSDIR=../../../htdocs</strong></span> (or
              similar, adjust <code class=
              "varname">HTDOCSDIR</code>!).</p>
            </li>

            <li>
              <p><span><strong class="command">cvs commit
              htdocs/Documentation/pkgsrc</strong></span></p>
            </li>
          </ul>
        </div>
      </div>
    </div>
  </div>
</body>
</html>