diff --git a/Makefile.am b/Makefile.am index 143ecd886b5a9e3384eafe8ce12c31033624a857..5ac128337e8a544cc0689504482793433330aa51 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 b1c89b84d6dffdda26158815205fd96018a16607..8e87c8c4ef9cc583f75dadedd6a118d203d1456b 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 0000000000000000000000000000000000000000..b4cbcfce8a70b6d555f4d1fa1eb249698453d88a --- /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 0000000000000000000000000000000000000000..906dcd37898039f5ac78f2a2343fbd006709cd75 --- /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 0000000000000000000000000000000000000000..f0fc3d9511085f30214c8765d19e8756e3bc9e30 --- /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)