Generate API docs with Doxygen

The motivation is as stated in issue #7814: even though the the C++ API
is internal and unstable, people still want it to be well documented for
sake of learning, code review, and other purposes that aren't predicated
on it being stable.

Fixes #7814

Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>

Makefile

@@ -16,7 +16,8 @@ makefiles = \
   misc/systemd/local.mk \
   misc/launchd/local.mk \
   misc/upstart/local.mk \
-  doc/manual/local.mk
+  doc/manual/local.mk \
+  doc/internal-api/local.mk
 
 -include Makefile.config
 

Makefile.config.in

@@ -22,6 +22,7 @@ LOWDOWN_LIBS = @LOWDOWN_LIBS@
 OPENSSL_LIBS = @OPENSSL_LIBS@
 PACKAGE_NAME = @PACKAGE_NAME@
 PACKAGE_VERSION = @PACKAGE_VERSION@
+RAPIDCHECK_HEADERS = @RAPIDCHECK_HEADERS@
 SHELL = @bash@
 SODIUM_LIBS = @SODIUM_LIBS@
 SQLITE3_LIBS = @SQLITE3_LIBS@
@@ -46,3 +47,4 @@ storedir = @storedir@
 sysconfdir = @sysconfdir@
 system = @system@
 tests = @tests@
+internal_api_docs = @internal_api_docs@

configure.ac

@@ -152,6 +152,11 @@ AC_ARG_ENABLE(tests, AS_HELP_STRING([--disable-tests],[Do not build the tests]),
   tests=$enableval, tests=yes)
 AC_SUBST(tests)
 
+# Building without API docs is the default as Nix' C++ interfaces are internal and unstable.
+AC_ARG_ENABLE(internal_api_docs, AS_HELP_STRING([--enable-internal-api-docs],[Build API docs for Nix's internal unstable C++ interfaces]),
+  internal_api_docs=$enableval, internal_api_docs=no)
+AC_SUBST(internal_api_docs)
+
 # LTO is currently broken with clang for unknown reasons; ld segfaults in the llvm plugin
 AC_ARG_ENABLE(lto, AS_HELP_STRING([--enable-lto],[Enable LTO (only supported with GCC) [default=no]]),
   lto=$enableval, lto=no)
@@ -286,6 +291,8 @@ PKG_CHECK_MODULES([GTEST], [gtest_main])
 # Look for rapidcheck.
 # No pkg-config yet, https://github.com/emil-e/rapidcheck/issues/302
 AC_LANG_PUSH(C++)
+AC_SUBST(RAPIDCHECK_HEADERS)
+[CXXFLAGS="-I $RAPIDCHECK_HEADERS $CXXFLAGS"]
 AC_CHECK_HEADERS([rapidcheck/gtest.h], [], [], [#include <gtest/gtest.h>])
 dnl No good for C++ libs with mangled symbols
 dnl AC_CHECK_LIB([rapidcheck], [])

doc/internal-api/.gitignore

@@ -0,0 +1,3 @@
+/doxygen.cfg
+/html
+/latex

doc/internal-api/doxygen.cfg.in

@@ -0,0 +1,63 @@
+# Doxyfile 1.9.5
+
+# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by
+# double-quotes, unless you are using Doxywizard) that should identify the
+# project for which the documentation is generated. This name is used in the
+# title of most generated pages and in a few other places.
+# The default value is: My Project.
+
+PROJECT_NAME           = "Nix"
+
+# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
+# could be handy for archiving the generated documentation or if some version
+# control system is used.
+
+PROJECT_NUMBER         = @PACKAGE_VERSION@
+
+# Using the PROJECT_BRIEF tag one can provide an optional one line description
+# for a project that appears at the top of each page and should give viewer a
+# quick idea about the purpose of the project. Keep the description short.
+
+PROJECT_BRIEF          = "Nix, the purely functional package manager; unstable internal interfaces"
+
+# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
+# The default value is: YES.
+
+GENERATE_LATEX         = NO
+
+# The INPUT tag is used to specify the files and/or directories that contain
+# documented source files. You may enter file names like myfile.cpp or
+# directories like /usr/src/myproject. Separate the files or directories with
+# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
+# Note: If this tag is empty the current directory is searched.
+
+# FIXME Make this list more maintainable somehow. We could maybe generate this
+# in the Makefile, but we would need to change how `.in` files are preprocessed
+# so they can expand variables despite configure variables.
+
+INPUT                  = \
+  src/libcmd \
+  src/libexpr \
+  src/libexpr/flake \
+  src/libexpr/tests \
+  src/libexpr/tests/value \
+  src/libexpr/value \
+  src/libfetchers \
+  src/libmain \
+  src/libstore \
+  src/libstore/build \
+  src/libstore/builtins \
+  src/libstore/tests \
+  src/libutil \
+  src/libutil/tests \
+  src/nix \
+  src/nix-env \
+  src/nix-store
+
+# The INCLUDE_PATH tag can be used to specify one or more directories that
+# contain include files that are not input files but should be processed by the
+# preprocessor. Note that the INCLUDE_PATH is not recursive, so the setting of
+# RECURSIVE has no effect here.
+# This tag requires that the tag SEARCH_INCLUDES is set to YES.
+
+INCLUDE_PATH           = @RAPIDCHECK_HEADERS@

doc/internal-api/local.mk

@@ -0,0 +1,19 @@
+.PHONY: internal-api-html
+
+ifeq ($(internal_api_docs), yes)
+
+$(docdir)/internal-api/html/index.html $(docdir)/internal-api/latex: $(d)/doxygen.cfg
+	mkdir -p $(docdir)/internal-api
+	{ cat $< ; echo "OUTPUT_DIRECTORY=$(docdir)/internal-api" ; } | doxygen -
+
+# Generate the HTML API docs for Nix's unstable internal interfaces.
+internal-api-html: $(docdir)/internal-api/html/index.html
+
+else
+
+# Make a nicer error message
+internal-api-html:
+	@echo "Internal API docs are disabled. Configure with '--enable-internal-api-docs', or avoid calling 'make internal-api-html'."
+	@exit 1
+
+endif

doc/manual/local.mk

@@ -88,7 +88,8 @@ $(d)/builtins.json: $(bindir)/nix
 	@mv $@.tmp $@
 
 # Generate the HTML manual.
-html: $(docdir)/manual/index.html
+.PHONY: manual-html
+manual-html: $(docdir)/manual/index.html
 install: $(docdir)/manual/index.html
 
 # Generate 'nix' manpages.

flake.nix

@@ -98,7 +98,11 @@
           ];
 
         testConfigureFlags = [
-          "CXXFLAGS=-I${lib.getDev rapidcheck}/extras/gtest/include"
+          "RAPIDCHECK_HEADERS=${lib.getDev rapidcheck}/extras/gtest/include"
+        ];
+
+        internalApiDocsConfigureFlags = [
+          "--enable-internal-api-docs"
         ];
 
         nativeBuildDeps =
@@ -136,6 +140,10 @@
           rapidcheck
         ];
 
+        internalApiDocsDeps = [
+          buildPackages.doxygen
+        ];
+
         awsDeps = lib.optional (stdenv.isLinux || stdenv.isDarwin)
           (aws-sdk-cpp.override {
             apis = ["s3" "transfer"];
@@ -517,9 +525,7 @@
 
             src = self;
 
-            configureFlags = [
+            configureFlags = testConfigureFlags;
-              "CXXFLAGS=-I${lib.getDev pkgs.rapidcheck}/extras/gtest/include"
-            ];
 
             enableParallelBuilding = true;
 
@@ -536,6 +542,33 @@
             hardeningDisable = ["fortify"];
           };
 
+        # API docs for Nix's unstable internal C++ interfaces.
+        internal-api-docs =
+          with nixpkgsFor.x86_64-linux.native;
+          with commonDeps { inherit pkgs; };
+
+          stdenv.mkDerivation {
+            pname = "nix-internal-api-docs";
+            inherit version;
+
+            src = self;
+
+            configureFlags = testConfigureFlags ++ internalApiDocsConfigureFlags;
+
+            nativeBuildInputs = nativeBuildDeps;
+            buildInputs = buildDeps ++ propagatedDeps
+              ++ awsDeps ++ checkDeps ++ internalApiDocsDeps;
+
+            dontBuild = true;
+
+            installTargets = [ "internal-api-html" ];
+
+            postInstall = ''
+              mkdir -p $out/nix-support
+              echo "doc internal-api-docs $out/share/doc/nix/internal-api" >> $out/nix-support/hydra-build-products
+            '';
+          };
+
         # System tests.
         tests.authorization = runNixOSTestFor "x86_64-linux" ./tests/nixos/authorization.nix;
 
@@ -653,9 +686,11 @@
             nativeBuildInputs = nativeBuildDeps
                                 ++ (lib.optionals stdenv.cc.isClang [ pkgs.bear pkgs.clang-tools ]);
 
-            buildInputs = buildDeps ++ propagatedDeps ++ awsDeps ++ checkDeps;
+            buildInputs = buildDeps ++ propagatedDeps
+              ++ awsDeps ++ checkDeps ++ internalApiDocsDeps;
 
-            configureFlags = configureFlags ++ testConfigureFlags;
+            configureFlags = configureFlags
+              ++ testConfigureFlags ++ internalApiDocsConfigureFlags;
 
             enableParallelBuilding = true;