summaryrefslogtreecommitdiff
path: root/debian/README.maintainers.in
diff options
context:
space:
mode:
Diffstat (limited to 'debian/README.maintainers.in')
-rw-r--r--debian/README.maintainers.in88
1 files changed, 88 insertions, 0 deletions
diff --git a/debian/README.maintainers.in b/debian/README.maintainers.in
new file mode 100644
index 0000000..c0b0cab
--- /dev/null
+++ b/debian/README.maintainers.in
@@ -0,0 +1,88 @@
+
+Hints for maintainers of Debian packages of Python extensions
+-------------------------------------------------------------
+
+Most of the content of this README can be found in the Debian Python policy.
+See /usr/share/doc/python/python-policy.txt.gz.
+
+Documentation Tools
+-------------------
+
+If your package ships documentation produced in the Python
+documentation format, you can generate it at build-time by
+build-depending on @PVER@-dev, and you will find the
+templates, tools and scripts in /usr/lib/@PVER@/doc/tools --
+adjust your build scripts accordingly.
+
+
+Makefile.pre.in issues
+----------------------
+
+Python comes with a `universal Unix Makefile for Python extensions' in
+/usr/lib/@PVER@/config/Makefile.pre.in (with Debian, this is included
+in the python-dev package), which is used by most Python extensions.
+
+In general, packages using the Makefile.pre.in approach can be packaged
+simply by running dh_make or by using one of debhelper's rules' templates
+(see /usr/doc/debhelper/examples/). Makefile.pre.in works fine with e.g.
+"make prefix=debian/tmp/usr install".
+
+One glitch: You may be running into the problem that Makefile.pre.in
+doesn't try to create all the directories when they don't exist. Therefore,
+you may have to create them manually before "make install". In most cases,
+the following should work:
+
+ ...
+ dh_installdirs /usr/lib/@PVER@
+ $(MAKE) prefix=debian/tmp/usr install
+ ...
+
+
+Byte-compilation
+----------------
+
+For speed reasons, Python internally compiles source files into a byte-code.
+To speed up subsequent imports, it tries to save the byte-code along with
+the source with an extension .pyc (resp. pyo). This will fail if the
+libraries are installed in a non-writable directory, which may be the
+case for /usr/lib/@PVER@/.
+
+Not that .pyc and .pyo files should not be relocated, since for debugging
+purposes the path of the source for is hard-coded into them.
+
+To precompile files in batches after installation, Python has a script
+compileall.py, which compiles all files in a given directory tree. The
+Debian version of compileall has been enhanced to support incremental
+compilation and to feature a ddir (destination dir) option. ddir is
+used to compile files in debian/usr/lib/python/ when they will be
+installed into /usr/lib/python/.
+
+
+Currently, there are two ways to use compileall for Debian packages. The
+first has a speed penalty, the second has a space penalty in the package.
+
+1.) Compiling and removing .pyc files in postinst/prerm:
+
+ Use dh_python(1) from the debhelper packages to add commands to byte-
+ compile on installation and to remove the byte-compiled files on removal.
+ Your package has to build-depend on: debhelper (>= 4.1.67), python.
+
+ In /usr/share/doc/@PVER@, you'll find sample.postinst and sample.prerm.
+ If you set the directory where the .py files are installed, these
+ scripts will install and remove the .pyc and .pyo files for your
+ package after unpacking resp. before removing the package.
+
+2.) Compiling the .pyc files `out of place' during installation:
+
+ As of 1.5.1, compileall.py allows you to specify a faked installation
+ directory using the "-d destdir" option, so that you can precompile
+ the files in their temporary directory
+ (e.g. debian/tmp/usr/lib/python2.1/site-packages/PACKAGE).
+
+
+
+ 11/02/98
+ Gregor Hoffleit <flight@debian.org>
+
+
+Last modified: 2007-10-14