Skip to content

Add an optional CMake build path for Bazel-unavailable environments (#75) - #78

Merged
jwcullen merged 1 commit into
AOMediaCodec:mainfrom
jlivingston-Cipher:cmake-build-path
Aug 6, 2026
Merged

Add an optional CMake build path for Bazel-unavailable environments (#75)#78
jwcullen merged 1 commit into
AOMediaCodec:mainfrom
jlivingston-Cipher:cmake-build-path

Conversation

@jlivingston-Cipher

Copy link
Copy Markdown
Contributor

Follows up on #75 (and the prior art in #12 / #16): an optional, non-default
CMake build path for the encoder_main / decoder_main / probe_main CLIs,
for environments where the Bazel toolchain cannot run — networks that allow
git clone but block the Bazel Central Registry and release-archive fetches.
Bazel remains the build system of record; nothing about the Bazel build is
touched.

What the PR adds — three new files, no existing file modified

  • CMakeLists.txt (top level, per the guidance in CMake build path for registry-restricted / Bazel-unavailable environments #75) — written from
    scratch against the Bazel BUILD graph; no Bazel-generated content is used or
    derived. Builds an iamf_core static library plus the three CLIs.
  • build_cmake.sh — the driver: clones the dependencies at MODULE.bazel's
    exact pins
    (abseil 20260107.1, protobuf v33.5, FDK-AAC ee76460e,
    loudness_ebur128 e9e73147, obr 478dc7c7, audio-to-tactile d3f449fd;
    pffft via the marton78 GitHub mirror at a fixed commit, since the restricted
    environments this path serves typically reach github.com only — the deviation
    is documented in the script header), satisfies opus/flac/expat/eigen from
    Ubuntu system packages via header shims, builds abseil → protobuf →
    iamf-tools, and ends by reconciling intent against outcome (each CLI present
    and executable; non-zero exit otherwise). Pinning everything keeps the CI job
    hermetic: a push to a dependency repo cannot change what this path builds.
  • .github/workflows/cmake.yml — the CI job requested in CMake build path for registry-restricted / Bazel-unavailable environments #75, and the
    answer to Is there plan to support cmake compile? #12's maintenance concern: one ubuntu-latest leg that builds the
    three CLIs from a clean checkout and then exercises them — probes two
    in-tree test files, decodes an in-tree 5.1 Opus file, and runs a full
    encode → probe → decode round-trip on in-tree vector test_000002. If a
    future change breaks the CMake path, this goes red visibly instead of
    failing silently for downstream users.

Platform scope, stated plainly

This path is Linux-only today (same posture as #75): the CI leg is
ubuntu-latest, and I make no macOS/Windows claims for it. The Bazel build's
platform matrix is unaffected. Toolchain verified: GCC 13 / CMake 3.28; the
declared CMake floor (3.22) is configure- and build-tested with CMake 3.22.6.

Verification

  • Builds current main (dd03679) unmodified — all three CLIs produced.
  • The shipped build_cmake.sh was run end-to-end from a clean checkout on a
    clean environment
    (fresh dependency clones at the pins, no pre-built
    state); its own reconciliation passed, and the CI workflow has a green
    hosted run on this branch.
  • Functional, not just linkable: probe_main fully parses in-tree test files
    and an external 7.1.4 Opus sequence (complete descriptor read, pre_skip
    312); decoder_main renders in-tree files; the encode → probe → decode
    round-trip passes with the encoder reporting "Test case expected to pass".
  • Differential vs the Bazel build (-c opt), same runner and checkout,
    over all 5 in-tree .iamf test files:
    • probe_main output content-identical on every file (4/5
      byte-identical; the fifth differs only in element print order, which the
      probe emits nondeterministically per process from hash-map iteration —
      verified by running a single binary repeatedly);
    • decoder_main PCM byte-identical on the FLAC file; the three Opus
      decodes agree within −121 dBFS worst-case (cross-build libopus
      float-decode variance, system 1.4 vs the source pin — far below audible
      or measurable significance at 32-bit output);
    • the encoder round-trip on test_000002 produced byte-identical
      bitstreams from both builds
      , and their decodes are byte-identical;
    • the one in-tree LPCM file is rejected identically by both builds (its
      Codec Config encodes num_samples_per_frame=0, which current validation
      rejects).
  • Two incidental findings from that differential — the num_samples_per_frame=0
    fixture that docs/iamf_decoder_main.md cites as its decode example, and the
    per-process element ordering in probe output — I would be happy to file (or
    fix) separately if useful.
  • Lint: shellcheck clean on build_cmake.sh; actionlint clean on the
    workflow.
  • The same port previously built a7b5f4b unmodified (noted in CMake build path for registry-restricted / Bazel-unavailable environments #75). The
    standalone interim repo
    (jlivingston-Cipher/cmake-iamf-tools)
    carries the same build; on merge I will point it here and thin or archive it.

Maintenance posture

Self-contained: deleting the three files removes the path entirely. I watch
this path, will keep the dependency pins moving with MODULE.bazel, and am
happy to be pinged on any breakage. If you would rather have the CI logic as a
composite action under .github/actions/ to match the existing jobs, or a
short pointer added to docs/build_instructions.md, I will amend.

Contributor agreement: executed (AOMedia contributor agreement, per
CONTRIBUTING), on file since 2026-07-27.

Three new files, nothing modified: a top-level CMakeLists.txt (written from scratch against the Bazel BUILD graph; no Bazel-generated content is used or derived), a build_cmake.sh driver that satisfies the dependencies from git clones and system packages at the MODULE.bazel pins, and a single-leg Linux CI job that builds the three CLIs from a clean checkout and exercises them: probe, decode, and a full encode -> probe -> decode round-trip on in-tree test data.

Implements the conditions discussed in #75 (CI job included in the PR; top-level file). Prior art: #12, #16. Bazel remains the build system of record; the Bazel build is untouched.

Three new files, nothing modified: a top-level CMakeLists.txt (written
from scratch against the Bazel BUILD graph; no Bazel-generated content
is used or derived), a build_cmake.sh driver that satisfies the
dependencies from git clones and system packages at the MODULE.bazel
pins, and a single-leg Linux CI job that builds the three CLIs from a
clean checkout and exercises them: probe, decode, and a full
encode -> probe -> decode round-trip on in-tree test data.

Implements the conditions discussed in AOMediaCodec#75 (CI job included in the PR;
top-level file). Prior art: AOMediaCodec#12, AOMediaCodec#16. Bazel remains the build system
of record; the Bazel build is untouched.
@jwcullen
jwcullen merged commit 81517e1 into AOMediaCodec:main Aug 6, 2026
7 checks passed
@jwcullen

jwcullen commented Aug 6, 2026

Copy link
Copy Markdown
Collaborator

Merged with some cleanups tp the shell script. If they don't work for your environment feel free to discuss or file another PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants