docs(build): Document manual changes to Carnix expression

1 files changed, 20 insertions, 1 deletions

diff --git a/default.nix b/default.nix
index e907c05967f0..b9197cbb79ec 100644
--- a/default.nix
+++ b/default.nix
@@ -1,4 +1,23 @@
-# Generated by carnix 0.6.7: carnix --standalone -o default.nix Cargo.lock
+# Most of this file was generated using `carnix`, however some fixes
+# have been applied manually. When upgrading dependencies, care must
+# be taken to not break those fixes:
+#
+# 1. Carnix derivations break if a crate's features start with a
+#    number, which is the case for several of Diesel's features. Those
+#    have had quotes added around them to fix the issue.
+#
+# 2. The last line of the derivation has been modified to return the
+#    derivation for Converse itself, rather than an attribute set of
+#    all crate derivations.
+#
+# 3. To fix an issue building Comrak, the Markdown parser, the
+#    derivation attributes have been overridden to provide a "dummy"
+#    environment variable that Comrak's binary attempts to read during
+#    the build.
+#    Unfortunately Carnix can not currently be configured to not build
+#    the binary of a dependency (even if the relevant feature is
+#    disabled), so this workaround is required.
+
 { pkgs ? import <nixpkgs> {} }:
 
 with pkgs; let kernel = buildPlatform.parsed.kernel.name;