Convert the internal API doc build to Meson

Makefile

@@ -68,10 +68,6 @@ ifeq ($(ENABLE_DOC_GEN), yes)
 makefiles-late += doc/manual/local.mk
 endif
 
-ifeq ($(ENABLE_INTERNAL_API_DOCS), yes)
-makefiles-late += doc/internal-api/local.mk
-endif
-
 ifeq ($(ENABLE_EXTERNAL_API_DOCS), yes)
 makefiles-late += doc/external-api/local.mk
 endif
@@ -132,13 +128,6 @@ manual-html manpages:
 	@exit 1
 endif
 
-ifneq ($(ENABLE_INTERNAL_API_DOCS), yes)
-.PHONY: internal-api-html
-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
-
 ifneq ($(ENABLE_EXTERNAL_API_DOCS), yes)
 .PHONY: external-api-html
 external-api-html:

Makefile.config.in

@@ -11,7 +11,6 @@ EDITLINE_LIBS = @EDITLINE_LIBS@
 ENABLE_BUILD = @ENABLE_BUILD@
 ENABLE_DOC_GEN = @ENABLE_DOC_GEN@
 ENABLE_FUNCTIONAL_TESTS = @ENABLE_FUNCTIONAL_TESTS@
-ENABLE_INTERNAL_API_DOCS = @ENABLE_INTERNAL_API_DOCS@
 ENABLE_EXTERNAL_API_DOCS = @ENABLE_EXTERNAL_API_DOCS@
 ENABLE_S3 = @ENABLE_S3@
 ENABLE_UNIT_TESTS = @ENABLE_UNIT_TESTS@

configure.ac

@@ -171,11 +171,6 @@ AS_IF(
   [test "$ENABLE_BUILD" == "no" && test "$ENABLE_DOC_GEN" == "yes"],
   [AC_MSG_ERROR([Cannot enable generated docs when building overall is disabled. Please do not pass '--enable-doc-gen' or do not pass '--disable-build'.])])
 
-# 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]),
-  ENABLE_INTERNAL_API_DOCS=$enableval, ENABLE_INTERNAL_API_DOCS=no)
-AC_SUBST(ENABLE_INTERNAL_API_DOCS)
-
 AC_ARG_ENABLE(external-api-docs, AS_HELP_STRING([--enable-external-api-docs],[Build API docs for Nix's external unstable C interfaces]),
   ENABLE_EXTERNAL_API_DOCS=$enableval, ENABLE_EXTERNAL_API_DOCS=no)
 AC_SUBST(ENABLE_EXTERNAL_API_DOCS)

doc/internal-api/local.mk

@@ -1,7 +0,0 @@
-$(docdir)/internal-api/html/index.html $(docdir)/internal-api/latex: $(d)/doxygen.cfg src/**/*.hh
-	mkdir -p $(docdir)/internal-api
-	{ cat $< ; echo "OUTPUT_DIRECTORY=$(docdir)/internal-api" ; } | doxygen -
-
-# Generate the HTML API docs for Nix's unstable internal interfaces.
-.PHONY: internal-api-html
-internal-api-html: $(docdir)/internal-api/html/index.html

doc/manual/src/contributing/documentation.md

@@ -196,15 +196,17 @@ You can also build and view it yourself:
 [Doxygen API documentation]: https://hydra.nixos.org/job/nix/master/internal-api-docs/latest/download-by-type/doc/internal-api-docs
 
 ```console
-# nix build .#hydraJobs.internal-api-docs
+$ nix build .#hydraJobs.internal-api-docs
-# xdg-open ./result/share/doc/nix/internal-api/html/index.html
+$ xdg-open ./result/share/doc/nix/internal-api/html/index.html
 ```
 
 or inside `nix-shell` or `nix develop`:
 
-```
+```console
-# make internal-api-html
+$ mesonConfigurePhase
-# xdg-open ./outputs/doc/share/doc/nix/internal-api/html/index.html
+$ cd build
+$ ninja src/internal-api-docs/html
+$ xdg-open src/internal-api-docs/html/index.html
 ```
 
 ## C API documentation

flake.nix

@@ -202,6 +202,15 @@
               ;
           };
 
+
+          nix-internal-api-docs = final.callPackage ./src/internal-api-docs/package.nix {
+            inherit
+              fileset
+              stdenv
+              versionSuffix
+              ;
+          };
+
           # See https://github.com/NixOS/nixpkgs/pull/214409
           # Remove when fixed in this flake's nixpkgs
           pre-commit =
@@ -279,6 +288,7 @@
           # system, we should reenable these.
           #"nix-util" = { };
           #"nix-store" = { };
+          "nix-internal-api-docs" = { };
         }
         // lib.optionalAttrs (builtins.elem system linux64BitSystems) {
         dockerImage =

maintainers/hydra.nix

@@ -124,11 +124,7 @@ in
   };
 
   # API docs for Nix's unstable internal C++ interfaces.
-  internal-api-docs = nixpkgsFor.x86_64-linux.native.callPackage ../package.nix {
+  internal-api-docs = nixpkgsFor.x86_64-linux.native.nix-internal-api-docs;
-    inherit fileset;
-    doBuild = false;
-    enableInternalAPIDocs = true;
-  };
 
   # API docs for Nix's C bindings.
   external-api-docs = nixpkgsFor.x86_64-linux.native.callPackage ../package.nix {

meson.build

@@ -9,3 +9,4 @@ project('nix-dev-shell', 'cpp',
 subproject('libutil')
 subproject('libstore')
 subproject('perl')
+subproject('internal-api-docs')

package.nix

@@ -93,9 +93,8 @@
 # - readline
 , readlineFlavor ? if stdenv.hostPlatform.isWindows then "readline" else "editline"
 
-# Whether to build the internal/external API docs, can be done separately from
+# Whether to build the external API docs, can be done separately from
 # everything else.
-, enableInternalAPIDocs ? forDevShell
 , enableExternalAPIDocs ? forDevShell
 
 # Whether to install unit tests. This is useful when cross compiling
@@ -185,11 +184,9 @@ in {
           ./scripts/local.mk
         ] ++ lib.optionals buildUnitTests [
           ./doc/manual
-        ] ++ lib.optionals enableInternalAPIDocs [
-          ./doc/internal-api
         ] ++ lib.optionals enableExternalAPIDocs [
           ./doc/external-api
-        ] ++ lib.optionals (enableInternalAPIDocs || enableExternalAPIDocs) [
+        ] ++ lib.optionals enableExternalAPIDocs [
           # Source might not be compiled, but still must be available
           # for Doxygen to gather comments.
           (fileset.difference ./src ./src/perl)
@@ -207,7 +204,7 @@ in {
     ++ lib.optional doBuild "dev"
     # If we are doing just build or just docs, the one thing will use
     # "out". We only need additional outputs if we are doing both.
-    ++ lib.optional (doBuild && (enableManual || enableInternalAPIDocs || enableExternalAPIDocs)) "doc"
+    ++ lib.optional (doBuild && (enableManual || enableExternalAPIDocs)) "doc"
     ++ lib.optional installUnitTests "check"
     ++ lib.optional doCheck "testresults"
     ;
@@ -231,7 +228,7 @@ in {
   ] ++ lib.optionals (doInstallCheck || enableManual) [
     jq # Also for custom mdBook preprocessor.
   ] ++ lib.optional stdenv.hostPlatform.isLinux util-linux
-    ++ lib.optional (enableInternalAPIDocs || enableExternalAPIDocs) doxygen
+    ++ lib.optional enableExternalAPIDocs doxygen
   ;
 
   buildInputs = lib.optionals doBuild [
@@ -294,7 +291,6 @@ in {
     (lib.enableFeature doBuild "build")
     (lib.enableFeature buildUnitTests "unit-tests")
     (lib.enableFeature doInstallCheck "functional-tests")
-    (lib.enableFeature enableInternalAPIDocs "internal-api-docs")
     (lib.enableFeature enableExternalAPIDocs "external-api-docs")
     (lib.enableFeature enableManual "doc-gen")
     (lib.enableFeature enableGC "gc")
@@ -324,7 +320,6 @@ in {
   '';
 
   installTargets = lib.optional doBuild "install"
-    ++ lib.optional enableInternalAPIDocs "internal-api-html"
     ++ lib.optional enableExternalAPIDocs "external-api-html";
 
   installFlags = "sysconfdir=$(out)/etc";
@@ -349,11 +344,7 @@ in {
   ) + lib.optionalString enableManual ''
     mkdir -p ''${!outputDoc}/nix-support
     echo "doc manual ''${!outputDoc}/share/doc/nix/manual" >> ''${!outputDoc}/nix-support/hydra-build-products
-  '' + lib.optionalString enableInternalAPIDocs ''
+  '' + lib.optionalString enableExternalAPIDocs ''
-    mkdir -p ''${!outputDoc}/nix-support
-    echo "doc internal-api-docs $out/share/doc/nix/internal-api/html" >> ''${!outputDoc}/nix-support/hydra-build-products
-  ''
-    + lib.optionalString enableExternalAPIDocs ''
     mkdir -p ''${!outputDoc}/nix-support
     echo "doc external-api-docs $out/share/doc/nix/external-api/html" >> ''${!outputDoc}/nix-support/hydra-build-products
   '';

src/internal-api-docs/.version

@@ -0,0 +1 @@
+../../.version

src/internal-api-docs/doxygen.cfg.in

@@ -12,7 +12,9 @@ PROJECT_NAME           = "Nix"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = @PACKAGE_VERSION@
+PROJECT_NUMBER         = @PROJECT_NUMBER@
+
+OUTPUT_DIRECTORY       = @OUTPUT_DIRECTORY@
 
 # 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
@@ -36,27 +38,27 @@ GENERATE_LATEX         = NO
 # so they can expand variables despite configure variables.
 
 INPUT                  = \
-  src/libcmd \
+  @src@/src/libcmd \
-  src/libexpr \
+  @src@/src/libexpr \
-  src/libexpr/flake \
+  @src@/src/libexpr/flake \
-  tests/unit/libexpr \
+  @src@/tests/unit/libexpr \
-  tests/unit/libexpr/value \
+  @src@/tests/unit/libexpr/value \
-  tests/unit/libexpr/test \
+  @src@/tests/unit/libexpr/test \
-  tests/unit/libexpr/test/value \
+  @src@/tests/unit/libexpr/test/value \
-  src/libexpr/value \
+  @src@/src/libexpr/value \
-  src/libfetchers \
+  @src@/src/libfetchers \
-  src/libmain \
+  @src@/src/libmain \
-  src/libstore \
+  @src@/src/libstore \
-  src/libstore/build \
+  @src@/src/libstore/build \
-  src/libstore/builtins \
+  @src@/src/libstore/builtins \
-  tests/unit/libstore \
+  @src@/tests/unit/libstore \
-  tests/unit/libstore/test \
+  @src@/tests/unit/libstore/test \
-  src/libutil \
+  @src@/src/libutil \
-  tests/unit/libutil \
+  @src@/tests/unit/libutil \
-  tests/unit/libutil/test \
+  @src@/tests/unit/libutil/test \
-  src/nix \
+  @src@/src/nix \
-  src/nix-env \
+  @src@/src/nix-env \
-  src/nix-store
+  @src@/src/nix-store
 
 # If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names
 # in the source code. If set to NO, only conditional compilation will be

src/internal-api-docs/meson.build

@@ -0,0 +1,31 @@
+project('nix-internal-api-docs',
+  version : files('.version'),
+  meson_version : '>= 1.1',
+  license : 'LGPL-2.1-or-later',
+)
+
+fs = import('fs')
+
+doxygen_cfg = configure_file(
+  input : 'doxygen.cfg.in',
+  output : 'doxygen.cfg',
+  configuration : {
+    'PROJECT_NUMBER': meson.project_version(),
+    'OUTPUT_DIRECTORY' : meson.current_build_dir(),
+    'src' : fs.parent(fs.parent(meson.project_source_root())),
+  },
+)
+
+doxygen = find_program('doxygen', native : true, required : true)
+
+custom_target(
+  'internal-api-docs',
+  command : [ doxygen , doxygen_cfg ],
+  input : [
+    doxygen_cfg,
+  ],
+  output : 'html',
+  install : true,
+  install_dir : get_option('datadir') / 'doc/nix/internal-api',
+  build_always_stale : true,
+)

src/internal-api-docs/package.nix

@@ -0,0 +1,56 @@
+{ lib
+, stdenv
+, releaseTools
+, fileset
+
+, meson
+, ninja
+, doxygen
+
+# Configuration Options
+
+, versionSuffix ? ""
+}:
+
+stdenv.mkDerivation (finalAttrs: {
+  pname = "nix-internal-api-docs";
+  version = lib.fileContents ./.version + versionSuffix;
+
+  src = fileset.toSource {
+    root = ../..;
+    fileset = let
+      cpp = fileset.fileFilter (file: file.hasExt "cc" || file.hasExt "hh");
+    in fileset.unions [
+      ./meson.build
+      ./doxygen.cfg.in
+      # Source is not compiled, but still must be available for Doxygen
+      # to gather comments.
+      (cpp ../.)
+      (cpp ../../tests/unit)
+    ];
+  };
+
+  nativeBuildInputs = [
+    meson
+    ninja
+    doxygen
+  ];
+
+  postUnpack = ''
+    sourceRoot=$sourceRoot/src/internal-api-docs
+  '';
+
+  preConfigure =
+    # "Inline" .version so it's not a symlink, and includes the suffix
+    ''
+      echo ${finalAttrs.version} > .version
+    '';
+
+  enableParallelBuilding = true;
+
+  strictDeps = true;
+
+  meta = {
+    platforms = lib.platforms.all;
+  };
+})