HACKING 4.89 KB
Newer Older
1

2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
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
----------
19 20

Patches should be submitted to bugzilla:
21

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

24 25 26
The gnome-keyring mailing list is:
gnome-keyring-list@gnome.org

27 28 29 30
An overview of the architecture and graphical outline can be found here:

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

31 32 33 34 35
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. 
36

37 38 39 40 41 42 43 44 45 46 47
daemon/control
   Binary protocol for controling and initializing the daemon.

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

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.
48

49 50 51 52
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.  

53 54 55
gck
   A public library for accessing PKCS#11 modules.

56 57 58 59 60 61
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.
   
62
pkcs11
63 64 65 66 67 68 69 70 71 72 73 74 75
   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.
76 77 78 79

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

80
testing
81
   Test tools and unit tests.
82

83 84 85
tool
   The gnome-keyring command line tool.

86 87 88
ui
   Prompting the user, asking for passwords.

89

90 91 92 93 94 95 96 97 98 99 100
TESTING
----------

Significant new code should be testable via:

$ make check

You check for memory errors by doing:

$ make check-memory

101 102 103 104 105 106
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

107

108 109 110
----------------------------------------------------------------------------------
  CODING STYLE
----------------------------------------------------------------------------------
111

112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138
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,
139 140 141
   return value on a separate line, arguments on separate lines.
   arguments should be indented with spaces past the column of the function
   name.
142 143

		static void
144 145
		my_special_function (int arg1,
		                     int arg2)
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
		{
			/* 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:
204

205 206 207 208
	/*
	 * This is a multiline comment.
	 * And it has a useless second line.
	 */
209

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