cargoDoc: add ability to run cargo doc on a workspace (#107)

CHANGELOG.md

@@ -6,6 +6,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## Unreleased
 
+## Added
+* `cargoDoc` can now be used for building the documentation of a workspace
+
 ## Changed
 * **Breaking**: `mkCargoDerivation` now includes a default `configurePhase`
   which does nothing but run the `preConfigure` and `postConfigure` hooks. This

checks/compilesFresh.nix

@@ -3,7 +3,7 @@
 , jq
 }:
 
-src: expected: args:
+expected: mkDrv: args:
 let
   runCargoAndCheckFreshness = cmd: extra: ''
     cargo ${cmd} \
@@ -23,13 +23,12 @@ let
     fi
   '';
 in
-cargoBuild (args // {
-  inherit src;
+mkDrv (args // {
   doInstallCargoArtifacts = false;
 
   # NB: explicit call here so that the buildDepsOnly call
   # doesn't inherit our build commands
-  cargoArtifacts = buildDepsOnly (args // { inherit src; });
+  cargoArtifacts = buildDepsOnly args;
 
   nativeBuildInputs = [ jq ];
 

checks/default.nix

@@ -57,16 +57,19 @@ myPkgs // {
   });
 
   compilesFresh = callPackage ./compilesFresh.nix { };
-  compilesFreshSimple = self.compilesFresh ./simple "simple" { };
+  compilesFreshSimple = self.compilesFresh "simple" (myLib.cargoBuild) {
+    src = ./simple;
+  };
   compilesFreshOverlappingTargets = self.compilesFresh
-    ./overlapping-targets
     (builtins.concatStringsSep "\n" [
       "bar"
       "baz"
       "foo"
       "overlapping-targets"
     ])
-    { };
+    myLib.cargoBuild {
+      src = ./overlapping-targets;
+    };
 
   customCargoTargetDirectory =
     let
@@ -82,6 +85,19 @@ myPkgs // {
       touch $out
     '';
 
+  docs = myLib.cargoDoc {
+    src = ./simple;
+    cargoArtifacts = myLib.buildDepsOnly {
+      src = ./simple;
+    };
+  };
+  docsFresh = self.compilesFresh "simple" (myLib.cargoDoc) {
+    src = ./simple;
+    cargoArtifacts = myLib.buildDepsOnly {
+      src = ./simple;
+    };
+  };
+
   depsOnlyVariousTargets = myLib.buildDepsOnly {
     src = ./various-targets;
   };

checks/features/default.nix

@@ -1,4 +1,5 @@
 { buildPackage
+, cargoBuild
 , compilesFresh
 , lib
 , linkFarmFromDrvs
@@ -16,8 +17,9 @@ let
     [
       crate
 
-      (compilesFresh ./features "features" {
+      (compilesFresh "features" cargoBuild {
         inherit cargoExtraArgs;
+        src = ./features;
         pname = "${pname}CompilesFresh";
       })
 

docs/API.md

@@ -352,6 +352,48 @@ environment variables during the build, you can bring them back via
 `.overrideAttrs`.
 * `cargoClippyExtraArgs`
 
+### `lib.cargoDoc`
+
+`cargoDoc :: set -> drv`
+
+Create a derivation which will run a `cargo doc` invocation in a cargo
+workspace.
+
+Except where noted below, all derivation attributes are delegated to
+`cargoBuild`, and can be used to influence its behavior.
+* `cargoBuildCommand` will be set to run `cargo doc --profile release` for
+  the workspace.
+  - `CARGO_PROFILE` can be set on the derivation to alter which cargo profile
+    is selected; setting it to `""` will omit specifying a profile
+    altogether.
+* `cargoExtraArgs` will have `cargoDocExtraArgs` appended to it
+  - Default value: `"--no-deps"`
+* `doCheck` is disabled
+* `pnameSuffix` will be set to `"-doc"`
+
+#### Required attributes
+* `cargoArtifacts`: A path (or derivation) which contains an existing cargo
+  `target` directory, which will be reused at the start of the derivation.
+  Useful for caching incremental cargo builds.
+  - This can be prepared via `buildDepsOnly`
+  - Alternatively, any cargo-based derivation which was built with
+    `doInstallCargoArtifacts = true` will work as well
+
+#### Optional attributes
+* `cargoDocExtraArgs`: additional flags to be passed in the rustdoc invocation (e.g.
+  deny specific lints)
+  - Default value: `"--no-deps"`
+* `cargoExtraArgs`: additional flags to be passed in the cargo invocation (e.g.
+  enabling specific features)
+  - Default value: `""`
+
+#### Remove attributes
+The following attributes will be removed before being lowered to
+`cargoBuild`. If you absolutely need these attributes present as
+environment variables during the build, you can bring them back via
+`.overrideAttrs`.
+* `cargoDocExtraArgs`
+
 ### `lib.cargoFmt`
 
 `cargoFmt :: set -> drv`

examples/quick-start/flake.nix

@@ -57,12 +57,15 @@
             cargoClippyExtraArgs = "--all-targets -- --deny warnings";
           };
 
+          my-crate-doc = craneLib.cargoDoc {
+            inherit cargoArtifacts src;
+          };
+
           # Check formatting
           my-crate-fmt = craneLib.cargoFmt {
             inherit src;
           };
 
-
           # Audit dependencies
           my-crate-audit = craneLib.cargoAudit {
             inherit src advisory-db;

lib/cargoDoc.nix

@@ -0,0 +1,19 @@
+{ cargoBuild
+}:
+
+{ cargoArtifacts
+, cargoDocExtraArgs ? "--no-deps"
+, cargoExtraArgs ? ""
+, ...
+}@origArgs:
+let
+  args = (builtins.removeAttrs origArgs [ "cargoDocExtraArgs" ]);
+in
+cargoBuild (args // {
+  pnameSuffix = "-doc";
+
+  cargoBuildCommand = "cargoWithProfile doc";
+  cargoExtraArgs = "${cargoExtraArgs} ${cargoDocExtraArgs}";
+
+  doCheck = false; # We don't need to run tests to build docs
+})

lib/default.nix

@@ -17,6 +17,7 @@ in
   cargoAudit = callPackage ./cargoAudit.nix { };
   cargoBuild = callPackage ./cargoBuild.nix { };
   cargoClippy = callPackage ./cargoClippy.nix { };
+  cargoDoc = callPackage ./cargoDoc.nix { };
   cargoFmt = callPackage ./cargoFmt.nix { };
   cargoNextest = callPackage ./cargoNextest.nix { };
   cargoTarpaulin = callPackage ./cargoTarpaulin.nix { };