NixOS/nix
NixOS/nix
1
0
Fork 0
mirror of https://github.com/NixOS/nix synced 2024-09-18 10:30:23 -04:00
Code Activity

Convert the internal API doc build to Meson

Browse source
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
Show stats Download patch file Download diff file Expand all files Collapse all files

11
Makefile
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:

1
Makefile.config.in
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@

5
configure.ac
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)

7
doc/internal-api/local.mk
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

12
doc/manual/src/contributing/documentation.md
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

10
flake.nix
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 =

6
maintainers/hydra.nix
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 {

1
meson.build
View file

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

19
package.nix
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
'';

0
doc/internal-api/.gitignore → src/internal-api-docs/.gitignore vendored
View file

1
src/internal-api-docs/.version Symbolic link
View file

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

46
doc/internal-api/doxygen.cfg.in → src/internal-api-docs/doxygen.cfg.in
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

31
src/internal-api-docs/meson.build Normal file
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,
)

56
src/internal-api-docs/package.nix Normal file
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;
};
})