README.source: Document the various makefiles and use of out-of-tree builds

debian/README.source

@@ -253,3 +253,26 @@ Several build profiles are understood and supported:
   with nopython as the build-dependencies will be unsatisfiable otherwise.
 - nopython: Disable Python bindings.  This currently disables building the
   linux-perf-<version> package, as the perf program embeds Python.
+
+Build rules
+===========
+
+The Debian build rules are split across multiple makefiles:
+
+- debian/rules: Standard top-level makefile for Debian package build.
+- debian/rules.gen: Intermediate makefile between debian/rules and
+  debian/rules.real.  This is generated by gencontrol.py based on
+  the configuration under debian/config.
+- debian/rules.real: Makefile for building a single kernel flavour
+  or other group of binary packages.
+- debian/rules.d: Makefiles for building userland code from specific
+  source directories.  The directory structure mirrors the kernel
+  source directories.  debian/rules.real uses the "make-tools" to
+  invoke these makefiles.
+
+All builds *must* be done out-of-tree in a subdirectory of
+debian/build, so that the output files do not end up in the
+linux-source-<version> binary package.  Currently kernel builds use
+debian/build/build_<arch>_<featureset>_<flavour>, userland code uses
+debian/build/build-tools/<source-dir> and documentation uses
+debian/build/build-doc.

debian/changelog

@@ -5,6 +5,7 @@ linux (4.19.37-4) UNRELEASED; urgency=medium
     - libbpf: Use only 2 components in soversion, matching package name
       (Closes: #929187)
     - libbpf: Build out-of-tree
+  * README.source: Document the various makefiles and use of out-of-tree builds
 
  -- Ben Hutchings <ben@decadent.org.uk>  Sun, 19 May 2019 00:04:16 +0100