[devman] more configure.ac documentation

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

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}