summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am2
-rw-r--r--doc/p11-kit-config.xml4
-rw-r--r--doc/p11-kit-devel.xml223
-rw-r--r--doc/p11-kit-docs.sgml13
-rw-r--r--doc/p11-kit-notes.xml48
5 files changed, 233 insertions, 57 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 6b2f31c..219b2d8 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -64,7 +64,7 @@ HTML_IMAGES=
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
-content_files=p11-kit-config.xml p11-kit-sharing.xml p11-kit-notes.xml
+content_files=p11-kit-config.xml p11-kit-sharing.xml p11-kit-devel.xml
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
diff --git a/doc/p11-kit-config.xml b/doc/p11-kit-config.xml
index b6fb480..d35b112 100644
--- a/doc/p11-kit-config.xml
+++ b/doc/p11-kit-config.xml
@@ -130,7 +130,7 @@ critical: yes
This can be used in the user configs to override loading of a module
specified in the system configuration.</para>
<para>If this is a relative path, then the module will be loaded
- from the <link linkend="notes-paths-modules">default module directory</link>.</para>
+ from the <link linkend="devel-paths-modules">default module directory</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -220,7 +220,7 @@ critical: yes
<para>The default system config file and module directory can be changed
when building p11-kit. Always
- <link linkend="notes-paths">lookup these paths</link> using
+ <link linkend="devel-paths">lookup these paths</link> using
<literal>pkg-config</literal>.</para>
</section>
</chapter>
diff --git a/doc/p11-kit-devel.xml b/doc/p11-kit-devel.xml
new file mode 100644
index 0000000..aaa6671
--- /dev/null
+++ b/doc/p11-kit-devel.xml
@@ -0,0 +1,223 @@
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<chapter xml:id="devel">
+ <title>Building, Packaging, and Contributing to p11-kit</title>
+
+ <section id="devel-links">
+ <title>Helpful Resources</title>
+
+ <para>Use the following to find more information about
+ contributing to p11-kit beyond what's in this manual:</para>
+
+ <itemizedlist>
+ <listitem><para><ulink href="http://p11-glue.freedesktop.org/p11-kit.html">Website</ulink></para></listitem>
+ <listitem><para><ulink href="mail:p11-glue@lists.freedesktop.org">Mailing list</ulink></para></listitem>
+ <listitem><para><ulink href="https://bugs.freedesktop.org/enter_bug.cgi?product=p11-glue&amp;component=p11-kit">Bugzilla</ulink></para></listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="devel-paths">
+ <title>Packaging PKCS#11 module configs</title>
+
+ <para>Developers or packagers of PKCS#11 modules need to install various
+ files into specific locations so that p11-kit will recognize and load the
+ module correctly.</para>
+
+ <para>You should use <literal>pkg-config</literal> as described below
+ to determine configuration paths. p11-kit installs a
+ <literal>pkg-config</literal> file called <literal>p11-kit-1.pc</literal>.
+ This file contains all the information about the various paths that p11-kit
+ looks for files at.</para>
+
+ <section id="devel-paths-config">
+ <title>Path to place module configuration</title>
+
+ <para>As described in the <link linkend="config-module">module configuration</link>
+ documentation, each PKCS#11 module should install a config file describing
+ that module. These config files should be installed to a specific directory which
+ can be determined by running:</para>
+
+ <programlisting>
+$ <command>pkg-config p11-kit-1 --variable p11_module_configs</command>
+/usr/share/p11-kit/modules</programlisting>
+ </section>
+
+ <section id="devel-paths-modules">
+ <title>Default path for modules with relative paths</title>
+
+ <para>If a <link linkend="config-module">module configuration</link>
+ contains a relative path in its <literal>module:</literal> setting,
+ then that module will be loaded from the default module path. This
+ path can be determined by running:</para>
+
+ <programlisting>
+$ <command>pkg-config p11-kit-1 --variable p11_module_path</command>
+/usr/lib64/pkcs11</programlisting>
+ </section>
+
+ </section>
+
+ <section id="devel-building">
+ <title>Compiling p11-kit from Source</title>
+ <para>This describes how to compiling the p11-kit package from
+ source code. This is normally only necessary for those wishing to
+ contribute to the project or package p11-kit.</para>
+
+ <para>You can download
+ <ulink href="http://p11-glue.freedesktop.org/releases/">tarballs
+ of the releases</ulink> of p11-kit or
+ <ulink href="http://cgit.freedesktop.org/p11-glue/p11-kit/">check
+ out the source code from git</ulink>. This documentation will not
+ go into all the details of how to get your development environment
+ set up and instead focus on the what's unique to compiling p11-kit.</para>
+
+ <section id="devel-building-unix">
+ <title>Building on UNIX</title>
+ <para>p11-kit uses the standard GNU build system, using autoconf for package
+ configuration and resolving portability issues, automake for building makefiles
+ that comply with the GNU Coding Standards, and libtool for building shared
+ libraries on multiple platforms. The normal sequence for compiling and
+ installing the p11-kit library is thus:</para>
+
+ <informalexample>
+<programlisting>
+$ ./configure --prefix=/path/to/prefix ...
+$ make
+$ make install
+</programlisting>
+ </informalexample>
+
+ <para>If you've checked out the source code from git, then the
+ <command>configure</command> script does not yet exist. So use
+ the following instead:</para>
+
+ <informalexample>
+<programlisting>
+$ ./autogen.sh --prefix=/path/to/prefix ...
+$ make
+$ make install
+</programlisting>
+ </informalexample>
+
+ <para>The standard options provided by GNU autoconf may be passed to the configure
+ script. Please see the autoconf documentation or run <literal>./configure --help</literal>
+ for information about the standard options. In particular you probably want to adjust
+ the <literal>--prefix=/xxx</literal> argument depending on your system and development
+ environment.</para>
+ </section>
+
+ <section id="devel-building-dependencies">
+ <title>Optional Dependencies</title>
+
+ <para>On a modern GNU Linux system, p11-kit has no required dependencies other
+ than the standard C library. However on older UNIX systems, some of the following
+ may be required.</para>
+
+ <itemizedlist>
+ <listitem><para><command>gettext</command> is required if your system doesn't
+ have the <literal>gettext()</literal> functionality for handling message
+ translation databases. This can be provided by the libintl library from
+ the <ulink href="http://www.gnu.org/software/gettext">GNU gettext
+ package</ulink>.</para></listitem>
+ <listitem><para><command>pthread</command> is required if your (ancient) system
+ doesn't have this included in the base system. How this is provided is platform
+ specific.</para></listitem>
+ </itemizedlist>
+
+ <para>In addition p11-kit has several optional dependencies. If these are not available
+ during the build, then certain features will be disabled.</para>
+
+ <itemizedlist>
+ <listitem><para><command>gtk-doc</command> is required to build the reference
+ manual. Use <literal>--enable-doc</literal> to control this
+ dependency.</para></listitem>
+ <listitem><para><command>xsltproc</command> is required to build the command
+ manual pages. Use <literal>--enable-doc</literal> to control this
+ dependency.</para></listitem>
+ </itemizedlist>
+
+ </section>
+
+ <section id="devel-building-configure">
+ <title>Extra Configuration Options</title>
+
+ <para>In addition to the normal options, the configure script in the p11-kit library
+ supports these additional arguments:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><option>--disable-debug</option>, <option>--enable-debug</option></term>
+ <listitem><para>By default p11-kit is built with debug symbols assertions and
+ and precondition checks. Enabling the debug option configures even more
+ detailed debug build, including disabling optimization. Disabling the debug
+ option is not recommended, as it disables all assertions, preconditions and
+ internal consistency checks, although it may result it a slightly faster
+ library.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--enable-doc</option></term>
+ <listitem><para>Enables building of the documentation and command line manual.
+ The documentation is built in the <literal>doc/html/</literal> directory of
+ the build. Requires the <literal>gtk-doc</literal> and <literal>xsltproc</literal>
+ dependencies.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--enable-strict</option></term>
+ <listitem><para>Enables strict checks during building of p11-kit. All
+ compiler warnings become errors.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--with-module-path</option></term>
+ <listitem><para>Specify the path to look for PKCS#11 modules which were
+ listed in a module config file with a relative path.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>--with-system-config</option></term>
+ <listitem><para>Specify the path to look for p11-kit config files. This
+ usually defaults to something like <literal>/etc/pkcs11</literal></para></listitem>
+ </varlistentry>
+ </variablelist>
+ <para></para>
+ </section>
+ </section>
+
+ <section id="devel-building-style">
+ <title>Coding Style</title>
+
+ <para>We use a code style similar to the linux kernel. Use tabs
+ to indent and spaces to align/wrap beyond the indentation level.</para>
+
+ <para>We don't try to guarantee completely robust and problem free
+ behavior in cases where the caller or system isn't behaving. We
+ consider these to be outside of our control:</para>
+
+ <itemizedlist>
+ <listitem><para>Broken input from callers. We use preconditions
+ to check input and immediately return. We don't try to provide
+ error codes for all the various ways callers can screw
+ around.</para></listitem>
+
+ <listitem>
+ <para>Out of memory. It is pretty much impossible to handle out
+ of memory errors correctly. Handling them alongside other errors
+ is naive and broken. We don't try to guarantee library state
+ (such as locks or memory leaks) when memory allocation fails.</para>
+ <para>We do check the results from all memory allocations, but
+ treat them as unexpected conditions. As a nod to the behavior
+ of callers of this library, we don't abort on memory allocation
+ failures. We use preconditions with somewhat sane results.</para>
+ <para>Exception: when reading files or allocating potentially
+ unbounded amounts of memory, we should respond robustly to memory
+ allocation failures.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>These unexpected conditions indicate a bug either in p11-kit or
+ in the system. All bets are off once this occurs.</para>
+
+ <para>Use the <literal>return_val_xxx()</literal> precondition macros to
+ check for unexpected conditions.</para>
+
+ </section>
+</chapter>
diff --git a/doc/p11-kit-docs.sgml b/doc/p11-kit-docs.sgml
index e8b694c..2d3760a 100644
--- a/doc/p11-kit-docs.sgml
+++ b/doc/p11-kit-docs.sgml
@@ -13,7 +13,6 @@
<xi:include href="p11-kit-config.xml"/>
<xi:include href="p11-kit-sharing.xml"/>
- <xi:include href="p11-kit-notes.xml"/>
<chapter xml:id="tools">
<title>Command Line Tools</title>
@@ -21,16 +20,18 @@
</chapter>
<chapter xml:id="reference">
- <title>Reference</title>
+ <title>API Reference</title>
<xi:include href="xml/p11-kit.xml"/>
<xi:include href="xml/p11-kit-uri.xml"/>
<xi:include href="xml/p11-kit-pin.xml"/>
<xi:include href="xml/p11-kit-util.xml"/>
<xi:include href="xml/p11-kit-future.xml"/>
+ <index id="api-index-full">
+ <title>API Index</title>
+ <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+ </index>
</chapter>
- <index id="api-index-full">
- <title>API Index</title>
- <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
- </index>
+ <xi:include href="p11-kit-devel.xml"/>
+
</book>
diff --git a/doc/p11-kit-notes.xml b/doc/p11-kit-notes.xml
deleted file mode 100644
index 02a3288..0000000
--- a/doc/p11-kit-notes.xml
+++ /dev/null
@@ -1,48 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-]>
-<chapter xml:id="config">
- <title>Developer and Packager Notes</title>
-
- <section id="notes-paths">
- <title>Using pkg-config to determine paths</title>
-
- <para>Developers or packagers of PKCS#11 modules need to install various
- files into specific locations so that p11-kit will recognize and load the
- module correctly.</para>
-
- <para>You should use <literal>pkg-config</literal> as described below
- to determine configuration paths. p11-kit installs a
- <literal>pkg-config</literal> file called <literal>p11-kit-1.pc</literal>.
- This file contains all the information about the various paths that p11-kit
- looks for files at.</para>
-
- <section id="notes-paths-config">
- <title>Path to place module configuration</title>
-
- <para>As described in the <link linkend="config-module">module configuration</link>
- documentation, each PKCS#11 module should install a config file describing
- that module. These config files should be installed to a specific directory which
- can be determined by running:</para>
-
- <programlisting>
-$ <command>pkg-config p11-kit-1 --variable p11_module_configs</command>
-/usr/share/p11-kit/modules</programlisting>
- </section>
-
- <section id="notes-paths-modules">
- <title>Default path for modules with relative paths</title>
-
- <para>If a <link linkend="config-module">module configuration</link>
- contains a relative path in its <literal>module:</literal> setting,
- then that module will be loaded from the default module path. This
- path can be determined by running:</para>
-
- <programlisting>
-$ <command>pkg-config p11-kit-1 --variable p11_module_path</command>
-/usr/lib64/pkcs11</programlisting>
- </section>
-
- </section>
-
-</chapter>