Port C API docs to Meson (#10936)

* Port C API docs to Meson

* don't cross-compile the docs
This commit is contained in:
Valentin Gagarin 2024-06-19 22:43:54 +02:00 committed by GitHub
parent 0c6029669d
commit 1c131ec2b7
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
16 changed files with 131 additions and 68 deletions

View file

@ -68,10 +68,6 @@ ifeq ($(ENABLE_DOC_GEN), yes)
makefiles-late += doc/manual/local.mk makefiles-late += doc/manual/local.mk
endif endif
ifeq ($(ENABLE_EXTERNAL_API_DOCS), yes)
makefiles-late += doc/external-api/local.mk
endif
# Miscellaneous global Flags # Miscellaneous global Flags
OPTIMIZE = 1 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'." @echo "Generated docs are disabled. Configure without '--disable-doc-gen', or avoid calling 'make manpages' and 'make manual-html'."
@exit 1 @exit 1
endif 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

View file

@ -11,7 +11,6 @@ EDITLINE_LIBS = @EDITLINE_LIBS@
ENABLE_BUILD = @ENABLE_BUILD@ ENABLE_BUILD = @ENABLE_BUILD@
ENABLE_DOC_GEN = @ENABLE_DOC_GEN@ ENABLE_DOC_GEN = @ENABLE_DOC_GEN@
ENABLE_FUNCTIONAL_TESTS = @ENABLE_FUNCTIONAL_TESTS@ ENABLE_FUNCTIONAL_TESTS = @ENABLE_FUNCTIONAL_TESTS@
ENABLE_EXTERNAL_API_DOCS = @ENABLE_EXTERNAL_API_DOCS@
ENABLE_S3 = @ENABLE_S3@ ENABLE_S3 = @ENABLE_S3@
ENABLE_UNIT_TESTS = @ENABLE_UNIT_TESTS@ ENABLE_UNIT_TESTS = @ENABLE_UNIT_TESTS@
GTEST_LIBS = @GTEST_LIBS@ GTEST_LIBS = @GTEST_LIBS@

View file

@ -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) ENABLE_UNIT_TESTS=$enableval, ENABLE_UNIT_TESTS=$ENABLE_BUILD)
AC_SUBST(ENABLE_UNIT_TESTS) 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( AS_IF(
[test "$ENABLE_BUILD" == "no" && test "$ENABLE_UNIT_TESTS" == "yes"], [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'.])]) [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"], [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_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( AS_IF(
[test "$ENABLE_FUNCTIONAL_TESTS" == "yes" || test "$ENABLE_DOC_GEN" == "yes"], [test "$ENABLE_FUNCTIONAL_TESTS" == "yes" || test "$ENABLE_DOC_GEN" == "yes"],
[NEED_PROG(jq, jq)]) [NEED_PROG(jq, jq)])

View file

@ -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

View file

@ -204,7 +204,6 @@ or inside `nix-shell` or `nix develop`:
```console ```console
$ mesonConfigurePhase $ mesonConfigurePhase
$ cd build
$ ninja src/internal-api-docs/html $ ninja src/internal-api-docs/html
$ xdg-open src/internal-api-docs/html/index.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 [C API documentation]: https://hydra.nixos.org/job/nix/master/external-api-docs/latest/download-by-type/doc/external-api-docs
```console ```console
# nix build .#hydraJobs.external-api-docs $ nix build .#hydraJobs.external-api-docs
# xdg-open ./result/share/doc/nix/external-api/html/index.html $ xdg-open ./result/share/doc/nix/external-api/html/index.html
``` ```
or inside `nix-shell` or `nix develop`: or inside `nix-shell` or `nix develop`:
``` ```
# make external-api-html $ mesonConfigurePhase
# xdg-open ./outputs/doc/share/doc/nix/external-api/html/index.html $ ninja src/external-api-docs/html
$ xdg-open src/external-api-docs/html/index.html
``` ```

View file

@ -211,7 +211,6 @@
; ;
}; };
nix-internal-api-docs = final.callPackage ./src/internal-api-docs/package.nix { nix-internal-api-docs = final.callPackage ./src/internal-api-docs/package.nix {
inherit inherit
fileset 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 # See https://github.com/NixOS/nixpkgs/pull/214409
# Remove when fixed in this flake's nixpkgs # Remove when fixed in this flake's nixpkgs
pre-commit = pre-commit =
@ -275,6 +282,8 @@
inherit (nixpkgsFor.${system}.native) inherit (nixpkgsFor.${system}.native)
changelog-d; changelog-d;
default = self.packages.${system}.nix; 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 } // lib.concatMapAttrs
# We need to flatten recursive attribute sets of derivations to pass `flake check`. # We need to flatten recursive attribute sets of derivations to pass `flake check`.
(pkgName: {}: { (pkgName: {}: {
@ -298,7 +307,6 @@
#"nix-util" = { }; #"nix-util" = { };
#"nix-store" = { }; #"nix-store" = { };
#"nix-fetchers" = { }; #"nix-fetchers" = { };
"nix-internal-api-docs" = { };
} }
// lib.optionalAttrs (builtins.elem system linux64BitSystems) { // lib.optionalAttrs (builtins.elem system linux64BitSystems) {
dockerImage = dockerImage =
@ -370,6 +378,8 @@
++ pkgs.nix-store.nativeBuildInputs ++ pkgs.nix-store.nativeBuildInputs
++ pkgs.nix-fetchers.nativeBuildInputs ++ pkgs.nix-fetchers.nativeBuildInputs
++ lib.optionals havePerl pkgs.nix-perl-bindings.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 modular.pre-commit.settings.package
(pkgs.writeScriptBin "pre-commit-hooks-install" (pkgs.writeScriptBin "pre-commit-hooks-install"

View file

@ -128,11 +128,7 @@ in
internal-api-docs = nixpkgsFor.x86_64-linux.native.nix-internal-api-docs; internal-api-docs = nixpkgsFor.x86_64-linux.native.nix-internal-api-docs;
# API docs for Nix's C bindings. # API docs for Nix's C bindings.
external-api-docs = nixpkgsFor.x86_64-linux.native.callPackage ../package.nix { external-api-docs = nixpkgsFor.x86_64-linux.native.nix-external-api-docs;
inherit fileset;
doBuild = false;
enableExternalAPIDocs = true;
};
# System tests. # System tests.
tests = import ../tests/nixos { inherit lib nixpkgs nixpkgsFor self; } // { tests = import ../tests/nixos { inherit lib nixpkgs nixpkgsFor self; } // {

View file

@ -11,3 +11,4 @@ subproject('libstore')
subproject('libfetchers') subproject('libfetchers')
subproject('perl') subproject('perl')
subproject('internal-api-docs') subproject('internal-api-docs')
subproject('external-api-docs')

View file

@ -20,7 +20,6 @@
, git , git
, gtest , gtest
, jq , jq
, doxygen
, libarchive , libarchive
, libcpuid , libcpuid
, libgit2 , libgit2
@ -53,8 +52,7 @@
, versionSuffix ? "" , versionSuffix ? ""
, officialRelease ? false , officialRelease ? false
# Whether to build Nix. Useful to skip for tasks like (a) just # Whether to build Nix. Useful to skip for tasks like testing existing pre-built versions of Nix
# generating API docs or (b) testing existing pre-built versions of Nix
, doBuild ? true , doBuild ? true
# Run the unit tests as part of the build. See `installUnitTests` for an # Run the unit tests as part of the build. See `installUnitTests` for an
@ -93,10 +91,6 @@
# - readline # - readline
, readlineFlavor ? if stdenv.hostPlatform.isWindows then "readline" else "editline" , 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 # Whether to install unit tests. This is useful when cross compiling
# since we cannot run them natively during the build, but can do so # since we cannot run them natively during the build, but can do so
# later. # later.
@ -184,13 +178,6 @@ in {
./scripts/local.mk ./scripts/local.mk
] ++ lib.optionals buildUnitTests [ ] ++ lib.optionals buildUnitTests [
./doc/manual ./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 [ ] ++ lib.optionals buildUnitTests [
./tests/unit ./tests/unit
] ++ lib.optionals doInstallCheck [ ] ++ lib.optionals doInstallCheck [
@ -204,7 +191,7 @@ in {
++ lib.optional doBuild "dev" ++ lib.optional doBuild "dev"
# If we are doing just build or just docs, the one thing will use # 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. # "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 installUnitTests "check"
++ lib.optional doCheck "testresults" ++ lib.optional doCheck "testresults"
; ;
@ -228,7 +215,6 @@ in {
] ++ lib.optionals (doInstallCheck || enableManual) [ ] ++ lib.optionals (doInstallCheck || enableManual) [
jq # Also for custom mdBook preprocessor. jq # Also for custom mdBook preprocessor.
] ++ lib.optional stdenv.hostPlatform.isLinux util-linux ] ++ lib.optional stdenv.hostPlatform.isLinux util-linux
++ lib.optional enableExternalAPIDocs doxygen
; ;
buildInputs = lib.optionals doBuild [ buildInputs = lib.optionals doBuild [
@ -291,7 +277,6 @@ in {
(lib.enableFeature doBuild "build") (lib.enableFeature doBuild "build")
(lib.enableFeature buildUnitTests "unit-tests") (lib.enableFeature buildUnitTests "unit-tests")
(lib.enableFeature doInstallCheck "functional-tests") (lib.enableFeature doInstallCheck "functional-tests")
(lib.enableFeature enableExternalAPIDocs "external-api-docs")
(lib.enableFeature enableManual "doc-gen") (lib.enableFeature enableManual "doc-gen")
(lib.enableFeature enableGC "gc") (lib.enableFeature enableGC "gc")
(lib.enableFeature enableMarkdown "markdown") (lib.enableFeature enableMarkdown "markdown")
@ -319,8 +304,7 @@ in {
mkdir $testresults mkdir $testresults
''; '';
installTargets = lib.optional doBuild "install" installTargets = lib.optional doBuild "install";
++ lib.optional enableExternalAPIDocs "external-api-html";
installFlags = "sysconfdir=$(out)/etc"; installFlags = "sysconfdir=$(out)/etc";
@ -344,9 +328,6 @@ in {
) + lib.optionalString enableManual '' ) + lib.optionalString enableManual ''
mkdir -p ''${!outputDoc}/nix-support mkdir -p ''${!outputDoc}/nix-support
echo "doc manual ''${!outputDoc}/share/doc/nix/manual" >> ''${!outputDoc}/nix-support/hydra-build-products 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. # So the check output gets links for DLLs in the out output.

View file

@ -0,0 +1 @@
../../.version

View file

@ -12,7 +12,9 @@ PROJECT_NAME = "Nix"
# could be handy for archiving the generated documentation or if some version # could be handy for archiving the generated documentation or if some version
# control system is used. # 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 # 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 # 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. # so they can expand variables despite configure variables.
INPUT = \ INPUT = \
src/libutil-c \ @src@/src/libutil-c \
src/libexpr-c \ @src@/src/libexpr-c \
src/libstore-c \ @src@/src/libstore-c \
doc/external-api/README.md @src@/doc/external-api/README.md
FILE_PATTERNS = nix_api_*.h *.md FILE_PATTERNS = nix_api_*.h *.md
@ -49,7 +51,6 @@ FILE_PATTERNS = nix_api_*.h *.md
# RECURSIVE has no effect here. # RECURSIVE has no effect here.
# This tag requires that the tag SEARCH_INCLUDES is set to YES. # This tag requires that the tag SEARCH_INCLUDES is set to YES.
INCLUDE_PATH = @RAPIDCHECK_HEADERS@
EXCLUDE_PATTERNS = *_internal.h EXCLUDE_PATTERNS = *_internal.h
GENERATE_TREEVIEW = YES GENERATE_TREEVIEW = YES
OPTIMIZE_OUTPUT_FOR_C = YES OPTIMIZE_OUTPUT_FOR_C = YES

View file

@ -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,
)

View file

@ -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;
};
})

View file

@ -46,6 +46,11 @@ stdenv.mkDerivation (finalAttrs: {
echo ${finalAttrs.version} > .version 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; enableParallelBuilding = true;
strictDeps = true; strictDeps = true;