From 6e34c6832796781667562e1e40e85fc09a085987 Mon Sep 17 00:00:00 2001 From: Valentin Gagarin Date: Mon, 17 Jun 2024 15:50:59 +0200 Subject: [PATCH] Convert the internal API doc build to Meson --- Makefile | 11 ---- Makefile.config.in | 1 - configure.ac | 5 -- doc/internal-api/local.mk | 7 --- doc/manual/src/contributing/documentation.md | 12 ++-- flake.nix | 10 ++++ maintainers/hydra.nix | 6 +- meson.build | 1 + package.nix | 19 ++----- .../internal-api-docs}/.gitignore | 0 src/internal-api-docs/.version | 1 + .../internal-api-docs}/doxygen.cfg.in | 46 +++++++-------- src/internal-api-docs/meson.build | 31 ++++++++++ src/internal-api-docs/package.nix | 56 +++++++++++++++++++ 14 files changed, 136 insertions(+), 70 deletions(-) delete mode 100644 doc/internal-api/local.mk rename {doc/internal-api => src/internal-api-docs}/.gitignore (100%) create mode 120000 src/internal-api-docs/.version rename {doc/internal-api => src/internal-api-docs}/doxygen.cfg.in (82%) create mode 100644 src/internal-api-docs/meson.build create mode 100644 src/internal-api-docs/package.nix diff --git a/Makefile b/Makefile index 6c96ef5db..257560028 100644 --- a/Makefile +++ b/Makefile @@ -68,10 +68,6 @@ ifeq ($(ENABLE_DOC_GEN), yes) makefiles-late += doc/manual/local.mk endif -ifeq ($(ENABLE_INTERNAL_API_DOCS), yes) -makefiles-late += doc/internal-api/local.mk -endif - ifeq ($(ENABLE_EXTERNAL_API_DOCS), yes) makefiles-late += doc/external-api/local.mk endif @@ -132,13 +128,6 @@ manual-html manpages: @exit 1 endif -ifneq ($(ENABLE_INTERNAL_API_DOCS), yes) -.PHONY: internal-api-html -internal-api-html: - @echo "Internal API docs are disabled. Configure with '--enable-internal-api-docs', or avoid calling 'make internal-api-html'." - @exit 1 -endif - ifneq ($(ENABLE_EXTERNAL_API_DOCS), yes) .PHONY: external-api-html external-api-html: diff --git a/Makefile.config.in b/Makefile.config.in index 7f517898c..56e67e5cd 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_INTERNAL_API_DOCS = @ENABLE_INTERNAL_API_DOCS@ ENABLE_EXTERNAL_API_DOCS = @ENABLE_EXTERNAL_API_DOCS@ ENABLE_S3 = @ENABLE_S3@ ENABLE_UNIT_TESTS = @ENABLE_UNIT_TESTS@ diff --git a/configure.ac b/configure.ac index 8211bec0b..2fefbe95a 100644 --- a/configure.ac +++ b/configure.ac @@ -171,11 +171,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'.])]) -# Building without API docs is the default as Nix' C++ interfaces are internal and unstable. -AC_ARG_ENABLE(internal-api-docs, AS_HELP_STRING([--enable-internal-api-docs],[Build API docs for Nix's internal unstable C++ interfaces]), - ENABLE_INTERNAL_API_DOCS=$enableval, ENABLE_INTERNAL_API_DOCS=no) -AC_SUBST(ENABLE_INTERNAL_API_DOCS) - 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) diff --git a/doc/internal-api/local.mk b/doc/internal-api/local.mk deleted file mode 100644 index be9b7bb55..000000000 --- a/doc/internal-api/local.mk +++ /dev/null @@ -1,7 +0,0 @@ -$(docdir)/internal-api/html/index.html $(docdir)/internal-api/latex: $(d)/doxygen.cfg src/**/*.hh - mkdir -p $(docdir)/internal-api - { cat $< ; echo "OUTPUT_DIRECTORY=$(docdir)/internal-api" ; } | doxygen - - -# Generate the HTML API docs for Nix's unstable internal interfaces. -.PHONY: internal-api-html -internal-api-html: $(docdir)/internal-api/html/index.html diff --git a/doc/manual/src/contributing/documentation.md b/doc/manual/src/contributing/documentation.md index 6e7c0a967..a5e2bfa83 100644 --- a/doc/manual/src/contributing/documentation.md +++ b/doc/manual/src/contributing/documentation.md @@ -196,15 +196,17 @@ You can also build and view it yourself: [Doxygen API documentation]: https://hydra.nixos.org/job/nix/master/internal-api-docs/latest/download-by-type/doc/internal-api-docs ```console -# nix build .#hydraJobs.internal-api-docs -# xdg-open ./result/share/doc/nix/internal-api/html/index.html +$ nix build .#hydraJobs.internal-api-docs +$ xdg-open ./result/share/doc/nix/internal-api/html/index.html ``` or inside `nix-shell` or `nix develop`: -``` -# make internal-api-html -# xdg-open ./outputs/doc/share/doc/nix/internal-api/html/index.html +```console +$ mesonConfigurePhase +$ cd build +$ ninja src/internal-api-docs/html +$ xdg-open src/internal-api-docs/html/index.html ``` ## C API documentation diff --git a/flake.nix b/flake.nix index 2b0e3c613..77b0870a2 100644 --- a/flake.nix +++ b/flake.nix @@ -202,6 +202,15 @@ ; }; + + nix-internal-api-docs = final.callPackage ./src/internal-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 = @@ -279,6 +288,7 @@ # system, we should reenable these. #"nix-util" = { }; #"nix-store" = { }; + "nix-internal-api-docs" = { }; } // lib.optionalAttrs (builtins.elem system linux64BitSystems) { dockerImage = diff --git a/maintainers/hydra.nix b/maintainers/hydra.nix index 6c07e65d4..235752979 100644 --- a/maintainers/hydra.nix +++ b/maintainers/hydra.nix @@ -124,11 +124,7 @@ in }; # API docs for Nix's unstable internal C++ interfaces. - internal-api-docs = nixpkgsFor.x86_64-linux.native.callPackage ../package.nix { - inherit fileset; - doBuild = false; - enableInternalAPIDocs = true; - }; + 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 { diff --git a/meson.build b/meson.build index f1ee7a571..95a6665a7 100644 --- a/meson.build +++ b/meson.build @@ -9,3 +9,4 @@ project('nix-dev-shell', 'cpp', subproject('libutil') subproject('libstore') subproject('perl') +subproject('internal-api-docs') diff --git a/package.nix b/package.nix index cb9554235..64096c7aa 100644 --- a/package.nix +++ b/package.nix @@ -93,9 +93,8 @@ # - readline , readlineFlavor ? if stdenv.hostPlatform.isWindows then "readline" else "editline" -# Whether to build the internal/external API docs, can be done separately from +# Whether to build the external API docs, can be done separately from # everything else. -, enableInternalAPIDocs ? forDevShell , enableExternalAPIDocs ? forDevShell # Whether to install unit tests. This is useful when cross compiling @@ -185,11 +184,9 @@ in { ./scripts/local.mk ] ++ lib.optionals buildUnitTests [ ./doc/manual - ] ++ lib.optionals enableInternalAPIDocs [ - ./doc/internal-api ] ++ lib.optionals enableExternalAPIDocs [ ./doc/external-api - ] ++ lib.optionals (enableInternalAPIDocs || enableExternalAPIDocs) [ + ] ++ lib.optionals enableExternalAPIDocs [ # Source might not be compiled, but still must be available # for Doxygen to gather comments. (fileset.difference ./src ./src/perl) @@ -207,7 +204,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 || enableInternalAPIDocs || enableExternalAPIDocs)) "doc" + ++ lib.optional (doBuild && (enableManual || enableExternalAPIDocs)) "doc" ++ lib.optional installUnitTests "check" ++ lib.optional doCheck "testresults" ; @@ -231,7 +228,7 @@ in { ] ++ lib.optionals (doInstallCheck || enableManual) [ jq # Also for custom mdBook preprocessor. ] ++ lib.optional stdenv.hostPlatform.isLinux util-linux - ++ lib.optional (enableInternalAPIDocs || enableExternalAPIDocs) doxygen + ++ lib.optional enableExternalAPIDocs doxygen ; buildInputs = lib.optionals doBuild [ @@ -294,7 +291,6 @@ in { (lib.enableFeature doBuild "build") (lib.enableFeature buildUnitTests "unit-tests") (lib.enableFeature doInstallCheck "functional-tests") - (lib.enableFeature enableInternalAPIDocs "internal-api-docs") (lib.enableFeature enableExternalAPIDocs "external-api-docs") (lib.enableFeature enableManual "doc-gen") (lib.enableFeature enableGC "gc") @@ -324,7 +320,6 @@ in { ''; installTargets = lib.optional doBuild "install" - ++ lib.optional enableInternalAPIDocs "internal-api-html" ++ lib.optional enableExternalAPIDocs "external-api-html"; installFlags = "sysconfdir=$(out)/etc"; @@ -349,11 +344,7 @@ 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 enableInternalAPIDocs '' - mkdir -p ''${!outputDoc}/nix-support - echo "doc internal-api-docs $out/share/doc/nix/internal-api/html" >> ''${!outputDoc}/nix-support/hydra-build-products - '' - + lib.optionalString enableExternalAPIDocs '' + '' + 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 ''; diff --git a/doc/internal-api/.gitignore b/src/internal-api-docs/.gitignore similarity index 100% rename from doc/internal-api/.gitignore rename to src/internal-api-docs/.gitignore diff --git a/src/internal-api-docs/.version b/src/internal-api-docs/.version new file mode 120000 index 000000000..b7badcd0c --- /dev/null +++ b/src/internal-api-docs/.version @@ -0,0 +1 @@ +../../.version \ No newline at end of file diff --git a/doc/internal-api/doxygen.cfg.in b/src/internal-api-docs/doxygen.cfg.in similarity index 82% rename from doc/internal-api/doxygen.cfg.in rename to src/internal-api-docs/doxygen.cfg.in index 6c6c325bd..9e7425581 100644 --- a/doc/internal-api/doxygen.cfg.in +++ b/src/internal-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,27 +38,27 @@ GENERATE_LATEX = NO # so they can expand variables despite configure variables. INPUT = \ - src/libcmd \ - src/libexpr \ - src/libexpr/flake \ - tests/unit/libexpr \ - tests/unit/libexpr/value \ - tests/unit/libexpr/test \ - tests/unit/libexpr/test/value \ - src/libexpr/value \ - src/libfetchers \ - src/libmain \ - src/libstore \ - src/libstore/build \ - src/libstore/builtins \ - tests/unit/libstore \ - tests/unit/libstore/test \ - src/libutil \ - tests/unit/libutil \ - tests/unit/libutil/test \ - src/nix \ - src/nix-env \ - src/nix-store + @src@/src/libcmd \ + @src@/src/libexpr \ + @src@/src/libexpr/flake \ + @src@/tests/unit/libexpr \ + @src@/tests/unit/libexpr/value \ + @src@/tests/unit/libexpr/test \ + @src@/tests/unit/libexpr/test/value \ + @src@/src/libexpr/value \ + @src@/src/libfetchers \ + @src@/src/libmain \ + @src@/src/libstore \ + @src@/src/libstore/build \ + @src@/src/libstore/builtins \ + @src@/tests/unit/libstore \ + @src@/tests/unit/libstore/test \ + @src@/src/libutil \ + @src@/tests/unit/libutil \ + @src@/tests/unit/libutil/test \ + @src@/src/nix \ + @src@/src/nix-env \ + @src@/src/nix-store # If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names # in the source code. If set to NO, only conditional compilation will be diff --git a/src/internal-api-docs/meson.build b/src/internal-api-docs/meson.build new file mode 100644 index 000000000..2568c56cf --- /dev/null +++ b/src/internal-api-docs/meson.build @@ -0,0 +1,31 @@ +project('nix-internal-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( + 'internal-api-docs', + command : [ doxygen , doxygen_cfg ], + input : [ + doxygen_cfg, + ], + output : 'html', + install : true, + install_dir : get_option('datadir') / 'doc/nix/internal-api', + build_always_stale : true, +) diff --git a/src/internal-api-docs/package.nix b/src/internal-api-docs/package.nix new file mode 100644 index 000000000..bb20a68d3 --- /dev/null +++ b/src/internal-api-docs/package.nix @@ -0,0 +1,56 @@ +{ lib +, stdenv +, releaseTools +, fileset + +, meson +, ninja +, doxygen + +# Configuration Options + +, versionSuffix ? "" +}: + +stdenv.mkDerivation (finalAttrs: { + pname = "nix-internal-api-docs"; + version = lib.fileContents ./.version + versionSuffix; + + src = fileset.toSource { + root = ../..; + fileset = let + cpp = fileset.fileFilter (file: file.hasExt "cc" || file.hasExt "hh"); + in fileset.unions [ + ./meson.build + ./doxygen.cfg.in + # Source is not compiled, but still must be available for Doxygen + # to gather comments. + (cpp ../.) + (cpp ../../tests/unit) + ]; + }; + + nativeBuildInputs = [ + meson + ninja + doxygen + ]; + + postUnpack = '' + sourceRoot=$sourceRoot/src/internal-api-docs + ''; + + preConfigure = + # "Inline" .version so it's not a symlink, and includes the suffix + '' + echo ${finalAttrs.version} > .version + ''; + + enableParallelBuilding = true; + + strictDeps = true; + + meta = { + platforms = lib.platforms.all; + }; +})