update docs
This commit is contained in:
@@ -0,0 +1,246 @@
|
||||
# Troubleshooting the build
|
||||
|
||||
Development reference and historical context. For current operating instructions, use the [user manual](../README.md). Acceptance applies only to the source and artifacts identified in each record.
|
||||
|
||||
|
||||
[Documentation index](README.md) · [First build](getting-started.md) · [Build reference](build-host.md)
|
||||
|
||||
Find the first failing command or `ERROR:` in the log, fix that problem, then
|
||||
repeat the same step. Do not continue past a failed bootstrap and interpret later
|
||||
missing files as independent problems. Run all commands below from the repository
|
||||
root, as your regular user, unless explicitly shown otherwise.
|
||||
|
||||
## Find the right log
|
||||
|
||||
| Failing action | Where to look |
|
||||
| --- | --- |
|
||||
| `make bootstrap` | `out/logs/bootstrap.log` |
|
||||
| Void build-container creation | `out/logs/xbps-bootstrap.log` |
|
||||
| `make smoke-test` | `out/logs/smoke-test.log` |
|
||||
| GNU hello build | `out/logs/xbps-hello.log` |
|
||||
| `make check` | Terminal output; this target does not save a log automatically |
|
||||
|
||||
For example, after a failed smoke-test:
|
||||
|
||||
```sh
|
||||
tail -n 80 out/logs/smoke-test.log
|
||||
rg -n 'ERROR:|FAILED|error:|No space left|Permission denied' out/logs/
|
||||
df -h .
|
||||
```
|
||||
|
||||
A search with no matches exits 1. Read the surrounding log too: upstream tools
|
||||
may report failures using other wording. Save logs before re-running if you need
|
||||
the previous output; see [Development](development.md#preserve-logs-and-identify-inputs).
|
||||
|
||||
## Unsupported host, root execution, or missing commands
|
||||
|
||||
- `M0 requires an x86_64 Linux build host` or `supports Arch Linux`: use the
|
||||
supported host described in [Your first build](getting-started.md). Changing
|
||||
the check alone does not port the build system to another platform.
|
||||
- `Run as a normal user, not root`: leave the root shell and run the build from
|
||||
your normal account. Only host package installation uses sudo.
|
||||
- `Missing host command`: install the prerequisites from the first-build guide,
|
||||
then repeat bootstrap. `readelf` comes from binutils, `bwrap` from bubblewrap,
|
||||
and `flock` from util-linux.
|
||||
- `checkout path without whitespace`: move or obtain the checkout at a path
|
||||
with no spaces, tabs, or other whitespace, then use that directory consistently.
|
||||
|
||||
If a previous root-run left files that your account cannot write, inspect their
|
||||
ownership before correcting it. Do not respond by running all later builds as root.
|
||||
|
||||
## Bubblewrap or user namespace failure
|
||||
|
||||
Reproduce the same capability check bootstrap uses:
|
||||
|
||||
```sh
|
||||
bwrap --ro-bind / / --unshare-user --uid 0 --gid 0 true
|
||||
```
|
||||
|
||||
If it reports `Operation not permitted` or a namespace error, the host kernel,
|
||||
container policy, or security configuration prevents the unprivileged container.
|
||||
Use an Arch host that permits this operation, or have the host administrator
|
||||
resolve the restriction. Repeated downloads, sudo builds, and a different Pi
|
||||
will not resolve this preflight failure. Success is a zero exit status with no
|
||||
output; run `make bootstrap` again once that works.
|
||||
|
||||
## Void submodule missing, wrong, or modified
|
||||
|
||||
Inspect before changing anything:
|
||||
|
||||
```sh
|
||||
cat VOID_PACKAGES_COMMIT
|
||||
git submodule status vendor/void-packages
|
||||
git -C vendor/void-packages status --short
|
||||
git -C vendor/void-packages diff HEAD --
|
||||
```
|
||||
|
||||
If the submodule is missing, `make bootstrap` initializes it. The directory must
|
||||
be part of a Git checkout; an unpacked source archive is insufficient. If a clone
|
||||
was interrupted by a network error, restore connectivity and repeat bootstrap.
|
||||
|
||||
`Void checkout mismatch` means the checked-out commit differs from the explicit
|
||||
pin. A `+` in `git submodule status` means it differs from the parent repository's
|
||||
gitlink. These are two separate checks. Do not update the pin merely to silence
|
||||
the error; first determine why the commits differ.
|
||||
|
||||
`Tracked Void files were changed` means upstream source has local edits. Preserve
|
||||
and review the diff. Move intentional FDS changes into the overlay design or a
|
||||
separate patch for review; restore upstream only after saving work you need.
|
||||
Generated ignored files such as `etc/conf`, `hostdir`, and the masterdir are
|
||||
normal. Never use a broad reset or clean command without checking what it removes.
|
||||
|
||||
## Configuration or overlay conflict
|
||||
|
||||
For `etc/conf differs from config/xbps-src.conf`, compare the two:
|
||||
|
||||
```sh
|
||||
diff -u vendor/void-packages/etc/conf config/xbps-src.conf
|
||||
```
|
||||
|
||||
Put the desired settings in `config/xbps-src.conf`, then follow
|
||||
[the explicit synchronization procedure](development.md#change-build-configuration-deliberately).
|
||||
A `diff` exit status of 1 means differences were found, not that the comparison failed.
|
||||
|
||||
For `Stale overlay`, compare the named `vendor/void-packages/srcpkgs/fds-*`
|
||||
directory with its source under `packages/`. Preserve any unique edits in the
|
||||
source first. Move that specific generated copy into a backup directory under
|
||||
`out/`, outside `srcpkgs/`, then run `./tools/prepare-void` again. Do not move or
|
||||
remove unrelated upstream packages. The Dasung package is now an active overlay. After changing it, reconcile that
|
||||
generated copy by this same procedure before rebuilding.
|
||||
|
||||
`Overlay would replace an upstream package` is an intentional protection. Choose
|
||||
an FDS-owned package name and design an overlay; do not disable the check or edit
|
||||
the tracked upstream template in place.
|
||||
|
||||
## Download failure, checksum mismatch, or apparent stall
|
||||
|
||||
Bootstrap and package builds need network access. The first run can spend much
|
||||
of its time downloading compiler packages. Read the latest log and check disk
|
||||
space before assuming that a quiet download is a deadlock:
|
||||
|
||||
```sh
|
||||
tail -n 40 out/logs/bootstrap.log
|
||||
tail -n 40 out/logs/xbps-hello.log
|
||||
du -sh out/downloads vendor/void-packages/hostdir
|
||||
df -h .
|
||||
```
|
||||
|
||||
A log or directory may not exist if its step has not started. Bootstrap's static
|
||||
XBPS download has retries and a timeout; an incomplete transfer uses a `.part`
|
||||
filename. A retry re-downloads that partial file. Completed cached archives are
|
||||
checksum-checked on every bootstrap.
|
||||
|
||||
For a checksum failure, retain the error and compare the named file against
|
||||
`config/host-tools.conf`. If the cached completed archive is corrupt, move that
|
||||
specific archive to a backup location and repeat bootstrap so it downloads again.
|
||||
Do not change the expected hash to match an unexplained download. If a clean
|
||||
re-download still disagrees, stop and investigate the source.
|
||||
|
||||
A Void mirror timeout is separate from the source pin: the templates are pinned,
|
||||
but bootstrap and missing build dependencies still use rolling binary repositories.
|
||||
An unavailable historical dependency may need a reviewed input/mirror solution;
|
||||
blindly changing the source commit does not establish an equivalent build.
|
||||
|
||||
## XBPS command not found or package index seems empty
|
||||
|
||||
The XBPS tools are intentionally not installed in the host's `/usr/bin`.
|
||||
`make bootstrap` creates `.host/xbps/usr/bin/`. FDS build helpers set PATH for you.
|
||||
For manual queries, use the explicit paths in the [package guide](packages.md).
|
||||
|
||||
When querying or indexing ARM output, set `XBPS_ARCH=aarch64`. The host's static
|
||||
musl executable can otherwise default to its own architecture and ignore the ARM
|
||||
package. `make smoke-test` uses the correct override. `tools/build-package` exports
|
||||
packages but does not update `out/packages/aarch64-repodata`; use the indexing
|
||||
command in the package guide after a standalone package build.
|
||||
|
||||
## Rust target, linker, or architecture error
|
||||
|
||||
Check the selected toolchain and local configuration:
|
||||
|
||||
```sh
|
||||
rustup show active-toolchain
|
||||
rustup target list --installed
|
||||
cat rust-toolchain.toml
|
||||
cat .cargo/config.toml
|
||||
printenv RUSTFLAGS CARGO_BUILD_TARGET CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_LINKER
|
||||
```
|
||||
|
||||
`printenv` exits nonzero when a listed variable is unset; that is normal here.
|
||||
Bootstrap installs the required target and rustfmt for the pinned toolchain.
|
||||
Repeat it if those components are missing.
|
||||
|
||||
Build from the repository root with the exact Cargo command in
|
||||
[Development](development.md#edit-and-rebuild-the-rust-program). Environment
|
||||
variables, command-line `+toolchain` overrides, or outside Cargo configuration
|
||||
can change the target, flags, or linker. Reconcile such overrides with the
|
||||
checked-in `rust-lld` and static CRT configuration. Adding an arbitrary system
|
||||
linker or glibc library is not a repair for a static-musl build.
|
||||
|
||||
## Exec format error, ldd output, and QEMU skips
|
||||
|
||||
`./out/fds-smoketest` normally gives `Exec format error` on x86_64: it is an ARM
|
||||
program. Run it explicitly with optional `qemu-aarch64`, as described in
|
||||
[the first-build guide](getting-started.md#7-optionally-execute-the-arm-rust-program).
|
||||
Do not change the target to x86_64 merely to make direct execution work.
|
||||
|
||||
`ldd: not a dynamic executable` with exit 1 is expected for the static program.
|
||||
Use `./tools/verify-elf out/fds-smoketest aarch64 static` for the actual check.
|
||||
Host `ldd` cannot establish that a foreign ARM program will run.
|
||||
|
||||
`SKIP: ARM execution` means QEMU is absent. Compilation and ELF checks still run.
|
||||
If QEMU is present but fails, the smoke-test must fail; inspect its diagnostic.
|
||||
The dynamic GNU hello program also requires an ARM glibc loader and libraries,
|
||||
so the simple static-program QEMU command is not a complete hello runtime setup.
|
||||
|
||||
## Missing artifacts or check fails before any build
|
||||
|
||||
`make check` expects the Cargo release artifact in `target/`. Run the Rust build
|
||||
or `make smoke-test` first. A bare Cargo build updates `target/`, while
|
||||
`make smoke-test` also refreshes `out/fds-smoketest` and the output manifests.
|
||||
If checksums fail after editing or replacing outputs, inspect what changed and
|
||||
rebuild through smoke-test; do not edit the manifest to conceal a mismatch.
|
||||
|
||||
For a Rust formatting failure, run `cargo fmt --all`, inspect the source diff,
|
||||
then repeat `make check`.
|
||||
|
||||
## Busy /tmp message during Void bootstrap
|
||||
|
||||
The initial verified bootstrap emitted
|
||||
`rm: cannot remove '//tmp': Device or resource busy` during upstream cleanup.
|
||||
The bubblewrap bind mount explained that instance; upstream exited successfully,
|
||||
and container GCC, the cross build, and the public M0 commands all passed.
|
||||
|
||||
Do not treat every later `/tmp` error as harmless. Confirm a zero command exit
|
||||
status and the final bootstrap PASS, then run smoke-test. If the command exits
|
||||
nonzero, report it as a failure with the surrounding log.
|
||||
|
||||
## Rootfs, images, and runtime commands
|
||||
|
||||
M1 implements `make rootfs PROFILE=cli` and `make rootfs-test`. If the target is
|
||||
missing, check that you are in the current checkout. Read [M1 rootfs](rootfs.md)
|
||||
for prerequisites, shell access, logs, and retained failed-build directories.
|
||||
Python 3.14+ is required for XBPS archive inspection. Supported profiles are
|
||||
`cli`, `development`, and `recovery`; unknown names fail explicitly. Package
|
||||
configuration must pass before an archive is published.
|
||||
|
||||
`tools/in-rootfs` supports ARM child execution through a private user-namespace
|
||||
binary-format handler. It requires Linux 6.7+ and namespaced `binfmt_misc` support.
|
||||
The workstation's global registry is unchanged. For a single ELF executable,
|
||||
`--direct` invokes QEMU without installing even a private child-execution handler.
|
||||
For example: `./tools/in-rootfs out/rootfs-aarch64 --direct /usr/bin/xbps-pkgdb -a`.
|
||||
|
||||
The tar is configured userspace, not a flashable image. M2 adds `make init-test`
|
||||
for a full ARM boot and `make vm` for a temporary development shell. Follow
|
||||
[Native init and ARM VM](init.md) for its dependencies, expected output, and
|
||||
failure logs. For the full kernel/stage0/SYSTEM path, use `make all`,
|
||||
`make boot-test`, then `make console-vm`. Run `fds bays` and `fds poweroff`
|
||||
inside the booted FDS console, not on the Arch host. An exported ARM binary will
|
||||
not execute directly on x86_64. Physical Pi acceptance remains deferred.
|
||||
|
||||
## What to include in a bug report
|
||||
|
||||
Include the exact failing command, its exit status if available, the relevant log
|
||||
excerpt, host distribution and architecture, current Void pin, and whether this
|
||||
is the first build or a previously working checkout. Mention local configuration
|
||||
changes and toolchain overrides. Preserve the initial error; a later missing-file
|
||||
message often only describes its consequence.
|
||||
Reference in New Issue
Block a user