name : README.maintainers 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 python3.12-dev, and you will find the templates, tools and scripts in /usr/lib/python3.12/doc/tools -- adjust your build scripts accordingly. Makefile.pre.in issues ---------------------- Python comes with a `universal Unix Makefile for Python extensions' in /usr/lib/python3.12/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/python3.12 $(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/python3.12/. 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/python3.12, 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