# 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:
| `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/):
| 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.