Differences between revisions 30 and 31
Revision 30 as of 2007-04-27 16:56:51
Size: 12351
Comment:
Revision 31 as of 2007-04-27 17:00:52
Size: 12369
Comment:
Deletions are marked like this. Additions are marked like this.
Line 7: Line 7:
This page will be worked soon. (TM)

While you wait, please examine the php-java-bridge /debian/* files, as this source package contains many tricks and hints leveraging debhelper scripts and avoiding pitfalls.
This is still being worked.

While you wait a stable version, please examine the php-java-bridge /debian/* files, as this source package contains many tricks and hints leveraging debhelper scripts and avoiding pitfalls.
Line 360: Line 360:
 *[23] thread: how pass variables from files for dh_install into rules? http://lists.debian.org/debian-mentors/2007/04/msg00019.html
http://lists.debian.org/debian-mentors/2007/04/msg00031.html
 *[23] thread: how pass variables from files for dh_install into rules? http://lists.debian.org/debian-mentors/2007/04/msg00019.html http://lists.debian.org/debian-mentors/2007/04/msg00031.html
Line 367: Line 366:
 *[29] GNU autoconf, automake, libtool book (online and paper) http://sourceware.org/autobook/  *[29] Autobook - GNU autoconf, automake, libtool book (online and paper) http://sourceware.org/autobook/

?TableOfContents()

How to split a package into several smaller packages

You want to create multiple binaries packages from one source package.

This is still being worked.

While you wait a stable version, please examine the php-java-bridge /debian/* files, as this source package contains many tricks and hints leveraging debhelper scripts and avoiding pitfalls.

Ideas collected from other package sources, discussion lists, Debian Policy, maintainers guide, man pages.

Special attention to /debian/rules and subpackage_name.* files, like php-java-bridge-j2ee.install , php-java-bridge-j2ee.dirs and so on.

Also, see the README.Debian file, containing many hints and instructions.

Please, note that this source package is a dynamic work in progress, constantly evolving. All suggestions are welcome at the users mailing list.

Readings

Splitting a Debian source package into several smaller binary packages is not trivial.

Before you start, you must read the essential guides [1] to [7], [10] to [12], [19] and feeling already comfortable creating single binary packages.

Variables in rules makefile

You must remember that /debian/rules is a makefile. It is not a shell batch script.

Read the following code:

        BUILDDIR := debian/php-java-bridge
        DESTDIR := ${CURDIR}/${BUILDDIR}
  • Variables MUST be set outside target rules
  • Target rules MUST start at column 1, then followed by ":"
  • Actions MUST start after a TAB, not blank spaces

The BUILDDIR was set to allow use of dh_install for .war files.

The Debian package makefile must be fully relocatable.

The build directory must be at a package tool discretion (usually at some source temporary subdirectory) and must not need root privileges.

For the installation, the destination directory MUST NOT be hard coded into the source.

If the upstream source has hardcoded directories, you must apply patches even before the configure target rule.

You must know the different types of makefile variables reading [20].

The effects of using a simply expanded variable ( := ) or a recursively expanded variable ( = ) are very different in a rules makefile.

At our example we want the simply expanded variable behaviour.

Shell command output into rules makefile

We want also collect some shell command output into some variables. [21]

There are some misconceptions that you should avoid [27].

        PHP_EXT_DIR := $(shell /usr/bin/php-config --extension-dir)
        PHP_INCLUDE_DIR := $(shell /usr/bin/php-config --include-dir)

Leveraging dpatch

dpatch is a clever development tool.

If you must have to apply some modifications to the upstream code before packaging for Debian, then one of the easiest modes is to use dpatch.

When you execute dpatch in a shell prompt, it opens a session and from now on until you exit the session, all you do will be recorded and converted to a patch for your upstream code into /debian/patches directory.

A good practice is to create small patches with clear, self explanatory and different names. For example, 10_relocate_build , 20_relocate_install, 30_correct_env_variable.

You must read the dpatch man page.

The following code snippet will apply the patches to source, walking through all patches into /debian/patches directory in the ascendant patchnamefile order.

And then stamp the configure step.

configure: patchsource configure-stamp

patchsource: patch-stamp

patch-stamp:
        dpatch apply-all
        dpatch cat-all >patch-stamp

configure-stamp:
        dh_testdir
        phpize
        ./configure --with-java=/usr/lib/jvm/java-1.5.0-sun --prefix=${DESTDIR}
        touch configure-stamp

Cleaning and deapplying patches

You must have a clean rule. Also, if you applied patches, you must deapply them in reverse order.

The dpatch helper will take care of this if you created the patches in a planned naming convention.

clean: clean-patched unpatch

clean-patched:
        dh_testdir
        dh_testroot
        rm -f build-stamp configure-stamp
        -$(MAKE) clean
        dh_clean 

unpatch:
        dpatch deapply-all
        rm -rf patch-stamp debian/patched

Compiling the binaries

The rule calls the "configure" rule and then test if it is at the correct directory for the step and if the /debian/control file exists. Finally, touch the build-stamp file.

build: build-stamp

build-stamp: configure 
        dh_testdir
        $(MAKE)
        #docbook-to-man debian/php-java-bridge.sgml > php-java-bridge.1
        touch $@

The phony targets

You must read the Make Manual, about phony targets [28].

Here, we intend to use them as like "subroutines".

.PHONY: build clean binary-indep binary-arch binary install configure installdocs installbasic installini

The relocatable install

Now we will use the "dirs" file and some inline commands to install into the relocated tree.

The "dirs" file is applicable to the default package, the first target rule. The debhelper dh_installdirs will create the listed directories if they not exist.

usr/bin
usr/sbin
etc/php5/conf.d
var/lib/tomcat5/webapps

Please, note the -k option for dh_clean. It keeps the files between binary packages generations. Study the man page for this and other options.

installbasic: build
        dh_testdir
        dh_testroot
        dh_clean -k 
        dh_installdirs 

install: installbasic
        $(MAKE) install DESTDIR=${DESTDIR}

This "installini" rule will be used to install some files in desired directories.

This rule could be substituded by a suitable "binary_package_name.install" file, used by dh_install.

Note the absence of leading "/" (for relocation) and one per line to avoid jumping to next rule (a debhelper behaviour of this version).

installini:
        dh_install java.ini etc/php5/conf.d
        dh_install mono.ini etc/php5/conf.d

The spliting begins

The compiled code is installed (almost) as the original upstream code intended.

It was sanely relocated.

Now you will distribute the installed files inside the multiple binary packages.

The first binary independent target

/debian/php-java-bridge-j2ee.dirs file

usr/bin
usr/sbin
etc/php5/conf.d
var/lib/tomcat5/webapps

/debian/php-java-bridge-j2ee.docs file

ABOUT.HTM
ChangeLog
COPYING
CREDITS
FAQ.html
INSTALL.J2EE
INSTALL.J2SE
INSTALL.LINUX
INSTALL.MONO+NET
INSTALL.ORACLE
INSTALL.WEBSPHERE
NEWS
PROTOCOL.TXT
README
README.GNU_JAVA
README.MONO+NET
VERSION

/debian/php-java-bridge-j2ee.install file for some file almost moved "by hand" after the make install. You use this file with dh_install instead a mv or cp.

java-servlet.ini etc/php5/conf.d

Note the -p$@ to use target name package files in /debian as parameters. [24]

Note the inline dh_install using dynamic variables referring to some directory configured at the begining of the rule file. [23]

The inline code does not have a leading "/" for relocating.

See how debhelper apps is leveraged, executing the hard detailed work for you.

Also, the /debian/control file must have some special variables for use here. [22] If they are not used, only a warning will be issued. They do not make harm. For sake of future builds, place them on the control file.

php-java-bridge-j2ee: build install

        dh_testdir
        dh_testroot
        dh_installdirs -p$@
        dh_installchangelogs -p$@ ChangeLog
        dh_installdocs -p$@
        dh_install -p$@ ${BUILDDIR}$(PHP_EXT_DIR)/JavaBridge.war var/lib/tomcat5/webapps
        dh_install -p$@
        dh_installman -p$@
        dh_link -p$@
        dh_strip
        dh_compress -p$@
        dh_fixperms -p$@
        dh_installdeb -p$@
        dh_shlibdeps -p$@
        dh_gencontrol -p$@
        dh_md5sums -p$@
        dh_builddeb -p$@

The second binary independent target

/debian/php-java-bridge-devel.docs file

ABOUT.HTM
ChangeLog
COPYING
CREDITS
FAQ.html
INSTALL.J2EE
INSTALL.J2SE
INSTALL.LINUX
INSTALL.MONO+NET
INSTALL.ORACLE
INSTALL.WEBSPHERE
NEWS
PROTOCOL.TXT
README
README.GNU_JAVA
README.MONO+NET
VERSION

/debian/php-java-bridge-devel.examples file for the debhelper placing at the correct directory.

examples
test.php
run-tests.php
security
tests.mono+net
tests.php4
tests.php5
unsupported
server/php/
server/test/
php_java_lib

pitfall-> packages may have "-" in their name. Do not create intermediate (phony) rules with this character or things may go really weird and unexpected (as of april 2007 versions).

See how variables are used at dh_install to point to directories that may be different as different related packages are released (php5).[23], [20]

php-java-bridge-devel: build install
        dh_testdir
        dh_testroot
        dh_installdirs -p$@
        dh_installchangelogs -p$@ ChangeLog
        dh_installdocs -p$@
        dh_installexamples -p$@
        dh_install -p$@ ${BUILDDIR}$(PHP_EXT_DIR)/*.jar $(PHP_INCLUDE_DIR)/ext/php-java-bridge
        dh_installman -p$@
        dh_link -p$@
        dh_strip
        dh_compress -p$@
        dh_fixperms -p$@
        dh_installdeb -p$@
        dh_shlibdeps -p$@
        dh_gencontrol -p$@
        dh_md5sums -p$@
        dh_builddeb -p$@

(to be continued)

External useful links