Skip to content

Commit

Permalink
Port C API docs to Meson (#10936)
Browse files Browse the repository at this point in the history
* Port C API docs to Meson

* don't cross-compile the docs
  • Loading branch information
fricklerhandwerk committed Jun 19, 2024
1 parent 0c60296 commit 1c131ec
Show file tree
Hide file tree
Showing 16 changed files with 131 additions and 68 deletions.
11 changes: 0 additions & 11 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
1 change: 0 additions & 1 deletion Makefile.config.in
Original file line number Diff line number Diff line change
Expand Up @@ -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@
Expand Down
9 changes: 0 additions & 9 deletions configure.ac
Original file line number Diff line number Diff line change
Expand Up @@ -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'.])])
Expand All @@ -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)])
Expand Down
7 changes: 0 additions & 7 deletions doc/external-api/local.mk

This file was deleted.

10 changes: 5 additions & 5 deletions doc/manual/src/contributing/documentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand All @@ -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
```
14 changes: 12 additions & 2 deletions flake.nix
Original file line number Diff line number Diff line change
Expand Up @@ -211,7 +211,6 @@
;
};


nix-internal-api-docs = final.callPackage ./src/internal-api-docs/package.nix {
inherit
fileset
Expand All @@ -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 =
Expand Down Expand Up @@ -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: {}: {
Expand All @@ -298,7 +307,6 @@
#"nix-util" = { };
#"nix-store" = { };
#"nix-fetchers" = { };
"nix-internal-api-docs" = { };
}
// lib.optionalAttrs (builtins.elem system linux64BitSystems) {
dockerImage =
Expand Down Expand Up @@ -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"
Expand Down
6 changes: 1 addition & 5 deletions maintainers/hydra.nix
Original file line number Diff line number Diff line change
Expand Up @@ -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; } // {
Expand Down
1 change: 1 addition & 0 deletions meson.build
Original file line number Diff line number Diff line change
Expand Up @@ -11,3 +11,4 @@ subproject('libstore')
subproject('libfetchers')
subproject('perl')
subproject('internal-api-docs')
subproject('external-api-docs')
25 changes: 3 additions & 22 deletions package.nix
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,6 @@
, git
, gtest
, jq
, doxygen
, libarchive
, libcpuid
, libgit2
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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 [
Expand All @@ -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"
;
Expand All @@ -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 [
Expand Down Expand Up @@ -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")
Expand Down Expand Up @@ -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";

Expand All @@ -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.
Expand Down
File renamed without changes.
1 change: 1 addition & 0 deletions src/external-api-docs/.version
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand All @@ -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
Expand Down
31 changes: 31 additions & 0 deletions src/external-api-docs/meson.build
Original file line number Diff line number Diff line change
@@ -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,
)
65 changes: 65 additions & 0 deletions src/external-api-docs/package.nix
Original file line number Diff line number Diff line change
@@ -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;
};
})
5 changes: 5 additions & 0 deletions src/internal-api-docs/package.nix
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down

0 comments on commit 1c131ec

Please sign in to comment.