This is the documentation of DiMA . The newest release is .
This documentation of the development version includes changes that are not released yet. The newest release is .
Development setup
The repository holds the library, the command line, the desktop app, the generators of the
documentation and citation files, the independent reference implementation used as a test
oracle, the test datasets and this documentation site. The working agreements for every change
are in Working agreements (the repository’s AGENTS.md).
Requirements
Section titled “Requirements”- Rust through rustup: the repository’s
rust-toolchain.tomlselects the stable toolchain withclippyandrustfmt. The minimum supported versions are 1.85 for the library and the command line and 1.95 for the desktop app, and both are tested. - Desktop app on Linux: the X11, Wayland and Vulkan development packages listed in
scripts/ci/install-gui-deps.sh. - Python 3.10 or newer, standard library only, for the reference implementation.
- Documentation: Node.js 24 (the version in
docs/.node-version) and pnpm (the exact version is pinned indocs/package.json;corepack enableprovides it).
Build and run
Section titled “Build and run”git clone https://github.com/ShanWeera/dima-perfcd dima-perfcargo build # library and command line (debug)cargo run -p dima -- analyze -i samples/mers_spike_aa.fasta -o /tmp/mers.jsoncargo run -p dima-gui # the desktop appcargo build --release -p dima # an optimised binary in target/release/A bare cargo build or cargo test covers the library and the command line; the desktop app is
built with -p dima-gui or --workspace.
Before every change
Section titled “Before every change”Run, in this order (cargo fmt first, because clippy checks the formatted code):
cargo fmt --all --checkcargo clippy --workspace --all-targets --locked -- -D warningscargo test --workspace --lockedRUSTUP_TOOLCHAIN=1.85 cargo test -p dima-core -p dima --locked # minimum Rust, core and CLIRUSTUP_TOOLCHAIN=1.95 cargo check -p dima-gui --all-targets --locked # minimum Rust, desktop appcargo xtask gen --mode checkRUSTDOCFLAGS="-D warnings" cargo doc --no-deps -p dima-core -p dima --locked # API docscargo bench --no-run -p dima-core --locked # benchmarks compilepython3 scripts/reference/dima_reference.py --self-testpython3 scripts/release/check-windows-crt.py --self-testpnpm -C docs install --frozen-lockfile && pnpm -C docs build # after documentation changesGenerated files
Section titled “Generated files”Some files are generated from the code and must never be edited by hand:
| File | Generated from |
|---|---|
docs/src/content/docs/reference/cli.md | the command-line definitions (crates/dima/src/cli) |
docs/src/content/docs/reference/bibliography.md, docs/src/references.json, docs/src/references.bib | the citation registry (crates/dima-core/src/citations.rs) |
CITATION.cff, .zenodo.json | the citation registry and the workspace version |
README.md (its citation section only) | the citation registry |
THIRD-PARTY-NOTICES.md | the dependency tree (python3 scripts/notices/generate.py, with cargo-about) |
cargo xtask gen --mode write # regenerate after changing options, help texts or referencescargo xtask gen --mode check # what CI runs: fails if a generated file is out of dateCheck mode also compares the citation registry with a stored Crossref snapshot
(xtask/data/crossref_snapshot.json); scripts/citations/crossref.py fetches every DOI from
Crossref again and reports where the snapshot differs (it changes nothing: check each difference,
then update the snapshot and the registry by hand).
Adding a reference
Section titled “Adding a reference”Every citation — in help texts, the desktop app’s tooltips, the results’ run.references and
these pages — comes from crates/dima-core/src/citations.rs (records with a DOI live in
citations_data.rs, sorted by key). Add the record there with its tier (domain, general or
standard; see the citation policy), run
cargo xtask gen --mode write, then cite it in the documentation by its key, for example
[@chao2013], with a locator, [@list2017, Rule 5], or several works at once,
[@seemann2013; @list2017, Rule 5], and end the page with a ## References heading followed by
a paragraph that contains only [^ref]. The site renders citations and the page’s reference
list from docs/src/references.json, so their texts are those of dima cite (led by a
standard’s designation, and with a year letter where the label has one) and of the Bibliography
page (docs/plugins/rehype-registry-citations.mjs). The build fails on an unknown
key, an empty locator, a citation inside a link, and a page with citations but no [^ref], or
the reverse.
The documentation site
Section titled “The documentation site”pnpm -C docs install --frozen-lockfilepnpm -C docs dev # live preview at http://localhost:4321/dima-perf/latest/pnpm -C docs run check # type and content checkspnpm -C docs run build # the site in docs/dist/, with internal link validationpnpm -C docs run test:a11y # WCAG 2.2 AA scan of every page (needs Chrome or Chromium)pnpm -C docs run test:lighthouse # Lighthouse budget (docs/lighthouserc.cjs)The site is built with Starlight. Pages are Markdown or MDX in
docs/src/content/docs/; link to other pages by their path without the base, such as
/reference/cli/, and the build adds the base path of the version being built (DOCS_BASE,
default /dima-perf/latest/). Formulas are written in TeX between $…$ and $$…$$, numbered
with \label{…} and referenced with $\eqref{…}$; they are rendered by MathJax with MathML for
screen readers. The accessibility and Lighthouse checks use an installed Chrome, or the browser
named by CHROME_PATH.
Making a release
Section titled “Making a release”- Set the new version in the workspace
Cargo.toml([workspace.package] version, following Semantic Versioning) and runcargo buildto updateCargo.lock. - Give the release a dated section in
CHANGELOG.md(## [X.Y.Z] - YYYY-MM-DD); the release notes are taken from it. - Run
cargo xtask gen --mode write(CITATION.cff,.zenodo.jsonand the README citation carry the version), thencargo xtask gen --mode check: it also lists every hand-written version number to update, in the install page, the citing page, the README and the Bioconda recipe. - Run the checks of Before every change, commit, and merge into
master. - Start the release: on GitHub, open Actions, choose Release, then Run workflow on
masterand enter the version (X.Y.Z). Pushing a tagvX.Y.Zdoes the same. The release workflow refuses a version that does not match the workspace version, has no dated changelog section or already has a release, runs the full CI suite, builds and checks every package, and publishes the release with its checksums and attestations. A run started from the Actions page releases the newestmastercommit at the time it starts and tags itvX.Y.Zat once; if the run fails or is cancelled, the tag is removed again, so its failed jobs can be re-run or a new run started. Only one release runs at a time. The documentation of the new version is then published at/dima-perf/vX.Y/. Do not create the release on GitHub’s release page: the workflow creates it.
Other scripts
Section titled “Other scripts”| Script | Purpose |
|---|---|
scripts/validate_paper.sh | Prints the comparison with the paper’s published values (Comparison with the paper) |
scripts/bench/run.sh | Regenerates BENCHMARK.md (Benchmarks) |
scripts/reference/dima_reference.py | The independent reference implementation (Testing) |
scripts/release/check-windows-crt.py | Checks that Windows programs need no Visual C++ runtime DLL, by reading their import tables; CI and the release workflow run it on every Windows program |