Skip to content

feat: build host-only doc tools in host config under cross --platforms#633

Draft
umaucher wants to merge 1 commit into
eclipse-score:mainfrom
umaucher:um_host_platform_transition
Draft

feat: build host-only doc tools in host config under cross --platforms#633
umaucher wants to merge 1 commit into
eclipse-score:mainfrom
umaucher:um_host_platform_transition

Conversation

@umaucher

@umaucher umaucher commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

Why

The runnable documentation targets created by docs()docs, docs_combo, docs_check, docs_link_check, live_preview, live_preview_combo_experimental, ide_support — are host tools that run Python/Sphinx on the build machine. When a consumer builds with a cross --platforms (e.g. --config=per-x86_64-qnx -- //...), these top-level targets get configured for the target platform and fail Python toolchain resolution (No matching toolchains ... tools/python), breaking the whole build in cross-compiling consumers (persistency, reference_integration).

What

Each host-only run target is wrapped in a small rule (_host_binary) whose incoming transition pins //command_line_option:platforms to whatever --host_platform is set to. The targets therefore always build and run in the host configuration regardless of the top-level --platforms.

  • The wrapper forwards the executable (via symlink), runfiles, and RunEnvironmentInfo, so bazel run //:docs (and the env-carrying targets) keep working unchanged.
  • The transition follows --host_platform dynamically rather than hardcoding a platform, so it works for any consumer's host.
  • sphinx_build is only ever consumed as a tool (already built in the exec/host config), so it needs no transition; it is tagged manual so a wildcard bazel build //... under a cross platform skips it instead of trying to configure it for the target platform.

Validation

  • Host: bazel build //:docs //:needs_json //:metrics_json, bazel run //:ide_support — no regression.
  • Cross: in a consumer with a local override, bazel build --config=per-x86_64-qnx -- //... no longer fails Python toolchain resolution — the wrapped run targets transition to the host config, while sphinx_build (a manual tool) is skipped by the wildcard and built only in the exec/host config when consumed by needs_json. cquery --transitions=lite confirms the wrapped targets transition to the host config. (The only remaining consumer failure is the unrelated valid_from metamodel skew fixed by Set valid_from attribute for all features score#3064.)
  • buildifier clean.

No tracking issue.

The runnable documentation targets (docs, docs_combo, docs_check,
docs_link_check, live_preview, live_preview_combo_experimental,
ide_support) are host tools that run Python/Sphinx locally. Under a cross
`--platforms` (e.g. QNX) they were configured for the target platform and
failed Python toolchain resolution, breaking `bazel build //...` in
cross-compiling consumers.

Wrap each in a small rule whose incoming transition pins
`//command_line_option:platforms` to `--host_platform`, so they always
build and run in the host configuration regardless of the top-level
`--platforms`. The wrapper forwards the executable, runfiles and
RunEnvironmentInfo so `bazel run //:docs` keeps working.

`sphinx_build` is only consumed as a tool (already built in the exec/host
config) and is tagged `manual` so wildcard builds under a cross platform do
not try to configure it for the target platform.
@github-actions

github-actions Bot commented Jul 8, 2026

Copy link
Copy Markdown

License Check Results

🚀 The license check job ran with the Bazel command:

bazel run --lockfile_mode=error //src:license-check

Status: ⚠️ Needs Review

Click to expand output
[License Check Output]
Extracting Bazel installation...
Starting local Bazel server (8.6.0) and connecting to it...
INFO: Invocation ID: 1364cb45-f071-485b-9bf6-779ced10787c
Computing main repo mapping: 
Loading: 
Loading: 0 packages loaded
Loading: 0 packages loaded
Loading: 0 packages loaded
    currently loading: src
WARNING: Target pattern parsing failed.
ERROR: Skipping '//src:license-check': no such target '//src:license-check': target 'license-check' not declared in package 'src' defined by /home/runner/work/docs-as-code/docs-as-code/src/BUILD
ERROR: no such target '//src:license-check': target 'license-check' not declared in package 'src' defined by /home/runner/work/docs-as-code/docs-as-code/src/BUILD
INFO: Elapsed time: 5.467s
INFO: 0 processes.
ERROR: Build did NOT complete successfully
ERROR: Build failed. Not running target

@github-actions

github-actions Bot commented Jul 8, 2026

Copy link
Copy Markdown

The created documentation from the pull request is available at: docu-html

@umaucher

umaucher commented Jul 8, 2026

Copy link
Copy Markdown
Contributor Author

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

Labels

None yet

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

1 participant