From fae6b0555a7185f145c95c9013a3af293d407a00 Mon Sep 17 00:00:00 2001
From: Virgile Prevosto <virgile.prevosto@m4x.org>
Date: Fri, 29 May 2020 10:38:24 +0200
Subject: [PATCH] [devman] more configure.ac documentation
---
doc/developer/advance.tex | 45 ++++++++++++++++++++++++++++++++++-----
doc/developer/changes.tex | 3 ++-
2 files changed, 42 insertions(+), 6 deletions(-)
diff --git a/doc/developer/advance.tex b/doc/developer/advance.tex
index 43d2fda3d05..d881a2b55cc 100644
--- a/doc/developer/advance.tex
+++ b/doc/developer/advance.tex
@@ -210,7 +210,7 @@ It takes two arguments, the name of the package (as known by \texttt{findlib}),
and a message that will be displayed if the package is not found.
The \texttt{configure\_library} macro takes three arguments. The first one is
-the (uppercase) name of the library, the second one is a filename
+the name of the library, the second one is a filename
which is used by the script to check the availability of the library.
In case there are multiple locations possible for the library, this
argument can be a list of filenames. In this case, the argument must
@@ -222,8 +222,19 @@ argument is a warning message to display if a configuration problem
appears (usually because the library does not exist). Using these
arguments, the script checks the availability of the library.
-Results of this macro are available through two variables which are
-substituted in the files generated by \texttt{configure}.
+Results of these macros are available through variables which are
+substituted in the files generated by \texttt{configure}, where
+\texttt{$library$} stands for the \emph{uppercased}
+version of the library name.
+\begin{itemize}
+\item For \texttt{configure\_pkg}:
+\begin{itemize}
+\item \texttt{HAS\_OCAML\_$library$}
+\scodeidxdef{configure.in}{HAS\_OCAML\_$library$}
+is set to \texttt{yes} or \texttt{no} depending on the availability
+of the library
+\end{itemize}
+\item For \texttt{configure\_library}:
\begin{itemize}
\item \texttt{HAS\_$library$}\scodeidxdef{configure.in}{HAS\_$library$}
is set to \texttt{yes} or \texttt{no} depending on the availability
@@ -231,8 +242,10 @@ substituted in the files generated by \texttt{configure}.
\item \texttt{SELECTED\_$library$}\scodeidxdef{configure.in}{SELECTED\_$library$}
contains the name of the version selected as described above.
\end{itemize}
+\end{itemize}
-When checking for \ocaml{} libraries and object files, remember that
+If checking for \ocaml{} libraries and object files without
+\texttt{configure\_pkg}, remember that
they come in two flavors: bytecode and native
code, which have distinct suffixes. Therefore, you should use the
variables \texttt{LIB\_SUFFIX}\scodeidx{configure.in}{LIB\_SUFFIX}
@@ -262,7 +275,22 @@ configure_library(
\subsection{Addition of Library/Tool Dependencies}\label{conf:dep-lib}
\index{Library!Dependency}\index{Tool!Dependency}
-Dependencies upon external tools and libraries are governed by two macros:
+Dependencies upon OCaml packages (checked by \texttt{configure\_pkg}) are
+governed by two macros:
+
+\begin{itemize}
+\item \texttt{plugin\_require\_pkg($plugin$,$library$)}%
+\scodeidxdef{configure.in}{plugin\_require\_pkg} indicates that
+$plugin$ requires $library$ in order to be compiled.
+\item \texttt{plugin\_use\_pkg($plugin$,$library$)}%
+\scodeidxdef{configure.in}{plugin\_use\_pkg} indicates that
+$plugin$ uses $library$, but can nevertheless be compiled if $library$
+is not installed (potentially offering reduced functionality).
+\end{itemize}
+
+Dependencies upon external tools and libraries (checked by
+\texttt{configure\_library} or \texttt{configure\_tool})
+are governed by two macros:
\begin{itemize}
\item \texttt{plugin\_require\_external($plugin$,$library$)}%
\scodeidxdef{configure.in}{plugin\_require\_external} indicates that
@@ -372,6 +400,13 @@ are met. This is done with the following macro:\scodeidxdef{configure.in}{check\
\begin{configurecode}
check_plugin_dependencies
\end{configurecode}
+It is only after this point that the variables
+\texttt{HAS\_$library$}, \texttt{SELECTED\_$library$}, and
+\texttt{ENABLE\_$plugin$} get their final value. If parts of the
+\texttt{configure} script depends on these variables,
+they should appear after the call to
+\texttt{check\_plugin\_dependencies}.
+
An external plug-in can
have dependencies upon previously installed plug-ins.
However two separately installed plug-ins can not be
diff --git a/doc/developer/changes.tex b/doc/developer/changes.tex
index c798e1cde66..8abcd5df6a1 100644
--- a/doc/developer/changes.tex
+++ b/doc/developer/changes.tex
@@ -7,7 +7,8 @@ This chapter summarizes the major changes in this documentation between each
\section*{21.0 Scandium}
\begin{itemize}
-\item \textbf{Configure}: Documentation of \texttt{configure\_pkg} macro.
+\item \textbf{Configure}: Documentation of \texttt{configure\_pkg},
+\texttt{plugin\_require\_pkg} and \texttt{plugin\_use\_pkg} macros.
\end{itemize}
\section*{20.0 Calcium}
--
GitLab