Merge "build internal API docs with Meson" into main

doc/internal-api/doxygen.cfg.in

@@ -14,6 +14,8 @@ PROJECT_NAME           = "Nix"
 
 PROJECT_NUMBER         = @PACKAGE_VERSION@
 
+OUTPUT_DIRECTORY       = @docdir@
+
 # 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.

doc/internal-api/meson.build

@@ -0,0 +1,33 @@
+doxygen_cfg = configure_file(
+  input : 'doxygen.cfg.in',
+  output : 'doxygen.cfg',
+  configuration : {
+    'PACKAGE_VERSION': meson.project_version(),
+    'RAPIDCHECK_HEADERS': rapidcheck_meson.get_variable('includedir'),
+    'docdir' : meson.current_build_dir(),
+  },
+)
+
+internal_api_docs = custom_target(
+  'internal-api-docs',
+  command : [
+    bash,
+    # Meson can you please just give us a `workdir` argument to custom targets...
+    '-c',
+    # We have to prefix the doxygen_cfg path with the project build root
+    # because of the cd in front.
+    'cd @0@ && @1@ @2@/@INPUT0@'.format(
+      meson.project_source_root(),
+      doxygen.full_path(),
+      meson.project_build_root(),
+    ),
+  ],
+  input : [
+    doxygen_cfg,
+  ],
+  output : 'html',
+  install : true,
+  install_dir : datadir / 'doc/nix/internal-api',
+)
+
+alias_target('internal-api-html', internal_api_docs)

flake.nix

@@ -26,7 +26,7 @@
     let
       inherit (nixpkgs) lib;
 
-      officialRelease = true;
+      officialRelease = false;
 
       # Set to true to build the release notes for the next release.
       buildUnreleasedNotes = false;
@@ -237,6 +237,7 @@
               inherit (pkgs) build-release-notes;
               internalApiDocs = true;
               busybox-sandbox-shell = pkgs.busybox-sandbox-shell;
+              buildWithMeson = true;
             };
           in
           nix.overrideAttrs (prev: {

meson.build

@@ -79,7 +79,25 @@ if not fs.is_absolute(sysconfdir)
   sysconfdir = '/' / sysconfdir
 endif
 
+# All of this has to go before the rest of the dependency checking,
+# so that internal-api-docs can be built with -Denable-build=false
+
 enable_docs = get_option('enable-docs')
+enable_internal_api_docs = get_option('internal-api-docs')
+
+doxygen = find_program('doxygen', required : enable_internal_api_docs)
+bash = find_program('bash')
+
+rapidcheck_meson = dependency('rapidcheck', required : enable_internal_api_docs)
+
+if enable_internal_api_docs.enabled()
+  message('subdiring()')
+  subdir('doc/internal-api')
+endif
+
+if not get_option('enable-build')
+  subdir_done()
+endif
 
 enable_tests = get_option('enable-tests')
 
@@ -223,6 +241,8 @@ lowdown = dependency('lowdown', version : '>=0.9.0', required : true)
 deps += lowdown
 
 # HACK(Qyriad): rapidcheck's pkg-config doesn't include the libs lol
+# Note: technically we 'check' for rapidcheck twice, for the internal-api-docs handling above,
+# but Meson will cache the result of the first one, and the required : arguments are different.
 rapidcheck_meson = dependency('rapidcheck', required : enable_tests)
 rapidcheck = declare_dependency(dependencies : rapidcheck_meson, link_args : ['-lrapidcheck'])
 deps += rapidcheck
@@ -252,7 +272,6 @@ deps += lix_doc
 #
 # Build-time tools
 #
-bash = find_program('bash')
 coreutils = find_program('coreutils')
 dot = find_program('dot', required : false)
 pymod = import('python')

meson.options

@@ -1,4 +1,9 @@
 # vim: filetype=meson
+
+option('enable-build', type : 'boolean', value : true,
+  description : 'Set to false to not actually build. Only really makes sense with -Dinternal-api-docs=true',
+)
+
 option('gc', type : 'feature',
   description : 'enable garbage collection in the Nix expression evaluator (requires Boehm GC)',
 )
@@ -51,6 +56,10 @@ option('enable-docs', type : 'boolean', value : true,
   description : 'whether to build documentation',
 )
 
+option('internal-api-docs', type : 'feature', value : 'auto',
+  description : 'whether to build internal API documentation (requires doxygen)',
+)
+
 # A relative path means it gets appended to prefix.
 option('profile-dir', type : 'string', value : 'etc/profile.d',
   description : 'the path to install shell profile files',

package.nix

@@ -178,9 +178,15 @@ stdenv.mkDerivation (finalAttrs: {
   dontBuild = false;
 
   # FIXME(Qyriad): see if this is still needed once the migration to Meson is completed.
-  mesonFlags = lib.optionals (buildWithMeson && stdenv.hostPlatform.isLinux) [
+  mesonFlags =
+    lib.optionals (buildWithMeson && stdenv.hostPlatform.isLinux) [
       "-Dsandbox-shell=${lib.getBin busybox-sandbox-shell}/bin/busybox"
-  ];
+    ]
+    ++ lib.optional (finalAttrs.dontBuild) "-Denable-build=false"
+    # mesonConfigurePhase automatically passes -Dauto_features=enabled,
+    # so we must explicitly enable or disable features that we are not passing
+    # dependencies for.
+    ++ lib.singleton (lib.mesonEnable "internal-api-docs" internalApiDocs);
 
   # We only include CMake so that Meson can locate toml11, which only ships CMake dependency metadata.
   dontUseCmakeConfigure = true;
@@ -209,7 +215,7 @@ stdenv.mkDerivation (finalAttrs: {
     ]
     ++ lib.optional stdenv.hostPlatform.isLinux util-linuxMinimal
     ++ lib.optional (!officialRelease && buildUnreleasedNotes) build-release-notes
-    ++ lib.optional internalApiDocs doxygen
+    ++ lib.optional (internalApiDocs || forDevShell) doxygen
     ++ lib.optionals buildWithMeson [
       meson
       ninja
@@ -236,6 +242,7 @@ stdenv.mkDerivation (finalAttrs: {
       libseccomp
       busybox-sandbox-shell
     ]
+    ++ lib.optional internalApiDocs rapidcheck
     ++ lib.optional stdenv.hostPlatform.isx86_64 libcpuid
     # There have been issues building these dependencies
     ++ lib.optional (stdenv.hostPlatform == stdenv.buildPlatform) aws-sdk-cpp-nix
@@ -313,6 +320,13 @@ stdenv.mkDerivation (finalAttrs: {
 
   installFlags = "sysconfdir=$(out)/etc";
 
+  # Make sure the internal API docs are already built, because mesonInstallPhase
+  # won't let us build them there. They would normally be built in buildPhase,
+  # but the internal API docs are conventionally built with doBuild = false.
+  preInstall = lib.optional (buildWithMeson && internalApiDocs) ''
+    meson ''${mesonBuildFlags:-} compile "$installTargets"
+  '';
+
   postInstall =
     lib.optionalString (!finalAttrs.dontBuild) ''
       mkdir -p $doc/nix-support