Source layout of rust-coreutils
===============================

The source package is built from three pieces, on purpose kept identical to
what the Ubuntu package does so that both distributions stay easy to merge:

 1. the *pristine* upstream tarball, i.e. the GitHub tag of uutils/coreutils,
 2. the l10n component tarball (uutils/coreutils-l10n), unpacked into l10n/,
 3. the vendored crates, in debian/rust-vendor/, shipped in the .debian.tar.

Nothing is repacked; debian/repack.sh is gone.


Importing a new upstream release
--------------------------------

    uscan --verbose --destdir ..

downloads both tarballs (rust-coreutils_<version>.orig.tar.gz and
rust-coreutils_<version>.orig-l10n.tar.gz). Unpack the first one over the
tree, the second one into l10n/, then refresh debian/patches and update
debian/changelog.


Refreshing the vendored crates
------------------------------

    cargo install cargo-vendor-filterer     # once; not packaged in Debian
    debian/rules vendor

That target regenerates debian/rust-vendor/ (filtered down to the tier-1/2
*-*-linux-gnu* targets, which is why no Windows/macOS/BSD-only crate is
vendored), blanks the per-crate checksum files so the crates can be patched,
regenerates debian/source/include-binaries and the XS-Vendored-Sources-Rust
field of debian/control, and commits the result.

Crates cannot be patched through debian/patches (dpkg-source would then also
carry the vendored copies in the diff), so vendor patches live in their own
quilt series, debian/patches/rust-vendor/, applied at build time by
dh_quilt_patch via QUILT_PATCH_DIR/QUILT_PC (see debian/rules).


Profile-guided optimization
---------------------------

On amd64 and arm64, override_dh_auto_build builds an instrumented multicall
binary, then runs upstream's util/build-pgo.sh to exercise it with the training
workloads it ships and merge the raw profiles into debian/pgo/coreutils.profdata,
which the real build then consumes through -Cprofile-use (PGO_RUSTFLAGS in
debian/rules).

The instrumented binary is built by debian/rules, with the same "make
build-coreutils" command that builds the shipped one, rather than by the
script's own step 1. This matters: a profile only applies to a build matching
the one it was collected from, and the script builds "--features unix" while
the package builds --no-default-features with an explicit list of utilities
plus feat_systemd_logind, feat_external_libstdbuf, openssl and selinux. Train
the wrong binary and -Cprofile-use finds no data for those symbols, reports
nothing, and PGO quietly becomes a no-op. d/p/pgo-use-prebuilt-binary.patch
adds the --instrumented-binary option used to hand the script our binary.

It is deliberately limited to those two arches: the training step has to *run*
the instrumented binary (so cross builds are out) and it roughly doubles the
build time, which s390x and the 32-bit arches cannot afford. Build it without
PGO with:

    DEB_BUILD_OPTIONS=nopgo dpkg-buildpackage -b

llvm-profdata has to match the LLVM rustc was built against, so debian/rules
looks for /usr/lib/llvm-<N>/bin/llvm-profdata with <N> taken from
"rustc --version --verbose" (falling back to a rustup toolchain's own copy,
which is what makes a local test build work). If neither is there, PGO is
skipped and the build proceeds normally.

OpenSSL
-------

The checksum utilities are built with the upstream "openssl" feature, so
cksum/md5sum/sha*sum use libcrypto instead of the pure-Rust digests.
OPENSSL_NO_VENDOR=1 is exported so openssl-sys links Debian's shared
libcrypto: the vendored openssl-src crate is never compiled, and no copy of
OpenSSL ends up in the binary package.


tldr examples
-------------

improve-man.diff adds an EXAMPLES section to every manpage, taken from the
tldr-pages project. Upstream downloads that archive at documentation build
time, which a Debian build cannot do, so a copy trimmed down to the English
pages (pages/common and pages/linux) is shipped as debian/tldr.zip and copied
into docs/ by override_dh_auto_configure. Refresh it with:

    curl -L https://github.com/tldr-pages/tldr/releases/latest/download/tldr.zip \
        -o /tmp/tldr.zip
    rm -rf /tmp/tldr && mkdir /tmp/tldr && cd /tmp/tldr && \
        unzip -q /tmp/tldr.zip 'pages/common/*' 'pages/linux/*' 'LICENSE*' && \
        zip -qr9 debian/tldr.zip .
