Skip to contents

Build Tools

Source: vignettes/articles/build-tools.Rmd
build-tools.Rmd

Overview

This article is maintainer-facing.

shiny.webawesome uses a small set of top-level build tools under tools/ to implement the documented package workflow.

These tools are the operational entry points for the repository’s generator, runtime-pruning, reporting, finalize, and website-build steps.

This article is a practical companion to the authoritative workflow documentation in projectdocs/. It describes the tool entry points and how they fit together, but it does not replace the project workflow docs.

All top-level tool entry points support --help (and -h) to print a summary of their command-line options.

Core Build Stages

The core reproducible package-build stages map closely to the documented pipeline through report:

  • clean_webawesome()
  • fetch_webawesome()
  • prune_webawesome()
  • generate_components()
  • report_components()
  • check_integrity()

clean_webawesome()

Removes generated artifacts and build outputs.

Use clean_webawesome() for the ordinary clean stage and distclean when you also want to remove fetched upstream inputs. The clean stage also removes the generated site output under website/.

fetch_webawesome()

Fetches the pinned upstream Web Awesome npm package, extracts the browser-ready dist-cdn/ tree, and stores it under vendor/webawesome/<version>/.

This tool uses npm by default. If the desired executable is not already on PATH, set SHINY_WEBAWESOME_NPM to the executable that should be run.

By default, the version comes from dev/webawesome-version.txt.

prune_webawesome()

Builds the pruned runtime bundle under inst/www/wa/ and copies the metadata inputs needed for generation into inst/extdata/webawesome/.

This stage is also responsible for prune-stage diagnostics and its integrity record.

generate_components()

Builds the component schema from custom-elements.json and emits:

  • generated wrappers under R/
  • generated bindings under inst/bindings/
  • generated update helpers where supported

This stage now also records generate-stage integrity output.

report_components()

Builds deterministic manifests and human-readable reports describing:

  • generated-file integrity
  • component coverage
  • API conformance
  • handwritten package API inventory

This stage is the structural diagnostics and reporting boundary. It is not the late-stage release-preparation step.

check_integrity()

Runs the final integrity gate over the recorded build surfaces.

This tool remains the hard integrity gate for the current generated surfaces, and it is also invoked by the later finalize_package.R workflow.

Late-Stage Release Preparation

finalize_package.R

Runs the recurring late-stage local release-preparation workflow.

This tool performs the documented finalize sequence, including:

  • stale handoff cleanup
  • integrity checking via check_integrity()
  • dry-run style and lint checks
  • dependency auditing
  • package tests
  • advisory package test coverage reporting
  • package documentation regeneration
  • site building plus local website link auditing with lychee
  • package URL auditing without auto-updating links, with package-owned website URLs validated against the built local site artifact
  • package checking
  • tarball creation
  • finalize handoff reporting under manifests/finalize/ and reports/finalize/

The finalize workflow supports iterative default mode and a stricter --strict release-preparation mode.

Strict clean-start enforcement belongs to the full build_package.R orchestrator, not to finalize_package.R itself. Strict finalize is the late-stage gate that runs after the earlier build stages have already recreated the package-owned generated surfaces.

The finalize workflow also checks handwritten JavaScript with ESLint. That means the developer environment should have ESLint, which in turn requires Node.js and npm, available before finalize is treated as ready-to-run. Use the manual setup command:

npm install --save-dev eslint@latest @eslint/js@latest

Strict finalize also expects the website link checker lychee to be available so the built local website/ tree can be audited before release. Do not use the snap package for this repository. Its filesystem confinement prevents lychee from auditing the repo’s built site reliably. Instead, download a pre-built lychee binary from:

https://github.com/lycheeverse/lychee/releases

and, if it is not already on PATH, point the workflow at it explicitly:

export SHINY_WEBAWESOME_LYCHEE=/path/to/lychee

External pre-release checks such as rhub and the final manual visual review remain outside the automatic finalize execution path. In strict mode, finalize_package.R requires explicit confirmation flags for those checks. The repository’s representative manual visual review app is launched with:

./tools/check_interactive.R

The repository’s helper for launching external R-hub checks from the current git branch is:

./tools/check_rhub.R

Orchestration Tools

The top-level orchestrators are intentionally explicit rather than collapsing multiple responsibilities into one opaque release command.

build_tools.R

Runs the source-level tool workflow by orchestrating:

  • tool tests
  • tool documentation generation

This is the prerequisite workflow for the tooling surface itself.

build_package.R

Runs build_tools.R first by default, then executes the currently available package build-stage scripts in sequence.

At the current stage of the repository, that sequence includes the package build stages through finalize, including fetch, prune, generate, binding-candidate review, report, integrity checking, and finalize.

build_package.R does not own publish. The release publication step remains separate so git tagging, pushing, and website deployment happen only when the maintainer explicitly decides the repository is ready to put out.

When invoked with --finalize-strict, build_package.R is the entry point that should enforce a clean release-build starting state. It also passes the external strict-finalize confirmation flags through to finalize_package.R: --confirmed-rhub-pass and --confirmed-visual-review.

Website Tool

build_site.R

Builds the pkgdown documentation site using the checked-in _pkgdown.yml configuration and writes output to the configured destination, currently website/.

When generated tool docs are present, this step also copies them into website/tool-docs/. When source apps are present under vignettes/shinylive-examples/, it can also publish matching standalone live-demo targets under website/live-examples/ when invoked with --with-live-examples. If shinylive export emits warnings, the site build writes a placeholder page instead of publishing a likely-broken demo shell. It also audits the built local site links with lychee; missing lychee produces a warning in ordinary runs and a hard failure when --strict-link-audit is requested. Do not use the snap package here; use a pre-built release binary instead, and set SHINY_WEBAWESOME_LYCHEE to the executable that should be run if that binary is not already on PATH.

This tool is intentionally separate from build_package.R. The docs-site workflow is maintainership-facing and may evolve on a different cadence from the core package-build stages.

Publish Tool

publish.R

Runs the explicit maintainer-invoked publish stage after finalize.

This tool is intentionally separate from build_package.R. That separation is deliberate: build_package.R is the recurring local package-build orchestrator, while publish is the explicit maintainer release action. Keeping publish outside the package-build orchestrator ensures that git tagging, pushing, and website deployment happen only when the maintainer decides the repository is ready to put out.

The publish tool verifies the recorded finalize handoff against the current repo state and then performs only the action groups explicitly requested at the CLI. Its core checks include:

  • release version consistency against DESCRIPTION and NEWS.md
  • finalize handoff presence and status
  • clean git working tree
  • current HEAD and tracked-tree checksum matching the handoff
  • tarball and built website/ artifact checksum matching the handoff
  • branch and tag readiness checks
  • website deployment readiness checks when site deployment is requested

The publish tool currently supports:

  • --dry-run for verification-only readiness checks
  • --do-tag to create and push the release tag and current branch
  • --deploy-site to deploy the already-built website/ artifact

--dry-run is verification-only even when --do-tag or --deploy-site are also supplied. In that mode, publish records the requested actions as planned but does not execute them.

The publish tool writes machine-readable and human-readable outputs under:

  • manifests/publish/
  • reports/publish/

deploy_site_netlify.R

The publish tool delegates site deployment to the dedicated Netlify wrapper:

./tools/deploy_site_netlify.R

This wrapper keeps site deployment explicit and narrow. In --dry-run mode, it verifies local website output, checks Netlify authentication, and confirms that the configured site id is visible to the authenticated account. In a real run, it then deploys the already-built website/ artifact with the Netlify CLI.

This tool requires the Netlify CLI. Install it manually with:

sudo npm install -g netlify-cli

The Netlify wrapper currently expects these environment variables:

  • NETLIFY_AUTH_TOKEN
  • NETLIFY_SITE_ID

Place those exports somewhere your shell session loads before you run publish or the deploy helper. A login-shell startup file such as ~/.profile is usually a better fit than placing them late in an interactive ~/.bashrc.

Typical setup:

export NETLIFY_AUTH_TOKEN=...
export NETLIFY_SITE_ID=...

Typical dry-run checks:

./tools/deploy_site_netlify.R --dry-run
./tools/publish.R --release-version 1.0.0 --dry-run --deploy-site

Tool Documentation

Generated tool documentation lives under tools/man/.

In the website build, the generated HTML tool docs are copied into tool-docs/.

Useful entry points include:

These generated docs are useful when you need the CLI and function-level details for a specific tool.

Notes for Maintainers

This article complements the authoritative project docs under projectdocs/, especially:

  • projectdocs/workflow/build-pipeline.md
  • projectdocs/workflow/agent-development-playbook.md

If the implemented tool entry points, stage boundaries, or orchestrators change, update both:

  • the relevant tool documentation
  • the authoritative workflow docs in projectdocs/
  • this maintainer-facing article so it remains consistent with the actual orchestrators and entry points