Time-stamp: "2025-07-12 18:59:15 tore"

This is the README for the AusweisApp backports available as zip
files at:
https://www.pvv.ntnu.no/~torfer/upload-ausweisapp/

The files in this zip file are unofficial Debian packages of the
German government's eID client AusweisApp version 2.3.2, backported to
bookworm. This backport consists of simple modifications to Debian's
official version in the 'sid' repository. [1]

The types of files included in this zip are: the source files (*.dsc,
*.gz and *.xz) which you can use to build your own deb packages, and
pre-built deb packages for the amd64 architecture and some meta/repo
files (*build*, *.changes, *.debdiff).

This text is a rough sketch of how to build the ausweisapp packages
yourself from source, meant mostly for package build beginners: it
indicates which steps must be taken and how they could be done with
command line examples using the debuild command; it is not a complete
recipe nor the only way to do things. (The source files in this zip
have already been backported, so this README is only about how to
build.)

Building from source:
=====================

If you have the proper Debian build tools installed [2], you may
unpack the source files and from them build Debian packages. Since
this is an unofficial build, you unpack or extract the source files
this way:

   # Create your own folder to build in; the resulting files will end
   # up here (run as normal user):
   mkdir my-build
   cd my-build
   dpkg-source --no-check -x ../ausweisapp2_2.3.2-1~bpo12+1~local1.dsc

A folder 'ausweisapp2-2.3.2' was created which contains the Debian
source files and debian package maintenance files [1], and the file
'ausweisapp2_2.3.2.orig.tar.gz' was copied to your 'my-build' folder.

To build the installation deb packages, you could do this:

   # First you store information of which packages you will
   # need to install in order to build ausweisapp, run as normal
   # user:
   apt -s build-dep ../ausweisapp2_2.3.2-1~bpo12+1~local1.dsc \
     > ausweisapp-build-dependencies.txt

   # Then install the needed build packages, run as root:
   apt build-dep ../ausweisapp2_2.3.2-1~bpo12+1~local1.dsc

   # As normal user, go into the source folder
   cd ausweisapp2-2.3.2
   # There you will see the sub-folder 'debian'.
   # To build, run (as normal user):
   DEB_BUILD_MAINT_OPTIONS=hardening=+all \
     debuild  -v1.26.2-1 \
     --lintian-opts -Xbinaries/spelling -Xdebian/watch/standard

The debuild command above makes reference to the previously officially
released AusweisApp version in bookworm (1.26.2-1). The rest in the
debuild command line makes lintian complain less. [2]
You can also build without lintian, assuming all is perfect:

   DEB_BUILD_MAINT_OPTIONS=hardening=+all debuild --no-lintian -v1.26.2-1

When you are satisfied and done building [4]: Uninstall the build-dep
packages that in 'ausweisapp-build-dependencies.txt' are listed as
needed to build (i.e. simulated as installed and configured), and then
delete the file 'ausweisapp-build-dependencies.txt'.

You may now install the deb package you just built. Run as root:

  gdebi ../ausweisapp_2.3.2-1~bpo12+1~local1_"$(dpkg --print-architecture)".deb

 = = =

If you don't want to build the binary package yourself, you may
install an earlier version (2.0) of AusweisApp from Debian's official
backports repository by adding bookworm-backports to your apt
sources.list (or similar) and install 'ausweisapp' instead of 'ausweisapp2'.

Or if you have an Intel/AMD machine, you may, but probably should not,
install the pre-built amd64 binary that came with this zip file, run as
root:

   gdebi /path-to-where-zip-was-unpacked/ausweisapp_2.3.2-1~bpo12+1~local1_amd64.deb

This deb was built with pbuilder/pdebuild, meaning it was built inside
a chroot and with a build environment approximating a pristine,
official bookworm build environment, documented in the file:

   ausweisapp2_2.3.2-1~bpo12+1~local1_amd64.buildinfo

So this deb package is unlikely tainted by changes I've done to my
own local machine. The build command used inside the pbuilder chroot
corresponded to the debuild command given above. The log file

   ausweisapp2_2.3.2-1~bpo12+1~local1_amd64.build

documents the pbuilder (or pdebuild) build and compilation process.
However, my machine could be infected/hacked, so you should really
build your own deb file. You have been warned.

 = = =

Bug version 2.3.1:
After starting AusweisApp: Under "Help -> Data and logs -> Show system
data" an unreadeble text is presented (you see a blurred horisontal
bar). To see the text, resize the application window until the text is
redrawn.

 = = =

Want to go further? To play around with the AusweisApp SDK, check out:
https://www.ausweisapp.bund.de/sdk/

Footnotes:
==========

[1]
In the source file 'ausweisapp2-2.3.2/debian/changelog' it's
documented what is changed in this backport: which files and why.
You can check the validity of this backport by comparing it with the
source officially released by Debian:

First, download the source from Debian's official sid repository by
adding this line to your /etc/apt/sources.list file:

   deb-src http://deb.debian.org/debian/ sid main

Since packages in 'unstable' get into 'testing' after a while you
might have to add such a line using 'testing' (or, if you prefere,
the distribution code name for 'testing') instead of 'sid'.

Then run, as root:

   # apt update

As normal user download the source package thus:

   apt-get source ausweisapp

Then you comment out (or delete) the new sid-line in /etc/apt/sources.list
and run 'apt update' again. (So that you stay in bookworm.)

Second, compare the files from this official source "package" (from
sid) with the changes done to create the backport (for bookworm) in
this zip file: only these files in the sub-folder 'debian' have been
changed: changelog, rules and control.
You can see all the changes together with the debdiff tool [2] by running:

   debdiff /path-to-apt-get-source-download/ausweisapp2_2.3.2-1.dsc \
     /path-to-where-zip-was-unpacked/ausweisapp2_2.3.2-1~bpo12+1~local1.dsc

Note: My changelog entries are elaborate, so they have bad form (too
much explanation). I wrote them for "normal" people not yet Debian
packaging experts. Read the Debian package maintenance guides on how
to be terse if you want to make your own packages or make changes to
other's packages.


[2]
Packages you might install (run as root):

   apt install devscripts build-essential gdebi

The Debian program gdebi makes it easier to resolve dependencies
during installation of a deb package file stored locally on your
system.
On how to use the debuild command, see chapter "6.3. debuild command":
https://www.debian.org/doc/manuals/maint-guide/build.en.html

Alternatively you could build with dpkg-buildpackage directely, see [3].


[3]
On how to use the dpkg-buildpackage command, see chapter "6.1. Complete
(re)build":
https://www.debian.org/doc/manuals/maint-guide/build.en.html


[4]
Re-building:

* ausweisapp version 2.2.2:
You will be able to rebuild ausweisapp version 2.2.2 with debuild on a
bookworm machine, using the backported source version
2.2.2-1~bpo12+1~local1. You might have do a clean first, with e.g.
'debuild -- clean' or 'dpkg-buildpackage -Tclean'.

* ausweisapp version 2.3.x, using 2.3.1 as an example:
Your first build with debuild, using the backported source version
ausweisapp2_2.3.1-1~bpo12+1~local1, should succeed. If you try to
rebuild, however, that will cause an error. Explanation:

During your first build of ausweisapp version 2.3.1 on bookworm (and
with its QT version 6.4.2), some QML source files are altered by
Debian's packaging system (debhelper), and those changes remain after
the build has finished. In the error message during the re-build
Debian's packaging system suggests you should patch the source "due to
unexpected upstream changes". One could do that.
However, for the purpose of re-building without backporting the source
further, there are workarounds without making such a patch:

Workaround 1: instead of re-building: start afresh by extracting the
source again in an empthy folder (i.e. dpkg-source -x), and you
build with an unaltered source. Such fresh first-builds will succeed
without errors.

Workaround 2: learn how to build using pbuilder/pdebuild. When
building with pbuilder/pdebuild, pbuilder (normally) first copies the
source files afresh into the chroot before the actual building process
begins, so this particular contamination of the source files during
build does not really matter. (With this pbuilder workaround you
sort of automate "Workaround 1".)

More details: When building the ausweisapp 2.3.1 on bookworm (with QT
6.4.2), the Debian debhelper program simply removes the "pragma
ComponentBehavior: Bound" from the *.qml source files under
src/ui/qml/modules/*, which you can see in the *.build log that came
with the zip file for the backport version
2.3.1-1~bpo12+1~local1.
Debian's packaging tool debhelper alters the qml source files during
build of version 2.3.1 due to this Qt bug:
https://bugreports.qt.io/browse/QTBUG-108684.

Are debhelper's changes to QML source files during build fatal, even
if the build succeeds? Potentially. My personal experience: On my own
bookworm machine the GUI of the backported version of AusweisApp 2.3.1
seems to work just as good as the GUI of the backported version of
AusweisApp 2.2.2.
If you don't like debhelper's alterations of qml source files, you may
stick with version 2.2.2 since during its build no source files are
altered by debhelper.

Changes to this README:
=======================
2025-07-12:
    * Added extra info for when Debian's 'stable' distribution is
      about to become 'oldstable', and when backported source was
      taken from Debian 'unstable' rather than 'testing'.
2025-04-29:
    * Minor text improvements, mostly for the benefit of beginners.
2025-04-22:
    * Minor text changes, hopefully more beginner friendly. Fixed
      more typos.
2025-04-12:
    * Added a footnote with workarounds for error during re-building
      of ausweisapp version 2.3.1 with debuild.
    * Fixed some typos in both text and command line examples.
2025-04-10:
    * This text is still only a rough sketch of a build guide: added
      text saying so.
    * Moved text about installing the self-built package till after
      all text about how to build the package and cleaning up after
      building.

This README text file was generated from a common boilerplate text,
adjusted for backporting AusweisApp version 2.3.2 from
Debian 'sid' (or 'unstable' as of 2025-07-12) to Debian 'bookworm'.

Enjoy.
TF