CREATING MODULE PACKAGES WITH M-A, MINI-HOWTO
---------------------------------------------

Let's look on how we create a module-package with source package, using
module-assistant where possible. 

A sample snapshot of the debian/ directory is located in the
/usr/share/doc/module-assistant/examples/.

To demonstrate the steps to package something from scratch, I will take shfs as
example:

1. Get the upstream source (I had to repack the upstream tarball,
   removing the half-cooked debian/ directory in shfs source, btw.)
2. Run dh_make as usual and select "multiple binary"
3. Edit debian/control and assign proper package names (I rename shfs to
   shfs-utils and shfs-doc to shfs-src and give proper descriptions). Don't
   forget to add debhelper to Depends of the -source package if it is used.
4. Edit debian/rules and substitute the package names to match those in control
5. Adapt or remove the example files in debian/
6. Edit the build-arch-stamp and install-arch rules to build/install
   ONLY the user applications (here: to build only the mount utilities)
7. Edit the build-indep rule to do nothing and the install rule to
   install the package source into a tarball, as following example
   shows. Optionaly, the -utils package can get a control script for
   module-assistant, which is simply the "default.sh" from m-a.

# create needed directories
	dh_installdirs -i usr/src/modules
# only if needed
	dh_installdirs -a usr/share/modass/overrides

# copy the driver source from shfs/ 
	cp -a shfs debian/shfs-source/usr/src/modules/

# copy all relevant debian/ files.
	mkdir debian/shfs-source/usr/src/modules/shfs/debian
	cd debian ; cp changelog control compat *.modules.in rules copyright shfs-source/usr/src/modules/shfs/debian

# entar the source
	cd debian/shfs-source/usr/src/ ; tar -c modules | bzip2 -9 > shfs.tar.bz2 && rm -rf modules

# install the control script, if wished. Not really required for package to be
# processed but helps m-a frontend: puts the package into the list of known
# packages
	ln -s ../packages/default.sh debian/shfs-utils/usr/share/modass/overrides/shfs-source

8. Return to the file header (or some position right before the module specific
   targets begin) and load the m-a includes:

# prefix of the target package name
PACKAGE=shfs-module
# modifieable for experiments or debugging m-a
MA_DIR ?= /usr/share/modass
# load generic variable handling
-include $(MA_DIR)/include/generic.make
# load default rules
-include $(MA_DIR)/include/common-rules.make

8. Complete the module-building routines, adding missig rules:

8.1. Add a cleaning rule

MAJOR=$(shell echo $(KVERS) | sed -e 's/\(...\).*/\1/')
ifeq ($(MAJOR),2.6)
KO=k
endif

kdist_clean:
	dh_clean
	make -C Linux-$(MAJOR) clean

8.2. Add the configuring rule and map the conventional target name to m-a

# prep-deb-files rewrites the debian/ files as needed. See RATIONALE for
# details
kdist_config: prep-deb-files
# ... additional kernel specific things to configure...

kdist_configure: kdist_config

8.2. Create the binary-modules rule, like the following one:

binary-modules: prep-deb-files
	dh_testdir
	dh_testroot
	dh_clean -k
	make -C Linux-$(MAJOR) KERNEL_SOURCES=$(KSRC) MODVERSIONS=detect KERNEL=linux-$(KVERS)
	install -m644 -b -D Linux-$(MAJOR)/shfs.$(KO)o $(CURDIR)/debian/$(PKGNAME)/lib/modules/$(KVERS)/shfs/shfs.$(KO)o
	dh_installdocs
	dh_installchangelogs
	dh_compress
	dh_fixperms
	dh_installdeb
	dh_gencontrol -- -v$(VERSION)
	dh_md5sums
	dh_builddeb --destdir=$(DEB_DESTDIR)

9. Add some hints for the users into README.Debian in both, utils and the
   -source package (the usual blah, blah, suggesting make-kpkg, 
   "m-a a-i thismodule" or similar things)

10. Add a thisPackage-_KVERS_.postinst.modules.in file where you invoke depmod
    (see other examples), restart some daemon, etc.pp.

DONE!













Here is what happens when a package has been ported from old rules files backed
up by dh-make to use module-assistant:

diff -u ipw2100-0.41/debian/control ipw2100-0.41/debian/control
--- ipw2100-0.41/debian/control
+++ ipw2100-0.41/debian/control
@@ -1,19 +1,22 @@
 Source: ipw2100
 Section: net
 Priority: optional
+Build-Depends: debhelper (>> 4.0)
 Maintainer: Sebastian Ley <ley@debian.org>
 Standards-Version: 3.6.1.0
 
 Package: ipw2100-source
 Architecture: all
-Depends: make, hostap-source
+Depends: module-assistant, hostap-source
 Description: Source for the ipw2100 driver.
  This package provides the source code for the ipw2100 kernel modules.
  Intel PRO/Wireless 2100 (IPW2100) mini PCI adapter is a common component
  of Centrino notebooks.
  .
- In order to compile these modules you need the kernel sources. For
- compile instructions look into /usr/share/doc/ipw2100-source/README.Debian.
+ In order to compile these modules you need the kernel sources (or the
+ kernel-headers for the kernel-image packages from Debian). For compile
+ instructions look into /usr/share/doc/ipw2100-source/README.Debian or
+ simply use the module-assistant utility.
  .
  The project's homepage can be found here:
  http://ipw2100.sourceforge.net
diff -u ipw2100-0.41/debian/postinst.modules.in ipw2100-0.41/debian/postinst.modules.in
--- ipw2100-0.41/debian/postinst.modules.in
+++ ipw2100-0.41/debian/postinst.modules.in
@@ -2,5 +2,5 @@
 set -e
 
-if [ "`uname -r`" = ${kpkg:Kernel-Version} ] ; then
+if [ "`uname -r`" = "_KVERS_" ] ; then
    depmod -a &
 fi
diff -u ipw2100-0.41/debian/rules ipw2100-0.41/debian/rules
--- ipw2100-0.41/debian/rules
+++ ipw2100-0.41/debian/rules
@@ -2,19 +2,12 @@
 # -*- makefile -*-
 # Sample debian/rules that uses debhelper. 
 # GNU copyright 1997 by Joey Hess.
-#
-# This version is for a hypothetical package that can build a kernel modules
-# architecture-dependant package via make-kpkg, as well as an
-# architecture-independent module source package, and other packages
-# either dep/indep for things like common files or userspace components
-# needed for the kernel modules.
+
+# simplified to use module-assistant by Eduard Bloch.
 
 # Uncomment this to turn on verbose mode. 
 #export DH_VERBOSE=1
 
-
-
-
 CFLAGS = -Wall -g
 
 ifneq (,$(findstring noopt,$(DEB_BUILD_OPTIONS)))
@@ -26,151 +19,32 @@
 	INSTALL_PROGRAM += -s
 endif
 
-### KERNEL SETUP
-### Setup the stuff needed for making kernel module packages
-### taken from /usr/share/kernel-package/sample.module.rules
-
-# Name of package
-package		= ipw2100
-# KSRC is the location of the kernel source. This is the default value,
-# when make-kpkg is used it will supply to real value
-KSRC		= /usr/src/linux
-# KDREV is the package-revision, as given to make-kpkg by the user.
-# Just put a simply default value in here which we use when we test
-# the packagebuilding without make-kpkg
-ifeq ($(strip $(KDREV)),)
-KDREV		= "test1.0"
-endif
-
-## Now to determine the kernel version, normally supplied by make-kpkg
-ifeq ($(strip $(KVERS)),)
-# Now we need to get the kernel-version somehow (we are not running
-# under make-kpkg?)
-ifeq ($(strip $(KSRC)),)
-$(error Error. I do not know how to determine the kernel version)
-else
-kversion :=$(shell egrep '^VERSION +=' $(KSRC)/Makefile 2>/dev/null | \
-                 sed -e 's/[^0-9]*\([0-9]*\)/\1/')
-kplevel  :=$(shell egrep '^PATCHLEVEL +=' $(KSRC)/Makefile 2>/dev/null | \
-                    sed -e 's/[^0-9]*\([0-9]*\)/\1/')
-ksublevel:=$(shell egrep '^SUBLEVEL +=' $(KSRC)/Makefile 2>/dev/null | \
-                  sed -e 's/[^0-9]*\([0-9]*\)/\1/')
-EXTRA_VERSION:=$(shell egrep '^EXTRAVERSION +=' $(KSRC)/Makefile 2>/dev/null | \
-                 sed -e 's/EXTRAVERSION[\t ]*=[\t ]*\(.*\)/\1/')
-kextra:=$(strip $(EXTRA_VERSION))
-HAVE_NEW_MODLIB:=$(shell egrep '\(INSTALL_MOD_PATH\)' \
-                            $(KSRC)/Makefile 2>/dev/null )
-
-# If you want to have more than one kernel configuration per kernel
-# version, set FLAVOUR in the top level kernel Makefile *before*
-# invoking make-kpkg -- it will be appended to UTS_RELEASE in
-# version.h (separated by a hyphen). This affects everything -- the
-# names and versions of the image, source, headers, and doc packages,
-# and where the modules are searched for in /lib/modules.
-
-ifdef FLAVOUR
-# uhm - should check if we really have a Makefile capable of Flavours?
-endif
-
-FLAVOUR:=$(shell grep ^FLAVOUR $(KSRC)/Makefile 2>/dev/null | \
-                  perl -ple 's/FLAVOUR[\s:=]+//g')
-
-ifneq ($(strip $(FLAVOUR)),)
-INT_FLAV := -$(FLAVOUR)
-FLAV_ARG := FLAVOUR=$(FLAVOUR)
-else
-INT_FLAV :=
-FLAV_ARG :=
-endif
-
-## This is the replacement for FLAVOUR
-ifneq ($(strip $(APPEND_TO_VERSION)),)
-iatv := $(strip $(APPEND_TO_VERSION))
-EXTRAV_ARG := EXTRAVERSION=${EXTRA_VERSION}${iatv}
-else
-iatv :=
-EXTRAV_ARG :=
-endif
-
-KVERS = $(kversion).$(kplevel).$(ksublevel)$(kextra)$(iatv)$(INT_FLAV)
-
-endif
-endif
-
-non_epoch_version=$(shell echo $(KVERS) | perl -pe 's/^\d+://')
-epoch=$(shell echo $(KVERS) | perl -ne 'm/^(\d+:)/ && print $$1')
-
-# We also need the package version
-pversion	= $(shell sed -ne '1s/.*\((.*)\).*/\1/' debian/changelog)
-pversion	= $(shell sed -ne '1s/.*(\(.*\)).*/\1/p' debian/changelog)
-
-# MODDIR is the place where the final .deb package should be made. This is the
-# default value, when make-kpkg is used it will supply to real value
-MODDIR		= ..
-
-pmodules = $(package)-modules-$(non_epoch_version)
-psource = $(package)-source
-
-# Prepares the package for distribution.  Intended for the kernel
-# maintainer.
-kdist: kdist_clean kdist_config kdist_image
-
-# The kdist_configure target is called by make-kpkg modules_config. It
-# should configure the module so it is ready for compilation (mostly
-# useful for calling configure)
-kdist_config:
-	@echo Nothing to configure
-
-# the kdist_image target is called by make-kpkg modules_image. It is
-# responsible for compiling the module and creating the package. It
-# should also clean up after making the module. Please note we use a
-# seperate binary-modules target to make testing the package building
-# easier
-kdist_image:
-	$(MAKE) $(MFLAGS) -f debian/rules binary-modules
-	$(MAKE) $(MFLAGS) -f debian/rules clean
-
-# the kdist_clean target is called by make-kpkg modules_clean. It is
-# responsible for cleaning up any changes that have been made by the
-# other kdist_commands (except for the .deb files created).
-kdist_clean:
-	$(MAKE) $(MFLAGS) -f debian/rules clean
-
-### end  KERNEL SETUP
+PACKAGE=ipw2100-modules
+psource=ipw2100-source
+MA_DIR ?= /usr/share/modass
+-include $(MA_DIR)/include/generic.make
+-include $(MA_DIR)/include/common-rules.make
 
 configure: configure-stamp
 configure-stamp:
-	dh_testdir
-	# Add here commands to configure the package.
-
-	touch configure-stamp
+#	dh_testdir
+#	# Add here commands to configure the package.
+#
+#	touch configure-stamp
 
 
 build-arch: configure-stamp  build-arch-stamp
 build-arch-stamp:
-	dh_testdir
-
-	# Add here command to compile/build the package.
-
-	touch build-arch-stamp
+#	dh_testdir
+#
+#	# Add here command to compile/build the package.
+#
+#	touch build-arch-stamp
 
 # the binary-modules target prepares the $(pmodules) package.
 # It is called by make-kpkg and *not* during a normal build
-binary-modules:
-	export DH_OPTIONS='-p$(pmodules)'
-
-	# Is this needed for setting up a Depends?
-	#echo "kpkg:Package-Version=$(epoch)$(pversion)+$(non_epoch_version)" \
-	#	 >> debian/$(package).substvars
-	echo "kpkg:Kernel-Version=$(non_epoch_version)" > \
-		debian/$(pmodules).substvars
-
-	# The substvars mechanism seems slightly broken, hack to get around it
-	# stolen from the qce-ga package. Yaaaa!
-	sed -e 's/$${kpkg\:Kernel\-Version}/$(non_epoch_version)/' \
-	debian/control.in > debian/control
-	sed -e 's/$${kpkg\:Kernel\-Version}/$(non_epoch_version)/' \
-	debian/postinst.in > debian/postinst
+binary-modules: kdist_config
+	export DH_OPTIONS='-p$(PKGNAME)'
 
 	dh_testdir
 	dh_testroot
@@ -188,27 +62,20 @@
 	dh_installdocs debian/README.firmware
 	dh_installchangelogs
 
-	# We're not using this yet
-	#dh_installmodules
-
 	dh_installdeb
-	#dh_gencontrol -- -v$(epoch)$(pversion)+$(non_epoch_version)+$(KDREV)
-	dh_gencontrol -- -v$(epoch)$(pversion)
+	dh_gencontrol -- -v$(VERSION)
 	dh_md5sums
-	#dh_builddeb --destdir=$(KSRC)/..
-	dh_builddeb --destdir=$(MODDIR)
+	dh_builddeb --destdir=$(DEB_DESTDIR)
 
+# now link some rules with common make-kpkg's and module-assistant's targets
+kdist_config: prep-deb-files
+kdist_configure: kdist_config
+kdist_clean: clean
 
 build-indep:  configure-stamp build-indep-stamp
 build-indep-stamp:
-	dh_testdir
-
-	# Add here command to compile/build the arch indep package.
-	# It's ok not to do anything here, if you don't need to build
-	#  anything for this package.
-	#/usr/bin/docbook-to-man debian/ipw2100.sgml > ipw2100.1
-
-	touch build-indep-stamp
+#	dh_testdir
+#	touch build-indep-stamp
 
 build: build-arch build-indep
 
@@ -238,23 +105,11 @@
 	# Copy only the driver source to the proper location
 	cp $(shell cat debian/driver.files) debian/$(psource)/usr/src/modules/$(package)/driver
 	# Copy the needed debian/ pieces to the proper location
-	cp debian/README.firmware \
-		debian/$(psource)/usr/src/modules/$(package)/debian
-	cp debian/control.modules.in \
-		debian/$(psource)/usr/src/modules/$(package)/debian/control.in
-	cp debian/postinst.modules.in \
-		debian/$(psource)/usr/src/modules/$(package)/debian/postinst.in
-	cp debian/rules \
-		debian/$(psource)/usr/src/modules/$(package)/debian
-	cp debian/changelog \
-		debian/$(psource)/usr/src/modules/$(package)/debian
-	cp debian/copyright \
-		debian/$(psource)/usr/src/modules/$(package)/debian
-	cp debian/compat \
-		debian/$(psource)/usr/src/modules/$(package)/debian
-	cd debian/ipw2100-source/usr/src; \
-		tar czf ipw2100-source.tar.gz modules;\
-		rm -rf modules
+	cp -a debian/README.firmware debian/control debian/*.modules.in* \
+			debian/rules debian/changelog debian/copyright debian/compat \
+	debian/$(psource)/usr/src/modules/$(package)/debian/
+	cd debian/ipw2100-source/usr/src && \
+		tar c modules | gzip -9 > ipw2100-source.tar.gz && rm -rf modules
 	dh_install
 
 # Build architecture-independent files here.
diff -u ipw2100-0.41/debian/changelog ipw2100-0.41/debian/changelog
--- ipw2100-0.41/debian/changelog
+++ ipw2100-0.41/debian/changelog
@@ -1,3 +1,10 @@
+ipw2100 (0.41-2) experimental; urgency=low
+
+  * experimental m-a adaption
+  * debhelper build dependency
+
+ -- Eduard Bloch <blade@debian.org>  Sat, 24 Apr 2004 21:40:49 +0200
+
 ipw2100 (0.41-1) experimental; urgency=low
 
   * Initial Release.
diff -u ipw2100-0.41/debian/control.modules.in ipw2100-0.41/debian/control.modules.in
--- ipw2100-0.41/debian/control.modules.in
+++ ipw2100-0.41/debian/control.modules.in
@@ -5,18 +5,18 @@
 Build-Depends: debhelper (>> 4.0.0), hostap-source
 Standards-Version: 3.6.1.0
 
-Package: ipw2100-modules-${kpkg:Kernel-Version}
+Package: ipw2100-modules-_KVERS_
 Architecture: any
-Depends: hostap-modules-${kpkg:Kernel-Version}, hotplug
+Depends: hostap-modules-_KVERS_, hotplug
 Provides: ipw2100-modules
-Description: ipw2100 modules for Linux (kernel ${kpkg:Kernel-Version}).
+Description: ipw2100 modules for Linux (kernel _KVERS_).
  This package contains the set of loadable kernel modules for the
  Intel PRO/Wireless 2100 (IPW2100) mini PCI adapter, which is a common component
  of Centrino notebooks. Please not that you need additional firmware to use
  this driver. The firmware is freely available, please see 
- /usr/share/doc/ipw2100-modules-${kpkg:Kernel-Version} for details.
+ /usr/share/doc/ipw2100-modules-_KVERS_ for details.
  .
- This package contains the compiled kernel modules for ${kpkg:Kernel-Version}
+ This package contains the compiled kernel modules for _KVERS_
  .
  If you have compiled your own kernel, you will most likely need to build
  your own ipw2100-modules.  The ipw2100-source package has been
diff -u ipw2100-0.41/debian/README.Debian ipw2100-0.41/debian/README.Debian
--- ipw2100-0.41/debian/README.Debian
+++ ipw2100-0.41/debian/README.Debian
@@ -7,6 +7,13 @@
 How to compile the driver
 ------------------------
 
+The easy way:
+
+type "m-a a-i ipw2100" and wait. If something is missing (eg. the kernel
+headers), you will see instructions for the additional steps.
+
+Manual way:
+
 Install prerequisite packages: build-essential, hostap-source,
 kernel-headers-$VERSION, where $VERSION is the version of the kernel
 you want to build the driver for.