Changes between Initial Version and Version 1 of AnatomyOfAPackage


Ignore:
Timestamp:
01/18/11 13:48:21 (10 years ago)
Author:
jdreed
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • AnatomyOfAPackage

    v1 v1  
     1This page duplicates (and plagiarizes) the information at http://debathena.mit.edu/packaging/.  However, this page is aimed more at working within the Athena repository.   
     2 
     3Within a package source, you'll find the `debian/` directory, which contains the following files: 
     4 
     5 * '''`debian/changelog`''': The Debian changelog for the package. The changelog is the authoritative source for the Debian version number of the package. It is typically installed to /usr/share/doc/package/changelog.Debian.gz. You can manage this with the dch command, or with Emacs' `change-log-mode`.   
     6 * '''`debian/compat`''': The debhelper compatability level of the package.  See CompatLevels for the correct value. 
     7 * '''`debian/control`''':  The Debian packaging system’s metadata for the package. A brief reference is available at the end of this document. Note that while this can be auto-updated with CDBS from control.in, it is essential that it exists. 
     8 * '''`debian/control.in`''': CDBS packages will often have a file called debian/control.in that looks exactly like debian/control except that it has @cdbs@ as a build dependency. This is replaced with various build dependencies that CDBS knows about (like debhelper and cdbs) at build time to generate debian/control. 
     9 * '''`debian/copyright`''':  A human-readable description of the copyright status of the package.   See [wiki:Copyright] for what to use in the Athena repository. 
     10 * '''`debian/rules`''': The executable makefile used to build the binary package.  The information in the table above (along with the control file reference at the end of this document) should be sufficient to generate the files mentioned so far aside from debian/rules, so we will focus attention on that. With CDBS, a simple package whose build system is based on autotools but where autoconf, automake, libtool, and aclocal should not be regenerated will probably look something like the following: 
     11 
     12#!/usr/bin/make -f 
     13 
     14include /usr/share/cdbs/1/rules/debhelper.mk 
     15include /usr/share/cdbs/1/class/autotools.mk 
     16 
     17DEB_CONFIGURE_EXTRA_FLAGS := --enable-shared 
     18# (this last line is from the qd package and is not generic) 
     19For packages that use other build systems, there are rules files in /usr/share/cdbs/1/class/ for make, python-distutils, ant, and a few others. If you plan to use quilt patches, you’ll want to include /usr/share/cdbs/1/rules/patchsys-quilt.mk. CDBS is primarily controlled through the setting of make variables in the rules file or through the existence of special files in the debian directory. Many changes to flags passed to during the build process can be implemented by just setting a single variable. Many of these variables can also be set on a per-package basis using names like CFLAGS_package. To get a definitive answer, one should inspect the code of debhelper.mk or the class file that you are using. Below we list some of the more useful ones: 
     20 
     21DEB_AUTO_UPDATE_DEBIAN_CONTROL 
     22Set this to enabled auto-generation of debian/control from debian/control.in. This option is basically banned in Debian because it apparently causes problems with NMUs, but it can save work. 
     23DEB_CONFIGURE_EXTRA_FLAGS (autotools.mk) 
     24Any extra flags you want to pass to configure. 
     25DEB_MAKE_ENVVARS (makefile.mk) 
     26Any environment variables you want to set for make. 
     27DEB_MAKE_INVOKE += … (makefile.mk) 
     28Pass extra flags to make (note the += here). 
     29DEB_MAKE_{BUILD,CLEAN,…}_TARGET (makefile.mk) 
     30Control what make targets CDBS uses. Note that make install and make check unless you set their corresponding target variable. 
     31DEB_MAKE_CLEAN_TARGET (makefile.mk) 
     32Often you want to set this to distclean. 
     33CFLAGS,CPPFLAGS,LDFLAGS,… (makefile.mk) 
     34Control common compiler and linker flags. 
     35DEB_CONFIGURE_EXTRA_FLAGS (autotools.mk) 
     36Any extra flags you want to pass to configure. 
     37DEB_AUTO_UPDATE_AUTOAUTO = version (makefile.mk) 
     38Have autotools component AUTOAUTO-version run at build time. 
     39DEB_DH_LINK_ARGS 
     40Create symlinks in your installation. 
     41DEB_DH_debhelper-tool_ARGS 
     42Add flags to any of a number of debhelper tools. 
     43Many simple tasks, such as installing an init script for your package can be handled easily be just creating the relevant file (CDBS is automatically invoking debhelper to do this). Below is a list of some of the more useful ones; for a complete list, read debhelper.mk: 
     44 
     45debian/package.install 
     46Pairs, one per line, of files and directories to install them to. Understands “*” and copies directories recursively. 
     47debian/package.init 
     48The package’s init script. Code to run update-rc.d and run the init script at package installation and removal is automatically added to maintainer scripts. 
     49debian/package.cron.d 
     50cron job to be automatically installed into /etc/cron.d. 
     51debian/package.docs 
     52List documentation files/directories to be automatically installed into /usr/share/doc/package. 
     53debian/package.dirs 
     54List directories to be automatically created. 
     55debian/package.postinst 
     56The package’s postinst maintainer script. Make sure you include #DEBHELPER# in maintainer scripts and handle all the right arguments. The best way to do this is to start from /usr/share/debhelper/dh_make/debian/postinst.ex. 
     57Below are a number of tables of commands and information sources that should help you get all the information you need to make packages using CDBS. However, you probably should look at some more examples and probably need some practice. Plentiful examples are available in the CDBS gallery and the Debathena source tree; for practice, a good exercise is to pick a random package, delete its debian/rules file, and try to get it working using CDBS.