roxml 0.4.2

Read-only, zero-copy, lazy XML reader for no_std environments, without allocation
Documentation
# Contributing to roxml

Contributions are welcome. Please open an issue or a pull request on
[Codeberg](https://codeberg.org/dibbots/roxml).

## Requirements

- Rust 1.95 or newer (MSRV)
- for coverage: a nightly toolchain with `llvm-tools-preview`
- tools: `cargo install cargo-make cargo-llvm-cov`, optionally `cargo-vet`
- for embedded targets: see [Embedded targets]#embedded-targets

## Checks before a pull request

```sh
cargo fmt --check
cargo clippy --all-targets --all-features
cargo test --all-features
cargo test --no-default-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
```

The tests are integration tests in [`tests`](tests) that use only the public API;
there are no unit tests in `src`. They also run the code examples of the
documentation and of `README.md`.

Keep the test coverage at 100% of the lines:

```sh
cargo make cov       # lcov report in coverage/lcov.info
cargo make cov-html  # html report in target/llvm-cov/html
```

Add an entry to [CHANGELOG.md](CHANGELOG.md) for every user visible change.

## Benchmarks

The benchmarks use [criterion](https://crates.io/crates/criterion):

```sh
cargo make bench-baseline   # save results as baseline 'main'
cargo make bench-compare    # compare against baseline 'main'
```

Run the baseline on the unchanged code before comparing a change.

## Design rules

- No allocation in the core: everything returned borrows from the source.
  Anything needing an allocator goes behind feature `alloc`.
- No intermediate representation: navigation scans the source on demand.
- Errors are reported only by `XmlReader::root_element()`; once a root element
  exists, navigation must not fail.
- Every public item is documented, entry points with an example.

## Supply chain

Dependencies are audited with [cargo-vet](https://mozilla.github.io/cargo-vet/), see
[`supply-chain`](supply-chain). After adding or updating a dependency run `cargo vet`.

## Embedded targets

The folder [`embedded`](embedded) contains three applications, each for two frameworks:

| Application | Purpose                                         |
|-------------|-------------------------------------------------|
| `usage`     | example of reading a configuration document     |
| `testing`   | tests running on the target                     |
| `benchmark` | timing of parsing and navigation on the target  |

### Ariel OS

The Ariel OS applications in [`embedded/ariel-os`](embedded/ariel-os) are a
[laze](https://github.com/kaspar030/laze) project; Ariel OS is fetched by laze.

```sh
./verify_embedded_compile.sh           # build usage and benchmark for all supported boards
./run_embedded_tests.sh <board>        # run testing, benchmark and usage on a connected board
laze build -b <board> -C embedded/ariel-os/usage run   # a single application
```

`<board>` is an Ariel OS board name, e.g. `rpi-pico2`, `nrf52840dk` or
`espressif-esp32-s3-devkitc-1`. The supported boards are listed in
`verify_embedded_compile.sh`.

### Embassy

The Embassy applications in [`embedded/embassy`](embedded/embassy) are one crate per
board, sharing the code in `common`. They are flashed with
[probe-rs](https://probe.rs/):

| Board                     | Folder       | Target                     |
|---------------------------|--------------|----------------------------|
| nRF52840 DK               | `nrf52840dk` | `thumbv7em-none-eabihf`    |
| Raspberry Pi Pico 2       | `rp235x`     | `thumbv8m.main-none-eabihf`|
| ESP32-S3 (e.g. XIAO)      | `esp32_s3`   | `xtensa-esp32s3-none-elf`, needs the `esp` toolchain from [espup]https://github.com/esp-rs/espup |

```sh
cd embedded/embassy/<board>
cargo run --release --bin usage
cargo run --release --bin benchmark
cargo test --release              # runs the tests on the target with embedded-test
```

### ESP32-S3 with probe-rs

probe-rs talks to the ESP32-S3 through the chip's native USB port (USB-Serial/JTAG).
Connect **only** that port. On boards with a second USB port for a USB-to-UART chip
(e.g. ESP32-S3-DevKitC-1), a cable in that port can pull GPIO0 (BOOT) low at power-on,
so the chip latches download mode.

A reset over USB-Serial/JTAG does not leave download mode. probe-rs then flashes
successfully, but the firmware never starts: no log lines appear, tests time out after
60 s, and the stack trace shows core 0 in the ROM (addresses `0x4004…`).

To recover, unplug the board completely and plug in only the native USB port, without
pressing BOOT. The same applies after flashing with espflash in download mode.
`espflash monitor` on the UART port shows the boot mode after a RESET:
`boot:0x8 (SPI_FAST_FLASH_BOOT)` is correct, `boot:0x0 (DOWNLOAD…)` is not.