Crate Packaging & Path Portability#

When OpenDAL's workspace was split into publishable sub-crates (RFC-6828), file-path assumptions that work in a git checkout began to break in crates.io tarballs. The core issue: include_str! paths that traverse above a sub-crate's own directory resolve correctly in the monorepo but point to non-existent locations in a published package. This issue has been resolved through a combination of path correction and symlink addition as of PR #8223.

The Breaking Pattern#

core/core/src/docs/mod.rs embeds the project changelog. Before the fix, it used:

#[doc = include_str!("../../../CHANGELOG.md")]
pub mod changelog {}

In the repository, ../../../ from core/core/src/docs/ resolved to the repo root, where CHANGELOG.md lives. In a crates.io tarball, however, only the core/core/ subtree is packaged — there is no parent directory, and the path resolved to nothing. This has been corrected to:

#[doc = include_str!("../../CHANGELOG.md")]
pub mod changelog {}

With a symlink at core/core/CHANGELOG.md pointing to ../../CHANGELOG.md, the file is now included in the published package.

How the Bug Was Triggered (v0.59.0, Issue #8222)#

The include_str! line existed for some time but was dormant because the docs module was gated behind a docsrs cfg flag — it only compiled when building for docs.rs. In the older single-crate layout, lib.rs declares:

#[cfg(docsrs)]
pub mod docs;

PR #8183 ("docs: establish OpenDAL specifications") changed core/core/src/lib.rs to expose the module unconditionally — making pub mod docs; always compile. From that point on, cargo check against the published opendal-core = "0.59.0" tarball failed with 2:

error: couldn't read `.../opendal-core-0.59.0/src/docs/../../../CHANGELOG.md`:
The system cannot find the file specified. (os error 2)
  --> .../opendal-core-0.59.0/src/docs/mod.rs:34:9
   |
34 | #[doc = include_str!("../../../CHANGELOG.md")]
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This issue was resolved in PR #8223 by adding a CHANGELOG.md symlink at core/core/CHANGELOG.md pointing to ../../CHANGELOG.md and updating the include_str! path from ../../../CHANGELOG.md to ../../CHANGELOG.md.

Root Causes#

1. include_str! paths that escape the crate root. Any path that traverses above the crate's top-level directory (../../.. from a deeply nested source file) will be valid in the monorepo but absent from the crates.io tarball.

2. Unconditional module exposure. When a module containing cross-boundary include_str! calls is only compiled under #[cfg(docsrs)], the build-time file resolution is deferred to docs.rs (where the full repo layout is available). Removing that guard surfaces the latent breakage for all users.

3. Missing include field in Cargo.toml. core/core/Cargo.toml uses exclude = ["/tests/"] but has no include field 3. Without an explicit include, only files inside the crate root are packed — cross-boundary file references are silently absent.

Resolution Patterns#

The symlink approach is the least invasive because cargo publish follows symlinks and includes their target content in the tarball. It keeps the include_str! path short and requires minimal source code changes.

Key Files#

• core/core/src/docs/mod.rs — contains the corrected include_str!("../../CHANGELOG.md") call 1
• core/core/CHANGELOG.md — symlink pointing to ../../CHANGELOG.md, added in PR #8223
• core/core/Cargo.toml — missing include field; only has exclude = ["/tests/"] 3
• core/src/lib.rs — #[cfg(docsrs)] pub mod docs; guard in the stable v0.53 layout 5
• Issue #8222 — canonical bug report with exact error and reproduction steps 2
• PR #8183 — removed the docsrs guard; triggered the regression
• PR #8223 — resolved the issue by adding the changelog symlink and correcting the path
• PR #7931 — precedent: symlinks used to include LICENSE/NOTICE in split crates

Checklist for New Sub-Crate Splits#

When adding a new publishable sub-crate from the OpenDAL workspace:

1. Audit every include_str! in that crate for paths that escape the crate root (../.. or deeper).
2. If the referenced file lives in a parent directory, either symlink it into the sub-crate root or copy it.
3. If a module is doc-only (changelog, RFCs), keep it gated on #[cfg(docsrs)] to avoid evaluating include_str! in downstream cargo check.
4. Consider adding an explicit include field to Cargo.toml to make packaging intent explicit and avoid silent omissions.