test: Add Debian 12/13 experiment suite for build

[luckyabsoluter]

Problem:

• We needed a fair and repeatable way to compare build behavior across Debian 12 and Debian 13 Docker environments.
• Previous checks mixed relative verdict logic and did not provide a clean per-image pass/fail matrix.
• Experimental artifacts needed to be grouped in a dedicated location with local documentation and ignore rules.

Actions:

• Added an isolated experiment package under experiments/debian12-13.
• Added Debian 12 and Debian 13 baseline Dockerfiles plus a Debian 13 remediated Dockerfile that pins a known-good toolchain workflow.
• Implemented run-compare.sh to execute the same build workflow per image and report per-case PASS/FAIL with toolchain versions and exit codes.
• Updated the experiment README to describe usage, optional flags, and matrix-style output.
• Added a local .gitignore for experiment artifacts and made the script clean the experiment out/ directory before running.

Result:

• The repository now has a self-contained, fair comparison harness that reports Docker-specific build pass/fail outcomes.
• Debian 13 remediation success can be verified as its own independent case without altering main project docs.
• Experiment files, docs, and ignores are consolidated in one dedicated directory.

Debian 13 docker toolchain fails to link (dangerous relocation), while Debian 12 succeeds

Summary

On this repository, the same build workflow (make binaries) behaves differently by Docker base image:

• Debian 12 (bookworm): build passes
• Debian 13 (trixie): build fails during link stage with relocation/type errors

This is reproducible with isolated experiment files under experiments/debian12-13.

Background

We needed a fair, per-image comparison (same command, same source tree, isolated output dirs).
A matrix script was added to run identical build steps per image and report PASS/FAIL independently.

Relevant experiment files:

• experiments/debian12-13/run-compare.sh
• experiments/debian12-13/Dockerfile.debian12
• experiments/debian12-13/Dockerfile.debian13
• experiments/debian12-13/Dockerfile.debian13-remediated
• experiments/debian12-13/README.md

Environment

• Repo: luckyabsoluter/airbreak-plus
• Docker Desktop / Linux engine
• Build command used inside each image:
  • make binaries BUILD=<case-output-dir>

Reproduction

./experiments/debian12-13/run-compare.sh

Observed Results (per-image)

debian12

• PASS
• toolchain:
  • arm-none-eabi-gcc (15:12.2.rel1-1) 12.2.1 20221205
  • GNU ld (2.40-2+18+b1) 2.40

debian13

• FAIL (exit=2)
• toolchain:
  • arm-none-eabi-gcc (15:14.2.rel1-1) 14.2.1 20241119
  • GNU ld (2.44-3+23+b1) 2.44
• failure occurs while linking common_code.elf

debian13-remediated

• PASS
• toolchain pinned to Debian 12-equivalent versions:
  • gcc 12.2.1, ld 2.40

Key Error Logs (Debian 13 baseline)

arm-none-eabi-ld: (tim_read_tim5): Unknown destination type (ARM/Thumb) in .../common_code.o
.../my_asv.c:47:(.text+0x44): dangerous relocation: unsupported relocation
.../common_code.c:57:(.text+0x1a0): dangerous relocation: unsupported relocation
.../common_code.c:64:(.text+0x1c6): dangerous relocation: unsupported relocation
...
make: *** [Makefile:95: .../common_code.elf] Error 1

Notes

This strongly suggests a toolchain compatibility issue (gcc/binutils/newlib set in Debian 13) rather than source or workflow differences, because:

1. same repository state
2. same build command
3. isolated output dirs
4. only toolchain/version changes across images

Proposed next steps

1. Document officially supported Docker/toolchain baseline (e.g., Debian 12/bookworm toolchain).
2. Optionally pin toolchain versions in official build Dockerfile.
3. Investigate exact linker behavior change between binutils 2.40 and 2.44 for these objects/relocations.

[m-kozlowski]

Can you try adding -m armelf to LD_FLAGS? I think it should fix linking on gcc 14.
EDIT: it's not. I think the proper fix would be to introduce second macro in stubs.S

#define NSTUB_FUNC(addr,name) \
        .global name; \
        .type name, %function; \
        .thumb_func; \
        name = addr

and use it for actual thumb functions

[luckyabsoluter]

@m-kozlowski confirmed

[Asmageddon]

What is this necessary/useful for? Debian packaging?

Is this directly relevant to the project itself?

[luckyabsoluter]

This is not really about Debian packaging, and Debian itself is not the root cause.

What the experiment shows is that the build result changes with the arm-none-eabi toolchain version: the older toolchain links successfully, while the newer GCC/binutils combination fails at link time with Unknown destination type (ARM/Thumb) / dangerous relocation.

I found this while trying to introduce continuous integration testing to this project.

This PR is closer to an issue/reproducer.

The likely root cause is that stubs.S currently defines absolute stub symbols without marking actual callable Thumb entries as function/Thumb symbols. Older binutils accepted or inferred this, but newer binutils is stricter for Thumb-only targets and refuses to guess the destination type.

I think the correct order is:

1. close this experiment PR;
2. make a smaller PR implementing the NSTUB_FUNC approach suggested by m-kozlowski and use it for actual Thumb functions;
3. after the build is fixed, introduce CI on top of that.

The actual fix will probably require changing quite a few stub entries.