Page MenuHomeFreeBSD
Differential D573 Diff 1945 en_US.ISO8859-1/books/porters-handbook/special/chapter.xml

Changeset View

Standalone View

View Options

en_US.ISO8859-1/books/porters-handbook/special/chapter.xml

Show First 20 Lines • Show All 2,735 Lines • ▼ Show 20 Lines </example>
</sect3> </sect3>
</sect2> </sect2>
</sect1> </sect1>
<sect1 xml:id="using-python"> <sect1 xml:id="using-python">
<title>Using Python</title> <title>Using Python</title>
<para>The Ports Collection supports parallel installation of <para>The Ports Collection supports parallel installation of
multiple Python versions. Ports must use a multiple Python versions. Ports must use a
matUnsubmitted
Not Done
Inline Actions

You should put the space back, the rule is bla.<space><space>Bla

mat: You should put the space back, the rule is `bla.<space><space>Bla`
correct <command>python</command> interpreter, according to correct <command>python</command> interpreter, according to
the user-settable <varname>PYTHON_VERSION</varname>. the user-settable <varname>PYTHON_VERSION</varname>.
Most prominently, this means replacing the path to Most prominently, this means replacing the path to
<command>python</command> executable in scripts with the value <command>python</command> executable in scripts with the value
of <varname>PYTHON_CMD</varname>.</para> of <varname>PYTHON_CMD</varname>.</para>
<para>Ports that install files under <para>Ports that install files under
<varname>PYTHON_SITELIBDIR</varname> must use the <varname>PYTHON_SITELIBDIR</varname> must use the
<literal>pyXY-</literal> package name prefix, so their package <literal>pyXY-</literal> package name prefix, so their package
name embeds the version of Python they are installed name embeds the version of Python they are installed
into.</para> into.</para>
<programlisting>PKGNAMEPREFIX= ${PYTHON_PKGNAMEPREFIX}</programlisting> <programlisting>PKGNAMEPREFIX= ${PYTHON_PKGNAMEPREFIX}</programlisting>
<table frame="none" xml:id="using-python-variables"> <table frame="none" xml:id="using-python-variables">
<title>Most Useful Variables for Ports That Use Python</title> <title>Most Useful Variables for Ports That Use Python</title>
<tgroup cols="2"> <tgroup cols="2">
<tbody> <tbody>
<row> <row>
<entry><varname>USE_PYTHON</varname></entry> <entry><varname>USES=python</varname></entry>
<entry>The port needs Python. Minimal required version <entry>The port needs Python. The minimal required version
wblockUnsubmitted
Not Done
Inline Actions

s/Minimal/The minimal/

wblock: s/Minimal/The minimal/
can be specified with values such as can be specified with values such as
<literal>2.6+</literal>. Version ranges can also be <literal>2.7+</literal>. Version ranges can also be
wblockUnsubmitted
Not Done
Inline Actions

The comma is unnecessary here:

specified by separating two version numbers with a

wblock: The comma is unnecessary here: specified by separating two version numbers with a
specified, by separating two version numbers with a specified by separating two version numbers with a
dash, for example, <literal>2.6-2.7</literal></entry> dash: <literal>USES=python:3.2-3.3</literal></entry>
wblockUnsubmitted
Not Done
Inline Actions

That e.g. is not helping and can be removed:

dash: <literal>USES=python:3.2-3.3</literal></entry>

wblock: That e.g. is not helping and can be removed: dash: <literal>USES=python:3.2-3.
</row> </row>
<row> <row>
<entry><varname>USE_PYDISTUTILS</varname></entry> <entry><varname>USE_PYTHON=distutils</varname></entry>
mvaAuthorUnsubmitted
Not Done
Inline Actions

Note that we have D581 cooking, which will replace PYTHON_FEATURES with USE_PYTHON to avoid inconsistencies. I'll go over the requested changes later today.

mva: Note that we have D581 cooking, which will replace PYTHON_FEATURES with USE_PYTHON to avoid…
wblockUnsubmitted
Not Done
Inline Actions

Harvard/Oxford comma:

s/compiling/compiling,/

wblock: Harvard/Oxford comma: s/compiling/compiling,/
<entry>Use Python distutils for configuring, compiling <entry>Use Python distutils for configuring, compiling,
and installing. This is required when the port comes and installing. This is required when the port comes
with <filename>setup.py</filename>. This overrides with <filename>setup.py</filename>. This overrides
the <buildtarget>do-build</buildtarget> and the <buildtarget>do-build</buildtarget> and
<buildtarget>do-install</buildtarget> targets and may <buildtarget>do-install</buildtarget> targets and may
also override <buildtarget>do-configure</buildtarget> also override <buildtarget>do-configure</buildtarget>
if <varname>GNU_CONFIGURE</varname> is not if <varname>GNU_CONFIGURE</varname> is not
defined.</entry> defined.</entry>
</row> </row>
<row> <row>
<entry><varname>USE_PYTHON=autoplist</varname></entry>
<entry>Create the packaging list automatically. This also requires
<literal>USE_PYTHON=distutils</literal> to be set.
</entry>
</row>
<row>
<entry><varname>USE_PYTHON=concurrent</varname></entry>
<entry>Marks the port as safe to be installed for different python
versions at the same time. The port will use an unique prefix for
wblockUnsubmitted
Not Done
Inline Actions

The second sentence can be more clear:

A unique prefix will be used for directories like <varname>EXAMPLESDIR</varname> and <varname>DOCSDIR</varname>. A suffix will be appended to the names of binaries and scripts.

(What suffix? Why? Is it ".py"?)

wblock: The second sentence can be more clear: A unique prefix will be used for directories like…
wblockUnsubmitted
Not Done
Inline Actions

s/an unique/a unique/

The entries tagged as <literal> are actually make variables, and should use <varname> tags.

wblock: s/an unique/a unique/ The entries tagged as <literal> are actually make variables, and should…
certain directories, such as <literal>EXAMPLESDIR</literal> and
<literal>DOCSDIR</literal> and also will append a suffix to binaries
and scripts to be installed.</entry>
</row>
<row>
<entry><varname>PYTHON_PKGNAMEPREFIX</varname></entry> <entry><varname>PYTHON_PKGNAMEPREFIX</varname></entry>
<entry>Used as a <varname>PKGNAMEPREFIX</varname> to <entry>Used as a <varname>PKGNAMEPREFIX</varname> to
distinguish packages for different Python versions. distinguish packages for different Python versions.
Example: <literal>py24-</literal></entry> Example: <literal>py27-</literal></entry>
</row> </row>
<row> <row>
<entry><varname>PYTHON_SITELIBDIR</varname></entry> <entry><varname>PYTHON_SITELIBDIR</varname></entry>
<entry>Location of the site-packages tree, that contains <entry>Location of the site-packages tree, that contains
installation path of Python (usually installation path of Python (usually
<varname>LOCALBASE</varname>). <varname>LOCALBASE</varname>).
<varname>PYTHON_SITELIBDIR</varname> can be <varname>PYTHON_SITELIBDIR</varname> can be
Show All 34 Lines <row>
Python 2.0 and higher as it is also in base Python 2.0 and higher as it is also in base
distribution).</entry> distribution).</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
</table> </table>
<para>A complete list of available variables can be found in <para>A complete list of available variables can be found in
<filename>/usr/ports/Mk/bsd.python.mk</filename>.</para> <filename>/usr/ports/Mk/Uses/python.mk</filename>.</para>
<example xml:id="python-Makefile">
<title>Makefile for a simple <application>Python</application>
wblockUnsubmitted
Not Done
Inline Actions

s/simple/Simple/

wblock: s/simple/Simple/
Module</title>
<programlisting>PORTNAME= sample
PORTVERSION= 1.2.3
CATEGORIES= devel
MAINTAINER= john@doe.tld
COMMENT= Python sample module
USES= python
USE_PYTHON= autoplist distutils
.include &lt;bsd.port.mk&gt;</programlisting>
</example>
wblockUnsubmitted
Not Done
Inline Actions

That file does not exist on my system, r364482.

wblock: That file does not exist on my system, r364482.
matUnsubmitted
Not Done
Inline Actions

It does, really, you're just lagging behind :-)
I don't like sending people to read files, the variables should be available in the handbook, either in this section, or in the USES=python section.

mat: It does, really, you're just lagging behind :-) I don't like sending people to read files, the…
wblockUnsubmitted
Not Done
Inline Actions

Okay, it's there now.

Agreed that referring people to files is ugly. An alternate method is to link to that file in svnweb:
<link xlink:href="http://svnweb.freebsd.org/ports/head/Mk/Uses/python.mk?view=co"></link>

wblock: Okay, it's there now. Agreed that referring people to files is ugly. An alternate method is…
matUnsubmitted
Not Done
Inline Actions

I have been thinking about this yesterday evening, would be best to add this as is, it is not bad and I would rather have this in sooner than later. I will go over it when it is in and document all variables here.

mat: I have been thinking about this yesterday evening, would be best to add this as is, it is not…
mvaAuthorUnsubmitted
Not Done
Inline Actions

I'm not sure about a plain documentation of the variables, since this certainly won't help people to identify, when those are needed.

Rather than just jotting down the variables, always lagging behind changes in python.mk, I'd like to create a set of context-based examples for the most important variables, so people actually know how and when to use them.

mva: I'm not sure about a plain documentation of the variables, since this certainly won't help…
matUnsubmitted
Not Done
Inline Actions

Well, lagging behind is because nobody ever really maintained the PHB, I'm doing it now, so it doesn't lag too much behind. It is important that things are documented outside the sources, not everyone likes to have to read through comments and code to figure out what things really do, people want one source of information, possibly nicely formatted, that's what the PHB is :-)

mat: Well, lagging behind is because nobody ever really maintained the PHB, I'm doing it now, so it…
mvaAuthorUnsubmitted
Not Done
Inline Actions

Understood :-). How about the following then:

We'll (Python) provide you the list of python-related knobs along with examples, so users know, how and when to use those. This should be better than just copy-pasting the knobs from the .mk file

mva: Understood :-). How about the following then: We'll (#Python) provide you the list of python…
matUnsubmitted
Not Done
Inline Actions

Could be nice to have the current complete list available in there, either here or in the USES chapter. But it can wait for later.

mat: Could be nice to have the current complete list available in there, either here or in the USES…
<para>Some Python applications claim to have <para>Some Python applications claim to have
<varname>DESTDIR</varname> support (which would be required <varname>DESTDIR</varname> support (which would be required
for staging) but it is broken (Mailman up to 2.1.16, for for staging) but it is broken (Mailman up to 2.1.16, for
instance). This can be worked around by recompiling the instance). This can be worked around by recompiling the
scripts. This can be done, for example, in the scripts. This can be done, for example, in the
<buildtarget>post-build</buildtarget> target. Assuming the <buildtarget>post-build</buildtarget> target. Assuming the
Python scripts are supposed to reside in Python scripts are supposed to reside in
▲ Show 20 Lines • Show All 1,773 Lines • Show Last 20 Lines