From 50a2ec1ef38d40212674378ae19e2b53ea8adabd Mon Sep 17 00:00:00 2001
From: imil <imil@pkgsrc.org>
Date: Thu, 5 Mar 2009 13:08:02 +0000
Subject: Added DESTDIR examples and section 10.1.3. Python modules and
 programs

---
 doc/guide/files/configuring.xml | 41 +++++++++++++++++++++++++++++-
 doc/guide/files/creating.xml    | 55 ++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 94 insertions(+), 2 deletions(-)

(limited to 'doc/guide')

diff --git a/doc/guide/files/configuring.xml b/doc/guide/files/configuring.xml
index 69cf0c4d325..7052242175c 100644
--- a/doc/guide/files/configuring.xml
+++ b/doc/guide/files/configuring.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: configuring.xml,v 1.32 2009/01/28 23:31:39 abs Exp $ -->
+<!-- $NetBSD: configuring.xml,v 1.33 2009/03/05 13:08:02 imil Exp $ -->
 
 <chapter id="configuring">
   <title>Configuring pkgsrc</title>
@@ -163,6 +163,45 @@ works.</para>
     <literal>package-install</literal> will ask again.</para>
     <para>With basic DESTDIR support, <userinput>make
     clean</userinput> needs to be run as root.</para>
+
+    <para>Considering the <filename>foo/bar</filename> package,
+    DESTDIR full support can be tested using the following commands
+
+<programlisting>
+&uprompt; id
+uid=1000(myusername) gid=100(users) groups=100(users),0(wheel)
+&uprompt; mkdir $HOME/packages
+&uprompt; cd $PKGSRCDIR/foo/bar
+</programlisting>
+
+    Verify <varname>DESTDIR</varname> full support, no root privileges
+    should be needed
+
+<programlisting>
+&uprompt; make USE_DESTDIR=full install
+</programlisting>
+
+    Create a package without root privileges
+
+<programlisting>
+&uprompt; make USE_DESTDIR=full PACKAGES=$HOME/packages package
+</programlisting>
+
+    For the following command, you must be able to gain root
+    privileges using &man.su.1;
+
+<programlisting>
+&uprompt; make USE_DESTDIR=full PACKAGES=$HOME/packages package-install
+</programlisting>
+
+    Then, as a simple user
+
+<programlisting>
+&uprompt; make clean
+</programlisting>
+
+    </para>
+
   </sect1>
 
 <sect1 id="conf.compiler">
diff --git a/doc/guide/files/creating.xml b/doc/guide/files/creating.xml
index f1fd9fac2a9..8e2ea030bb9 100644
--- a/doc/guide/files/creating.xml
+++ b/doc/guide/files/creating.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: creating.xml,v 1.7 2007/06/01 11:07:24 rillig Exp $ -->
+<!-- $NetBSD: creating.xml,v 1.8 2009/03/05 13:08:02 imil Exp $ -->
 
 <chapter id="creating">
 <title>Creating a new pkgsrc package from scratch</title>
@@ -127,6 +127,59 @@ settings that are typical of KDE packages.</para>
 
 </sect2>
 
+<sect2 id="creating.python-module">
+<title>Python modules and programs</title>
+
+<para>Python modules and programs packages are easily created using a
+set of predefined variables.</para>
+
+<para>Most Python packages use either <quote>distutils</quote> or
+easy-setup (<quote>eggs</quote>).
+If the software uses <quote>distutils</quote>, set the
+<varname>PYDISTUTILSPKG</varname> variable to <quote>yes</quote> so
+pkgsrc will make use of this framework.
+<quote>distutils</quote> uses a script called <filename>setup.py</filename>,
+if the <quote>distutils</quote> driver is not called
+<filename>setup.py</filename>, set the <varname>PYSETUP</varname> variable
+to the name of the script.</para>
+
+<para>
+If the default Python versions are not supported by the software, set the
+<varname>PYTHON_VERSIONS_ACCEPTED</varname> variable to the Python versions
+the software is known to work with, from the most recent to the older
+one, e.g.
+<programlisting>
+PYTHON_VERSIONS_ACCEPTED=       25 24 23
+</programlisting></para>
+
+<para>
+If the packaged software is a Python module, include
+<quote><filename>../../lang/python/extension.mk</filename></quote>.
+In this case, the package directory should be called
+<quote>py-software</quote> and <varname>PKGNAME</varname> should be set to
+<quote>${PYPKGPREFIX}-${DISTNAME}</quote>, e.g.
+<programlisting>
+DISTNAME=   foopymodule-1.2.10
+PKGNAME=    ${PYPKGPREFIX}-${DISTNAME}
+</programlisting></para>
+
+<para>If it is an application, also include
+<quote><filename>../../lang/python/application.mk</filename></quote>
+before <quote>extension.mk</quote>.</para>
+
+<para>If the packaged software, either it is an application or a module, is
+egg-aware, you only need to include
+<quote><filename>../../lang/python/egg.mk</filename></quote>.</para>
+
+<para>In order to correctly set the path to the Python interpreter, use the
+<varname>REPLACE_PYTHON</varname> variable and set it to the list of files
+that must be corrected. For example :
+<programlisting>
+REPLACE_PYTHON=   ${WRKSRC}/*.py
+</programlisting></para>
+
+</sect2>
+
 </sect1>
 
 <sect1 id="creating.examples">
-- 
cgit v1.2.3