source: trunk/doc-new/guide/xml/macports.conf.xml @ 75365

Last change on this file since 75365 was 75365, checked in by singingwolfboy@…, 9 years ago

Documented place_worksymlink option in macports.conf

File size: 12.9 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4<section id="internals.configuration-files">
5  <title>Configuration Files</title>
6
7  <para>The MacPorts configuration files do not need to be modified for the
8  general end user. They contain options that may be of use to advanced users
9  and port developers.</para>
10
11  <para>There are three MacPorts configuration files that define important
12  variables used by the MacPorts system: <filename>macports.conf</filename>,
13  <filename>sources.conf</filename>, and <filename>variants.conf</filename>.
14  All MacPorts configurations files are located in
15  <filename>${prefix}/etc/macports</filename>.</para>
16
17  <para>MacPorts configuration file format is a simple key/value pair
18  separated by either a space or a tab. Lines beginning with '#' are comments,
19  empty lines are ignored.</para>
20
21  <section id="internals.configuration-files.macports-conf">
22    <title>macports.conf</title>
23
24    <para>macports.conf is the configuration file used to bootstrap the
25    MacPorts system. This file is read by the port command and determines how
26    it behaves.</para>
27
28    <para>Options locating other .conf files.</para>
29
30    <variablelist>
31      <varlistentry>
32        <term>sources_conf</term>
33
34        <listitem>
35          <para>Where to find the sources list.</para>
36
37          <para>Default:
38          <filename>${prefix}/etc/macports/sources.conf</filename></para>
39        </listitem>
40      </varlistentry>
41
42      <varlistentry>
43        <term>variants_conf</term>
44
45        <listitem>
46          <para>Where to find global variants definition file
47          (optional).</para>
48
49          <para>Default:
50          <filename>${prefix}/etc/macports/variants.conf</filename></para>
51        </listitem>
52      </varlistentry>
53    </variablelist>
54
55    <para>Options for MacPorts general operating characteristics.</para>
56
57    <variablelist>
58      <varlistentry>
59        <term>prefix</term>
60
61        <listitem>
62          <para>Sets the directory where ports are installed. Any path may be
63          used but those with spaces and/or non-ASCII characters should be
64          avoided because it can break some ports.</para>
65
66          <para>Default: <filename>/opt/local</filename></para>
67        </listitem>
68      </varlistentry>
69
70      <varlistentry>
71        <term>portdbpath</term>
72
73        <listitem>
74          <para>Directory where MacPorts keeps working data as downloaded
75          sources, installed port receipts, and the main registry. Same path
76          restrictions apply as for '${prefix}'.</para>
77
78          <para>Default: ${prefix}/var/macports</para>
79        </listitem>
80      </varlistentry>
81
82      <varlistentry>
83        <term>portdbformat</term>
84
85        <listitem>
86          <para>Storage type to use for the MacPorts registry: flat or sqlite.
87          Preferred format is sqlite, flat is legacy.</para>
88
89          <para>Default: <option>sqlite</option></para>
90        </listitem>
91      </varlistentry>
92
93      <varlistentry>
94        <term>portinstalltype</term>
95
96        <listitem>
97          <para>Sets the mode in which ports are installed by MacPorts.
98          Supported values are "direct" or "image". In "direct" mode ports are
99          installed directly into "${prefix}" and only one version of a port
100          can be installed at any given time. In "image" mode multiple
101          versions (and any possible combination of its variants) can be
102          installed concurrently into "${portdbpath}/software/${portname}" and
103          only one can be "activated" (hardlinked) into "${prefix}".</para>
104
105          <para>Default: <option>image</option></para>
106        </listitem>
107      </varlistentry>
108     
109      <varlistentry>
110        <term>build_arch</term>
111
112        <listitem>
113          <para>The machine architecture to build for in normal use.
114          Options include: ppc, i386, ppc64, x86_64</para>
115
116          <para>Default: </para>
117          <para>(Snow Leopard) <option>x86_64</option> or <option>i386</option> depending on hardware</para>
118          <para>(Leopard/Tiger) <option>i386</option> or <option>ppc</option> depending on hardware</para>
119        </listitem>
120      </varlistentry>
121
122      <varlistentry>
123        <term>applications_dir</term>
124
125        <listitem>
126          <para>Directory to install MacPorts that install Mac OS X .app
127          bundles.</para>
128
129          <para>Default: <filename>/Applications/MacPorts</filename></para>
130        </listitem>
131      </varlistentry>
132
133      <varlistentry>
134        <term>frameworks_dir</term>
135
136        <listitem>
137          <para>Directory to install frameworks installed by ports.</para>
138
139          <para>Default:
140          <filename>${prefix}/Library/Frameworks</filename></para>
141        </listitem>
142      </varlistentry>
143     
144      <varlistentry>
145        <term>developer_dir</term>
146
147        <listitem>
148          <para>Directory where Xcode Tools is installed.</para>
149
150          <para>Default:
151          <filename>/Developer</filename></para>
152        </listitem>
153      </varlistentry>
154
155      <varlistentry>
156        <term>portarchivemode</term>
157
158        <listitem>
159          <para>Create and use binary archive packages for
160          installation/reinstallation ease.</para>
161
162          <para>Default: <option>no</option></para>
163        </listitem>
164      </varlistentry>
165
166      <varlistentry>
167        <term>portarchivepath</term>
168
169        <listitem>
170          <para>Where to store/retrieve port binary archive files.</para>
171
172          <para>Default:
173          <filename>${prefix}/var/macports/packages</filename></para>
174        </listitem>
175      </varlistentry>
176
177      <varlistentry>
178        <term>portarchivetype</term>
179
180        <listitem>
181          <para>Type of binary archive packages to create when using archive
182          mode. Available types are: tgz, tar, tbz, tbz2, tlz, xar, zip, cpgz,
183          cpio.</para>
184
185          <para>Multiple types are supported to build multiple file types in
186          one step. Unarchive uses multiple types as a search list to locate
187          an archive, and the first to match a specified type is used.
188          Multiple types must be separated by a colon or comma (NO
189          spaces).</para>
190
191          <para>Default: <filename>.tgz</filename></para>
192        </listitem>
193      </varlistentry>
194
195      <varlistentry>
196        <term>configureccache</term>
197
198        <listitem>
199          <para>Use ccache (C/C++ compiler cache) - see
200          http://ccache.samba.org/</para>
201
202          <para>Default: <option>no</option></para>
203        </listitem>
204      </varlistentry>
205
206      <varlistentry>
207        <term>configuredistcc</term>
208
209        <listitem>
210          <para>Use distcc (distributed compiler) - see
211          http://distcc.samba.org/</para>
212
213          <para>Default: <option>no</option></para>
214        </listitem>
215      </varlistentry>
216
217      <varlistentry>
218        <term>configurepipe</term>
219
220        <listitem>
221          <para>Use pipes rather than intermediate files when compiling
222          C/C++/etc</para>
223
224          <para>Default: <option>yes</option></para>
225        </listitem>
226      </varlistentry>
227
228      <varlistentry>
229        <term>buildnicevalue</term>
230
231        <listitem>
232          <para>Lowered scheduling priority (0-20) to use for make when
233          building ports.</para>
234
235          <para>Default: 0</para>
236        </listitem>
237      </varlistentry>
238
239      <varlistentry>
240        <term>buildmakejobs</term>
241
242        <listitem>
243          <para>Number of simultaneous make jobs (commands) to use when
244          building ports. Using "0" will cause a runtime autodetection to use
245          all available processor cores.</para>
246
247          <para>Default: 0</para>
248        </listitem>
249      </varlistentry>
250
251      <varlistentry>
252        <term>portautoclean</term>
253
254        <listitem>
255          <para>Set whether to automatically execute "clean" after "install"
256          of ports.</para>
257
258          <para>Default: <option>yes</option></para>
259        </listitem>
260      </varlistentry>
261
262      <varlistentry>
263        <term>rsync_server</term>
264
265        <listitem>
266          <para>Rsync server from which to fetch MacPorts sources.</para>
267
268          <para>Default: rsync.macports.org</para>
269        </listitem>
270      </varlistentry>
271
272      <varlistentry>
273        <term>rsync_dir</term>
274
275        <listitem>
276          <para>Rsync directory from which to pull the base/ component
277          (infrastructure) of MacPorts.</para>
278
279          <para>Default: <filename>release/base/</filename></para>
280        </listitem>
281      </varlistentry>
282
283      <varlistentry>
284        <term>rsync_options</term>
285
286        <listitem>
287          <para>Rsync options</para>
288
289          <para>Default: -rtzv --delete-after</para>
290        </listitem>
291      </varlistentry>
292
293      <varlistentry>
294        <term>destroot_umask</term>
295
296        <listitem>
297          <para>Umask value to use during the destrooting or a port.</para>
298
299          <para>Default: 022</para>
300        </listitem>
301      </varlistentry>
302
303      <varlistentry>
304        <term>binpath</term>
305
306        <listitem>
307          <para>Sets env(PATH), the directory search path for locating system executables
308          (rsync, tar, etc.) during port installation. Only applications in
309          these directories are available while ports are being installed even
310          if other paths are specified by $PATH in a user's
311          environment.</para>
312
313          <para>Default:
314          ${prefix}/bin:${prefix}/sbin:/bin:/sbin:/usr/bin:/usr/sbin</para>
315
316          <note>
317            <para>The binpath is implicitly defined, but it may be overwritten
318            by defining the variable in macports.conf. However, using a
319            non-default binpath is discouraged and should only be performed by
320            advanced users.</para>
321          </note>
322        </listitem>
323      </varlistentry>
324    </variablelist>
325
326    <para>Options for MacPorts Universal Binaries (+universal variant)</para>
327
328    <variablelist>
329      <varlistentry>
330        <term>universal_archs</term>
331
332        <listitem>
333          <para>The machine architectures to use for +universal variant
334          (multiple entries must be space delimited). Options include: ppc,
335          i386, ppc64, x86_64</para>
336
337          <para>Default: <option>x86_64 i386</option> (<option>ppc
338          i386</option> for 10.5 and earlier)</para>
339        </listitem>
340      </varlistentry>
341    </variablelist>
342
343    <para>Options for StartupItems</para>
344
345    <variablelist>
346      <varlistentry>
347        <term>startupitem_type</term>
348
349        <listitem>
350          <para>Options for generated startup items, though this may be
351          overridden by the "startupitem.type" Portfile key. Options are
352          "default" option, "SystemStarter", "launchd", or "none". For an
353          empty or "default" option, a startupitem type appropriate to the
354          platform is used; if "none", no port startupitems are
355          installed.</para>
356
357          <para>Default: <option>default</option></para>
358        </listitem>
359      </varlistentry>
360    </variablelist>
361
362    <para>Other options</para>
363
364    <variablelist>
365      <varlistentry>
366        <term>extra_env</term>
367
368        <listitem>
369          <para>Extra environment variables to keep. Any variables listed here
370          are added to the list of variables that are not removed from the
371          environment used while processing ports.</para>
372
373          <para>Default: none</para>
374        </listitem>
375      </varlistentry>
376    </variablelist>
377
378    <variablelist>
379      <varlistentry>
380        <term>place_worksymlink</term>
381
382        <listitem>
383            <para>Set whether to place a symlink named "work" from your ports tree to
384                the build directory of a port, when the port is being built. This
385                is convenient, but may not be ideal if you care about the structure
386                of your ports tree. For example, some developers keep their ports
387                tree synchronized across multiple computers, and don't want to also
388                synch build directories.
389            </para>
390          <para>Default: yes</para>
391        </listitem>
392      </varlistentry>
393    </variablelist>
394  </section>
395
396  <section id="internals.configuration-files.sources-conf">
397    <title>sources.conf</title>
398
399    <para>This file enables rsync synchronization of the default ports tree
400    with the MacPorts rsync server when either of the commands <command>port
401    selfupdate</command> or <command>port sync</command> are run.</para>
402
403    <para>Default:
404    <filename>rsync://rsync.macports.org/release/ports/</filename></para>
405
406    <para>Optional local repositories are enabled using a file url:
407    <replaceable>file:///path/to/localportsrepository</replaceable></para>
408  </section>
409
410  <section id="internals.configuration-files.variants-conf">
411    <title>variants.conf</title>
412
413    <para>This optional file specifies any variants you'd like to be invoked
414    globally. If a variant specified ib this file is not supported by a given
415    Portfile, the variant is simply ignored.</para>
416
417    <para>Default: none</para>
418  </section>
419</section>
Note: See TracBrowser for help on using the repository browser.