[elbe-devel] [PATCH 5/5] docs: elbe-debianize: Explain alternatives

[Bastian Germann]

Explain alternatives to the `elbe debianize` command and keep it in elbe
for now. This should enable people who still use it to switch to other
means of generating Debian source packages for Linux and U-Boot.

Signed-off-by: Bastian Germann <bage at linutronix.de>
---
 docs/elbe-debianize.txt | 78 ++++++++++++++++++++++++++---------------
 1 file changed, 50 insertions(+), 28 deletions(-)

diff --git a/docs/elbe-debianize.txt b/docs/elbe-debianize.txt
index e9c3ba7299..98507853f6 100644
--- a/docs/elbe-debianize.txt
+++ b/docs/elbe-debianize.txt
@@ -3,44 +3,66 @@ elbe-debianize(1)
 
 NAME
 ----
-elbe-debianize - generate a debianization
+elbe-debianize - How to debianize software
 
 
-SYNOPSIS
---------
-[verse]
-'elbe debianize'
-
 DESCRIPTION
 -----------
-'elbe debianize' generates a 'debian' folder inside e.g. a kernel source tree.
-This contains the information needed to transfer the source into debian source
-and binary packages.
+'elbe debianize' used to be a command that generated a 'debian' directory
+inside a source tree of the Linux kernel, U-Boot, or Barebox. The templates
+that the command used for that directory do not follow Debian's best practices
+and broke for Linux >= 5.16. Therefore, 'elbe debianize' was removed and is no
+longer supported.
+
+In order to package U-Boot, please use the u-boot source package from the Debian
+archive. Modifying it for your target architecture or a vendor source tree
+should be straight-forward.
+
+For Barebox, there is no alternative currently.
+However, Debian bug #900958 asks for a barebox package.
+When that is resolved, please refer to that package.
+
+Linux has a built-in deb-pkg make target for a long time.
+The problem with using it as 'elbe debianize' alternative is that it builds the
+source and binary packages directly after inserting the debian directory into
+the source. To build only the source package, one must set the make variable
+DPKG_FLAGS=-S on the deb-pkg call. Just be sure to configure the kernel so that
+a .config file is available, and to set the variables that are evaluated by the
+script. See this man page's EXAMPLES section.
+After the source package is built, there is one generated file that does not
+belong to an unbuilt debian directory: debian/files. You can usually drop
+debian/arch as well as it is only used while generating the debian directory.
+
+Instead of specifying a specific defconfig the .config will end up being used.
+There is no compiler prefix embedded in debian/rules for cross compilation,
+so you need to specify it while building the package.
+
+This will only generate the source package format that is specified in the
+Linux tree, which is 1.0 for versions < 6.3.
+The resulting kernel image format will be the default for the build architecture
+and the uImage load address is not included in the debian directory but it
+should be derived from some defconfig value if needed.
+
+Several Linux versions will not generate all the Build-Depends that are needed
+to build in a clean environment and you will probably need to fix them manually.
+
 
 EXAMPLES
 --------
-to debianize a stable kernel for an armhf system use the following commands.
+In order to debianize and build a stable kernel for an arm64 system use the
+following commands. Most of the environment and make variables are optional
+but demonstrate the replacements for the 'elbe debianize' fields.
 +
 ------------
 $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
 $ cd linux-stable
-$ elbe debianize
+$ export CROSS_COMPILE=aarch64-linux-gnu-
+$ export DEBEMAIL="`git config user.name` <`git config user.email`>"
+$ export KDEB_CHANGELOG_DIST=unstable
+$ make ARCH=arm64 defconfig
+$ make ARCH=arm64 DPKG_FLAGS=-S KERNELRELEASE=6.2-elbe deb-pkg
+$ rm debian/arch debian/files
 $ git add -f debian
-$ git commit -sm 'add the elbe generated debianization'
+$ git commit -sm 'add the deb-pkg generated debianization'
+$ CC=aarch64-linux-gnu-gcc dpkg-buildpackage -b -aarm64
 ------------
-
-if you selected a cross compiler, the package could be built with
-+
-------------
-$ dpkg-buildpackage -a armhf
-------------
-
-otherwise use 'elbe-pbuilder'
-+
-------------
-$ elbe pbuilder build /var/cache/elbe/<uuid>
-------------
-
-ELBE
-----
-Part of the linkgit:elbe[1] suite
-- 
2.39.2