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