#!/usr/bin/make -f
#
# source:
#   $Source: /var/cvs/projects/debian/dpkg.common/rules,v $
#
# revision:
#   @(#) $Id: rules,v 1.14 1998/06/06 18:43:17 jplejacq Exp $
#
# copyright:
#   Copyright (C) 1998 Jean Pierre LeJacq <jplejacq@quoininc.com>
#
#   Distributed under the GNU GENERAL PUBLIC LICENSE.
#
# synopsis:
#   rules [build|binary|binary-indep|binary-arch|get-orig-source|clean]
#   rules [set-scheme-opt|set-scheme-standard|set-links|clean_dist|check]
#
# description:
#   Package building script for package.
#
#   The first synopsis shows the standard Debian package building makefile
#   targets.  The second synopsis shows my own target extensions to add extra
#   capabilities.  Generally, you will not have to use the second set of
#   targets.
#
#   I've organized this package a little differently than most Debian packages
#   to hopefully simplify building and maintaining packages.  It is fully
#   compatible with dpkg-buildpackage and abides by both the Debian policy and
#   packaging manuals.  While this package uses many components of debhelper it
#   is not fully compatible with it.  The rest of this comments describe the
#   basic architecture.
#
#   I had several goals for packaging beyond compatibility with the
#   Debian standard:
#     * Installation in either the standard directory hierarchy or an
#       alternative.  Currently, the only supported alternative is the
#       /opt hierarchy.
#     * Localize all edits to upstream original source in a single
#       script.
#     * Support multiple packages from source.
#     * Minimize need for super user access.
#     * Reuse of packaging building components across packages.  Use
#       of debhelper is one example of this.
#     * Source control of packaging files with CVS.
#
#   These goals are met by defining a number of parameterized scripts which
#   modify both the upstream sources and Debian added files.  The parameters
#   that define the files and directories are defined in a file
#   dpkg.common/substfiles and dpkg.scripts/substfiles.
#
#   debian packaging architecture:
#     I use CVS to source control the packaging scripts and files used to build
#     the package.  Many of the files are reused across different packages and
#     I use CVS's module facility to automatically provide reuse.  After
#     checkout, the directory hierarchy for the project looks like:
#
#       <source>.orig.tar.gz
#       <source>-<version>/
#         debian/
#           dpkg.common/
#             check
#             clean
#             installcontrol.in
#             installsrc.in
#             modifydpkg
#             rules
#             rules_var.mk
#             substfiles
#           dpkg.scripts/
#             build.in
#             installdirs.in
#             installfiles.in
#             installowners.in
#             modifysrc
#             substfiles
#           dpgk.src/
#             changelog
#             control
#             copyright.in
#
#     The topmost directory is given the name of the package source name and
#     version number.  At the same level is the original pristine upstream
#     source files in tar.gz format.  The directory contains three directories.
#     The "dpkg.common" directory contains files that are shared among all the
#     Debian packages I maintain.  The "dpkg.scripts" directory contains files
#     that are used to build the package and do not become part of the final
#     binary packages. The "dpkg.src" directory contains files that are added
#     to the upstream source to form the final binary packages.  I've shown
#     several files in each directory that are commonly used across my Debian
#     packages.
#
#     The following files in dpkg.common can be overridden by providing a file
#     with the same name in dpkg.scripts when a package needs to override the
#     default behavior defined.
#       check
#       clean
#       modifydpkg
#       installcontrol.in
#       installsrc.in
#
#   build process:
#     Notice that the "rules" file (which you are reading now) is package
#     independent. This was achieved by moving all of the real work into the
#     programs in the directory dpkg.scripts and using some advanced features
#     of GNU make.  The rules files provides a framework for building packages
#     by defining the processes and their execution order. It was designed to
#     work with dpkg-buildpackage with the "-r" option to gain root access.
#     I've successfully used both "super" and "fakeroot" with this architecture
#     and recommend "fakeroot".
#
#     When first checked out of the CVS repository, one additional step must be
#     done before using dpkg_buildpackage.  Similarly, before checking into
#     the CVS repository, one additional step must be taken after the normal
#     "clean" target.  After moving to the the top most directory, the total
#     steps are:
#
#       0. Setup for operation with dpkg-buildpackage (only needs to
#          be done when first checking out from CVS).
#
#          $ debian/dpkg.common/rules set-links
#
#       1. Optionally, setup for building binary packages for "/opt"
#          directory layout (This does not follow the normal Debian directory
#          hierarchy but does follow the FHS standard).
#
#          $ debian/rules set-scheme-opt
#
#       2. Optionally, download original source.
#
#          $ debian/rules get-orig-source
#
#       3. Build all binary and source packages.
#
#          $ dpkg-buildpackage -rfakeroot
#
#       4. Optionally, check the binary packages.  Currently, this
#          uses lintian and the weblint and nsgmls tools for HTML page
#          validation.  It also checks that no parameterization
#          variables remain in the binary packages.
#
#          $ debian/rules check
#
#       5. Optionally, clean build directories.
#
#          $ fakeroot debian/rules clean
#
#       6. Optionally, remove all non-source controlled files (only
#          needs to be done when committing into CVS).
#
#          $ fakeroot debian/rules clean_dist
#
#   packages:
#     The "rules" file is designed to work with Debian packages that
#     produce both single and multiple binary packages.  It achieves
#     this by using several debhelper programs to define several make
#     macros defined in the file "rules_var.mk".  After a complete
#     build the directory hierarchy looks like:
#
#      <source>.orig.tar.gz
#      <source>-<version>/
#        debian/
#          dpkg.common/
#          dpkg.scripts/
#          dpgk.src/
#          <package>.src/
#          <package>.tmp/
#
#     For each binary package a "<package>.src" directory is created
#     which contains the original source code modified by the file
#     "dpkg.scripts/modifysrc".  The final build directory for each
#     package is "<package>.tmp".
#
#   target directory hierarchy:
#     I've designed this package to be built for either installation
#     in the normal directory hierarchy or the /opt directory.  If the
#     make target "set-scheme-opt" is executed before building, the
#     /opt directory hierarchy is used.  The ability to support
#     multiple target directory hierarchies was achieved by
#     parameterizing the files in the "dpkg.src" and "dpkg.scripts".
#     These all have the suffix "*.in".  The file
#     "dpkg.scripts/substfiles" defines the directories for the
#     alternate layouts.  The files "dpkg.scripts/modifydpkg" and
#     "dpkg.scripts/modifysrc" replace all occurrences of
#     "@@variable@@" with the variables defined in substfiles.
#
#   building as normal user:
#     This program can be executed without root privilege except for the
#     following commands:
#       * chown
#       * chmod   Not always necessary, only if there is a sgid file
#                 that gets reset when the ownership is changed.
#       * tar     Not always necessary, only if file not readable by
#                 the package builder.
#       *         Any others?
#
#     The basic strategy is to build as much as possible before changing the
#     ownership from the builder to the final installed ownership.  This
#     prevents possible damage when building the package.  It also enables the
#     package to be built by the real maintainer with the resulting packages
#     pgp signed with the maintainer's real key.
#
#     I have enable a check for root using dh_testroot in all the makefile
#     targets documented in the debian packaging modules.
#
#     To enable these commands, you can use super with the "-r" option of
#     dpkg-buildpackage.  I create an entry in /etc/super.tab for
#     "debian/rules" and then protected each of the required makefile targets
#     with a call to dh_testroot.  The entry in /etc/super.tab must be an
#     absolute path to debian/rules which causes a problem when trying to
#     support multiple projects.  I solve this by always building Debian
#     projects in a set directory and use a symbolic link showing which project
#     I'm currently building.  The entry in /etc/super.tab then refers to this
#     symbolic link.  Notice that the directory containing this link should be
#     carefully protected to prevent security problems.
#
#       /home/jplejacq/projects/debian
#         drwxrws---   4 jplejacq develop  .
#         drwxrwxr-x  15 jplejacq jplejacq ..
#         drwxrwxr-x   4 jplejacq develop  cracklib
#         lrwxrwxrwx   1 jplejacq develop  current -> cracklib/
#         drwxrwxr-x   4 jplejacq develop  printop
#
#     Alternatively, you can use the fakeroot package.  This doesn't execute as
#     root at all and is therefore safer.  I recommend this approach though
#     there does seem to be problem when building on an NFS mounted directory.
#
# bugs:
#   dh_makeshlibs and dh_md5sums should not require root privileges
#   and therefore should be in the debian/build target.


include debian/dpkg.common/rules_var.mk


# public interface:
  build: $(patsubst %,debian/%.stamp-build,$(rules_pkgs))


  binary: binary-indep binary-arch


  binary-indep: $(patsubst %,debian/%.stamp-binary,$(rules_pkgs_indep))


  binary-arch: $(patsubst %,debian/%.stamp-binary,$(rules_pkgs_arch))


  get-orig-source: debian/dpkg.stamp-modify
	dh_testdir
	debian/dpkg.scripts/installsrc


  clean:
	dh_testdir
	dh_testroot
	debian/dpkg.scripts/clean



# non-standard public interface:
  #
  # Set build process to use /opt directory layout.
  #
  set-scheme-opt:
	dh_testdir
	rm -f debian/scheme-*
	touch debian/scheme-opt


  #
  # Set build process to use normal directory layout.
  #
  set-scheme-standard:
	dh_testdir
	rm -f debian/scheme-*
	touch debian/scheme-standard


  #
  # Create symbolic links so that standard debian packaging tools can
  # find required files. Only create link if package doesn't override
  # standard scripts.  Cannot use dh_testdir here since it looks for
  # debian/control.
  #
  set-links:
	ln -f -s dpkg.common/rules debian
	ln -f -s dpkg.src/changelog debian
	ln -f -s dpkg.src/control debian
	ln -f -s dpkg.src/copyright debian
	-(test -f debian/dpkg.src/shlibs.in &&\
	  ln -f -s dpkg.src/shlibs debian)
	-(test ! -f debian/dpkg.scripts/clean &&\
	  ln -f -s ../dpkg.common/clean debian/dpkg.scripts)
	-(test ! -f debian/dpkg.scripts/modifydpkg &&\
	  ln -f -s ../dpkg.common/modifydpkg debian/dpkg.scripts)
	-(test ! -f debian/dpkg.scripts/check.in &&\
	  ln -f -s ../dpkg.common/check.in debian/dpkg.scripts)
	-(test ! -f debian/dpkg.scripts/installcontrol.in &&\
	  ln -f -s ../dpkg.common/installcontrol.in debian/dpkg.scripts)
	-(test ! -f debian/dpkg.scripts/installsrc.in &&\
	  ln -f -s ../dpkg.common/installsrc.in debian/dpkg.scripts)



  #
  # Remove all files and links that are not source controlled with CVS.
  #
  clean_dist: clean
	dh_testdir
	-rm -f debian/scheme-*
	-rm -f debian/rules
	-rm -f debian/changelog
	-rm -f debian/control
	-rm -f debian/copyright
	-rm -f debian/shlibs
	-(test -L debian/dpkg.scripts/clean &&\
	  rm -f debian/dpkg.scripts/clean)
	-(test -L debian/dpkg.scripts/modifydpkg &&\
	  rm -f debian/dpkg.scripts/modifydpkg)
	-(test -L debian/dpkg.scripts/check.in &&\
	  rm -f debian/dpkg.scripts/check.in)
	-(test -L debian/dpkg.scripts/installcontrol.in &&\
	  rm -f debian/dpkg.scripts/installcontrol.in)
	-(test -L debian/dpkg.scripts/installsrc.in &&\
	  rm -f debian/dpkg.scripts/installsrc.in)
	-rm -f ../*.deb ../*.dsc ../*.changes ../*.tar.gz


   #
   # Check all binary packages.
   #
   check: $(patsubst %,debian/%.stamp-check,$(rules_pkgs))



# private interface:
  #
  # Check target for each binary package.
  #
  $(patsubst %,debian/%.stamp-check,$(rules_pkgs)):\
	  %.stamp-check : %.stamp-binary
	dh_testdir
	@echo "rules: check: checking package..."
	  debian/dpkg.scripts/check -p$(rules_pkg) -P$(rules_tmpdir)
	touch $(@)


  #
  # Binary target for each binary package.
  #
  $(patsubst %,debian/%.stamp-binary,$(rules_pkgs)):\
	  %.stamp-binary : %.stamp-build
	dh_testdir
	dh_testroot
	@echo "rules: binary: generating shlib..."
	  (umask 022 && dh_makeshlibs -p$(rules_pkg) -P$(rules_tmpdir))
	@echo "rules: binary: generating md5 checksums..."
	  (umask 022 && dh_md5sums -p$(rules_pkg) -P$(rules_tmpdir))
	@echo "rules: binary: setting ownership..."
	  debian/dpkg.scripts/installowners -p$(rules_pkg) -P$(rules_tmpdir)
	@echo "rules: binary: building binary package..."
	  dh_builddeb -p$(rules_pkg) -P$(rules_tmpdir)
	touch $(@)


  #
  # Build target for each binary package.
  #
  $(patsubst %,debian/%.stamp-build,$(rules_pkgs)):\
	  %.stamp-build : %.stamp-modify
	dh_testdir
	@echo "rules: build: configuring and compiling package..."
	  debian/dpkg.scripts/build -p$(rules_pkg) -P$(rules_tmpdir)
	@echo "rules: build: creating package directory hierarchy..."
	  debian/dpkg.scripts/installdirs -p$(rules_pkg) -P$(rules_tmpdir)
	@echo "rules: build: copying package files..."
	  debian/dpkg.scripts/installfiles -p$(rules_pkg) -P$(rules_tmpdir)
	@echo "rules: build: stripping binaries and libraries..."
	  dh_strip -p$(rules_pkg) -P$(rules_tmpdir)
	@echo "rules: build: creating debian control directory..."
	  debian/dpkg.scripts/installcontrol -p$(rules_pkg) -P$(rules_tmpdir)
	@echo "rules: build: calculate shared library dependencies..."
	  dh_shlibdeps -p$(rules_pkg) -P$(rules_tmpdir)
	@echo "rules: build: generating package control file..."
	  (umask 022 && dpkg-gencontrol -p$(rules_pkg) -P$(rules_tmpdir))
	touch $(@)


  #
  # Source modification target for each binary package.
  #
  $(patsubst %,debian/%.stamp-modify,$(rules_pkgs)): debian/dpkg.stamp-modify
	dh_testdir
	debian/dpkg.scripts/modifysrc -p$(rules_pkg) -P$(rules_tmpdir)
	touch $(@)


  #
  # Debian package file modification target for source package.
  #
  debian/dpkg.stamp-modify: debian/dpkg.scripts/modifydpkg
	dh_testdir
	debian/dpkg.scripts/modifydpkg
	touch $(@)


  .PHONY: build binary binary-arch binary-indep clean get-orig-source
  .PHONY: set-scheme-opt set-scheme-standard set-links clean_dist check