#!/usr/bin/make -f
#
# source:
#   /var/cvs/projects/debian/dpkg.common/rules,v
#
# revision:
#   @(#) rules,v 1.20 1999/04/02 19:30:51 jplejacq Exp
#
# copyright:
#   Copyright (C) 1999 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|distclean|check]
#
# description:
#   Package building program 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 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>_<version>.orig.tar.gz
#       <source>-<version>/
#         debian/
#           dpkg.common/
#             get_option_dopackages
#             get_option_tmpdir
#             get_packages
#
#             build
#             check
#             clean
#             installcontrol
#             installdirs
#             installfiles
#             installowners
#             installsrc
#             modifydpkg
#             modifysrc
#             rules
#             rules_var.mk
#             substfiles
#           dpkg.scripts/
#             build
#             check
#             clean
#             installcontrol
#             installdirs
#             installfiles
#             installowners
#             installsrc
#             modifydpkg
#             modifysrc
#             rules
#             rules_var.mk
#             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 debian subdirectory contains three
#     directories.  The "dpkg.common" directory contains files that are shared
#     among all the Debian packages I maintain.  The first three files, "get*",
#     implement several debhelper routines that are no longer available as
#     shell programs.  The remaining files are used to build the package and do
#     not become part of the final binary packages and are package independent.
#     The "dpkg.scripts" directory contains files that override these second
#     set of files in "dpkg.common" for package specific building.  The
#     "dpkg.src" directory contains files that are added to the upstream source
#     to form the final binary packages.
#
#   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 directories dpkg.common and 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".
#
#     The rules file thus defines a standard build procedure and delegates to
#     the programs the details of each step of the process.  The standard steps
#     are defined by the second set of files in dpkg.common and the rules file
#     only knows about these.  These files can delegate to overriding files in
#     dpkg.scripts by simply providing a file with the same name in that
#     directory.
#
#     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:
#
#       1. Setup for operation with dpkg-buildpackage (only needs to
#          be done when first checking out from CVS).
#
#          $ debian/dpkg.common/rules set-scheme-standard
#
#          or
#
#          $ debian/dpkg.common/rules set-scheme-opt
#
#          This second command setups for building binary packages for "/opt"
#          directory layout (This does not follow the normal Debian directory
#          hierarchy but does follow the FHS standard).
#
#       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 distclean
#
#   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>_<version>.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.common/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".
#     These all have the suffix "*.in".  The file "dpkg.scripts/substfiles"
#     defines the directories for the alternate layouts.  The file
#     "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.
#
#     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:
#   I have enable a check for root using dh_testroot in all the makefile
#   targets documented in the debian packaging modules.  This forces you to be
#   root when executing rules for certain target.  This prevents use of super
#   but does work fine with fakeroot.
#
#   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 %,%.stamp-build,$(rules_pkgs))\
		debian/changelog\
		debian/control\
		debian/copyright


  binary: binary-indep binary-arch


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


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


  get-orig-source: debian/changelog debian/control dpkg.stamp-modify
	dh_testdir
	debian/dpkg.common/installsrc


  #
  # Remove generated files.
  #
  clean:
	dh_testdir
	dh_testroot
	debian/dpkg.common/clean



# non-standard public interface:
  #
  # Set build process to use /opt directory layout.
  #
  # The standard debian tools expect to see the files debian/rules and
  # debian/changelog.  This target prepares these files.  Cannot use dh_testdir
  # here since it looks for debian/control.
  #
  set-scheme-opt: debian/rules debian/changelog
	dh_testdir
	rm -f scheme-*
	touch scheme-opt


  #
  # Set build process to use normal directory layout.
  #
  # The standard debian tools expect to see the files debian/rules and
  # debian/changelog.  This target prepares these files.
  #
  # I cannot use dh_testdir here since it looks for debian/control.
  #
  set-scheme-standard: debian/rules debian/changelog
	dh_testdir
	rm -f scheme-*
	touch scheme-standard


  #
  # Remove all files and links that are not source controlled with CVS.
  #
  distclean: clean
	dh_testdir
	-rm -f debian/rules
	-rm -f debian/changelog
	-rm -f debian/control
	-rm -f debian/copyright
	-rm -f scheme-*
	-rm -f ../*.deb ../*.dsc ../*.changes ../*.diff.gz


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



# private interface:
  debian/rules: debian/dpkg.common/rules
	cp "$(<)" "$(@)"

  debian/changelog: debian/dpkg.src/changelog
	cp "$(<)" "$(@)"

  debian/control: debian/dpkg.src/control
	cp "$(<)" "$(@)"

  debian/copyright: debian/dpkg.src/copyright
	cp "$(<)" "$(@)"



  #
  # Check target for each binary package.
  #
  $(patsubst %,%.stamp-check,$(rules_pkgs)): %.stamp-check: %.stamp-binary
	dh_testdir
	debian/dpkg.common/check -p$(rules_pkg) -P$(rules_tmpdir)
	touch $(@)


  #
  # Binary target for each binary package.
  #
  $(patsubst %,%.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.common/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 %,%.stamp-build,$(rules_pkgs)): %.stamp-build: %.stamp-modify
	dh_testdir
	@echo "rules: build: configuring and compiling package..."
	  debian/dpkg.common/build -p$(rules_pkg) -P$(rules_tmpdir)
	@echo "rules: build: creating package directory hierarchy..."
	  debian/dpkg.common/installdirs -p$(rules_pkg) -P$(rules_tmpdir)
	@echo "rules: build: copying package files..."
	  debian/dpkg.common/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.common/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 %,%.stamp-modify,$(rules_pkgs)): dpkg.stamp-modify
	dh_testdir
	debian/dpkg.common/modifysrc -p$(rules_pkg)
	touch $(@)


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


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