source: trunk/doc-new/guide/xml/portfile-dependencies.xml

Last change on this file was 134587, checked in by ionic@…, 4 years ago

doc-new/guide/xml: indentation and whitespace fixes.

File size: 7.3 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="reference.dependencies">
5  <title>Dependencies</title>
6
7  <para>Free and open source software is highly modular, and MacPorts ports
8  often require that other ports be installed beforehand; these prerequisites
9  for a given port are called a port's <quote>dependencies</quote>.</para>
10
11  <para>The keywords used when specifying dependencies in a Portfile are
12  related to port install phases, and they refer to what are called library,
13  build, fetch, extract and run dependencies. Though all of them install dependencies
14  before a given port is installed, specifying dependencies with the correct keyword
15  is important for proper port upgrade and uninstall behavior, or when running targets
16  other than install. For example,
17  you may not uninstall a port that is a library dependency for another installed port,
18  though you may remove one that is a build dependency. Likewise, if you run the
19  fetch target for a port, only the fetch dependencies will be installed first, so
20  they should be all that is needed for that target.</para>
21
22  <variablelist>
23    <varlistentry>
24      <term>depends_fetch</term>
25
26      <term>depends_fetch-append</term>
27
28      <term>depends_fetch-delete</term>
29
30      <listitem>
31        <para>The list of dependencies to check before phases
32        <option>fetch</option>, <option>checksum</option>,
33        <option>extract</option>, <option>patch</option>,
34        <option>configure</option>, <option>build</option>,
35        <option>destroot</option>, <option>install</option>, and
36        <option>package</option>. Fetch dependencies are needed to download
37        the distfiles for a port, and are not needed at all once the software
38        is installed.</para>
39      </listitem>
40    </varlistentry>
41
42    <varlistentry>
43      <term>depends_extract</term>
44
45      <term>depends_extract-append</term>
46
47      <term>depends_extract-delete</term>
48
49      <listitem>
50        <para>The list of dependencies to check before phases
51        <option>extract</option>, <option>patch</option>,
52        <option>configure</option>, <option>build</option>,
53        <option>destroot</option>, <option>install</option>, and
54        <option>package</option>. Extract dependencies are needed to unpack a
55        port's distfiles into the work directory, and are not needed at all once
56        the software is installed.</para>
57      </listitem>
58    </varlistentry>
59
60    <varlistentry>
61      <term>depends_build</term>
62
63      <term>depends_build-append</term>
64
65      <term>depends_build-delete</term>
66
67      <listitem>
68        <para>The list of dependencies to check before phases
69        <option>configure</option>, <option>build</option>,
70        <option>destroot</option>, <option>install</option>, and
71        <option>package</option>. Build dependencies are needed when software
72        is being built, but not needed at all once it is installed.</para>
73      </listitem>
74    </varlistentry>
75
76    <varlistentry>
77      <term>depends_lib</term>
78
79      <term>depends_lib-append</term>
80
81      <term>depends_lib-delete</term>
82
83      <listitem>
84        <para>The list of dependencies to check before phases
85        <option>configure</option>, <option>build</option>,
86        <option>destroot</option>, <option>install</option>, and
87        <option>package</option>. Library dependencies are needed both at
88        build time (for headers and libraries to link against) and at run
89        time.</para>
90      </listitem>
91    </varlistentry>
92
93    <varlistentry>
94      <term>depends_run</term>
95
96      <term>depends_run-append</term>
97
98      <term>depends_run-delete</term>
99
100      <listitem>
101        <para>The list of dependencies to check before phases
102        <option>destroot</option>, <option>install</option>, and
103        <option>package</option>. Run dependencies are needed when the
104        software is run, but not to compile it.</para>
105      </listitem>
106    </varlistentry>
107  </variablelist>
108
109  <section id="reference.dependencies.types">
110    <title>Port and File Dependencies</title>
111
112    <para>There are two types of dependencies: port dependencies and file
113    dependencies. Port dependencies can be satisfied by reference to a port
114    (the MacPorts registry is queried), or by reference to a file (whether
115    provided by a port or not). The most commonly-used type of dependencies in
116    Portfiles are port dependencies, because dependencies should be provided
117    by MacPorts ported software whenever possible, and usually only one port
118    can provide the needed libraries and files.</para>
119
120    <para>But when satisfying a dependency with vendor-supplied software is
121    preferred for special reasons, or when it is possible for more than one
122    port to satisfy a dependency, then file dependencies may be used. An
123    example of the former is with ubiquitous utilities like awk, grep, make or
124    sed, where OS X's versions are often sufficient; an example of the latter
125    is with <quote>-devel</quote> ports—these ports provide a different
126    version of the same files (though only one can be activated at a
127    time).</para>
128
129    <para>Port dependencies, the preferred type, are specified as shown in
130    these examples:</para>
131
132    <programlisting>depends_lib         port:rrdtool port:apache2
133
134depends_build       port:libtool
135
136depends_run         port:apache2 port:php5</programlisting>
137
138    <para>File dependencies should only be used if one of the reasons listed
139    above applies. There are three types: <option>bin</option> for
140    programs, <option>lib</option> for libraries, and <option>path</option>
141    for any installed file. File dependencies are specified in the form:
142    <replaceable>&lt;type&gt;</replaceable>:<replaceable>&lt;filespec&gt;</replaceable>:<replaceable>&lt;port&gt;</replaceable>.</para>
143
144    <para>For <option>bin</option> dependencies,
145    <replaceable>&lt;filespec&gt;</replaceable> is the name of a program in a
146    bin directory like <filename>${prefix}/bin</filename>, /usr/bin, /bin, and
147    the associated sbin directories.</para>
148
149    <para>For <option>lib</option> dependencies,
150    <replaceable>&lt;filespec&gt;</replaceable> is the name of a library
151    (but without its extension) in a lib directory like
152    <filename>${prefix}/lib</filename>, /usr/lib, /lib, some Framework
153    directories, and those found in environment variables like DYLD_LIBRARY_PATH.</para>
154
155    <para>For <option>path</option> dependencies,
156    <replaceable>&lt;filespec&gt;</replaceable> is the complete absolute path
157    to the file, or more usually, when the file is inside
158    <filename>${prefix}</filename>, it is specified relative to
159    <filename>${prefix}</filename>.
160    Since <option>path</option> dependencies are the only ones which would find
161    files only in an absolute path or a path inside <filename>${prefix}</filename>
162    they are - in cases when a port needs to be more restrictive - often used
163    instead of <option>bin</option> and <option>lib</option> dependencies .</para>
164
165    <para>Note that the <replaceable>&lt;port&gt;</replaceable> specified is
166    only installed if the specified library, binary, or file is not found. See
167    the examples below:</para>
168
169    <programlisting>depends_lib         lib:libX11.6:xorg
170
171depends_build       bin:glibtool:libtool
172
173depends_run         path:lib/libltdl.a:libtool</programlisting>
174  </section>
175</section>
Note: See TracBrowser for help on using the repository browser.