Generate API docs with Doxygen
The motivation is as stated in issue #7814: even though the the C++ API is internal and unstable, people still want it to be well documented for sake of learning, code review, and other purposes that aren't predicated on it being stable. Fixes #7814 Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
This commit is contained in:
John Ericson
parent
66f49864f3
commit
6910f5dcb6
3
Makefile
3
Makefile
|
|
@ -16,7 +16,8 @@ makefiles = \
|
|||
misc/systemd/local.mk \
|
||||
misc/launchd/local.mk \
|
||||
misc/upstart/local.mk \
|
||||
doc/manual/local.mk
|
||||
doc/manual/local.mk \
|
||||
doc/internal-api/local.mk
|
||||
|
||||
-include Makefile.config
|
||||
|
||||
|
|
|
|||
|
|
@ -22,6 +22,7 @@ LOWDOWN_LIBS = @LOWDOWN_LIBS@
|
|||
OPENSSL_LIBS = @OPENSSL_LIBS@
|
||||
PACKAGE_NAME = @PACKAGE_NAME@
|
||||
PACKAGE_VERSION = @PACKAGE_VERSION@
|
||||
RAPIDCHECK_HEADERS = @RAPIDCHECK_HEADERS@
|
||||
SHELL = @bash@
|
||||
SODIUM_LIBS = @SODIUM_LIBS@
|
||||
SQLITE3_LIBS = @SQLITE3_LIBS@
|
||||
|
|
@ -46,3 +47,4 @@ storedir = @storedir@
|
|||
sysconfdir = @sysconfdir@
|
||||
system = @system@
|
||||
tests = @tests@
|
||||
internal_api_docs = @internal_api_docs@
|
||||
|
|
|
|||
|
|
@ -152,6 +152,11 @@ AC_ARG_ENABLE(tests, AS_HELP_STRING([--disable-tests],[Do not build the tests]),
|
|||
tests=$enableval, tests=yes)
|
||||
AC_SUBST(tests)
|
||||
|
||||
# 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]),
|
||||
internal_api_docs=$enableval, internal_api_docs=no)
|
||||
AC_SUBST(internal_api_docs)
|
||||
|
||||
# LTO is currently broken with clang for unknown reasons; ld segfaults in the llvm plugin
|
||||
AC_ARG_ENABLE(lto, AS_HELP_STRING([--enable-lto],[Enable LTO (only supported with GCC) [default=no]]),
|
||||
lto=$enableval, lto=no)
|
||||
|
|
@ -286,6 +291,8 @@ PKG_CHECK_MODULES([GTEST], [gtest_main])
|
|||
# Look for rapidcheck.
|
||||
# No pkg-config yet, https://github.com/emil-e/rapidcheck/issues/302
|
||||
AC_LANG_PUSH(C++)
|
||||
AC_SUBST(RAPIDCHECK_HEADERS)
|
||||
[CXXFLAGS="-I $RAPIDCHECK_HEADERS $CXXFLAGS"]
|
||||
AC_CHECK_HEADERS([rapidcheck/gtest.h], [], [], [#include <gtest/gtest.h>])
|
||||
dnl No good for C++ libs with mangled symbols
|
||||
dnl AC_CHECK_LIB([rapidcheck], [])
|
||||
|
|
|
|||
|
|
@ -0,0 +1,3 @@
|
|||
/doxygen.cfg
|
||||
/html
|
||||
/latex
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
# Doxyfile 1.9.5
|
||||
|
||||
# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by
|
||||
# double-quotes, unless you are using Doxywizard) that should identify the
|
||||
# project for which the documentation is generated. This name is used in the
|
||||
# title of most generated pages and in a few other places.
|
||||
# The default value is: My Project.
|
||||
|
||||
PROJECT_NAME = "Nix"
|
||||
|
||||
# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
|
||||
# could be handy for archiving the generated documentation or if some version
|
||||
# control system is used.
|
||||
|
||||
PROJECT_NUMBER = @PACKAGE_VERSION@
|
||||
|
||||
# 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
|
||||
# quick idea about the purpose of the project. Keep the description short.
|
||||
|
||||
PROJECT_BRIEF = "Nix, the purely functional package manager; unstable internal interfaces"
|
||||
|
||||
# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
|
||||
# The default value is: YES.
|
||||
|
||||
GENERATE_LATEX = NO
|
||||
|
||||
# The INPUT tag is used to specify the files and/or directories that contain
|
||||
# documented source files. You may enter file names like myfile.cpp or
|
||||
# directories like /usr/src/myproject. Separate the files or directories with
|
||||
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
|
||||
# Note: If this tag is empty the current directory is searched.
|
||||
|
||||
# FIXME Make this list more maintainable somehow. We could maybe generate this
|
||||
# in the Makefile, but we would need to change how `.in` files are preprocessed
|
||||
# so they can expand variables despite configure variables.
|
||||
|
||||
INPUT = \
|
||||
src/libcmd \
|
||||
src/libexpr \
|
||||
src/libexpr/flake \
|
||||
src/libexpr/tests \
|
||||
src/libexpr/tests/value \
|
||||
src/libexpr/value \
|
||||
src/libfetchers \
|
||||
src/libmain \
|
||||
src/libstore \
|
||||
src/libstore/build \
|
||||
src/libstore/builtins \
|
||||
src/libstore/tests \
|
||||
src/libutil \
|
||||
src/libutil/tests \
|
||||
src/nix \
|
||||
src/nix-env \
|
||||
src/nix-store
|
||||
|
||||
# The INCLUDE_PATH tag can be used to specify one or more directories that
|
||||
# contain include files that are not input files but should be processed by the
|
||||
# preprocessor. Note that the INCLUDE_PATH is not recursive, so the setting of
|
||||
# RECURSIVE has no effect here.
|
||||
# This tag requires that the tag SEARCH_INCLUDES is set to YES.
|
||||
|
||||
INCLUDE_PATH = @RAPIDCHECK_HEADERS@
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
.PHONY: internal-api-html
|
||||
|
||||
ifeq ($(internal_api_docs), yes)
|
||||
|
||||
$(docdir)/internal-api/html/index.html $(docdir)/internal-api/latex: $(d)/doxygen.cfg
|
||||
mkdir -p $(docdir)/internal-api
|
||||
{ cat $< ; echo "OUTPUT_DIRECTORY=$(docdir)/internal-api" ; } | doxygen -
|
||||
|
||||
# Generate the HTML API docs for Nix's unstable internal interfaces.
|
||||
internal-api-html: $(docdir)/internal-api/html/index.html
|
||||
|
||||
else
|
||||
|
||||
# Make a nicer error message
|
||||
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
|
||||
|
|
@ -88,7 +88,8 @@ $(d)/builtins.json: $(bindir)/nix
|
|||
@mv $@.tmp $@
|
||||
|
||||
# Generate the HTML manual.
|
||||
html: $(docdir)/manual/index.html
|
||||
.PHONY: manual-html
|
||||
manual-html: $(docdir)/manual/index.html
|
||||
install: $(docdir)/manual/index.html
|
||||
|
||||
# Generate 'nix' manpages.
|
||||
|
|
|
|||
47
flake.nix
47
flake.nix
|
|
@ -98,7 +98,11 @@
|
|||
];
|
||||
|
||||
testConfigureFlags = [
|
||||
"CXXFLAGS=-I${lib.getDev rapidcheck}/extras/gtest/include"
|
||||
"RAPIDCHECK_HEADERS=${lib.getDev rapidcheck}/extras/gtest/include"
|
||||
];
|
||||
|
||||
internalApiDocsConfigureFlags = [
|
||||
"--enable-internal-api-docs"
|
||||
];
|
||||
|
||||
nativeBuildDeps =
|
||||
|
|
@ -136,6 +140,10 @@
|
|||
rapidcheck
|
||||
];
|
||||
|
||||
internalApiDocsDeps = [
|
||||
buildPackages.doxygen
|
||||
];
|
||||
|
||||
awsDeps = lib.optional (stdenv.isLinux || stdenv.isDarwin)
|
||||
(aws-sdk-cpp.override {
|
||||
apis = ["s3" "transfer"];
|
||||
|
|
@ -517,9 +525,7 @@
|
|||
|
||||
src = self;
|
||||
|
||||
configureFlags = [
|
||||
"CXXFLAGS=-I${lib.getDev pkgs.rapidcheck}/extras/gtest/include"
|
||||
];
|
||||
configureFlags = testConfigureFlags;
|
||||
|
||||
enableParallelBuilding = true;
|
||||
|
||||
|
|
@ -536,6 +542,33 @@
|
|||
hardeningDisable = ["fortify"];
|
||||
};
|
||||
|
||||
# API docs for Nix's unstable internal C++ interfaces.
|
||||
internal-api-docs =
|
||||
with nixpkgsFor.x86_64-linux.native;
|
||||
with commonDeps { inherit pkgs; };
|
||||
|
||||
stdenv.mkDerivation {
|
||||
pname = "nix-internal-api-docs";
|
||||
inherit version;
|
||||
|
||||
src = self;
|
||||
|
||||
configureFlags = testConfigureFlags ++ internalApiDocsConfigureFlags;
|
||||
|
||||
nativeBuildInputs = nativeBuildDeps;
|
||||
buildInputs = buildDeps ++ propagatedDeps
|
||||
++ awsDeps ++ checkDeps ++ internalApiDocsDeps;
|
||||
|
||||
dontBuild = true;
|
||||
|
||||
installTargets = [ "internal-api-html" ];
|
||||
|
||||
postInstall = ''
|
||||
mkdir -p $out/nix-support
|
||||
echo "doc internal-api-docs $out/share/doc/nix/internal-api" >> $out/nix-support/hydra-build-products
|
||||
'';
|
||||
};
|
||||
|
||||
# System tests.
|
||||
tests.authorization = runNixOSTestFor "x86_64-linux" ./tests/nixos/authorization.nix;
|
||||
|
||||
|
|
@ -653,9 +686,11 @@
|
|||
nativeBuildInputs = nativeBuildDeps
|
||||
++ (lib.optionals stdenv.cc.isClang [ pkgs.bear pkgs.clang-tools ]);
|
||||
|
||||
buildInputs = buildDeps ++ propagatedDeps ++ awsDeps ++ checkDeps;
|
||||
buildInputs = buildDeps ++ propagatedDeps
|
||||
++ awsDeps ++ checkDeps ++ internalApiDocsDeps;
|
||||
|
||||
configureFlags = configureFlags ++ testConfigureFlags;
|
||||
configureFlags = configureFlags
|
||||
++ testConfigureFlags ++ internalApiDocsConfigureFlags;
|
||||
|
||||
enableParallelBuilding = true;
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue