Annotation of htdocs/docs/pkgsrc/configuring.html, revision 1.1

1.1     ! dsieger     1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
        !             2: <html>
        !             3: <head>
        !             4: <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
        !             5: <title>Chapter 5. Configuring pkgsrc</title>
        !             6: <link rel="stylesheet" href="/NetBSD.css" type="text/css">
        !             7: <meta name="generator" content="DocBook XSL Stylesheets VX.X.X">
        !             8: <link rel="start" href="index.html" title="The pkgsrc guide">
        !             9: <link rel="up" href="users-guide.html" title="Part I. The pkgsrc user's guide">
        !            10: <link rel="prev" href="using.html" title="Chapter 4. Using pkgsrc">
        !            11: <link rel="next" href="binary.html" title="Chapter 6. Creating binary packages">
        !            12: </head>
        !            13: <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
        !            14: <div class="navheader">
        !            15: <table width="100%" summary="Navigation header">
        !            16: <tr><th colspan="3" align="center">Chapter 5. Configuring pkgsrc</th></tr>
        !            17: <tr>
        !            18: <td width="20%" align="left">
        !            19: <a accesskey="p" href="using.html">Prev</a> </td>
        !            20: <th width="60%" align="center">Part I. The pkgsrc user's guide</th>
        !            21: <td width="20%" align="right"> <a accesskey="n" href="binary.html">Next</a>
        !            22: </td>
        !            23: </tr>
        !            24: </table>
        !            25: <hr>
        !            26: </div>
        !            27: <div class="chapter" lang="en">
        !            28: <div class="titlepage"><div><div><h2 class="title">
        !            29: <a name="configuring"></a>Chapter 5. Configuring pkgsrc</h2></div></div></div>
        !            30: <div class="toc">
        !            31: <p><b>Table of Contents</b></p>
        !            32: <dl>
        !            33: <dt><span class="sect1"><a href="configuring.html#general-configuration">5.1. General configuration</a></span></dt>
        !            34: <dt><span class="sect1"><a href="configuring.html#variables-affecting-build">5.2. Variables affecting the build process</a></span></dt>
        !            35: <dt><span class="sect1"><a href="configuring.html#conf.compiler">5.3. Selecting and configuring the compiler</a></span></dt>
        !            36: <dd><dl>
        !            37: <dt><span class="sect2"><a href="configuring.html#selecting-the-compiler">5.3.1. Selecting the compiler</a></span></dt>
        !            38: <dt><span class="sect2"><a href="configuring.html#conf.cflags">5.3.2. Additional flags to the compiler (<code class="varname">CFLAGS</code>)</a></span></dt>
        !            39: <dt><span class="sect2"><a href="configuring.html#conf.ldflags">5.3.3. Additional flags to the linker (<code class="varname">LDFLAGS</code>)</a></span></dt>
        !            40: </dl></dd>
        !            41: <dt><span class="sect1"><a href="configuring.html#developer-advanced-settings">5.4. Developer/advanced settings</a></span></dt>
        !            42: <dt><span class="sect1"><a href="configuring.html#selecting-build-options">5.5. Selecting Build Options</a></span></dt>
        !            43: </dl>
        !            44: </div>
        !            45: <p>The whole pkgsrc system is configured in a single file, usually
        !            46: called <code class="filename">mk.conf</code>. In which directory pkgsrc looks for
        !            47: that file depends on the installation. On NetBSD, when you use
        !            48: <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> from the base system, it is in the directory
        !            49: <code class="filename">/etc/</code>. In all other cases the default location is
        !            50: <code class="literal">${PREFIX}/etc/</code>, depending on where you told the
        !            51: bootstrap program to install the binary packages.</p>
        !            52: <p>During the bootstrap, an example configuration file is created. To
        !            53: use that, you have to create the directory
        !            54: <code class="filename">${PREFIX}/etc</code> and copy the example file
        !            55: there.</p>
        !            56: <p>The format of the configuration file is that of the usual
        !            57: BSD-style <code class="filename">Makefile</code>s. The whole pkgsrc configuration
        !            58: is done by setting variables in this file. Note that you can define all
        !            59: kinds of variables, and no special error checking (for example for
        !            60: spelling mistakes) takes place, so you have to try it out to see if it
        !            61: works.</p>
        !            62: <div class="sect1" lang="en">
        !            63: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
        !            64: <a name="general-configuration"></a>5.1. General configuration</h2></div></div></div>
        !            65: <p>In this section, you can find some variables that apply to all
        !            66:     pkgsrc packages. A complete list of the variables that can be
        !            67:     configured by the user is available in
        !            68:     <code class="filename">mk/defaults/mk.conf</code>, together with some
        !            69:     comments that describe each variable's intent.</p>
        !            70: <div class="itemizedlist"><ul type="disc">
        !            71: <li><p><code class="varname">LOCALBASE</code>: Where
        !            72:            packages will be installed. The default is
        !            73:            <code class="filename">/usr/pkg</code>. Do not mix binary packages
        !            74:            with different <code class="varname">LOCALBASE</code>s!</p></li>
        !            75: <li><p><code class="varname">CROSSBASE</code>: Where
        !            76:            &#8220;<span class="quote">cross</span>&#8221; category packages will be
        !            77:            installed. The default is
        !            78:            <code class="filename">${LOCALBASE}/cross</code>.</p></li>
        !            79: <li><p><code class="varname">X11BASE</code>: Where
        !            80:            X11 is installed on the system. The default is
        !            81:            <code class="filename">/usr/X11R6</code>.</p></li>
        !            82: <li><p><code class="varname">DISTDIR</code>: Where to store the
        !            83:            downloaded copies of the original source distributions used
        !            84:            for building pkgsrc packages. The default is
        !            85:            <code class="filename">${PKGSRCDIR}/distfiles</code>.</p></li>
        !            86: <li><p><code class="varname">PKG_DBDIR</code>: Where the
        !            87:            database about installed packages is stored.  The default is
        !            88:            <code class="filename">/var/db/pkg</code>.</p></li>
        !            89: <li><p><code class="varname">MASTER_SITE_OVERRIDE</code>:
        !            90:            If set, override the packages'
        !            91:            <code class="varname">MASTER_SITES</code> with this value.</p></li>
        !            92: <li><p><code class="varname">MASTER_SITE_BACKUP</code>:
        !            93:            Backup location(s) for distribution files and patch files
        !            94:            if not found locally or in
        !            95:            <code class="filename">${MASTER_SITES}</code> or
        !            96:            <code class="filename">${PATCH_SITES}</code> respectively.
        !            97:            The defaults are
        !            98:            <code class="filename">ftp://ftp.NetBSD.org/pub/NetBSD/packages/distfiles/${DIST_SUBDIR}/</code>
        !            99:            and
        !           100:            <code class="filename">ftp://ftp.freebsd.org/pub/FreeBSD/distfiles/${DIST_SUBDIR}/</code>.</p></li>
        !           101: <li><p><code class="varname">BINPKG_SITES</code>:
        !           102:            List of sites carrying binary pkgs. <em class="replaceable"><code>rel</code></em> and
        !           103:            <em class="replaceable"><code>arch</code></em> are replaced with OS
        !           104:            release (&#8220;<span class="quote">2.0</span>&#8221;, etc.) and architecture
        !           105:            (&#8220;<span class="quote">mipsel</span>&#8221;, etc.).</p></li>
        !           106: <li><p><code class="varname">ACCEPTABLE_LICENSES</code>:
        !           107:            List of acceptable licenses. Whenever you try to build a package
        !           108:            whose license is not in this list, you will get an error message
        !           109:            that includes instructions on how to change this variable.</p></li>
        !           110: </ul></div>
        !           111: </div>
        !           112: <div class="sect1" lang="en">
        !           113: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
        !           114: <a name="variables-affecting-build"></a>5.2. Variables affecting the build process</h2></div></div></div>
        !           115: <p>XXX
        !           116:       </p>
        !           117: <div class="itemizedlist"><ul type="disc">
        !           118: <li><p><code class="varname">PACKAGES</code>: The top level
        !           119:            directory for the binary packages. The default is
        !           120:            <code class="filename">${PKGSRCDIR}/packages</code>.</p></li>
        !           121: <li><p><code class="varname">WRKOBJDIR</code>:
        !           122:            The top level directory where, if defined, the separate
        !           123:            working directories will get created, and symbolically
        !           124:            linked to from <code class="filename">${WRKDIR}</code> (see below).
        !           125:            This is useful for building packages on several
        !           126:            architectures, then <code class="filename">${PKGSRCDIR}</code>
        !           127:            can be NFS-mounted while <code class="filename">${WRKOBJDIR}</code>
        !           128:            is local to every architecture. (It should be noted that
        !           129:            <code class="varname">PKGSRCDIR</code> should not be set by the user
        !           130:            &mdash; it is an internal definition which refers to the
        !           131:            root of the pkgsrc tree. It is possible to have many
        !           132:            pkgsrc tree instances.)</p></li>
        !           133: <li><p><code class="varname">LOCALPATCHES</code>:
        !           134:            Directory for local patches that aren't part of pkgsrc.
        !           135:            See <a href="components.html#components.patches" title="10.3. patches/*">Section 10.3, &#8220;patches/*&#8221;</a> for more
        !           136:            information.</p></li>
        !           137: <li><p><code class="varname">PKGMAKECONF</code>: Location of
        !           138:            the <code class="filename">mk.conf</code> file used by a package's
        !           139:            BSD-style Makefile. If this is not set,
        !           140:            <code class="varname">MAKECONF</code> is set to
        !           141:            <code class="filename">/dev/null</code> to avoid picking up
        !           142:            settings used by builds in <code class="filename">/usr/src</code>.</p></li>
        !           143: <li><p><code class="varname">DEPENDS_TARGET</code>:
        !           144:            By default, dependencies are only installed, and no binary
        !           145:            package is created for them. You can set this variable to
        !           146:            <code class="literal">package</code> to automatically create binary
        !           147:            packages after installing dependencies.</p></li>
        !           148: </ul></div>
        !           149: </div>
        !           150: <div class="sect1" lang="en">
        !           151: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
        !           152: <a name="conf.compiler"></a>5.3. Selecting and configuring the compiler</h2></div></div></div>
        !           153: <div class="sect2" lang="en">
        !           154: <div class="titlepage"><div><div><h3 class="title">
        !           155: <a name="selecting-the-compiler"></a>5.3.1. Selecting the compiler</h3></div></div></div>
        !           156: <p>By default, pkgsrc will use GCC to build packages.  This may be
        !           157:     overridden by setting the following variables in /etc/mk.conf:</p>
        !           158: <div class="variablelist"><dl>
        !           159: <dt><span class="term"><code class="varname">PKGSRC_COMPILER</code>:</span></dt>
        !           160: <dd>
        !           161: <p>This is a list of values specifying the chain of
        !           162:          compilers to invoke when building packages.  Valid values
        !           163:          are:</p>
        !           164: <div class="itemizedlist"><ul type="disc">
        !           165: <li><p><code class="varname">distcc</code>:
        !           166:            distributed C/C++ (chainable)</p></li>
        !           167: <li><p><code class="varname">ccache</code>:
        !           168:            compiler cache (chainable)</p></li>
        !           169: <li><p><code class="varname">gcc</code>:
        !           170:            GNU C/C++ Compiler</p></li>
        !           171: <li><p><code class="varname">mipspro</code>:
        !           172:            Silicon Graphics, Inc. MIPSpro (n32/n64)</p></li>
        !           173: <li><p><code class="varname">mipspro</code>:
        !           174:            Silicon Graphics, Inc. MIPSpro (o32)</p></li>
        !           175: <li><p><code class="varname">sunpro</code>:
        !           176:            Sun Microsystems, Inc. WorkShip/Forte/Sun ONE Studio</p></li>
        !           177: </ul></div>
        !           178: <p>The default is
        !           179:          &#8220;<span class="quote"><code class="varname">gcc</code></span>&#8221;.  You can use
        !           180:          <code class="varname">ccache</code> and/or
        !           181:          <code class="varname">distcc</code> with an appropriate
        !           182:          <code class="varname">PKGSRC_COMPILER</code> setting,
        !           183:          e.g. &#8220;<span class="quote"><code class="varname">ccache gcc</code></span>&#8221;.  This
        !           184:          variable should always be terminated with a value for
        !           185:          a real compiler.  Note that only one real compiler
        !           186:          should be listed (e.g. &#8220;<span class="quote"><code class="varname">sunpro gcc</code></span>&#8221;
        !           187:          is not allowed).</p>
        !           188: </dd>
        !           189: <dt><span class="term"><code class="varname">GCC_REQD</code>:</span></dt>
        !           190: <dd><p>This specifies the minimum version of GCC to use
        !           191:          when building packages.  If the system GCC doesn't
        !           192:          satisfy this requirement, then pkgsrc will build and
        !           193:          install one of the GCC packages to use instead.</p></dd>
        !           194: </dl></div>
        !           195: </div>
        !           196: <div class="sect2" lang="en">
        !           197: <div class="titlepage"><div><div><h3 class="title">
        !           198: <a name="conf.cflags"></a>5.3.2. Additional flags to the compiler (<code class="varname">CFLAGS</code>)</h3></div></div></div>
        !           199: <p>If you wish to set the <code class="varname">CFLAGS</code> variable,
        !           200:        please make sure to use the <code class="literal">+=</code> operator
        !           201:        instead of the <code class="literal">=</code> operator:</p>
        !           202: <pre class="programlisting">
        !           203: CFLAGS+=        -your -flags
        !           204: </pre>
        !           205: <p>Using <code class="varname">CFLAGS=</code> (i.e. without the
        !           206:        &#8220;<span class="quote">+</span>&#8221;) may lead to problems with packages that need
        !           207:        to add their own flags.  Also, you may want to take a look at
        !           208:        the <a href="ftp://ftp.NetBSD.org/pub/pkgsrc/current/pkgsrc/devel/cpuflags/README.html" target="_top"><code class="filename">devel/cpuflags</code></a> package if
        !           209:        you're interested in optimization for the current CPU.</p>
        !           210: </div>
        !           211: <div class="sect2" lang="en">
        !           212: <div class="titlepage"><div><div><h3 class="title">
        !           213: <a name="conf.ldflags"></a>5.3.3. Additional flags to the linker (<code class="varname">LDFLAGS</code>)</h3></div></div></div>
        !           214: <p>If you want to pass flags to the linker, both in the configure
        !           215: step and the build step, you can do this in two ways.  Either set
        !           216: <code class="varname">LDFLAGS</code> or <code class="varname">LIBS</code>.  The difference
        !           217: between the two is that <code class="varname">LIBS</code> will be appended to
        !           218: the command line, while <code class="varname">LDFLAGS</code> come earlier.
        !           219: <code class="varname">LDFLAGS</code> is pre-loaded with rpath settings for ELF
        !           220: machines depending on the setting of <code class="varname">USE_IMAKE</code> or
        !           221: the inclusion of <code class="filename">mk/x11.buildlink3.mk</code>.  As with
        !           222: <code class="varname">CFLAGS</code>, if you do not wish to override these
        !           223: settings, use the <code class="literal">+=</code> operator:</p>
        !           224: <pre class="programlisting">
        !           225: LDFLAGS+=        -your -linkerflags
        !           226: </pre>
        !           227: </div>
        !           228: </div>
        !           229: <div class="sect1" lang="en">
        !           230: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
        !           231: <a name="developer-advanced-settings"></a>5.4. Developer/advanced settings</h2></div></div></div>
        !           232: <p>XXX
        !           233:       </p>
        !           234: <div class="itemizedlist"><ul type="disc">
        !           235: <li>
        !           236: <p><code class="varname">PKG_DEVELOPER</code>:
        !           237:            Run some sanity checks that package developers want:
        !           238:            </p>
        !           239: <div class="itemizedlist"><ul type="circle">
        !           240: <li><p>make sure patches apply with zero
        !           241:              fuzz</p></li>
        !           242: <li><p>run check-shlibs to see that all
        !           243:              binaries will find their shared libs.</p></li>
        !           244: </ul></div>
        !           245: <p>
        !           246:        </p>
        !           247: </li>
        !           248: <li><p><code class="varname">PKG_DEBUG_LEVEL</code>: The level
        !           249:        of debugging output which is displayed whilst making and
        !           250:        installing the package.  The default value for this is 0,
        !           251:        which will not display the commands as they are executed
        !           252:        (normal, default, quiet operation); the value 1 will display
        !           253:        all shell commands before their invocation, and the value 2
        !           254:        will display both the shell commands before their invocation,
        !           255:        and their actual execution progress with <span><strong class="command">set
        !           256:        -x</strong></span> will be displayed.</p></li>
        !           257: </ul></div>
        !           258: <p>
        !           259:     </p>
        !           260: </div>
        !           261: <div class="sect1" lang="en">
        !           262: <div class="titlepage"><div><div><h2 class="title" style="clear: both">
        !           263: <a name="selecting-build-options"></a>5.5. Selecting Build Options</h2></div></div></div>
        !           264: <p>Some packages have build time options, usually to select
        !           265:     between different dependencies, enable optional support for big
        !           266:     dependencies or enable experimental features.</p>
        !           267: <p>To see which options, if any, a package supports, and which
        !           268:     options are mutually exclusive, run <span><strong class="command">make
        !           269:     show-options</strong></span>, for example:</p>
        !           270: <pre class="programlisting">
        !           271:     The following options are supported by this package:
        !           272:         ssl      Enable SSL support.
        !           273:     Exactly one of the following gecko options is required:
        !           274:         firefox  Use firefox as gecko rendering engine.
        !           275:         mozilla  Use mozilla as gecko rendering engine.
        !           276:     At most one of the following database options may be selected:
        !           277:         mysql    Enable support for MySQL database.
        !           278:         pgsql    Enable support for PostgreSQL database.
        !           279: 
        !           280:     These options are enabled by default: firefox
        !           281:     These options are currently enabled: mozilla ssl
        !           282: </pre>
        !           283: <p>The following variables can be defined in
        !           284:     <code class="filename">/etc/mk.conf</code> to select which options to
        !           285:     enable for a package: <code class="varname">PKG_DEFAULT_OPTIONS</code>,
        !           286:     which can be used to select or disable options for all packages
        !           287:     that support them, and
        !           288:     <code class="varname">PKG_OPTIONS.<em class="replaceable"><code>pkgbase</code></em></code>,
        !           289:     which can be used to select or disable options specifically for
        !           290:     package <em class="replaceable"><code>pkgbase</code></em>.  Options listed in
        !           291:     these variables are selected, options preceded by &#8220;<span class="quote">-</span>&#8221;
        !           292:     are disabled. A few examples:</p>
        !           293: <pre class="screen">
        !           294: <code class="prompt">$</code> <span><strong class="command">grep "PKG.*OPTION" /etc/mk.conf</strong></span>
        !           295: PKG_DEFAULT_OPTIONS=    -arts -dvdread -esound
        !           296: PKG_OPTIONS.kdebase=    debug -sasl
        !           297: PKG_OPTIONS.apache=     suexec </pre>
        !           298: <p>The following settings are consulted in the order given, and
        !           299:     the last setting that selects or disables an option is
        !           300:     used:</p>
        !           301: <div class="orderedlist"><ol type="1">
        !           302: <li><p>the default options as suggested by the package
        !           303:       maintainer</p></li>
        !           304: <li><p>the options implied by the settings of legacy
        !           305:       variables (see below)</p></li>
        !           306: <li><p><code class="varname">PKG_DEFAULT_OPTIONS</code></p></li>
        !           307: <li><p><code class="varname">PKG_OPTIONS.<em class="replaceable"><code>pkgbase</code></em></code></p></li>
        !           308: </ol></div>
        !           309: <p>For groups of mutually exclusive options, the last option
        !           310:     selected is used, all others are automatically disabled.  If an
        !           311:     option of the group is explicitly disabled, the previously
        !           312:     selected option, if any, is used.  It is an error if no option
        !           313:     from a required group of options is selected, and building the
        !           314:     package will fail.</p>
        !           315: <p>Before the options framework was introduced, build options
        !           316:     were selected by setting a variable (often named
        !           317:     <code class="varname">USE_<em class="replaceable"><code>FOO</code></em></code>) in
        !           318:     <code class="filename">/etc/mk.conf</code> for each option.  To ease
        !           319:     transition to the options framework for the user, these legacy
        !           320:     variables are converted to the appropriate options setting
        !           321:     (<code class="varname">PKG_OPTIONS.<em class="replaceable"><code>pkgbase</code></em></code>)
        !           322:     automatically.  A warning is issued to prompt the user to update
        !           323:     <code class="filename">/etc/mk.conf</code> to use the options framework
        !           324:     directly.  Support for the legacy variables will be removed
        !           325:     eventually.</p>
        !           326: </div>
        !           327: </div>
        !           328: <div class="navfooter">
        !           329: <hr>
        !           330: <table width="100%" summary="Navigation footer">
        !           331: <tr>
        !           332: <td width="40%" align="left">
        !           333: <a accesskey="p" href="using.html">Prev</a> </td>
        !           334: <td width="20%" align="center"><a accesskey="u" href="users-guide.html">Up</a></td>
        !           335: <td width="40%" align="right"> <a accesskey="n" href="binary.html">Next</a>
        !           336: </td>
        !           337: </tr>
        !           338: <tr>
        !           339: <td width="40%" align="left" valign="top">Chapter 4. Using pkgsrc </td>
        !           340: <td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
        !           341: <td width="40%" align="right" valign="top"> Chapter 6. Creating binary packages</td>
        !           342: </tr>
        !           343: </table>
        !           344: </div>
        !           345: </body>
        !           346: </html>

CVSweb <webmaster@jp.NetBSD.org>