From 1c131ec2b71fa7ad6fd285ed2a9fcc4cf616b3a6 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Wed, 19 Jun 2024 22:43:54 +0200 Subject: [PATCH] Port C API docs to Meson (#10936) * Port C API docs to Meson * don't cross-compile the docs --- Makefile | 11 ---- Makefile.config.in | 1 - configure.ac | 9 --- doc/external-api/local.mk | 7 -- doc/manual/src/contributing/documentation.md | 10 +-- flake.nix | 14 +++- maintainers/hydra.nix | 6 +- meson.build | 1 + package.nix | 25 +------ .../external-api-docs}/.gitignore | 0 src/external-api-docs/.version | 1 + .../external-api-docs}/README.md | 0 .../external-api-docs}/doxygen.cfg.in | 13 ++-- src/external-api-docs/meson.build | 31 +++++++++ src/external-api-docs/package.nix | 65 +++++++++++++++++++ src/internal-api-docs/package.nix | 5 ++ 16 files changed, 131 insertions(+), 68 deletions(-) delete mode 100644 doc/external-api/local.mk rename {doc/external-api => src/external-api-docs}/.gitignore (100%) create mode 120000 src/external-api-docs/.version rename {doc/external-api => src/external-api-docs}/README.md (100%) rename {doc/external-api => src/external-api-docs}/doxygen.cfg.in (91%) create mode 100644 src/external-api-docs/meson.build create mode 100644 src/external-api-docs/package.nix diff --git a/Makefile b/Makefile index 257560028..227aaf6d9 100644 --- a/Makefile +++ b/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 diff --git a/Makefile.config.in b/Makefile.config.in index 56e67e5cd..3100d2073 100644 --- a/Makefile.config.in +++ b/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@ diff --git a/configure.ac b/configure.ac index 2fefbe95a..2b5cd115f 100644 --- a/configure.ac +++ b/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)]) diff --git a/doc/external-api/local.mk b/doc/external-api/local.mk deleted file mode 100644 index ae2b44db8..000000000 --- a/doc/external-api/local.mk +++ /dev/null @@ -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 diff --git a/doc/manual/src/contributing/documentation.md b/doc/manual/src/contributing/documentation.md index a5e2bfa83..a14ecedd6 100644 --- a/doc/manual/src/contributing/documentation.md +++ b/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 -# xdg-open ./result/share/doc/nix/external-api/html/index.html +$ nix build .#hydraJobs.external-api-docs +$ xdg-open ./result/share/doc/nix/external-api/html/index.html ``` or inside `nix-shell` or `nix develop`: ``` -# make external-api-html -# xdg-open ./outputs/doc/share/doc/nix/external-api/html/index.html +$ mesonConfigurePhase +$ ninja src/external-api-docs/html +$ xdg-open src/external-api-docs/html/index.html ``` diff --git a/flake.nix b/flake.nix index 5c8d84a75..4e7363cd6 100644 --- a/flake.nix +++ b/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" diff --git a/maintainers/hydra.nix b/maintainers/hydra.nix index 293dee5cd..abd44efef 100644 --- a/maintainers/hydra.nix +++ b/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 { - inherit fileset; - doBuild = false; - enableExternalAPIDocs = true; - }; + external-api-docs = nixpkgsFor.x86_64-linux.native.nix-external-api-docs; # System tests. tests = import ../tests/nixos { inherit lib nixpkgs nixpkgsFor self; } // { diff --git a/meson.build b/meson.build index ebad238b1..e67fd4a7a 100644 --- a/meson.build +++ b/meson.build @@ -11,3 +11,4 @@ subproject('libstore') subproject('libfetchers') subproject('perl') subproject('internal-api-docs') +subproject('external-api-docs') diff --git a/package.nix b/package.nix index 64096c7aa..f414b9a73 100644 --- a/package.nix +++ b/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 -# generating API docs or (b) testing existing pre-built versions of Nix +# Whether to build Nix. Useful to skip for tasks like 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" - ++ lib.optional enableExternalAPIDocs "external-api-html"; + installTargets = lib.optional doBuild "install"; 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. diff --git a/doc/external-api/.gitignore b/src/external-api-docs/.gitignore similarity index 100% rename from doc/external-api/.gitignore rename to src/external-api-docs/.gitignore diff --git a/src/external-api-docs/.version b/src/external-api-docs/.version new file mode 120000 index 000000000..b7badcd0c --- /dev/null +++ b/src/external-api-docs/.version @@ -0,0 +1 @@ +../../.version \ No newline at end of file diff --git a/doc/external-api/README.md b/src/external-api-docs/README.md similarity index 100% rename from doc/external-api/README.md rename to src/external-api-docs/README.md diff --git a/doc/external-api/doxygen.cfg.in b/src/external-api-docs/doxygen.cfg.in similarity index 91% rename from doc/external-api/doxygen.cfg.in rename to src/external-api-docs/doxygen.cfg.in index cd8b4989b..1be71d895 100644 --- a/doc/external-api/doxygen.cfg.in +++ b/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/libexpr-c \ - src/libstore-c \ - doc/external-api/README.md + @src@/src/libutil-c \ + @src@/src/libexpr-c \ + @src@/src/libstore-c \ + @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 diff --git a/src/external-api-docs/meson.build b/src/external-api-docs/meson.build new file mode 100644 index 000000000..62474ffe4 --- /dev/null +++ b/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, +) diff --git a/src/external-api-docs/package.nix b/src/external-api-docs/package.nix new file mode 100644 index 000000000..aa5cd49eb --- /dev/null +++ b/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; + }; +}) diff --git a/src/internal-api-docs/package.nix b/src/internal-api-docs/package.nix index bb20a68d3..b5f1b0da1 100644 --- a/src/internal-api-docs/package.nix +++ b/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;