HACKING

HACKING GNOME KEYRING

BUILD OPTIONS
---------------

Build options for developers:

  --enable-strict: Build with -Werror, disable deprecations, and fatal warnings

  --enable-debug: Turn off compiler optimization
  --disable-debug: Turn off all debug options and output.

  --enable-coverage: Build coverage, use 'make coverage' for summary.


PATCHES
----------

Patches should be submitted to bugzilla:

http://bugzilla.gnome.org/enter_bug.cgi?product=gnome-keyring

The gnome-keyring mailing list is:
gnome-keyring-list@gnome.org

An overview of the architecture and graphical outline can be found here:

http://live.gnome.org/GnomeKeyring/Architecture

Gnome Keyring is made up of several distinct parts working on concert with 
each other. These parts generally live in different directories:

daemon 
   The main daemon startup code and gnome-keyring password protocol operations. 

daemon/control
   Binary protocol for controling and initializing the daemon.

daemon/dbus
   Various DBus bits of the daemon including the Secret Service API.

daemon/gpg-agent
   A GPG agent implementation that uses a PKCS#11 module for it's password storage.

daemon/login
   Used to lock and unlock the daemon.

daemon/ssh-agent
   An SSH agent implementation that uses a PKCS#11 module for it's cryto and key storage.

egg
   Code that either: a) Really should be implemented elsewhere (eg: glib) but isn't.
   b) Code that needs to be shared between loosely coupled gnome-keyring components.  

gck
   A public library for accessing PKCS#11 modules.

gcr
   A public library for bits of crypto UI and parsing etc...
   
pam 
   The PAM module that unlocks the login keyring when the user logs in.
   
pkcs11
   The various bits of the PKCS#11 implementation.

pkcs11/gck
   A base library for implementing our internal PKCS#11 modules.
   
pkcs11/rpc-layer
   A PKCS#11 module that calls into the daemon. This is the module that apps actually use.
   
pkcs11/ssh-store
   A PKCS#11 module which exposes objects in ~/.ssh directory.
   
pkcs11/user-store
   A PKCS#11 module for general storage of certificates and keys.

pkcs11/wrap-layer
   A PKCS#11 module that combines slots from multiple PKCS#11 modules into one module.

testing
   Test tools and unit tests.

tool
   The gnome-keyring command line tool.

ui
   Prompting the user, asking for passwords.


TESTING
----------

Significant new code should be testable via:

$ make check

You check for memory errors by doing:

$ make check-memory

To test the pam code, you must first place some custom PAM configuration
in your /etc/pam.d. This will not be used by anything else. To do this:

$ sudo make enable-pam-tests
$ sudo make disable-pam-tests


----------------------------------------------------------------------------------
  CODING STYLE
----------------------------------------------------------------------------------

Our coding style is very similar to the linux coding style:

  http://lxr.linux.no/linux/Documentation/CodingStyle

Summary below. Differences from Linux coding style are marked with a plus
instead of an asterisk:

 + Space between function name and parentheses.

		my_function_call (arg1, arg2);

 * Braces on the same line as conditional with spaces around braces:

		if (test) {
			do_y ();
			do_z ();
		}

		switch (value) {
		case CONSTANT:
			do_z ();
			break;
		default:
			break;
		}

 * Braces around functions on a separate line from function name,
   return value on a separate line, arguments on separate lines.
   arguments should be indented with spaces past the column of the function
   name.

		static void
		my_special_function (int arg1,
		                     int arg2)
		{
			/* body of function */
		}

 * Don't use braces unnecessarily:

		if (test)
			do_this_thing ();

 * But use braces here, when one section has more than a line:

		if (test) {
			do_this_thing ();
		} else {
			do_other_thing ();
			smile_nicely ();
		}

 * Use of tabs for 8 char indent.

	------->if (test) {
	------->------->Value;
	------->------->Value;
	------->}

 * No trailing whitespace on lines. Git will warn you about this.
   Please enforce it like so (in gnome-keyring checkout):

	$ cp -ipv .git/hooks/pre-commit.sample .git/hooks/pre-commit

 * The '*' in a pointer declaraction belongs with the variable name:

	char *name;

 + Extra long wrapped lines should wrap to function opening brace
   using spaces past indentation point.

	------>my_function_call ("this is a very long argument here",
	------>                  "wrapped argument is indented with spaces");

 * Function names are in lower case with _ separators.

	this_is_a_long_function_name ();

 * Constants are all in upper case with _ separators.

	THIS_IS_A_CONSTANT

 + Structures should be typedefed to avoid saying 'struct' and names
   are CamelCase:

        ThisIsAStruct

 * One line comments should look like:

	/* This is a one line comment */

 * Multi line comments should look like:

	/*
	 * This is a multiline comment.
	 * And it has a useless second line.
	 */

When in doubt adapt to the style of the code around your patch.