Port C API docs to Meson (#10936)

* Port C API docs to Meson

* don't cross-compile the docs

Makefile

@@ -68,10 +68,6 @@ ifeq ($(ENABLE_DOC_GEN), yes)
 makefiles-late += doc/manual/local.mk
 endif
 
-ifeq ($(ENABLE_EXTERNAL_API_DOCS), yes)
-makefiles-late += doc/external-api/local.mk
-endif
-
 # Miscellaneous global Flags
 
 OPTIMIZE = 1
@@ -127,10 +123,3 @@ manual-html manpages:
 	@echo "Generated docs are disabled. Configure without '--disable-doc-gen', or avoid calling 'make manpages' and 'make manual-html'."
 	@exit 1
 endif
-
-ifneq ($(ENABLE_EXTERNAL_API_DOCS), yes)
-.PHONY: external-api-html
-external-api-html:
-	@echo "External API docs are disabled. Configure with '--enable-external-api-docs', or avoid calling 'make external-api-html'."
-	@exit 1
-endif

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_EXTERNAL_API_DOCS = @ENABLE_EXTERNAL_API_DOCS@
 ENABLE_S3 = @ENABLE_S3@
 ENABLE_UNIT_TESTS = @ENABLE_UNIT_TESTS@
 GTEST_LIBS = @GTEST_LIBS@

configure.ac

@@ -149,11 +149,6 @@ AC_ARG_ENABLE(unit-tests, AS_HELP_STRING([--disable-unit-tests],[Do not build th
   ENABLE_UNIT_TESTS=$enableval, ENABLE_UNIT_TESTS=$ENABLE_BUILD)
 AC_SUBST(ENABLE_UNIT_TESTS)
 
-# Build external API docs by default
-AC_ARG_ENABLE(external_api_docs, AS_HELP_STRING([--enable-external-api-docs],[Build API docs for Nix's C interface]),
-  external_api_docs=$enableval, external_api_docs=yes)
-AC_SUBST(external_api_docs)
-
 AS_IF(
   [test "$ENABLE_BUILD" == "no" && test "$ENABLE_UNIT_TESTS" == "yes"],
   [AC_MSG_ERROR([Cannot enable unit tests when building overall is disabled. Please do not pass '--enable-unit-tests' or do not pass '--disable-build'.])])
@@ -171,10 +166,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'.])])
 
-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)
-
 AS_IF(
   [test "$ENABLE_FUNCTIONAL_TESTS" == "yes" || test "$ENABLE_DOC_GEN" == "yes"],
   [NEED_PROG(jq, jq)])

doc/external-api/local.mk

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

doc/manual/src/contributing/documentation.md

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

flake.nix

@@ -211,7 +211,6 @@
               ;
           };
 
-
           nix-internal-api-docs = final.callPackage ./src/internal-api-docs/package.nix {
             inherit
               fileset
@@ -220,6 +219,14 @@
               ;
           };
 
+          nix-external-api-docs = final.callPackage ./src/external-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 =
@@ -275,6 +282,8 @@
         inherit (nixpkgsFor.${system}.native)
           changelog-d;
         default = self.packages.${system}.nix;
+        nix-internal-api-docs = nixpkgsFor.${system}.native.nix-internal-api-docs;
+        nix-external-api-docs = nixpkgsFor.${system}.native.nix-external-api-docs;
       } // lib.concatMapAttrs
         # We need to flatten recursive attribute sets of derivations to pass `flake check`.
         (pkgName: {}: {
@@ -298,7 +307,6 @@
           #"nix-util" = { };
           #"nix-store" = { };
           #"nix-fetchers" = { };
-          "nix-internal-api-docs" = { };
         }
         // lib.optionalAttrs (builtins.elem system linux64BitSystems) {
         dockerImage =
@@ -370,6 +378,8 @@
             ++ pkgs.nix-store.nativeBuildInputs
             ++ pkgs.nix-fetchers.nativeBuildInputs
             ++ lib.optionals havePerl pkgs.nix-perl-bindings.nativeBuildInputs
+            ++ pkgs.nix-internal-api-docs.nativeBuildInputs
+            ++ pkgs.nix-external-api-docs.nativeBuildInputs
             ++ [
               modular.pre-commit.settings.package
               (pkgs.writeScriptBin "pre-commit-hooks-install"

maintainers/hydra.nix

@@ -128,11 +128,7 @@ in
   internal-api-docs = nixpkgsFor.x86_64-linux.native.nix-internal-api-docs;
 
   # API docs for Nix's C bindings.
-  external-api-docs = nixpkgsFor.x86_64-linux.native.callPackage ../package.nix {
+  external-api-docs = nixpkgsFor.x86_64-linux.native.nix-external-api-docs;
-    inherit fileset;
-    doBuild = false;
-    enableExternalAPIDocs = true;
-  };
 
   # System tests.
   tests = import ../tests/nixos { inherit lib nixpkgs nixpkgsFor self; } // {

meson.build

@@ -11,3 +11,4 @@ subproject('libstore')
 subproject('libfetchers')
 subproject('perl')
 subproject('internal-api-docs')
+subproject('external-api-docs')

package.nix

@@ -20,7 +20,6 @@
 , git
 , gtest
 , jq
-, doxygen
 , libarchive
 , libcpuid
 , libgit2
@@ -53,8 +52,7 @@
 , versionSuffix ? ""
 , officialRelease ? false
 
-# Whether to build Nix. Useful to skip for tasks like (a) just
+# Whether to build Nix. Useful to skip for tasks like testing existing pre-built versions of Nix
-# generating API docs or (b) testing existing pre-built versions of Nix
 , doBuild ? true
 
 # Run the unit tests as part of the build. See `installUnitTests` for an
@@ -93,10 +91,6 @@
 # - readline
 , readlineFlavor ? if stdenv.hostPlatform.isWindows then "readline" else "editline"
 
-# Whether to build the external API docs, can be done separately from
-# everything else.
-, enableExternalAPIDocs ? forDevShell
-
 # Whether to install unit tests. This is useful when cross compiling
 # since we cannot run them natively during the build, but can do so
 # later.
@@ -184,13 +178,6 @@ in {
           ./scripts/local.mk
         ] ++ lib.optionals buildUnitTests [
           ./doc/manual
-        ] ++ lib.optionals enableExternalAPIDocs [
-          ./doc/external-api
-        ] ++ lib.optionals enableExternalAPIDocs [
-          # Source might not be compiled, but still must be available
-          # for Doxygen to gather comments.
-          (fileset.difference ./src ./src/perl)
-          ./tests/unit
         ] ++ lib.optionals buildUnitTests [
           ./tests/unit
         ] ++ lib.optionals doInstallCheck [
@@ -204,7 +191,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 || enableExternalAPIDocs)) "doc"
+    ++ lib.optional (doBuild && enableManual) "doc"
     ++ lib.optional installUnitTests "check"
     ++ lib.optional doCheck "testresults"
     ;
@@ -228,7 +215,6 @@ in {
   ] ++ lib.optionals (doInstallCheck || enableManual) [
     jq # Also for custom mdBook preprocessor.
   ] ++ lib.optional stdenv.hostPlatform.isLinux util-linux
-    ++ lib.optional enableExternalAPIDocs doxygen
   ;
 
   buildInputs = lib.optionals doBuild [
@@ -291,7 +277,6 @@ in {
     (lib.enableFeature doBuild "build")
     (lib.enableFeature buildUnitTests "unit-tests")
     (lib.enableFeature doInstallCheck "functional-tests")
-    (lib.enableFeature enableExternalAPIDocs "external-api-docs")
     (lib.enableFeature enableManual "doc-gen")
     (lib.enableFeature enableGC "gc")
     (lib.enableFeature enableMarkdown "markdown")
@@ -319,8 +304,7 @@ in {
     mkdir $testresults
   '';
 
-  installTargets = lib.optional doBuild "install"
+  installTargets = lib.optional doBuild "install";
-    ++ lib.optional enableExternalAPIDocs "external-api-html";
 
   installFlags = "sysconfdir=$(out)/etc";
 
@@ -344,9 +328,6 @@ 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 enableExternalAPIDocs ''
-    mkdir -p ''${!outputDoc}/nix-support
-    echo "doc external-api-docs $out/share/doc/nix/external-api/html" >> ''${!outputDoc}/nix-support/hydra-build-products
   '';
 
   # So the check output gets links for DLLs in the out output.

src/external-api-docs/.version

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

src/external-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,10 +38,10 @@ GENERATE_LATEX         = NO
 # so they can expand variables despite configure variables.
 
 INPUT                  = \
-  src/libutil-c \
+  @src@/src/libutil-c \
-  src/libexpr-c \
+  @src@/src/libexpr-c \
-  src/libstore-c \
+  @src@/src/libstore-c \
-  doc/external-api/README.md
+  @src@/doc/external-api/README.md
 
 FILE_PATTERNS = nix_api_*.h *.md
 
@@ -49,7 +51,6 @@ FILE_PATTERNS = nix_api_*.h *.md
 # RECURSIVE has no effect here.
 # This tag requires that the tag SEARCH_INCLUDES is set to YES.
 
-INCLUDE_PATH           = @RAPIDCHECK_HEADERS@
 EXCLUDE_PATTERNS = *_internal.h
 GENERATE_TREEVIEW = YES
 OPTIMIZE_OUTPUT_FOR_C  = YES

src/external-api-docs/meson.build

@@ -0,0 +1,31 @@
+project('nix-external-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(
+  'external-api-docs',
+  command : [ doxygen , doxygen_cfg ],
+  input : [
+    doxygen_cfg,
+  ],
+  output : 'html',
+  install : true,
+  install_dir : get_option('datadir') / 'doc/nix/external-api',
+  build_always_stale : true,
+)

src/external-api-docs/package.nix

@@ -0,0 +1,65 @@
+{ lib
+, stdenv
+, releaseTools
+, fileset
+
+, meson
+, ninja
+, doxygen
+
+# Configuration Options
+
+, versionSuffix ? ""
+}:
+
+stdenv.mkDerivation (finalAttrs: {
+  pname = "nix-external-api-docs";
+  version = lib.fileContents ./.version + versionSuffix;
+
+  src = fileset.toSource {
+    root = ../..;
+    fileset =
+      let
+        cpp = fileset.fileFilter (file: file.hasExt "cc" || file.hasExt "h");
+      in
+      fileset.unions [
+        ./meson.build
+        ./doxygen.cfg.in
+        ./README.md
+        # Source is not compiled, but still must be available for Doxygen
+        # to gather comments.
+        (cpp ../libexpr-c)
+        (cpp ../libstore-c)
+        (cpp ../libutil-c)
+      ];
+  };
+
+  nativeBuildInputs = [
+    meson
+    ninja
+    doxygen
+  ];
+
+  postUnpack = ''
+    sourceRoot=$sourceRoot/src/external-api-docs
+  '';
+
+  preConfigure =
+    # "Inline" .version so it's not a symlink, and includes the suffix
+    ''
+      echo ${finalAttrs.version} > .version
+    '';
+
+  postInstall = ''
+    mkdir -p ''${!outputDoc}/nix-support
+    echo "doc external-api-docs $out/share/doc/nix/external-api/html" >> ''${!outputDoc}/nix-support/hydra-build-products
+  '';
+
+  enableParallelBuilding = true;
+
+  strictDeps = true;
+
+  meta = {
+    platforms = lib.platforms.all;
+  };
+})

src/internal-api-docs/package.nix

@@ -46,6 +46,11 @@ stdenv.mkDerivation (finalAttrs: {
       echo ${finalAttrs.version} > .version
     '';
 
+  postInstall = ''
+    mkdir -p ''${!outputDoc}/nix-support
+    echo "doc internal-api-docs $out/share/doc/nix/internal-api/html" >> ''${!outputDoc}/nix-support/hydra-build-products
+  '';
+
   enableParallelBuilding = true;
 
   strictDeps = true;