From 866e3204cee593817850f5e5c23a0bcf7af9c591 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Tue, 5 Feb 2013 11:50:16 +0100 Subject: Add documentation about contributing to p11-kit --- doc/Makefile.am | 2 +- doc/p11-kit-config.xml | 4 +- doc/p11-kit-devel.xml | 223 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/p11-kit-docs.sgml | 13 +-- doc/p11-kit-notes.xml | 48 ----------- 5 files changed, 233 insertions(+), 57 deletions(-) create mode 100644 doc/p11-kit-devel.xml delete mode 100644 doc/p11-kit-notes.xml (limited to 'doc') 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. If this is a relative path, then the module will be loaded - from the default module directory. + from the default module directory. @@ -220,7 +220,7 @@ critical: yes The default system config file and module directory can be changed when building p11-kit. Always - lookup these paths using + lookup these paths using pkg-config. 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 @@ + + + + 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 +
+ +
+ +
+ 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. + + +
+ +
+ Extra Configuration Options + + In addition to the normal options, the configure script in the p11-kit library + supports these additional arguments: + + + + , + 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. + + + + Specify the path to look for PKCS#11 modules which were + listed in a module config file with a relative path. + + + + 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. + +
+ 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 @@ - Command Line Tools @@ -21,16 +20,18 @@ - Reference + API Reference + + API Index + + - - API Index - - + + 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 @@ - - - - Developer and Packager Notes - -
- Using pkg-config to determine paths - - 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 -
- -
- - -- cgit v1.1