The GNU Binutils run on an "host" architecture and manipulate binary objects intended for later execution on a "target" architecture. Most combinations of supported Debian architectures are built from the binutils source package and extensively documented elsewhere.

This page collects informal suggestions and advices for packagers of the tools for less common "targets" with specific requirements. Usually, "host" is a desktop computer manipulating programs that will eventually be executed on an embedded "target" device with limited resources.

Scope

The following command should list packages with similar concerns.

   1 aptitude search '~n^binutils- !~n-dbg$ !~e^binutils$ !~v' -F%e | uniq

For each result, the best source of information is usually "https://tracker.debian.org/pkg/PACKAGE".

The bpf, or1k-elf and sh-elf targets implement the recipes given in this page, so you may want to look at their sources, here for example.

Package names

For Debian architectures, the binary package is named binutils-TARGET_GNU_TYPE, with underscores replaced with dashes. New packages should follow this convention for consistency.

The source package should a priori have the same name.

Source package

Despite deriving from the same code base, the source packages for different targets should be separate Debian source packages. If a single source package were to produce binary packages for different targets, a release-critical bug affecting one target would get all targets removed from a Debian release. Maintainers of other targets are usually not in position to investigate because they do not own the specific hardware.

In order to share the upstream code, Debian patches and build system via the usual Build-Depends mechanism, the binutils source package distributes its own source in the binutils-source binary package.

If possible, the source package should be native (in the sense that debian/source/format should contain 3.0 (native)) and Build-Depend on binutils-source. This option requires that the target keeps up with binutils development, and is always buildable using whatever the current version of binutils-source is.

If this assumption seems unrealistic, for example when the hardware vendor applies lots of patches and refreshes them unfrequently, a non-native package with an ad-hoc .orig tarball may be preferable.

Debian control file

Ideally, a paragraph of the long description should describe binutils generally and be identical in all similar binary packages, as this reduces the burden for translators.

On multiarch systems, triplet-prefixed tools should generally be marked "Multiarch: foreign" (see this bug for example). This means that the interface the package exposes, when used as a build-dependency, is not architecture-dependent, and that any architecture's binutils-TARGET package may be used to satisfy the dependency when several are available. However, additional constraints may apply (to gcc for example).

Binary package layout

Executable commands

Each TOOL (e.g. ld or strings) must be installed as /usr/bin/TARGET_GNU_TYPE-TOOL.

However, existing scripts often search the unprefixed name under the traditional usr/TARGET_GNU_TYPE/bin directory, so a symbolic link should make /usr/bin/TARGET_GNU_TYPE-TOOL available as /usr/TARGET_GNU_TYPE/bin/TOOL.

When the target is a full Debian architecture, the multiarch layout (/usr/lib/<multiarch triplet>/...) is used instead, but this is another story.

Dynamic linker scripts

if any, should be installed in /usr/lib/TARGET_MULTIARCH/ldscripts/*.

Private libraries

The upstream system links the tools statically.

The Debian build system links tools dynamically with private libraries within the same package (namely, /usr/lib/HOST_MULTIARCH/lib{bfd,ctf}*TARGET*.so*).

For less common targets, the difference is small and the choice is mostly a matter of convenience.

Manual pages and translations

The manpage for TARGET_GNU_TYPE-TOOL may be identical to the one for TOOL in binutils-common.

The binary package may Depend on binutils-common and make /usr/share/man/man1/TOOL.1.gz available as a /usr/share/man/man1/TARGET_GNU_TYPE-TOOL.1.gz symbolic link.

The dependency must not require a specific version, else each upload of binutils would have to wait for all packagers of niche targets. Anyhow, this would not help much as the list of tools rarely changes.

The manual pages are small, so duplicating the contents is perfectly valid if more convenient.

Non-native packages must provide license information for the source version and patches they rely upon, and maintain a file largely redundant with the one from binutils-common.

Native packages must only describe the license of the packaging work, but must add a "Built-Using" dependency in debian/control, so that the Debian archive keeps the exact sources available alongside the executable as required by the binutils license.

If you want to generate a copyright file containing the binutils-source copyright, see binutils-bpf for example.

Message translations

If the package already Depends on binutils-common for manual pages, the tools will display internationalized messages.

Else, the package may Recommend binutils-common and insert a paragraph like

Localized messages require the additionnal binutils-common package.

to the long description. Ideally, the paragraph should be identical for all targets so that itself requires only one translation.

In both cases, no version restriction should apply. Users of cross-compilers are expected to fear uninstallable toolchains more than untranslated messages.

Tests

The upstream post-build test suite is quite long and mostly target-independant, so you may decide to skip it.

Continuous integration tests should be restricted to simple tasks involving only binutils. An upload of binutils triggers CI tests for all recursive reverse dependencies, so there is not much point in duplicating the libc(s) or compiler(s) CI tests.

On the other hand, autopkgtests may be more extensive. It is for example possible to test a full compilation using the existing other elements of the toolchain. For targets with QEMU and bare-metal picolibc support (currently ARM, AARCH64 and RISC-V), it should be reasonably easy to adapt the test suite used at PicolispActions. Another example may be found in binutils-arm-none-eabi, whichs runs the compiler examples (though during continuous integration).

Stuff specific to the native scenario

Package version

A natural number should be sufficient as source package version (in debian/changelog), but the version of the binary package (set by {dpkg-,dh_}gencontrol) should change when a rebuild involves a new binutils-source version.

The binary version should join the binutils source version and the source version with a + (- would suggest a non-native package).

Source extraction

The directory extracted from the binutils tarball must be recreated during each build, in case the tarball has been updated.

This currently requires a build-dependency on xz-utils.

This invalidates the usual motivations for a versioned directory name or a separate build trees, so debian/rules may be simplified a bit.

In the following, the directory is arbitrary named src/.

It should also contain a copy of /src/binutils/debian/.

Patches

If patches are necessary, they must be stored outside the src/ throwable directory.

Please forward new patches as soon as possible, either to the upstream maintainers or via a Debian bug against binutils. Keeping a patch queue up-to-date for a single target is hopeless in the long run.

The debian/patches path is ignored by dpkg for native packages, but silents a lintian warning about a build-dependency on quilt without patches, and is probably more compatible with existing settings like QUILT_PATCHES.

It is convenient to export QUILT_PATCHES=../debian/patches, so that quilt considers src/ as the top source directory and writes patches that can be forwarded unchanged.

These commands should be added after extraction:

   1 cd src
   2 export QUILT_PATCHES=../debian/patches
   3 quilt push -a

When refreshing patches, please use `-pab --no-timestamps --no-index --sort` for normalized and less noisy patches.

Build dependencies

The list may vary depending on the target, but it at least contains * chrpath, lsb-release for the binutils Debian packaging, * bison, flex, zlib1g-dev for the upstream build system, * dejagnu if upstream post-build tests are enabled * quilt if patches are applied

Build

If you enable dh_autoreconf, be warned that only 2.69 is currently supported.

Lintian overrides

Example of debian/lintian-overrides:

# Traditional location of cross compiler tools.
non-standard-dir-in-usr usr/*/
file-in-unusual-dir usr/*/bin/*

# These private libraries are named after the target architecture,
# and only used by executables from this package.
package-name-doesnt-match-sonames lib*
exit-in-shared-library usr/lib/*/lib*
no-symbols-control-file usr/lib/*/lib*

GCC and the ISO C standard library

In addition to Binutils, it is often desired to build a C compiler, optionally with an implementation of the ISO C standard library. This is especially pertinent when making a toolchain for embedded devices. Unfortunately, this often poses bootstrap problems: the C compiler needs the standard library at build time in order to get acquainted with it, but you need a C compiler to build the standard library.

This can be solved using build profiles, to build a bootstrap, freestanding C compiler first, use it to build the C library, then build a final compiler. In the particular case of GCC and Newlib, however, this can be avoided. Best practice in this case is to use a combined tree, as documented at the GCC simulator test how-to and elsewhere. This builds the appropriate parts of GCC and Newlib in order to alleviate bootstrap trouble, and ensures compatibility by building them simultaneously. Another advantage for supported targets is that, when combined with gdb-source, a simulator can be built which allows running the target binaries, and hence can allow running the GCC test suite. The GCC test suite assumes the target binaries can be run on the host; if not building a simulator, or one doesn't exist (e.g. Xtensa), the tests should be skipped.

As with Binutils, building GCC (possibly with Newlib or the simulator) should leverage gcc-*-source, newlib-source (bug #912271), and gdb-source packages when possible, and the build should be set up by a native package. A Built-Using entry should not be provided for Newlib, however, because the binaries are non-copyleft licensed and the sources do not need to be kept around for license compliance, as is the case with GCC and GDB.