From df29c0dcb6cce6a215dee9dc4e17aff59ae67c5b Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Mon, 11 Mar 2013 10:56:07 +0100 Subject: doc: Move manual into doc/manual subdirectory --- doc/manual/p11-kit-devel.xml | 299 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 299 insertions(+) create mode 100644 doc/manual/p11-kit-devel.xml (limited to 'doc/manual/p11-kit-devel.xml') diff --git a/doc/manual/p11-kit-devel.xml b/doc/manual/p11-kit-devel.xml new file mode 100644 index 0000000..bbe6c0a --- /dev/null +++ b/doc/manual/p11-kit-devel.xml @@ -0,0 +1,299 @@ + + + + Building, Packaging, and Contributing to p11-kit + + + +
+ Packaging PKCS#11 module configs + + 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. + + You should use pkg-config as described below + to determine configuration paths. p11-kit installs a + pkg-config file called p11-kit-1.pc. + This file contains all the information about the various paths that p11-kit + looks for files at. + +
+ Path to place module configuration + + As described in the module configuration + 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: + + +$ pkg-config p11-kit-1 --variable p11_module_configs +/usr/share/p11-kit/modules +
+ +
+ Default path for modules with relative paths + + If a module configuration + contains a relative path in its module: setting, + then that module will be loaded from the default module path. This + path can be determined by running: + + +$ pkg-config p11-kit-1 --variable p11_module_path +/usr/lib64/pkcs11 +
+ +
+ +
+ Customizing installed commands + + The p11-kit tool provides a + extract-trust command which extracts trust + policy information such as certificate anchors and so on + into files for use with libraries that cannot read this trust + information directly. + + In order to be useful the extract-trust + command needs to be customized per distribution or site. You can + find this file in at tools/p11-kit-trust-extract.in + in the p11-kit source code. + + The command is implemented as a simple script which + performs the various p11-kit extract commands + necessary to extract the information. + + Using this script as a standard way to extract this + information allows for consistency between distributions and ease + of system administration. +
+ +
+ Compiling p11-kit from Source + 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. + + You can download + tarballs + of the releases of p11-kit or + check + out the source code from git. 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. + +
+ Building on UNIX + 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: + + +$ ./configure --prefix=/path/to/prefix ... +$ make +$ make install + + + If you've checked out the source code from git, then the + configure script does not yet exist. So use + the following instead: + + +$ ./autogen.sh --prefix=/path/to/prefix ... +$ make +$ make install + + + The standard options provided by GNU autoconf may be passed to the configure + script. Please see the autoconf documentation or run ./configure --help + for information about the standard options. In particular you probably want to adjust + the --prefix=/xxx argument depending on your system and development + environment. +
+ +
+ Optional Dependencies + + 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. + + + gettext is required if your system doesn't + have the gettext() functionality for handling message + translation databases. This can be provided by the libintl library from + the GNU gettext + package. + pthread is required if your (ancient) system + doesn't have this included in the base system. How this is provided is platform + specific. + + + In addition p11-kit has several optional dependencies. If these are not available + during the build, then certain features will be disabled. + + + gtk-doc is required to build the reference + manual. Use --enable-doc to control this + dependency. + xsltproc is required to build the command + manual pages. Use --enable-doc to control this + dependency. + libtasn1 is required to build the trust + module and code that interacts with certificates. + + +
+ +
+ Extra Configuration Options + + In addition to the normal options, the configure script in the p11-kit library + supports these additional arguments: + + + + + Disables building of the trust policy module. + + + , + 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. + + + + Enables building of the documentation and command line manual. + The documentation is built in the doc/html/ directory of + the build. Requires the gtk-doc and xsltproc + dependencies. + + + + Enables strict checks during building of p11-kit. All + compiler warnings become errors. + + + , + Build with a dependency on the libtasn1 library. This dependency + allows the trust policy module to be built as well as other code that interacts with + certificates. + + + + Specify the path to look for PKCS#11 modules which were + listed in a module config file with a relative path. + + + + Specify the files or directories to look for system + certificate anchors. Multiple files and/or directories are specified with + a : in between them. + + + + Specify the files or directories to look for other + non-anchor system certificates. Multiple files and/or directories are + specified with a : in between them. + + + + Specify the path to look for p11-kit config files. This + usually defaults to something like /etc/pkcs11 + + + +
+
+ +
+ Coding Style + + We use a code style similar to the linux kernel. Use tabs + to indent and spaces to align/wrap beyond the indentation level. + + 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: + + + 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. + + + 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. + 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. + Exception: when reading files or allocating potentially + unbounded amounts of memory, we should respond robustly to memory + allocation failures. + + + + These unexpected conditions indicate a bug either in p11-kit or + in the system. All bets are off once this occurs. + + Use the return_val_xxx() precondition macros to + check for unexpected conditions. +
+ +
+ Testing and Code Coverage + + As a general rule changes to p11-kit should have a tests exercising + that change. Use the make check command to run all + the tests. If you run it from a subdirectory only the tests in that + directory will be run. + + Build p11-kit with the configure + option to build code coverage support. + + Once you've done that you can either use make coverage + to build code coverage information. Alternatively (and this is usually + easier) you can use + + git coverage to easily check whether + you've tested the lines changed by a patch. + + A code coverage report is + available online. +
+ +
+ Debugging Tips + + Unexpected conditions will produce critical warnings by p11-kit. + These are often failed internal preconditions, and usually indicate a + bug either in p11-kit or the software calling it. + + You can use the environment variable P11_KIT_STRICT=yes + to make p11-kit do an abort() (and core dump depending on + your configuration) when a critical warning occurs. +
+ -- cgit v1.1