contributing

## Contributing to mochiOS Libraries ##
Thank you for your interest in contributing to mochiOS Libraries!

This repository maintains the infrastructure for building and distributing
third-party libraries for mochiOS.

Contributions are welcome, including new library ports, improvements to
existing recipes, bug fixes, and build infrastructure improvements.



Before contributing
-----------------------------------------
Before starting work, please check existing issues and pull requests to
avoid duplicate efforts.

For new library ports, we recommend opening a library request issue before
beginning implementation.



Requesting a library
-----------------------------------------
To request support for a new library, open an issue using the library
request template.

Please provide:

  - Library name and upstream repository
  - Brief description and intended use
  - License information
  - Required dependencies
  - Known compatibility or porting considerations

A request does not guarantee that a library will be added.



Adding a library
-----------------------------------------
New libraries are registered in libraries.toml.

To add a library:

  1. Add the library definition to libraries.toml.
  2. Declare its dependencies.
  3. Create a build recipe under recipes/<library-name>/.
  4. Add the required build configuration and verification probe.
  5. Ensure the upstream license is correctly identified.
  6. Run the available validation and tests.

Any required upstream patches should be minimal and limited to the
relevant library.



Modifying existing libraries
-----------------------------------------
Changes to existing libraries should preserve compatibility whenever
possible.

When updating a library:

  - Verify upstream source and version rules.
  - Review dependency changes.
  - Check for ABI compatibility concerns.
  - Update build recipes and verification probes as necessary.

Avoid unrelated modifications.



Validation and testing
-----------------------------------------
Before submitting a pull request, run:

  python3 tools/libs.py check
  python3 -m unittest discover -s tests -v

All applicable checks should pass.

If testing cannot be completed, explain the reason in the pull request.

Do not claim that a library has been tested on mochiOS unless such testing
has actually been performed.



Pull requests
-----------------------------------------
Submit contributions through pull requests against the main branch.

Each pull request should:

  - Clearly describe the changes and their purpose.
  - Reference related issues when applicable.
  - Include relevant testing results.
  - Identify any limitations or known issues.
  - Avoid unrelated modifications.

Maintainers may request changes before merging.



Licensing
-----------------------------------------
Third-party libraries retain their original upstream licenses.

Contributors must ensure that required copyright notices and license
information are preserved.

Contributions must comply with applicable licenses and redistribution
requirements.



Reporting issues
-----------------------------------------

Bug reports and improvement suggestions are welcome.

Please include the affected library, relevant configuration, error messages,
and steps to reproduce the problem when applicable.

Cross-build backends
-----------------------------------------
Recipes select cmake, meson, or autotools. All backends use the SDK's
mochiOS compiler drivers and are followed by ELF and consumer-link checks.
Target executables are never run during the build. Meson uses a cross file
with needs_exe_wrapper=true and disables subproject downloads. Its install_tags
must select library/development data rather than target command-line tools.

Autotools recipes use explicit --host and --build triples. Optional bootstrap
is limited to autoreconf. configure contains argument arrays, not shell text.
Build/install subdirectories and generated public headers can be declared
when an upstream package also contains unrelated executables.

patches lists repository-owned unified patches relative to the recipe. They
are applied after bootstrap to a fresh disposable source copy. Their hashes
are part of the frozen build identity and verified package provenance. A
changed upstream context fails the build instead of silently skipping a patch.

Source submodules must declare HTTPS URLs and full commits in libraries.toml.
Every gitlink and .gitmodules URL is checked; unknown/nested dependencies and
modified cached sources are rejected. The network is unavailable during the
actual library build. Dependency prefixes include the transitive closure, so
pkg-config cannot fall back to host libraries for indirect dependencies.

Official generated source distributions can declare source_archive as an HTTPS
URL template containing {version}. sources.lock.json records the corresponding
Git tag/commit and archive URL/SHA-256. Refreshing to a newer upstream release
freezes its distribution digest before building; the bytes of an already pinned
release must never change. Cached extracted sources have a complete inventory
and are rejected if modified. No build commands are run while fetching sources.

Known platform requirements
-----------------------------------------
The registry uses published SDK 27.0-dp.1-shared.4, including its native TLS
record archive and header. GLib is enabled; its resolver
interfaces cover the record types required by GIO. glib-networking and libsoup
are enabled after native HTTPS/TLS 1.3/HTTP2, certificate rejection and
cancellation verification. WebKit remains disabled pending platform integration.
See tooling/gio-tls.md and tests/mochios-tls/reproduce.md for scope and reproduction.

See tooling/platform-requirements.json for each port's verification evidence
and limitations. mochiOS uses startup-linked shared libraries; successful
cross-compilation does not establish runtime loading or native OS behavior.
GLib's runtime/devel install contains libraries, headers and code generators.
The gi-compile-repository, gi-decompile-typelib and gi-inspect-typelib command
line tools are bin-devel targets and are excluded from this library-only
package. Installed ELF validation still rejects executables.
Libgcrypt uses the SDK getentropy interface and native libgpg-error locks.
The pinned SDK does not provide mlock, so OS-backed locked memory is not
available in this port. Linux reference tests do not verify mochiOS runtime.

Approval-gated library releases
-----------------------------------------
When reviewed changes reach main, "Build libraries and approve publication"
automatically tests the infrastructure, freezes the reviewed source/SDK plan,
builds in the pinned isolated container and verifies all release artifacts.
The workflow never refreshes upstream source versions directly; source updates
must be reviewed and merged first.

After the build succeeds, the Publish job waits for the library-release
GitHub Environment. A member of mochiOS/devkit-maintainer opens the waiting
run, selects Review deployments, then Approve and deploy. This approves
publication of the entire verified plan; no workflow-dispatch button, manual
archive upload, or separate approval for every library is required.

The publishing job downloads that same run's frozen-plan and verified-libraries,
rechecks the Environment policy, revalidates the exact artifacts and publishes
the selected prereleases. Existing asset bytes are never overwritten. Older
revisions remain available, and failed build/import/hash checks stop publication.

Environment setup (once per repository)
-----------------------------------------
Settings -> Environments -> library-release:

  - Required reviewers: mochiOS/devkit-maintainer only.
  - Deployment branches and tags: selected branches, main only.
  - The team needs read access to the repository; code write access is not
    required for reviewers. Only the publishing job receives contents:write.
  - If the same team member pushes and approves, Prevent self-review must
    remain disabled so that person can approve their own workflow run.

The read-only release-policy job blocks publication if the Environment is
missing, unreadable or no longer requires the selected team. Publication
checks the policy again after approval. Configure protection before enabling
the workflow; an automatically created, unprotected Environment is insufficient.

GitHub's approval UI is documented at:
https://docs.github.com/en/actions/how-tos/managing-workflow-runs-and-deployments/managing-deployments/reviewing-deployments

Release layout and verification
-----------------------------------------
Library releases belong to mochiOS/libs, separately from the SDK. Every
build revision uses its own tag, such as libgcrypt-1.12.4-r6. The matching
release contains these three assets:

  <library>-<version>-r<revision>-x86_64-unknown-mochios-mochios-1.tar.gz
  <library>-<version>-r<revision>-x86_64-unknown-mochios-mochios-1.json
  <library>-<version>-r<revision>-x86_64-unknown-mochios-mochios-1.sha256

The archive contains the target sysroot and embedded manifest. The external
JSON binds source, SDK, recipe, verification and file hashes. The checksum
file covers the archive and JSON and is uploaded last as a completion marker.
Changed inputs under an existing build revision require a new revision and
rebuild; publication does not clobber assets to bypass this rule.
Published releases are immutable: later revisions create a new draft and tag,
never append assets to an existing public release. Historical version-only tags
remain untouched. An identical, complete published revision is reused; an
incomplete published revision fails before upload and requires a new revision.
A partial draft can resume uploads and is published only after read-back digest
verification. Environment approval is still required for every publication job.

These are development prereleases verified by cross-compilation and linking.
Only claim native runtime testing when it was actually performed. Local
out/text-port prefixes are development evidence, not distribution archives.
For inspection, download both artifacts from the same run and use a clean
checkout of its exact commit (Python 3.12+ and readelf are required):

  gh run download RUN_ID --repo mochiOS/libs --name frozen-plan --dir out/release-plan
  gh run download RUN_ID --repo mochiOS/libs --name verified-libraries --dir out/release-assets
  python3 tools/releases.py verify --plan out/release-plan/plan.json --artifacts out/release-assets

Upstream update proposals
-----------------------------------------
"Propose upstream library updates" checks enabled libraries daily at 04:23 UTC.
It reads the reviewed upstream repositories, rejects moved baseline tags and
pins newer source commits and official archive hashes. The scanner does not
modify main or publish anything. Disabled/incomplete ports are excluded.

When updates exist, an isolated read-only validation job applies the candidate
registry, runs the infrastructure tests and cross-builds the full dependency
plan. New upstream versions start at r1; unchanged downstream versions receive
new revisions when their dependency inputs change.

A separate PR job creates one grouped update branch/PR and mentions
@mochiOS/devkit-maintainer. Successful candidates are ready for review; failed
candidates are Draft PRs with a link to the failed run. The exact validation
outcome is also recorded on the PR commit as library-update-validation.
The automation neither merges PRs nor publishes releases. After a maintainer
merges an update, the normal main build and Environment approval flow applies.

GitHub does not start another pull_request workflow for PRs created with the
repository GITHUB_TOKEN. Candidate validation therefore runs in this same
scheduled workflow before PR creation, and the PR job attaches its result to
the commit explicitly. Repository branch rules can require the
library-update-validation status for these proposals.

Repeated scans reuse the same proposal branch and PR, without repeating the
team mention. Closed proposals are respected until the candidate changes.
The bot does not force-push or overwrite unrelated maintainer edits to a PR.

Repository setup for PR automation:
Settings -> Actions -> General -> Workflow permissions -> enable
"Allow GitHub Actions to create and approve pull requests". Keep default
workflow permissions read-only; only the PR job requests contents, pull-request
and commit-status writes. The automation never submits approving PR reviews.

The organization policy must also allow this combined GitHub setting. A 409
response stating that the organization forbids PR creation/approval cannot be
resolved at repository level. An organization administrator must enable the
same option in mochiOS organization Settings -> Actions -> General before
the repository option can be enabled. This is an organization-wide policy;
the automation does not change it or substitute a personal access token.

Build output
-----------------------------------------
Build jobs stream compiler/configure output and stderr into the Actions log
while retaining the exact output in out/builds/<input_id>/container.log.
The host reports the library name, package index and stage (source fetch,
container build/link checks, artifact verification/packaging, completion).
Partial lines are shown before process exit, and nonzero exits fail the job.
Build containers start in /work, the explicitly writable output mount. Compiler
and linker detection may create temporary files in their current directory;
starting in the read-only root would make those probes fail. The root, SDK,
source input and dependency mounts retain their read-only protections.
The failure-evidence artifact still retains the full per-library log files.
Upstream console output is not interpreted as GitHub workflow commands.

libxml2 dependency headers
-----------------------------------------
The libxml2 recipe sets NO_SYSTEM_FROM_IMPORTED on its LibXml2 target. CMake
otherwise emits the imported Iconv header directory as -isystem, after the
SDK driver's libc compatibility headers. The SDK iconv.h declares iconv_*;
GNU libiconv's header maps those names to its exported libiconv_* symbols.
Selecting the library without its matching header fails strict import checks.
Keep this override target-local; do not disable SDK import validation or add
ambient host include paths. The regression fixture reproduces the conflicting
headers and verifies that the unpatched build fails and the patched build links.


Unpublished SDK verification
----------------------------
The existing libraries workflow can use the reviewed SDK Actions artifact with
`sdk_candidate=true`. `tooling/sdk-candidate.json` pins the exact successful
SDK workflow run, source commit, runtime sources and required exports. This is
an artifact-only verification build, not an SDK or library release. Candidate
artifacts never reuse published release assets and publication is rejected both
by the workflow and the publisher. The normal production SDK pin stays in
`sdk.lock.toml`; candidate preparation changes that file only in the runner's
disposable checkout. Advancing the candidate requires reviewing a new source
commit and successful SDK build, then updating the tracked candidate policy.

The candidate policy enables Mesa from the ordinary registry only in its
disposable runner checkout. The published SDK build keeps it disabled.
Mesa currently supplies surfaceless EGL/GLES2 through softpipe for port
verification. It requires the candidate shared.5 SDK and is not yet runtime
validated. It does not provide a GPU, window-system backend or a working WebKit
engine. WebKit ports use the same registry, recipes and libraries workflow.