From cda3d89b0e7c1ca7b872fd4f9df8ae12ba1fbaba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vivek=20Das=C2=A0Mohapatra?= <vivek@collabora.co.uk> Date: Thu, 20 Jul 2017 00:54:56 +0100 Subject: [PATCH] Standalone man pages for utility build scripts --- Makefile.am | 1 + configure.ac | 2 + doc/capsule-init-project.xml | 94 ++++++++++++++++++++ doc/capsule-mkstublib.xml | 163 +++++++++++++++++++++++++++++++++++ documentation.mk | 17 ++++ 5 files changed, 277 insertions(+) create mode 100644 doc/capsule-init-project.xml create mode 100644 doc/capsule-mkstublib.xml create mode 100644 documentation.mk diff --git a/Makefile.am b/Makefile.am index 143ecd886..5ac128337 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 b1c89b84d..8e87c8c4e 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 000000000..b4cbcfce8 --- /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 000000000..906dcd378 --- /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 000000000..f0fc3d951 --- /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) -- GitLab