From a3637fedf62f3b1782b970e252c9c76c811ff9d2 Mon Sep 17 00:00:00 2001 From: Daniel Hilst <392820+dhilst@users.noreply.github.com> Date: Tue, 11 Aug 2026 12:16:52 -0300 Subject: [PATCH] docs(xcat-dep): POD for sbuild-all.pl + Ubuntu-scoped BUILD.md build instructions Acceptance requirements for the Ubuntu dep build (VersatusHPC/xcat-core#49): - Add full POD to sbuild-all.pl (NAME/SYNOPSIS/DESCRIPTION/PHASES/OPTIONS) with --man and --help via Pod::Usage, so `perldoc sbuild-all.pl` / `--man` document the tool (parity with the EL mockbuild-all.pl). Drops the drift-prone usage() sub. - BUILD.md: explicit Ubuntu-scoped instructions for building ONE specific version (--dists / --target -) and ALL supported versions. Also: make_tarball creates its run dir before taring (an assemble-only run has no genesis phase to create it), so the tarball phase never errors. Signed-off-by: Daniel Hilst <392820+dhilst@users.noreply.github.com> --- BUILD.md | 53 +++++++++++---- sbuild-all.pl | 183 +++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 201 insertions(+), 35 deletions(-) diff --git a/BUILD.md b/BUILD.md index 22796a5..2b60847 100644 --- a/BUILD.md +++ b/BUILD.md @@ -307,23 +307,52 @@ Codename ↔ version (the single supported set — `BuildUtils` is the source of ## Usage (per arch, as root on the matching build host) +Run `sbuild-all.pl` on the build host for the arch you are building (amd64 on the x86 Ubuntu host, +ppc64el on the ppc Ubuntu host). The Ubuntu version(s) to build are selected with **`--dists`** (a +space/comma list of codenames) or, for exactly one, **`--target -`**. Version ↔ +codename: `20.04`=`focal`, `22.04`=`jammy`, `24.04`=`noble`, `26.04`=`resolute`. + +### Build ALL supported Ubuntu versions + ```bash -# amd64 host — build all four codenames, sign, assemble the apt tree: +# amd64 host — build focal+jammy+noble+resolute, sign, assemble the apt tree: ./sbuild-all.pl --arch amd64 --dists "focal jammy noble resolute" \ - --xcat-source ../xcat-core --genesis-rpm \ - --genesis-rpm-ppc \ + --xcat-source ../xcat-core --genesis-rpm \ + --genesis-rpm-ppc \ --gpg-sign --gpg-key-id xcat@megware.com --gpg-home - -# ppc64el host — arch-specific deps only (the arch:all boot components come from amd64): -./sbuild-all.pl --arch ppc64el --dists "focal jammy noble resolute" \ - --xcat-source ../xcat-core --genesis-rpm --gpg-sign ... - -# a single target / a dry run: -./sbuild-all.pl --target noble-amd64 ... -./sbuild-all.pl --dry-run --skip-build --skip-genesis ... ``` -`sbuild-all.pl --help` lists every option; the shared flags (`--repo-root`, `--manifest`, +`--dists` may be omitted entirely — with no `--dists`/`--target`, **all supported codenames** are +built (the default is `focal jammy noble resolute`). + +### Build ONE specific Ubuntu version + +```bash +# just 24.04 (noble) on amd64 — two equivalent forms: +./sbuild-all.pl --arch amd64 --dists noble --xcat-source ../xcat-core --genesis-rpm --gpg-sign ... +./sbuild-all.pl --target noble-amd64 --xcat-source ../xcat-core --genesis-rpm --gpg-sign ... + +# just 20.04 (focal): +./sbuild-all.pl --arch amd64 --dists focal ... +``` + +### ppc64el host + +```bash +# arch-specific deps only (the Architecture:all boot components come from the amd64 build): +./sbuild-all.pl --arch ppc64el --dists "focal jammy noble resolute" \ + --xcat-source ../xcat-core --genesis-rpm --gpg-sign ... +``` + +### Handy variants + +```bash +./sbuild-all.pl --dry-run --arch amd64 --dists noble # print the plan, do nothing +./sbuild-all.pl --skip-build --skip-genesis --gpg-sign ... # assemble-only (re-index/re-sign staging) +``` + +`sbuild-all.pl --help` lists every option and `sbuild-all.pl --man` (or `perldoc sbuild-all.pl`) +prints the full manual; the shared flags (`--repo-root`, `--manifest`, `--skip-build/-install/-genesis/-xcat-dep`, `--build-number`, `--gpg-sign`, `--dry-run`, …) match `mockbuild-all.pl`. diff --git a/sbuild-all.pl b/sbuild-all.pl index 0453d78..557d1dc 100755 --- a/sbuild-all.pl +++ b/sbuild-all.pl @@ -30,6 +30,7 @@ use File::Path qw(make_path remove_tree); use File::Copy qw(copy); use File::Temp qw(tempdir); use Getopt::Long qw(GetOptions); +use Pod::Usage qw(pod2usage); use POSIX qw(strftime); use FindBin qw($RealBin); use lib $RealBin; @@ -122,9 +123,10 @@ $spec{'genesis-rpm=s'} = \$genesis_rpm; $spec{'genesis-rpm-ppc=s'} = \$genesis_rpm_ppc; $spec{'require-ppc-genesis!'} = \$require_ppc_genesis; $spec{'output=s'} = \$output_root; # --output alias -$spec{'help|h'} = sub { usage(); exit 0; }; +$spec{'help|h'} = sub { pod2usage(-verbose => 1, -exitval => 0); }; +$spec{'man'} = sub { pod2usage(-verbose => 2, -exitval => 0); }; -GetOptions(%spec) or die usage(); +GetOptions(%spec) or pod2usage(-verbose => 1, -exitval => 2); # --------------------------------------------------------------------------------------------------- # Configuration @@ -460,31 +462,11 @@ sub make_tarball { return if $skip_tarball; print_step('Tarball'); my $tb = "$output_root/$run_id/xcat-dep-$arch-$run_id.tar.gz"; + make_path(dirname($tb)) unless $dry_run; # the run dir may not exist yet (e.g. an assemble-only run) run("tar -C " . sh_quote(dirname($apt_dir)) . " -czf " . sh_quote($tb) . " " . sh_quote(basename($apt_dir)), nofail => 1); print " $tb\n"; } -sub usage { - return <<"USAGE"; -Usage: sbuild-all.pl [options] - --arch host arch (default: dpkg --print-architecture) - --dists "" codenames to build (default: @{[known_codenames()]}) - --target build a single target (arch must match --arch) - --manifest per-target manifest (default: /debs-manifest.conf) - --repo-root / --xcat-source - --output-root / --apt-dir - --mirror chroot bootstrap mirror (default: BR archive) - --genesis-deb native xcat-genesis-base deb to INGEST (repeatable; preferred) - --genesis-rpm native-arch genesis rpm to convert (fallback) - --genesis-rpm-ppc cross-arch ppc genesis rpm to convert on amd64 (#7610) - --require-ppc-genesis make a missing ppc64el genesis fatal (default: warn) - --gpg-sign --gpg-key-id --gpg-home - --build-number --build-timestamp --run-id - --skip-build --skip-install --skip-genesis --skip-xcat-dep --skip-createrepo --skip-tarball - --dry-run -USAGE -} - # --------------------------------------------------------------------------------------------------- # Main # --------------------------------------------------------------------------------------------------- @@ -497,3 +479,158 @@ validate_manifest(); assemble_apt(); make_tarball(); print_step("Completed ($arch: @dist_list)"); + +__END__ + +=head1 NAME + +sbuild-all.pl - build, validate, sign and assemble the xcat-dep Ubuntu/Debian apt repository + +=head1 SYNOPSIS + + sbuild-all.pl [options] + + # build ALL supported Ubuntu versions for this host's arch, sign + assemble the apt tree: + sbuild-all.pl --arch amd64 --dists "focal jammy noble resolute" \ + --xcat-source ../xcat-core --genesis-rpm \ + --gpg-sign --gpg-key-id xcat@megware.com --gpg-home + + # build ONE Ubuntu version only: + sbuild-all.pl --arch amd64 --dists noble ... + sbuild-all.pl --target noble-amd64 ... # equivalent single-target form + + # assemble-only (re-sign/re-index from already-built staging): + sbuild-all.pl --skip-build --skip-genesis --gpg-sign --gpg-key-id --gpg-home + + sbuild-all.pl --help # option summary + sbuild-all.pl --man # this manual + perldoc sbuild-all.pl + +=head1 DESCRIPTION + +sbuild-all.pl is the top-level Ubuntu/Debian dependency-build orchestrator for xcat-dep -- the +apt/sbuild analogue of the EL C, sharing its CLI vocabulary +(C) and its manifest-driven, zero-tolerance, fail-hard design. It +absorbs the three former shell scripts (C, C, +C) into one Perl entrypoint and drives each package's B C +packaging (never re-implemented) via its per-package C<< /sbuild.pl >> builder. + +One host builds one architecture (C<--arch>, default C) for a set of +Ubuntu codenames (C<--dists>). Each C<< - >> is a B with a section in +C. Everything is built and validated into a fresh, per-arch B tree +first; the published apt repo is (re)assembled from validated staging only after the complete +expected set validates -- so a partial or failed build never reaches the repo and stale debs never +accumulate. Any missing chroot / package / artifact, or any version-pin mismatch, fails the whole +run non-zero. + +=head1 PHASES + +=over 4 + +=item Ensure chroots + +Auto-initializes any missing C<< --sbuild >> chroot on first run (main + universe, +fast mirror, shared-tree bind-mount); idempotent. Skipped with C<--skip-build>. + +=item Build + +Runs each manifest package's C<< /sbuild.pl >> in the matching chroot into +CcodenameE/EarchE/>. + +=item Genesis + +Produces the C deb: a native deb is ingested as-is when provided +(C<--genesis-deb>); otherwise the rpm is converted while B +(Depends/Breaks/Replaces) and maintainer scripts. The amd64 host also converts the cross-arch +ppc64el genesis (issue #7610) unless C<--require-ppc-genesis> gates it. Skipped with C<--skip-genesis>. + +=item Validate + +Asserts every manifest-required package is present at its pinned version (zero tolerance). + +=item Assemble + +Wipes+repopulates each codename's published C/C from validated staging, indexes per +CarchE> (Architecture:all packages land in every arch index) and gpg-signs +C/C. Skipped with C<--skip-createrepo>. + +=item Tarball + +A repo tarball build artifact (the deployable offline FRS dep bundle is produced by the pipeline's +C). Skipped with C<--skip-tarball>. + +=back + +=head1 OPTIONS + +=over 4 + +=item B<--arch> C + +Host architecture. Default: C. + +=item B<--dists> C<"EcodenamesE"> + +Space/comma list of Ubuntu codenames to build. Default: all supported (C). + +=item B<--target> C<< - >> + +Build a single target; the arch must match C<--arch>. + +=item B<--manifest> C + +Per-target manifest. Default: C<< /debs-manifest.conf >>. + +=item B<--repo-root> / B<--xcat-source> C + +xcat-dep root (default: the script's dir) / xcat-core root (for the maintained genesis packaging). + +=item B<--output-root> / B<--apt-dir> C + +Staging + build-output base / published apt tree (default C<< /repos/apt >>). + +=item B<--mirror> C + +Chroot bootstrap mirror (default: a fast BR archive mirror; C times out from the +build hosts). + +=item B<--genesis-deb> C + +Native C deb to ingest (repeatable; preferred over conversion). + +=item B<--genesis-rpm> / B<--genesis-rpm-ppc> C + +Native-arch genesis rpm to convert / cross-arch ppc genesis rpm to convert on amd64 (issue #7610). + +=item B<--require-ppc-genesis> + +Make a missing ppc64el genesis fatal (default: warn). + +=item B<--gpg-sign> B<--gpg-key-id> C B<--gpg-home> C + +Sign C/C with the given key from the given GNUPGHOME. + +=item B<--build-number> C B<--build-timestamp> C B<--run-id> C + +CD identifiers; C<--build-timestamp> also sets C for reproducible builds. + +=item B<--skip-build> B<--skip-install> B<--skip-genesis> B<--skip-xcat-dep> B<--skip-createrepo> B<--skip-tarball> + +Skip the corresponding phase(s). C<--skip-build --skip-genesis> gives an assemble-only run. + +=item B<--dry-run> + +Print the planned actions without executing them. + +=item B<--help> / B<--man> + +Option summary / this manual. + +=back + +=head1 SEE ALSO + +C (the EL analogue), C, C<< /sbuild.pl >>, +C, and F. + +=cut