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

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

guide: update python portgroup docs

File size: 8.7 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.add_archflags</term>
103        <listitem>
104          <para>When yes (the default), the PortGroup will automatically
105          try to pass the correct arch-specific flags during build time
106          (via the standard CFLAGS, LDFLAGS, etc environment variables).
107          Set this to no and setup those variables in build.env manually
108          if the default does not work.</para>
109          <itemizedlist>
110            <listitem>
111              <para>Type: optional</para>
112            </listitem>
113            <listitem>
114              <para>Example:</para>
115
116              <programlisting>python.add_archflags     no</programlisting>
117            </listitem>
118          </itemizedlist>
119        </listitem>
120      </varlistentry>
121    </variablelist>
122  </section>
123
124  <section id="reference.portgroup.python.variables">
125    <title>python PortGroup Specific Variables</title>
126
127    <para>When the python PortGroup is declared within a Portfile, the
128    following variables are provided.</para>
129
130    <variablelist>
131      <varlistentry>
132        <term>python.version</term>
133
134        <listitem>
135          <para>The python version in use in the current subport. This will be
136          one of the versions listed in python.versions.</para>
137        </listitem>
138      </varlistentry>
139
140      <varlistentry>
141        <term>python.branch</term>
142
143        <listitem>
144          <para>The python version in use in the current subport, in normal
145          dotted notation. For example, if python.version is "26",
146          python.branch will be "2.6".</para>
147        </listitem>
148      </varlistentry>
149
150      <varlistentry>
151        <term>python.prefix</term>
152
153        <listitem>
154          <para>The prefix in which the current python version is installed.
155          For framework builds, this is <filename>${frameworks_dir}/Python.framework/Versions/${python.branch}</filename>,
156          whereas for non-framework builds, it is the same as ${prefix}.</para>
157        </listitem>
158      </varlistentry>
159
160      <varlistentry>
161        <term>python.bin</term>
162
163        <listitem>
164          <para>The path to the MacPorts Python executable.</para>
165        </listitem>
166      </varlistentry>
167
168      <varlistentry>
169        <term>python.lib</term>
170
171        <listitem>
172          <para>The Python dynamic library path, i.e.
173          <filename>${python.prefix}/Python</filename> (framework builds) or
174          <filename>${prefix}/lib/libpython2.4.dylib</filename> (python24).</para>
175        </listitem>
176      </varlistentry>
177
178      <varlistentry>
179        <term>python.libdir</term>
180
181        <listitem>
182          <para>The path to python's lib directory, i.e.
183          <filename>${python.prefix}/lib/python${python.branch}</filename>.</para>
184        </listitem>
185      </varlistentry>
186
187      <varlistentry>
188        <term>python.include</term>
189
190        <listitem>
191          <para>Path to the Python include directory.</para>
192        </listitem>
193      </varlistentry>
194
195      <varlistentry>
196        <term>python.pkgd</term>
197
198        <listitem>
199          <para>Path to the Python site-packages directory. (i.e.,
200          <filename>${python.prefix}/lib/python${python.branch}/site-packages</filename>).</para>
201        </listitem>
202      </varlistentry>
203    </variablelist>
204  </section>
205
206  <section id="reference.portgroup.python.sugar">
207    <title>python PortGroup Sugar</title>
208
209    <para>Portfiles using PortGroup python do not need to define the
210    following variables:</para>
211
212    <variablelist>
213      <varlistentry>
214        <term>categories</term>
215
216        <listitem>
217          <para>Default: python</para>
218        </listitem>
219      </varlistentry>
220
221      <varlistentry>
222        <term>depends_lib</term>
223
224        <listitem>
225          <para>Default: port:python${python.version}</para>
226        </listitem>
227      </varlistentry>
228
229      <varlistentry>
230        <term>use_configure</term>
231
232        <listitem>
233          <para>Default: no</para>
234        </listitem>
235      </varlistentry>
236
237      <varlistentry>
238        <term>build.cmd</term>
239
240        <listitem>
241          <para>Default: ${python.bin} setup.py --no-user-cfg</para>
242        </listitem>
243      </varlistentry>
244
245      <varlistentry>
246        <term>build.target</term>
247
248        <listitem>
249          <para>Default: build</para>
250        </listitem>
251      </varlistentry>
252
253      <varlistentry>
254        <term>destroot.cmd</term>
255
256        <listitem>
257          <para>Default: ${python.bin} setup.py --no-user-cfg</para>
258        </listitem>
259      </varlistentry>
260
261      <varlistentry>
262        <term>destroot.destdir</term>
263
264        <listitem>
265          <para>Default: --prefix=${python.prefix} --root=${destroot}</para>
266        </listitem>
267      </varlistentry>
268
269      <varlistentry>
270        <term>pre-destroot</term>
271
272        <listitem>
273          <para>Default: creates directory
274          <filename>${destroot}${prefix}/share/doc/${subport}/examples</filename>.</para>
275        </listitem>
276      </varlistentry>
277    </variablelist>
278  </section>
279</section>
Note: See TracBrowser for help on using the repository browser.