wks: Let the client only export the requested UID.
[gnupg.git] / doc / HACKING
index 5d72017..94e65d8 100644 (file)
@@ -46,11 +46,14 @@ are
  - scd     :: The scdaemon component
  - ccid    :: The CCID driver in scdaemon
  - dirmngr :: The dirmngr component
+ - wks     :: The web key service tools
+ - tools   :: Other code in tools
  - w32     :: Windows related code
  - po      :: Translations
  - build   :: Changes to the build system
  - speedo  :: Speedo build system specific changes
  - doc     :: Documentation changes
+ - indent  :: Indentation and similar changes
 
 Typo fixes and documentation updates don't need a ChangeLog entry;
 thus you would use a commit message like
@@ -73,7 +76,6 @@ do this after this scissor line:
 Note that such a comment will be removed if the git commit option
 =--cleanup=scissor= is used.
 
-
 ** License policy
 
   GnuPG is licensed under the GPLv3+ with some files under a mixed
@@ -123,11 +125,69 @@ Note that such a comment will be removed if the git commit option
   need.  If you really need to do it, use a separate commit for such a
   change.
 
-  - C99 syntax should not be used; stick to C90.
+  - Only certain C99 features may be used (see below); in general
+    stick to C90.
   - Please do not use C++ =//= style comments.
   - Try to fit lines into 80 columns.
   - Ignore signed/unsigned pointer mismatches
   - No arithmetic on void pointers; cast to char* first.
+  - We use our own printf style functions like =es_printf=, and
+    =gpgrt_asprintf= (or the =es_asprintf= macro) which implement most
+    C99 features with the exception of =wchar_t= (which should anyway
+    not be used).  Please use them always and do not resort to those
+    provided by libc.  The rationale for using them is that we know
+    that the format specifiers work on all platforms and that we do
+    not need to chase platform dependent bugs.  Note also that in
+    gnupg asprintf is a macro already evaluating to gpgrt_asprintf.
+  - It is common to have a label named "leave" for a function's
+    cleanup and return code.  This helps with freeing memory and is a
+    convenient location to set a breakpoint for debugging.
+  - Always use xfree() instead of free().  If it is not easy to see
+    that the freed variable is not anymore used, explicitly set the
+    variable to NULL.
+  - Init function local variables only if needed so that the compiler
+    can do a better job in detecting uninitialized variables which may
+    indicate a problem with the code.
+  - Never init static or file local variables to 0 to make sure they
+    end up in BSS.
+  - Use --enable-maintainer-mode with configure.
+
+** Variable names
+
+  Follow the GNU standards.  Here are some conventions you may want to
+  stick to (do not rename existing "wrong" uses without a goog
+  reason).
+
+  - err :: This conveys an error code of type =gpg_error_t= which is
+           compatible to an =int=.  To compare such a variable to a
+           GPG_ERR_ constant, it is necessary to map the value like
+           this: =gpg_err_code(err)=.
+  - ec  :: This is used for a gpg-error code which has no source part
+           (=gpg_err_code_t=) and will eventually be used as input to
+           =gpg_err_make=.
+  - rc  :: Used for all kind of other errors; for example system
+           calls.  The value is not compatible with gpg-error.
+
+
+*** C99 language features
+
+  In GnuPG 2.x, but *not in 1.4* and not in most libraries, a limited
+  set of C99 features may be used:
+
+  - Variadic macros:
+    : #define foo(a,...)  bar(a, __VA_ARGS__)
+
+  - The predefined macro =__func__=:
+    : log_debug ("%s: Problem with foo\n", __func__);
+
+  - Variable declaration inside a for():
+    : for (int i = 0; i < 5; ++)
+    :   bar (i);
+
+  Although we usually make use of the =u16=, =u32=, and =u64= types,
+  it is also possible to include =<stdint.h>= and use =int16_t=,
+  =int32_t=, =int64_t=, =uint16_t=, =uint32_t=, and =uint64_t=.  But do
+  not use =int8_t= or =uint8_t=.
 
 ** Commit log keywords