build internal API docs with Meson

This commit adds the capability for building the Doxygen internal API
docs in the Meson buildsystem, and also makes doing so the default for
the internal-api-docs hydra job. Aside from the /nix-support directory,
which differed only by the hash part of a store path, the outputs of
hydraJobs.internal-api-docs before and after this commit were
bit-for-bit identical on my machine.

Change-Id: I98f0017891c25b06866c15f7652fe74f706ec8e1

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;
@@ -264,6 +264,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) [
-    "-Dsandbox-shell=${lib.getBin busybox-sandbox-shell}/bin/busybox"
-  ];
+  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