From baadba018e9ba08670f120c40e7f048cfe4371b8 Mon Sep 17 00:00:00 2001 From: Qyriad Date: Thu, 11 Apr 2024 12:17:19 -0600 Subject: [PATCH] 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 | 2 ++ doc/internal-api/meson.build | 33 +++++++++++++++++++++++++++++++++ flake.nix | 3 ++- meson.build | 21 ++++++++++++++++++++- meson.options | 9 +++++++++ package.nix | 22 ++++++++++++++++++---- 6 files changed, 84 insertions(+), 6 deletions(-) create mode 100644 doc/internal-api/meson.build diff --git a/doc/internal-api/doxygen.cfg.in b/doc/internal-api/doxygen.cfg.in index ad5af97e6..55bccebd7 100644 --- a/doc/internal-api/doxygen.cfg.in +++ b/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. diff --git a/doc/internal-api/meson.build b/doc/internal-api/meson.build new file mode 100644 index 000000000..35d8a0e5b --- /dev/null +++ b/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) diff --git a/flake.nix b/flake.nix index 8eb5582b0..0223f0ccc 100644 --- a/flake.nix +++ b/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: { diff --git a/meson.build b/meson.build index 22739a4ab..cd264c16f 100644 --- a/meson.build +++ b/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') diff --git a/meson.options b/meson.options index c71ec18ae..e66b6c5ed 100644 --- a/meson.options +++ b/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', diff --git a/package.nix b/package.nix index e1d3cfcd5..aab98c0ae 100644 --- a/package.nix +++ b/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