source: trunk/doc-new/guide/xml/portgroup-python.xml @ 103894

Last change on this file since 103894 was 103894, checked in by jmr@…, 7 years ago

guide: document python.link_binaries_suffix, use varname tags in a few places they were forgotten

File size: 9.4 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.portgroup.python">
5
6  <title>PortGroup python</title>
7
8  <para>PortGroup python allows for efficient porting of python-based open
9  source software.</para>
10
11  <note>
12      <para>
13      A number of python-version-specific PortGroups also exist, such as
14      python27 and python32. These should not be used for new development, and
15      ports using them should be migrated to the unified python PortGroup.
16      </para>
17    </note>
18
19  <section id="reference.portgroup.python.keywords">
20    <title>python PortGroup Specific Keywords</title>
21
22    <para>Portfiles using the python PortGroup allow for port authors to
23    set the following keywords in addition to the general Portfile
24    keywords.</para>
25
26    <variablelist>
27      <varlistentry>
28        <term>python.versions</term>
29
30        <listitem>
31          <para>Defines the python versions supported by this port. If the
32          port name starts with "py-", then a subport will be defined for each
33          version in the list. For example, if a port named "py-foo" declares
34          "python.versions 26 27", subports "py26-foo" and "py27-foo" will be
35          created, and will depend on python26 and python27 respectively.</para>
36          <para>If the port name does not start with "py-", it is interpreted
37          as an application written in python rather than a python module. In
38          this case, no subports are defined, and python.versions defaults to
39          the value of python.default_version, which must be set. For example,
40          if a port named "mercurial" sets "python.default_version 27", then
41          python.versions will automatically be set to "27", and a dependency
42          on python27 will be added.</para>
43
44          <itemizedlist>
45            <listitem>
46              <para>Type: required for modules, optional for apps</para>
47            </listitem>
48            <listitem>
49              <para>Example:</para>
50
51              <programlisting>python.versions     25 26 27</programlisting>
52            </listitem>
53          </itemizedlist>
54        </listitem>
55      </varlistentry>
56      <varlistentry>
57        <term>python.default_version</term>
58
59        <listitem>
60          <para>For modules (i.e. name starts with "py-"), this sets the
61          subport that will be installed if the user asks to install "py-foo"
62          rather than e.g. "py26-foo" or "py27-foo". If not explicitly set, a
63          reasonable default is chosen from the list in python.versions.</para>
64          <para>For apps (i.e. name does not start with "py-"), this chooses
65          which version of python to use, and must be set. It can be changed
66          in variants if desired.</para>
67
68          <itemizedlist>
69            <listitem>
70              <para>Type: required for apps, optional for modules</para>
71            </listitem>
72            <listitem>
73              <para>Example:</para>
74
75              <programlisting>python.default_version     32</programlisting>
76            </listitem>
77          </itemizedlist>
78        </listitem>
79      </varlistentry>
80      <varlistentry>
81        <term>python.link_binaries</term>
82
83        <listitem>
84          <para>When yes (the default), tells the PortGroup to automatically
85          link any executable binaries installed in the bin/ directory within
86          the framework into
87          <filename>${prefix}/bin</filename>.</para>
88
89          <itemizedlist>
90            <listitem>
91              <para>Type: optional</para>
92            </listitem>
93            <listitem>
94              <para>Example:</para>
95
96              <programlisting>python.link_binaries     no</programlisting>
97            </listitem>
98          </itemizedlist>
99        </listitem>
100      </varlistentry>
101      <varlistentry>
102        <term>python.link_binaries_suffix</term>
103
104        <listitem>
105          <para>Suffix to add the the names of the links created in
106          <filename>${prefix}/bin</filename> when <varname>${python.link_binaries}</varname>
107          is enabled. Can be cleared if no suffix is desired.</para>
108
109          <itemizedlist>
110            <listitem>
111              <para>Type: optional</para>
112            </listitem>
113            <listitem>
114                <para>Default: -<varname>${python.branch}</varname></para>
115            </listitem>
116          </itemizedlist>
117        </listitem>
118      </varlistentry>
119      <varlistentry>
120        <term>python.add_archflags</term>
121        <listitem>
122          <para>When yes (the default), the PortGroup will automatically
123          try to pass the correct arch-specific flags during build time
124          (via the standard CFLAGS, LDFLAGS, etc environment variables).
125          Set this to no and setup those variables in build.env manually
126          if the default does not work.</para>
127          <itemizedlist>
128            <listitem>
129              <para>Type: optional</para>
130            </listitem>
131            <listitem>
132              <para>Example:</para>
133
134              <programlisting>python.add_archflags     no</programlisting>
135            </listitem>
136          </itemizedlist>
137        </listitem>
138      </varlistentry>
139    </variablelist>
140  </section>
141
142  <section id="reference.portgroup.python.variables">
143    <title>python PortGroup Specific Variables</title>
144
145    <para>When the python PortGroup is declared within a Portfile, the
146    following variables are provided.</para>
147
148    <variablelist>
149      <varlistentry>
150        <term>python.version</term>
151
152        <listitem>
153          <para>The python version in use in the current subport. This will be
154          one of the versions listed in python.versions.</para>
155        </listitem>
156      </varlistentry>
157
158      <varlistentry>
159        <term>python.branch</term>
160
161        <listitem>
162          <para>The python version in use in the current subport, in normal
163          dotted notation. For example, if python.version is "26",
164          python.branch will be "2.6".</para>
165        </listitem>
166      </varlistentry>
167
168      <varlistentry>
169        <term>python.prefix</term>
170
171        <listitem>
172          <para>The prefix in which the current python version is installed.
173          For framework builds, this is <filename>${frameworks_dir}/Python.framework/Versions/${python.branch}</filename>,
174          whereas for non-framework builds, it is the same as <varname>${prefix}</varname>.</para>
175        </listitem>
176      </varlistentry>
177
178      <varlistentry>
179        <term>python.bin</term>
180
181        <listitem>
182          <para>The path to the MacPorts Python executable.</para>
183        </listitem>
184      </varlistentry>
185
186      <varlistentry>
187        <term>python.lib</term>
188
189        <listitem>
190          <para>The Python dynamic library path, i.e.
191          <filename>${python.prefix}/Python</filename> (framework builds) or
192          <filename>${prefix}/lib/libpython2.4.dylib</filename> (python24).</para>
193        </listitem>
194      </varlistentry>
195
196      <varlistentry>
197        <term>python.libdir</term>
198
199        <listitem>
200          <para>The path to python's lib directory, i.e.
201          <filename>${python.prefix}/lib/python${python.branch}</filename>.</para>
202        </listitem>
203      </varlistentry>
204
205      <varlistentry>
206        <term>python.include</term>
207
208        <listitem>
209          <para>Path to the Python include directory.</para>
210        </listitem>
211      </varlistentry>
212
213      <varlistentry>
214        <term>python.pkgd</term>
215
216        <listitem>
217          <para>Path to the Python site-packages directory. (i.e.,
218          <filename>${python.prefix}/lib/python${python.branch}/site-packages</filename>).</para>
219        </listitem>
220      </varlistentry>
221    </variablelist>
222  </section>
223
224  <section id="reference.portgroup.python.sugar">
225    <title>python PortGroup Sugar</title>
226
227    <para>Portfiles using PortGroup python do not need to define the
228    following variables:</para>
229
230    <variablelist>
231      <varlistentry>
232        <term>categories</term>
233
234        <listitem>
235          <para>Default: python</para>
236        </listitem>
237      </varlistentry>
238
239      <varlistentry>
240        <term>depends_lib</term>
241
242        <listitem>
243          <para>Default: port:python<varname>${python.version}</varname></para>
244        </listitem>
245      </varlistentry>
246
247      <varlistentry>
248        <term>use_configure</term>
249
250        <listitem>
251          <para>Default: no</para>
252        </listitem>
253      </varlistentry>
254
255      <varlistentry>
256        <term>build.cmd</term>
257
258        <listitem>
259          <para>Default: <varname>${python.bin}</varname> setup.py --no-user-cfg</para>
260        </listitem>
261      </varlistentry>
262
263      <varlistentry>
264        <term>build.target</term>
265
266        <listitem>
267          <para>Default: build</para>
268        </listitem>
269      </varlistentry>
270
271      <varlistentry>
272        <term>destroot.cmd</term>
273
274        <listitem>
275          <para>Default: <varname>${python.bin}</varname> setup.py --no-user-cfg</para>
276        </listitem>
277      </varlistentry>
278
279      <varlistentry>
280        <term>destroot.destdir</term>
281
282        <listitem>
283          <para>Default: --prefix=<varname>${python.prefix}</varname> --root=<varname>${destroot}</varname></para>
284        </listitem>
285      </varlistentry>
286
287      <varlistentry>
288        <term>pre-destroot</term>
289
290        <listitem>
291          <para>Default: creates directory
292          <filename>${destroot}${prefix}/share/doc/${subport}/examples</filename>.</para>
293        </listitem>
294      </varlistentry>
295    </variablelist>
296  </section>
297</section>
Note: See TracBrowser for help on using the repository browser.