[PATCH v4 4/4] doc: add compat/native targets to user manual

[Adriaan Schmidt <adriaan.schmidt@siemens.com>]

Signed-off-by: Adriaan Schmidt <adriaan.schmidt@siemens.com>
---
 RECIPE-API-CHANGELOG.md |  8 ++++++++
 doc/user_manual.md      | 19 ++++++++++++-------
 2 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/RECIPE-API-CHANGELOG.md b/RECIPE-API-CHANGELOG.md
index e48c98c7..b7fc710e 100644
--- a/RECIPE-API-CHANGELOG.md
+++ b/RECIPE-API-CHANGELOG.md
@@ -476,3 +476,11 @@ Bitbake 2.0 for better performance. It also requires isar-sstate script to be
 migrated to zstd.
 Mixing old Gzip-based and new ZStandatd-based sstate cache is not recommended
 and should be avoid for correct compatibility.
+
+### The `compat-arch` override was removed
+
+Recipes inheriting dpkg-base now automatically have a bitbake target
+`<foo>-compat`, if `ISAR_ENABLE_COMPAT_ARCH == "1"`, and if a compat architecture
+exists for the current `DISTRO_ARCH`.
+In that case the compat package can be built by adding `<foo>-compat`
+to `DEPENDS` or `IMAGE_INSTALL`.
diff --git a/doc/user_manual.md b/doc/user_manual.md
index b9a0bb64..3db5eb26 100644
--- a/doc/user_manual.md
+++ b/doc/user_manual.md
@@ -963,18 +963,24 @@ Debian cross-compilation works out of the box. Currently the following build con
 
 Experimental support for riscv64 is available as well.
 
-### Cross-building for a compat architecture
+### Building for a compat and/or native architecture
 
 Some architectures, under Isar amd64 and arm64 so far, support running 32-bit
 legacy applications on 64-bit kernels. Debian supports this via the multiarch
 concept.
 
 Isar can build 32-bit packages as part of a 64-bit image build and also enable
-the image with the necessary packages. To activate the compat mode of a build,
-set `ISAR_ENABLE_COMPAT_ARCH = "1"` in `local.conf`. Packages that shall be
-built for the compat arch need to be tagged individually by setting
-`PACKAGE_ARCH = "${COMPAT_DISTRO_ARCH}"` in the package recipe. Non-tagged
-packages will continue to be built for the primary target architecture.
+the image with the necessary packages. To activate compat support,
+set `ISAR_ENABLE_COMPAT_ARCH = "1"` in `local.conf`. This will install neccessary
+build dependencies in the buildchroot.
+
+For all dpkg package recipes, Isar automatically provides a `<package>-compat`
+target that builds the package for the `COMPAT_DISTRO_ARCH`. This can be
+referenced using the `DEPENDS` and `IMAGE_INSTALL` variables.
+
+To explicitly build a package for the build host architecture (in cross build
+scenarios, or when generating an SDK), Isar automatically provides a
+`<package>-native` target for all dpkg package recipes.
 
 ### Cross Support for Imagers
 
@@ -987,7 +993,6 @@ In case your setup does not support cross-imaging, you can disable this
 just for the particular image by adding `ISAR_CROSS_COMPILE = "0"` to your
 image recipe.
 
-
 ## Examining and debugging package generation inside their buildchroot
 
 Just like OpenEmbedded, Isar supports a devshell target for all dpkg package
-- 
2.30.2