Convert the internal API doc build to Meson

This commit is contained in:
Valentin Gagarin 2024-06-17 15:50:59 +02:00 committed by John Ericson
parent 69d404edad
commit 6e34c68327
14 changed files with 136 additions and 70 deletions

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

@ -9,3 +9,4 @@ project('nix-dev-shell', 'cpp',
subproject('libutil')
subproject('libstore')
subproject('perl')
subproject('internal-api-docs')

View file

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

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

View file

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

View file

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