okooooooo/UniXNU
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: point AGENTS.md to docs and sync CONTRIBUTING.md with the site

Browse Source
This commit is contained in:
UniXNU Docs committed 2026-10-25 05:40:06 +08:00
1 parent 9d18904512
commit 2ed313fd5f
2 files changed
+46 -196
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

AGENTS.md
+1 -135
View File
@@ -1,135 +1 @@
# UniXNU agent guide
## Responsibility
UniXNU owns the build tools, component catalog, ARM64 support, OS profiles,
UEFI package, device template, and documentation site. SoC repositories own
shared hardware descriptions and platform operations. Device repositories own
board peripherals, firmware selections, partition layouts, and packaging.
Component repositories own drivers, libraries, loaders, and tools.
## Required reading
Read the root `AGENTS.md` and `README.md` of each repository you edit. Read these
files in UniXNU before selecting components or changing a port:
| Task | Required reading |
| --- | --- |
| Every port | `docs/porting/index.md`, `docs/porting/soc-support.md`, `docs/porting/device-repository.md`, `docs/reference/components.md`, `components.toml` |
| Hardware description | `docs/porting/device-tree.md`, `docs/drivers/device-tree-matching.md`, selected SoC `README.md`, `soc.toml`, DTSI and bindings |
| Component work | Component page under `docs/drivers/`, component `README.md`, catalog build command, dependencies, and relevant source |
| Kernel work | `docs/xnu/source-and-patches.md`, `docs/xnu/patch-reference.md`, selected OS `profile.toml`, XNU source and ordered patch series |
| Image assembly | `docs/concepts/prelink.md`, `docs/concepts/payload.md`, `docs/porting/uefi-firmware.md`, device firmware configuration |
| Verification | `docs/building.md`, `docs/porting/bring-up.md`, `docs/porting/log-capture.md`, selected device page |
| Migration | `docs/porting/migration.md` |
| Documentation | `docs/contributing/documentation.md` |
The published documentation is at https://unixnu.com. Site sources,
navigation, translations, assets, build configuration, and deployment belong
to this repository. Update English and Chinese pages together.
Link every documentation page from a relevant guide or topic index reachable
through body links from `docs/porting/index.md` and its Chinese edition.
Keep prerequisites and next steps in the page body.
Task pages list inputs, working directory, ordered operations and expected results.
Link field and implementation references to the corresponding task procedure.
## Component discovery
1. Search `components.toml` by function, hardware, scope, and dependencies.
2. Read the candidate's page, README, build command, and implementation.
3. Check its OS ABI, board inputs, and verified devices separately.
4. Reuse the component when its interfaces match the port. Add shared SoC
operations to the SoC repository and board policy to the device repository.
5. Add a component when existing implementations leave a concrete requirement
uncovered. Record its dependencies and required inputs in the catalog.
Use canonical component IDs for selections, paths, commands, and outputs.
Official compatibility names resolve through repository identity. Community
forks keep their repository identity. Preserve source filenames, runtime
classes, bundle identifiers, plugin filenames, symbols, and protocols; record
these in `runtime_identifiers`.
## Configuration
Format 2 uses `schema_version = 2`. Resolve ARM64, SoC, OS, and device profiles
in that order. Tables merge by key; ordinary arrays replace. List every required
component, configuration fragment, and patch series in the effective arrays.
The selected defconfig follows the configuration fragments.
New ports and migrations use the completion checklist and publication steps in
`docs/porting/device-repository.md`. Keep the template and both workflows aligned.
Published device repositories carry the `unixnu` GitHub topic.
Pin SoC and component sources. Inspect `unixnu status --json` before building.
Place generated sources, patched XNU, and outputs in the resolved target tree.
## Commands
Run from the UniXNU checkout:
```sh
./unixnu defconfig sheng_defconfig -D ../UniXNU-sheng
./unixnu fetch
./unixnu status --json
./unixnu tree
./unixnu build kernel
./unixnu build package
./unixnu build firmware --uefi ../uefi-sheng
./unixnu build payload --unique-chip-id <hex> --trust-cache <bundle> --data-ramdisk <seed>
./unixnu bootimg --uefi ../uefi-sheng --dtb <firmware.dtb>
```
Use the selected device's documented inputs. For documentation:
```sh
cd docs
npm ci
npm run build
```
For a Mu-Silicium initrd payload, include `UniXNURamDiskDxe`, DiskIoDxe and
FAT support in the firmware DSC and FDF. Run `./unixnu build firmware` and
build the payload before `./unixnu bootimg`. Follow
[required firmware integration](https://unixnu.com/porting/uefi-firmware#required-integration).
## Verification and reporting
Run existing checks and targeted build exercises for changed behavior. Add a
test when a credible future edit would cause a specific device failure that
existing checks miss. Report the command, selected profiles, source revisions,
output path, result, and unresolved input. Report hardware boot, storage,
display, input, and GPU observations separately from host builds.
Preserve unrelated working-tree changes. Keep documentation concise and describe
current behavior. Use standard terms, neutral headings, and ordinary punctuation.
## Porting record
Read the device's `porting.toml` and the
[record guide](https://unixnu.com/porting/records) before implementation.
For storage, also read the [UFS guide](https://unixnu.com/porting/ufs).
Update each affected area's findings or evidence with its code change.
The documentation site renders this same record. Follow its schema and
completion levels for both maintainer and agent work.
## Local builds and boot diagnosis
Copy `unixnu.example.toml` to `unixnu.local.toml` in the main checkout and fill
in device inputs using the [configuration reference](https://unixnu.com/reference/configuration#local-build-inputs).
Read [boot arguments](https://unixnu.com/xnu/boot-arguments#apply-arguments)
before changing the command line. Rebuild the payload and boot image after
argument changes. Use the [green-bar diagnosis](https://unixnu.com/guide/debugging#green-bar)
for stalls at loader handoff. Record the last confirmed stage and relevant logs.
## Hardware adaptation
Follow [Port a device](https://unixnu.com/porting/) in order. Read the
[driver adaptation checklist](https://unixnu.com/porting/drivers) before selecting
components. Follow each subsystem guide for board inputs, implementation paths,
archive integration and expected results. Include board-package services such as
brightness, buttons, Wi-Fi, DSP, battery and CPU frequency in the porting record.
Driver guides describe implementation steps for the selected hardware. Link exact
source files and relevant symbols, identify the interface to implement, and give
build integration and observable results. Use board implementations as examples.
Keep board status in device records and cite reviewed source revisions.
See docs/.
CONTRIBUTING.md
+45 -61
View File
@@ -1,28 +1,37 @@
# Contributing to UniXNU
Read [AGENTS.md](AGENTS.md) and the [documentation](https://unixnu.com) before changing the build driver, the kernel patches or a device port. The [repository layout](https://unixnu.com/contributing/repository) page describes the module system.
Read the [documentation](https://unixnu.com) before changing the build driver, the kernel patches or a device port. The source is in `docs/`. The [repository layout](https://unixnu.com/contributing/repository) page describes the module system.
## Repository scope
| Repository | Changes |
| Repository | Responsibility |
| --- | --- |
| `UniXNU` | Build tools, component catalog, ARM64 and OS profiles, template, UEFI package and documentation site |
| `UniXNU-<soc>-common` | SoC configuration, DTSI, platform operations and patches |
| `UniXNU-<device>` | Board DTS, peripheral inputs, component selection, partition layout and packaging |
| Component repository | Driver, library, loader or tool with a defined hardware, protocol or functional scope |
| `uefi-<device>` | Mu-Silicium UEFI port |
| `UniXNU` | Build tools, component catalog, ARM64 support, OS profiles, template, UEFI package, documentation site |
| `UniXNU-<soc>-common` | Shared SoC configuration, DTSI, platform operations, patch series |
| `UniXNU-<device>` | Board DTS, peripherals, selected components, partitions, packaging |
| Component repositories | Drivers, libraries, loaders, tools |
| `uefi-<device>` | UEFI platform integration |
Board policy belongs in the device repository. Shared SoC operations belong in the SoC repository. Reusable drivers and libraries belong in component repositories. Build tools, ARM64 support, OS profiles and site documentation belong in UniXNU.
Board policy belongs in the device repository. Shared SoC operations belong in the SoC repository. Reusable drivers and libraries belong in component repositories. The site source, navigation, translations, assets, configuration and deployment workflow belong in `UniXNU`.
Profiles select catalog components by canonical ID. Feeds and submodules supply source repositories. Inspect component scope, OS ABI and board dependencies before adding an implementation.
## Component work
1. Search `components.toml` and inspect existing interfaces.
2. Put shared controller or protocol code in its component repository.
3. Put SoC operations and resources in the SoC repository and board policy in the device repository.
4. Record source identity, revision, dependencies, build command, outputs and runtime identifiers.
5. Update consumers, README and the English and Chinese site pages together.
6. Run the affected build commands and record host and hardware results separately.
Canonical names use hardware scope, protocol or function. Repository renames preserve history and pinned revisions. Compatibility aliases use official source identity; community sources keep their own identity.
## Repository topics
Every repository in the UniXNU organization carries the `unixnu` topic. Every independently maintained driver repository also carries the topic before a device repository references it. Add the topic before a repository is linked from the documentation or used as a module.
Every maintained driver repository and every published device repository carries the `unixnu` GitHub topic. See [driver repositories](https://unixnu.com/drivers/repositories) and [device repository](https://unixnu.com/porting/device-repository).
## Private blobs
Do not commit Apple IPSW files, kernelcaches, disk images, trust caches, Data seeds, vendor firmware or other proprietary binaries. Keep them in a local cache or external storage. The macOS runner deletes these inputs after the artifacts are uploaded.
Do not commit Apple IPSW files, kernelcaches, disk images, trust caches, Data seeds, vendor firmware or other proprietary binaries. The device repository lists its inputs in `proprietary-files.txt`; the files stay in `.cache/firmware`.
## Development
@@ -31,60 +40,39 @@ git clone https://github.com/UniXNU/UniXNU
cd UniXNU
./unixnu defconfig <name> -D ../UniXNU-<device>
./unixnu fetch
./unixnu build kernel package firmware payload
./unixnu status --json
./unixnu build kernel
./unixnu build payload
./unixnu bootimg --uefi ../uefi-<device> --dtb <board>.dtb
```
Use `--local-module` or `--local` to test a module from a working directory without committing it.
## Change guidelines
## Kernel patches
- State the current behavior in the code and documentation.
- Keep one subject per commit.
- Add a test when it prevents a failure a future edit would introduce. A behavior visible on every run needs no assertion.
- Put device-specific values in the device repository.
- Put shared SoC operations in the SoC repository and reusable implementations in component repositories.
- Keep the documentation site, navigation, assets and deployment in `UniXNU`.
- Keep the English and Simplified Chinese documentation pages in sync.
Follow [source and patches](https://unixnu.com/xnu/source-and-patches#procedure):
1. Build the selected kernel once to prepare `out/<device>/<os_profile>/<config>/tree/.cache/xnu-work`.
2. Copy the files to edit into a temporary Git directory with their XNU-relative paths and stage them.
3. Edit the copy and export the patch with `git diff`.
4. Add the patch to the owning series (ARM64, SoC, OS, device or component) in dependency order.
5. Check the order with `./unixnu status --json` and rebuild the kernel.
## Commit messages
```
feat(<area>): <summary>
fix(<area>): <summary>
docs: <summary>
build(<area>): <summary>
chore: <summary>
```
| Prefix | Subject |
| --- | --- |
| `feat(<area>)` | New capability |
| `fix(<area>)` | Defect repair |
| `docs` | Documentation |
| `build(<area>)` | Build system |
| `chore` | Maintenance |
The message describes the change. The documentation describes the resulting state.
## Kernel patches
1. Edit `out/<device>/<os_profile>/<config>/tree/.cache/xnu-work` after kernel preparation.
2. Generate the patch with `git diff`.
3. Add it to the owning profile's patch series in dependency order.
4. Rebuild the kernel and the prelink.
5. Record the kernelcache pin if the ABI changed.
`unixnu status --json` reports the resolved patch order.
## Drivers
- One hardware driver per repository.
- SoC and device profiles select components through `components.toml`.
- A driver is contributed to the UniXNU organization only when it serves an official device or the generic stack. Otherwise it stays independently maintained and is linked as a submodule.
- Every driver repository carries the `unixnu` topic.
- Built-in XNU drivers compile against the recorded XNU flags in `*.cpo.json`.
- UEFI drivers use the EDK II module layout.
- Kext bundles keep the standard bundle layout.
- A driver that touches hardware reports each stage through a boot argument while it is under bring-up.
Commit messages describe changes. Documentation describes current behavior. Keep one subject per commit.
## Documentation
After a device port, contribute the device page and the porting notes to this repository.
The documentation source is in `docs/`. The site is bilingual:
The site is a bilingual VitePress project in `docs/`, published to https://unixnu.com.
| Locale | Path |
| --- | --- |
@@ -98,7 +86,11 @@ npm run dev
npm run build
```
Add a page to both locales and to the sidebar in `docs/.vitepress/config.mts`.
Follow the [documentation procedure](https://unixnu.com/contributing/documentation#procedure). A page change updates both locales in the same pull request. Add a new page to both sidebars in `docs/.vitepress/config.mts` and link it from a page reachable from [Port a device](https://unixnu.com/porting/). `npm run build` fails on a broken internal link.
## Device records
Official devices maintain `porting.toml`. Update the affected areas' findings or evidence with each code change. The site renders the revision pinned in `devices.toml`. See the [record guide](https://unixnu.com/porting/records).
## Security
@@ -107,11 +99,3 @@ Report a security issue privately to the maintainers. Do not open a public issue
## License
Contributions are licensed under BSD-2-Clause-Patent. The `LICENSE` file in each directory applies to that directory.
## Official device records
Update the affected areas in the device's `porting.toml` with each code change.
Use the [record guide](https://unixnu.com/porting/records) for required hardware,
configuration, findings, evidence and completion criteria. The site renders the
same record for maintainers and agents. Official device branches require its CI
check. Board driver submodules belong to device repositories.