summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorVivek Das Mohapatra <vivek@collabora.co.uk>2017-07-19 23:54:56 (GMT)
committerVivek Das Mohapatra <vivek@collabora.co.uk>2017-07-19 23:54:56 (GMT)
commitcda3d89b0e7c1ca7b872fd4f9df8ae12ba1fbaba (patch)
treed1ff5209fbc84f3c0fc7f07a7dbd4f4cd52aaee9
parent0fe3fc78e18f028dabc91f1099aca8660b0f1ef7 (diff)
downloadlibcapsule-cda3d89b0e7c1ca7b872fd4f9df8ae12ba1fbaba.tar.gz
libcapsule-cda3d89b0e7c1ca7b872fd4f9df8ae12ba1fbaba.tar.xz
Standalone man pages for utility build scripts
-rw-r--r--Makefile.am1
-rw-r--r--configure.ac2
-rw-r--r--doc/capsule-init-project.xml94
-rw-r--r--doc/capsule-mkstublib.xml163
-rw-r--r--documentation.mk17
5 files changed, 277 insertions, 0 deletions
diff --git a/Makefile.am b/Makefile.am
index 143ecd8..5ac1283 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -88,4 +88,5 @@ dist_pkgdata_DATA = data/capsule-shim.h \
CLEANFILES = $(shim_files) $(shim_srcs)
BUILT_SOURCES = $(shim_srcs)
+include documentation.mk
include disabled.mk
diff --git a/configure.ac b/configure.ac
index b1c89b8..8e87c8c 100644
--- a/configure.ac
+++ b/configure.ac
@@ -35,4 +35,6 @@ AC_RUN_IFELSE([AC_LANG_PROGRAM([#include <libelf.h>],
[AC_MSG_ERROR([ELF_C_READ_MMAP missing: libelfg vs libelf0?])])
AC_SEARCH_LIBS([dlmopen], [dl])
+AC_PATH_PROG([XSLTPROC], [xsltproc])
+
AC_OUTPUT([Makefile data/capsule.pc data/dirconf.txt])
diff --git a/doc/capsule-init-project.xml b/doc/capsule-init-project.xml
new file mode 100644
index 0000000..b4cbcfc
--- /dev/null
+++ b/doc/capsule-init-project.xml
@@ -0,0 +1,94 @@
+<refentry id="capsule-init-project">
+
+ <refentryinfo>
+ <title>capsule-init-project</title>
+ <productname>libcapsule</productname>
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>Vivek</firstname>
+ <surname>Das Mohapatra</surname>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>capsule-init-project</refentrytitle>
+ <manvolnum>1</manvolnum>
+ <refmiscinfo class="manual">User Commands</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>capsule-init-project</refname>
+ <refpurpose>libcapsule proxy library project setup tool</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>capsule-init-project</command>
+ <arg choice="plain">TARGET</arg>
+ <arg choice="opt">
+ FOREIGN-TREE
+ <arg choice="opt">PROJECT-DIR</arg>
+ </arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ <command>capsule-init-project</command> creates a project which
+ uses libcapsule to create a proxy for a library, usually from
+ a foreign filesystem tree.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Arguments</title>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>TARGET</option></term>
+ <listitem>
+ <para>
+ The base name of the target, of the form libFOO.so.X (eg libz.so.1)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>FOREIGN-TREE</option></term>
+ <listitem>
+ <para>
+ Mount point of the filesystem tree which contains the target.
+ </para>
+ <para>
+ For example a container could mount a different root filesystem
+ at /host in order to make its libraries available.
+ </para>
+ <para>
+ FOREIGN-TREE defaults to /host if unset or empty.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>PROJECT-DIR</option></term>
+ <listitem>
+ <para>The directory in which the new project will be created.</para>
+ <para>Defaults to ./libFOO-proxy (if TARGET is libFOO.so.X)</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect1>
+
+ <refsect1><title>See also</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>capsule-mkstublib</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/doc/capsule-mkstublib.xml b/doc/capsule-mkstublib.xml
new file mode 100644
index 0000000..906dcd3
--- /dev/null
+++ b/doc/capsule-mkstublib.xml
@@ -0,0 +1,163 @@
+<refentry id="capsule-mkstublib">
+
+ <refentryinfo>
+ <title>capsule-mkstublib</title>
+ <productname>libcapsule</productname>
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>Vivek</firstname>
+ <surname>Das Mohapatra</surname>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>capsule-mkstublib</refentrytitle>
+ <manvolnum>1</manvolnum>
+ <refmiscinfo class="manual">User Commands</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>capsule-mkstublib</refname>
+
+ <refpurpose>
+ Command used by the libcapsule build system to generate proxy
+ library source files.
+ </refpurpose>
+
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>capsule-mkstublib</command>
+ <arg choice="plain">TARGET</arg>
+ <arg choice="plain">EXCLUDES</arg>
+ <arg choice="plain">EXPORTS</arg>
+ <arg choice="plain">OUTPUT</arg>
+ <arg choice="plain">DSO-VERSION</arg>
+ <arg choice="plain">TREE</arg>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para>
+ <command>capsule-mkstublib</command> generates the source code
+ for a libcapsule proxy library from a standard set of inputs
+ (described below).
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Arguments</title>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>TARGET</option></term>
+ <listitem>
+ <para>
+ The base name of the target, of the form libFOO.so.X (eg libz.so.1)
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>EXCLUDES</option></term>
+ <listitem>
+ <para>
+ A file containing a list of DSOs (one on each line) not to
+ include in the libcapsule proxy: DSOs listed here will not
+ be loaded from the foreign tree and must come from the
+ normal set searched by the linker.
+ </para>
+ <para>
+ For example i libz.so.1 is listed here, and TARGET depends
+ on libz.so.1 then it will be run-time linked against the
+ copy of libz from / - not any copies which are found under TREE
+ </para>
+ <para>
+ This file is empty by default in new prjects.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>EXPORTS</option></term>
+ <listitem>
+ <para>
+ A file containing a list of DSOs (one on each line) whose
+ symbols should be exported.
+ </para>
+ <para>Symbols from TARGET are always exported.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>EXPORTS</option></term>
+ <listitem>
+ <para>
+ A file containing a list of DSOs (one on each line) whose
+ symbols should be exported.
+ </para>
+ <para>Symbols from TARGET are always exported.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>OUTPUT</option></term>
+ <listitem>
+ <para>
+ Output filename
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>DSO-VERSION</option></term>
+ <listitem>
+ <para>
+ The version of the target library our proxy will pretend to be,
+ in the format MAJOR:MINOR:SUB
+ </para>
+ <para>
+ The format is the same format as consumed by libtool.
+ Only MAJOR must be present.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>TREE</option></term>
+ <listitem>
+ <para>
+ The mount point of the foreign filesystem tree from which TARGET
+ and its dependencies will be acquired.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Bugs</title>
+ <para>
+ The order of arguments is a bit pathological: This is for
+ historical reasons. Since the command is not expected to be
+ invoked outside of libcapsule's build scripts this is not
+ considered a major problem.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>See also</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>capsule-init-project</refentrytitle>
+ <manvolnum>1</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/documentation.mk b/documentation.mk
new file mode 100644
index 0000000..f0fc3d9
--- /dev/null
+++ b/documentation.mk
@@ -0,0 +1,17 @@
+XSLTPROC_FLAGS = \
+ --nonet \
+ --stringparam man.output.quietly 1 \
+ --stringparam funcsynopsis.style ansi \
+ --stringparam man.th.extra1.suppress 1 \
+ --stringparam man.authors.section.enabled 0 \
+ --stringparam man.copyright.section.enabled 0
+
+XSLT_MAN = http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
+
+#include gtk-doc.make
+
+%.1: doc/%.xml
+ $(AM_V_GEN) $(XSLTPROC) $(XSLTPROC_FLAGS) $(XSLT_MAN) $<
+
+man_MANS = capsule-init-project.1 capsule-mkstublib.1
+CLEANFILES += $(man_MANS)