Systematize builtins.fetchTree docs

Makefile.config.in

@@ -4,6 +4,7 @@ BOOST_LDFLAGS = @BOOST_LDFLAGS@
 BUILD_SHARED_LIBS = @BUILD_SHARED_LIBS@
 CC = @CC@
 CFLAGS = @CFLAGS@
+CMARK_LIBS = @CMARK_LIBS@
 CXX = @CXX@
 CXXFLAGS = @CXXFLAGS@
 CXXLTO = @CXXLTO@

configure.ac

@@ -372,21 +372,24 @@ PKG_CHECK_MODULES([RAPIDCHECK], [rapidcheck rapidcheck_gtest])
 PKG_CHECK_MODULES([NLOHMANN_JSON], [nlohmann_json >= 3.9])
 
 
+# Look for cmark library.
+PKG_CHECK_MODULES([CMARK], [libcmark], [CXXFLAGS="$CMARK_CFLAGS $CXXFLAGS"])
+
 # Look for lowdown library.
-AC_ARG_ENABLE([markdown], AS_HELP_STRING([--enable-markdown], [Enable Markdown rendering in the Nix binary (requires lowdown) [default=auto]]),
-  enable_markdown=$enableval, enable_markdown=auto)
-AS_CASE(["$enable_markdown"],
+AC_ARG_ENABLE([lowdown], AS_HELP_STRING([--enable-lowdown], [Enable Markdown rendering in the Nix binary (requires lowdown) [default=auto]]),
+  enable_lowdown=$enableval, enable_lowdown=auto)
+AS_CASE(["$enable_lowdown"],
   [yes | auto], [
     PKG_CHECK_MODULES([LOWDOWN], [lowdown >= 0.9.0], [
       CXXFLAGS="$LOWDOWN_CFLAGS $CXXFLAGS"
       have_lowdown=1
       AC_DEFINE(HAVE_LOWDOWN, 1, [Whether lowdown is available and should be used for Markdown rendering.])
     ], [
-      AS_IF([test "x$enable_markdown" == "xyes"], [AC_MSG_ERROR([--enable-markdown was specified, but lowdown was not found.])])
+      AS_IF([test "x$enable_lowdown" == "xyes"], [AC_MSG_ERROR([--enable-lowdown was specified, but lowdown was not found.])])
     ])
   ],
   [no], [have_lowdown=],
-  [AC_MSG_ERROR([bad value "$enable_markdown" for --enable-markdown, must be one of: yes, no, auto])])
+  [AC_MSG_ERROR([bad value "$enable_lowdown" for --enable-lowdown, must be one of: yes, no, auto])])
 
 
 # Look for libgit2.

flake.nix

@@ -6,6 +6,8 @@
   inputs.nixpkgs-23-11.url = "github:NixOS/nixpkgs/a62e6edd6d5e1fa0329b8653c801147986f8d446";
   inputs.flake-compat = { url = "github:edolstra/flake-compat"; flake = false; };
   inputs.libgit2 = { url = "github:libgit2/libgit2/v1.8.1"; flake = false; };
+  # Until https://github.com/commonmark/cmark/pull/524 is released
+  inputs.cmark = { url = "github:commonmark/cmark"; flake = false; };
 
   # dev tooling
   inputs.flake-parts.url = "github:hercules-ci/flake-parts";

package.nix

@@ -23,6 +23,7 @@
 , libseccomp
 , libsodium
 , man
+, cmark
 , lowdown
 , mdbook
 , mdbook-linkcheck
@@ -79,7 +80,7 @@
 , enableGC ? !stdenv.hostPlatform.isWindows
 
 # Whether to enable Markdown rendering in the Nix binary.
-, enableMarkdown ? !stdenv.hostPlatform.isWindows
+, enableLowdown ? !stdenv.hostPlatform.isWindows
 
 # Which interactive line editor library to use for Nix's repl.
 #
@@ -228,7 +229,8 @@ in {
     toml11
     xz
     ({ inherit readline editline; }.${readlineFlavor})
-  ] ++ lib.optionals enableMarkdown [
+    cmark
+  ] ++ lib.optionals enableLowdown [
     lowdown
   ] ++ lib.optionals buildUnitTests [
     gtest
@@ -255,7 +257,7 @@ in {
     (lib.enableFeature doInstallCheck "functional-tests")
     (lib.enableFeature enableManual "doc-gen")
     (lib.enableFeature enableGC "gc")
-    (lib.enableFeature enableMarkdown "markdown")
+    (lib.enableFeature enableLowdown "lowdown")
     (lib.enableFeature installUnitTests "install-unit-tests")
     (lib.withFeatureAs true "readline-flavor" readlineFlavor)
   ] ++ lib.optionals (!forDevShell) [

packaging/dependencies.nix

@@ -140,6 +140,11 @@ scope: {
       ];
   });
 
+  cmark = pkgs.cmark.overrideAttrs (_: {
+    src = inputs.cmark;
+    version = inputs.lastModifiedDate;
+  });
+
   busybox-sandbox-shell = pkgs.busybox-sandbox-shell or (pkgs.busybox.override {
     useMusl = true;
     enableStatic = true;

packaging/hydra.nix

@@ -90,9 +90,9 @@ in
 
   # Toggles some settings for better coverage. Windows needs these
   # library combinations, and Debian build Nix with GNU readline too.
-  buildReadlineNoMarkdown = forAllSystems (system:
+  buildReadlineNoLowdown = forAllSystems (system:
     self.packages.${system}.nix.override {
-      enableMarkdown = false;
+      enableLowdown = false;
       readlineFlavor = "readline";
     }
   );

src/libexpr/eval.cc

@@ -500,7 +500,7 @@ Value * EvalState::addPrimOp(PrimOp && primOp)
         v.mkApp(vPrimOp, vPrimOp);
         return addConstant(primOp.name, v, {
             .type = nThunk, // FIXME
-            .doc = primOp.doc,
+            .doc = primOp.doc.c_str(),
         });
     }
 
@@ -527,13 +527,14 @@ std::optional<EvalState::Doc> EvalState::getDoc(Value & v)
 {
     if (v.isPrimOp()) {
         auto v2 = &v;
-        if (auto * doc = v2->primOp()->doc)
+        auto & doc = v2->primOp()->doc;
+        if (doc != "")
             return Doc {
                 .pos = {},
                 .name = v2->primOp()->name,
                 .arity = v2->primOp()->arity,
                 .args = v2->primOp()->args,
-                .doc = doc,
+                .doc = doc.c_str(),
             };
     }
     if (v.isLambda()) {

src/libexpr/eval.hh

@@ -88,7 +88,7 @@ struct PrimOp
     /**
      * Optional free-form documentation about the primop.
      */
-    const char * doc = nullptr;
+    const std::string doc = "";
 
     /**
      * Add a trace item, `while calling the '<name>' builtin`

src/libexpr/local.mk

@@ -20,7 +20,7 @@ libexpr_CXXFLAGS += \
 
 libexpr_LIBS = libutil libstore libfetchers
 
-libexpr_LDFLAGS += -lboost_context $(THREAD_LDFLAGS)
+libexpr_LDFLAGS += -lboost_context $(THREAD_LDFLAGS) $(CMARK_LIBS)
 ifdef HOST_LINUX
   libexpr_LDFLAGS += -ldl
 endif