From cc29aa8ea29521b5720cce83b033e5baaf6ed584 Mon Sep 17 00:00:00 2001 From: Ivan Petkov Date: Tue, 3 Sep 2024 16:50:10 -0700 Subject: [PATCH] docs: add a FAQ entry about git-deps and relative file paths (#695) --- docs/SUMMARY.md | 1 + docs/faq/building-with-non-rust-includes.md | 4 +++ docs/faq/git-dep-cannot-find-relative-path.md | 36 +++++++++++++++++++ 3 files changed, 41 insertions(+) create mode 100644 docs/faq/git-dep-cannot-find-relative-path.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 11f7a52..c4aff7e 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -45,6 +45,7 @@ * [Dealing with sandbox-unfriendly build scripts](./faq/sandbox-unfriendly-build-scripts.md) * [Cargo.toml is not at the source root](./faq/workspace-not-at-source-root.md) * [Found invalid metadata files for crate error](./faq/invalid-metadata-files-for-crate.md) + * [A git dependency fails to find a file by a relative path](./faq/git-dep-cannot-find-relative-path.md) --- * [Advanced Techniques](./advanced/advanced.md) * [Overriding function behavior](./advanced/overriding-function-behavior.md) diff --git a/docs/faq/building-with-non-rust-includes.md b/docs/faq/building-with-non-rust-includes.md index 2eafa54..9749e89 100644 --- a/docs/faq/building-with-non-rust-includes.md +++ b/docs/faq/building-with-non-rust-includes.md @@ -8,3 +8,7 @@ use `include_str!`, `include_bytes!`, or any other attempt at accessing such a file you may need to tweak the source filter to ensure the files are included. Check out the [source filtering](../source-filtering.md) section for more info! + +Note that if the error is originating from a git-dependency, it [may be a +problem with the upstream source +itself](./git-dep-cannot-find-relative-path.md). diff --git a/docs/faq/git-dep-cannot-find-relative-path.md b/docs/faq/git-dep-cannot-find-relative-path.md new file mode 100644 index 0000000..8d2510f --- /dev/null +++ b/docs/faq/git-dep-cannot-find-relative-path.md @@ -0,0 +1,36 @@ +## A git dependency fails to find a file by a relative path + +Sometimes various Rust projects are written in a way where a [build script or +`include_str!` invocation](./building-with-non-rust-includes.md) attempts to +read files outside of the crate's root, but this causes problems if such a +project is used as a git-dependency. + +Normally when cargo downloads a package source from a registry like crates.io, +it extracts each crate into its own separate directory (even if the upstream +source is a workspace with multiple crates). This means that published crates +usually do not suffer from this situation, however, cargo handles git +dependencies in a different (i.e. inconsistent) manner: cargo will download the +entire git directory _but keep all files in place_, which means that those +crates _happen_ to be able to rely on a file structure which matches the +upstream repo. + +Crane implements source fetching by following the behavior of the `cargo vendor` +command: each crate (whether it comes from a registry or a git repo) is extracted +in a separate directory. Thus the problem of trying to locate files outside of +the crate's (not the _workspace's_) root directory can also be demonstrated by +calling `cargo vendor` and then following its instructions (normally copying +some configuration to `.config/cargo.toml`) and then building as normal. + +If building like this after running `cargo vendor` **succeeds but fails when +building with Crane** please open an issue with a reproduction! However, if the +**build fails even without Crane** there are a few options to remedying the +problem: + +* Consider reporting the situation to the upstream project and/or contributing a + change there. If the primary authors are not familiar with or users of either + Nix or Crane, consider explaining that their project cannot be used by anyone + who wants to vendor their sources (e.g. through using `cargo vendor`). +* Consider forking the crate and remedying the problem there until it is + accepted upstream +* Consider [locally patching the dependency source while building with + Nix](../patching_dependency_sources.md)