ipetkov/crane
1
1
Fork 0
mirror of https://github.com/ipetkov/crane.git synced 2024-11-22 05:36:09 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs: add a FAQ entry about git-deps and relative file paths (#695)

Browse Source
This commit is contained in:
Ivan Petkov 2024-09-03 16:50:10 -07:00 committed by GitHub
parent 96fd12c710
commit cc29aa8ea2
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 41 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/SUMMARY.md
View File

@ -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)

4
docs/faq/building-with-non-rust-includes.md
View File

@ -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).

36
docs/faq/git-dep-cannot-find-relative-path.md Normal file
View File

@ -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)