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: “<span class="quote">cross</span>” 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 (“<span class="quote">2.0</span>”, etc.) and architecture
! 105: (“<span class="quote">mipsel</span>”, 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: — 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, “patches/*”</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: “<span class="quote"><code class="varname">gcc</code></span>”. 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. “<span class="quote"><code class="varname">ccache gcc</code></span>”. 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. “<span class="quote"><code class="varname">sunpro gcc</code></span>”
! 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: “<span class="quote">+</span>”) 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 “<span class="quote">-</span>”
! 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>