aboutsummaryrefslogtreecommitdiff
path: root/debian/librules-manual.txt
diff options
context:
space:
mode:
Diffstat (limited to 'debian/librules-manual.txt')
-rw-r--r--debian/librules-manual.txt116
1 files changed, 116 insertions, 0 deletions
diff --git a/debian/librules-manual.txt b/debian/librules-manual.txt
new file mode 100644
index 0000000..5ddb48a
--- /dev/null
+++ b/debian/librules-manual.txt
@@ -0,0 +1,116 @@
+Manual for the librules helper -*- Text -*-
+------------------------------
+$Id$
+
+This file documents an experimental new debian/rules helper, a
+makefile called "librules.mk", which does all the boring work of
+building a package.
+
+Usage:
+
+The very first non-comment thing in your debian/rules should be the
+following line:
+librules_interface = 1
+This helps to spot incompatibilities with debian/rules and the
+librules.mk file currently in use.
+
+Include "debian/librules.mk" just after that line. Precede it with a
+variable definition "librules_native_pkg=yes" if the package you are building
+is a Debian native package.
+
+Define a target debian/stamp/build that builds the package (like the
+build target does in conventional debian/rules files). Put "touch $@"
+as the last action in that rule.
+
+For every binary package <package> you want to build:
+
+ - If the package is "arch: all", make debian/stamp/binary/indep depend
+ on debian/stamp/binary/<package>; otherwise make debian/stamp/binary/arch
+ depend on that target
+
+ - Write a target debian/stamp/binary/<package> using the following template:
+
+debian/stamp/binary/<package>: package=<package>
+debian/stamp/binary/<package>: debian/stamp/build
+ $(prebinary)
+ # Add here your own commands
+ $(postbinary)
+ touch $@
+
+ The $(prebinary) macro will create a skeletal build tree for the
+ package. It also installs debian/prerm.<package> and
+ debian/postinst.<package> as the prerm and postinst scripts;
+ it will also install the copyright file (debian/copyright)
+ and the Debian changelog file (debian/changelog).
+
+ See below for instructions about how to write your own install commands.
+
+ The $(postbinary) macro fixes directory permissions, generates the binary
+ control file and builds the package.
+
+ - You may want to define targets "clean", "clean-binary" and "clean-build"
+ to reverse the effects of your own commands in the build and binary targets.
+ The librules.mk file cleans up for itself, you don't need to worry about that.
+
+
+How to write your own commands for binary targets:
+
+Use the following macros to install files:
+
+ $(install_exec) SOURCE TARGET
+ $(install_exec) SOURCE SOURCE ... DIRECTORY
+ installs one or more binary executables
+ (TARGET need not be a directory name)
+
+ $(install_nonex) SOURCE TARGET
+ $(install_nonex) SOURCE SOURCE ... DIRECTORY
+ install one or more non-executable files
+ (TARGET need not be a directory name)
+
+ $(install_dir) DIRECTORY
+ create the directory
+
+ $(install_script) SOURCE TARGET
+ $(install_script) SOURCE SOURCE ... DIRECTORY
+ install one or more executable scripts
+ (TARGET need not be a directory name)
+
+The macros above are wrappers around the "install" utility.
+
+ $(install_symlink) SOURCE [TARGET]
+ Install a symlink from SOURCE to TARGET
+ (This macro is a wrapper around ln -s)
+
+ $(gzip) FILE ...
+ Compress the given files
+ (This is a wrapper around gzip)
+
+ $(strip_lib) FILE ...
+ Strip the given files the way shared libraries are stripped
+ (This is a wrapper around strip)
+
+
+*Never* refer to a file in the install target tree by their real name.
+Use the following macros instead:
+
+ $(rootdir) - the directory that masquerades as / in the target tree
+ (usually a subdirectory under debian/tmp)
+ $(ctldir) - the directory where control files are installed
+ (usually $(rootdir)/DEBIAN)
+ $(bindir) - the main binary directory
+ (usually $(rootdir)/usr/bin)
+ $(docdir) - the main doc directory
+ (usually $(rootdir)/usr/share/doc/<package>)
+ ...
+(see librules.mk for what's available)
+
+
+If your debian/rules needs the dpkg-architecture variables, add the
+definition "librules_need_archvars=yes" before the include at the top
+of the file. If you use this feature, you need to Build-Depend on
+"dpkg-dev (>= 1.4.1.5)".
+
+If you want to patch/unpatch the package, add the definitions
+"librules_patch_support=yes" and "librules_patches=file1.diff
+file2.diff ... filen.diff" before the include at the top of the file.
+If you use this, you need to Build-Depend on "patch".