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/p11-kit-devel.xml | 299 -------------------------------------------------- 1 file changed, 299 deletions(-) delete mode 100644 doc/p11-kit-devel.xml (limited to 'doc/p11-kit-devel.xml') diff --git a/doc/p11-kit-devel.xml b/doc/p11-kit-devel.xml deleted file mode 100644 index bbe6c0a..0000000 --- a/doc/p11-kit-devel.xml +++ /dev/null @@ -1,299 +0,0 @@ - - - - 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