Document specifying/overriding a Cargo.lock file (#94)

README.md

@@ -373,6 +373,25 @@ There are two main ways to avoid unnecessary builds:
    can omit any files know to not be needed while building the crate (for
    example, all `*.nix` sources, `flake.lock`, and so on)
 
+### I'm trying to build another cargo project from source which has no lock file
+
+First consider if there is a release of this project available _with_ a lock
+file as it may be simpler and more consistent to use the exact dependencies
+published by the project itself. Projects published on crates.io always come
+with a lock file and `nixpkgs` has a `fetchCrate` fetcher which pulls straight
+from crates.io.
+
+If that is not an option, the next best thing is to generate your own
+`Cargo.lock` file and pass it in as an override by setting `cargoLock =
+./path/to/Cargo.lock`. If you are calling `buildDepsOnly` or `vendorCargoDeps`
+directly the value must be passed there; otherwise you can pass it into
+`buildPackage` or `cargoBuild` and it will automatically passed through.
+
+Note that the `Cargo.lock` file must be accessible _at evaluation time_ for the
+dependency vendoring to work, meaning the file cannot be generated within the
+same derivation that builds the project. It _may_ come from another derivation,
+but it may require enabling IFD if flakes are not used.
+
 ## License
 
 This project is licensed under the [MIT license].

checks/default.nix

@@ -35,6 +35,23 @@ myPkgs // {
 
   cargoAuditTests = callPackage ./cargoAudit.nix { };
 
+  # NB: explicitly using a github release (not crates.io release)
+  # which lacks a Cargo.lock file, so we can test adding our own
+  cargoLockOverride = myLib.buildPackage rec {
+    pname = "cargo-llvm-cov";
+    version = "0.4.14";
+
+    src = pkgs.fetchFromGitHub {
+      owner = "taiki-e";
+      repo = pname;
+      rev = "v${version}";
+      sha256 = "sha256-sNwizxYVUNyv5InR8HS+CyUsroA79h/FpouS+fMWJUI=";
+    };
+
+    doCheck = false; # Tests need llvm-tools installed
+    cargoLock = ./testCargoLockOverride.lock;
+  };
+
   cargoTarpaulin = lib.optionalAttrs x64Linux (myLib.cargoTarpaulin {
     src = ./simple;
   });