Fix README doctest path so the published crate can be tested - #315
Open
npuichigo wants to merge 1 commit into
Open
Fix README doctest path so the published crate can be tested#315npuichigo wants to merge 1 commit into
npuichigo wants to merge 1 commit into
Conversation
`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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
cargo testfails to compile on the crate as published to crates.io:Reproduce without a checkout:
Cause
rustfst/src/lib.rshas:../../README.mdis correct in the repository — fromrustfst/src/itresolves to the workspace-root README.
It is wrong in the published package.
readme = '../README.md'makes Cargocopy that file into the package root, so inside the package the README sits next
to
src/and../../README.mdpoints outside the package.Normal builds are unaffected because the include is
#[cfg(test)], but anyonevendoring the crate or running its test suite from the registry copy hits it.
Fix
Add
rustfst/README.mdas a symlink to the workspace README, pointreadmeatit, and include it as
../README.md— a path that resolves identically in therepository and in the package. Cargo follows symlinks when packaging, so the
release still ships a real README at the crate root.
Verification
cargo package --listyields the sameREADME.mdentry as before the change.cargo test --lib --no-runcompiles in-repo.compile (it previously failed at compile time). The remaining
tests_openfstfailures there are unrelated and pre-existing — those tests need the
rustfst-tests-datadirectory, which is not part of the published package.One thing to check
generate_readme_from_rustdoc.shrunscargo sync-readme -f libfromrustfst/. Writing through the symlink updates the workspace README as before,but if
cargo-sync-readmereplaces the file rather than writing through it, thesymlink would be clobbered and would need restoring. I could not verify that
behaviour here.
If you would rather avoid a symlink, two alternatives:
readme = '../README.md'and move the README doctest into an integrationtest under
rustfst/tests/, where the packaged path is stable; ordoc_comment!include entirely if the README examples are coveredelsewhere.
Happy to switch to whichever you prefer.