Skip to content

Fix README doctest path so the published crate can be tested - #315

Open
npuichigo wants to merge 1 commit into
garvys-org:mainfrom
npuichigo:fix-packaged-readme-doctest
Open

Fix README doctest path so the published crate can be tested#315
npuichigo wants to merge 1 commit into
garvys-org:mainfrom
npuichigo:fix-packaged-readme-doctest

Conversation

@npuichigo

Copy link
Copy Markdown

Problem

cargo test fails to compile on the crate as published to crates.io:

error: couldn't read `.../rustfst-1.3.1/src/../../README.md`:
       No such file or directory (os error 2)
error: could not compile `rustfst` (lib test)

Reproduce without a checkout:

cargo new /tmp/repro && cd /tmp/repro
cargo add rustfst@1.3.1
cargo vendor >/dev/null && cd vendor/rustfst && cargo test

Cause

rustfst/src/lib.rs has:

#[cfg(test)]
doc_comment!(include_str!("../../README.md"));

../../README.md is correct in the repository — from rustfst/src/ it
resolves to the workspace-root README.

It is wrong in the published package. readme = '../README.md' makes Cargo
copy that file into the package root, so inside the package the README sits next
to src/ and ../../README.md points outside the package.

Normal builds are unaffected because the include is #[cfg(test)], but anyone
vendoring the crate or running its test suite from the registry copy hits it.

Fix

Add rustfst/README.md as a symlink to the workspace README, point readme at
it, and include it as ../README.md — a path that resolves identically in the
repository and in the package. Cargo follows symlinks when packaging, so the
release still ships a real README at the crate root.

Verification

  • cargo package --list yields the same README.md entry as before the change.
  • cargo test --lib --no-run compiles in-repo.
  • Patching the vendored 1.3.1 package the same way makes its lib test target
    compile (it previously failed at compile time). The remaining tests_openfst
    failures there are unrelated and pre-existing — those tests need the
    rustfst-tests-data directory, which is not part of the published package.

One thing to check

generate_readme_from_rustdoc.sh runs cargo sync-readme -f lib from
rustfst/. Writing through the symlink updates the workspace README as before,
but if cargo-sync-readme replaces the file rather than writing through it, the
symlink would be clobbered and would need restoring. I could not verify that
behaviour here.

If you would rather avoid a symlink, two alternatives:

  • keep readme = '../README.md' and move the README doctest into an integration
    test under rustfst/tests/, where the packaged path is stable; or
  • drop the doc_comment! include entirely if the README examples are covered
    elsewhere.

Happy to switch to whichever you prefer.

`rustfst/src/lib.rs` pulls the README into the doctests with
`include_str!("../../README.md")`. That path is correct in the repository,
where it resolves to the workspace-root README, but wrong in the published
package: Cargo copies the file named by `readme` into the package root, so
inside the package the README sits next to `src/` and `../../README.md`
points outside the package entirely.

As a result `cargo test` fails to compile on the crates.io release:

    error: couldn't read `.../rustfst-1.3.1/src/../../README.md`:
           No such file or directory (os error 2)
    error: could not compile `rustfst` (lib test)

Normal builds were unaffected because the include is `#[cfg(test)]`, but
anyone vendoring the crate or running its tests from the registry copy hits
this.

Add `rustfst/README.md` as a symlink to the workspace README, point
`readme` at it, and include it as `../README.md`, which now resolves
identically in the repository and in the published package. Cargo follows
symlinks when packaging, so the release still ships a real README at the
crate root.

Verified: `cargo package --list` produces the same `README.md` entry as
before, and `cargo test --lib --no-run` now compiles in-repo.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant