gpg: Emit FAILURE stati now in almost all cases.
[gnupg.git] / doc / HACKING
index 11ae53b..bd16856 100644 (file)
@@ -38,26 +38,31 @@ are delimited by a comma (e.g. =scd,w32:=). Commonly found keywords
 are
 
  - agent   :: The gpg-agent component
- - ssh     :: The ssh-agent part of the agent
- - common  :: Code in common
- - iobuf   :: The IOBUF system in common
- - gpg     :: The gpg or gpgv components
- - gpgsm   :: The gpgsm component
- - scd     :: The scdaemon component
+ - build   :: Changes to the build system
  - ccid    :: The CCID driver in scdaemon
+ - common  :: Code in common
  - dirmngr :: The dirmngr component
- - w32     :: Windows related code
- - po      :: Translations
- - build   :: Changes to the build system
- - speedo  :: Speedo build system specific changes
  - doc     :: Documentation changes
+ - gpg     :: The gpg or gpgv components
+ - sm      :: The gpgsm component (also "gpgsm")
+ - gpgscm  :: The regression test driver
  - indent  :: Indentation and similar changes
+ - iobuf   :: The IOBUF system in common
+ - po      :: Translations
+ - scd     :: The scdaemon component
+ - speedo  :: Speedo build system specific changes
+ - ssh     :: The ssh-agent part of the agent
+ - tests   :: The regressions tests
+ - tools   :: Other code in tools
+ - w32     :: Windows related code
+ - wks     :: The web key service tools
+ - yat2m   :: The yat2m tool.
 
 Typo fixes and documentation updates don't need a ChangeLog entry;
 thus you would use a commit message like
 
 #+begin_example
-Fix typo in a comment
+doc: Fix typo in a comment
 
 --
 #+end_example
@@ -74,7 +79,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
@@ -127,28 +131,70 @@ Note that such a comment will be removed if the git commit option
   - Only certain C99 features may be used (see below); in general
     stick to C90.
   - Please do not use C++ =//= style comments.
+  - Do not use comments like:
+#+begin_src
+      if (foo)
+        /* Now that we know that foo is true we can call bar.  */
+        bar ();
+#+end_src
+    instead write the comment on the if line or before it.  You may
+    also use a block and put the comment inside.
+  - Please use asterisks on the left of longer comments.  This makes
+    it easier to read without syntax highlighting, on printouts, and
+    for blind people.
   - Try to fit lines into 80 columns.
   - Ignore signed/unsigned pointer mismatches
   - No arithmetic on void pointers; cast to char* first.
+  - Do not use
+#+begin_src
+      if ( 42 == foo )
+#+end_src
+    this is harder to read and modern compilers are pretty good in
+    detecing accidential assignments.  It is also suggested not to
+    compare to 0 or NULL but to test the value direct or with a '!';
+    this makes it easier to see that a boolean test is done.
   - We use our own printf style functions like =es_printf=, and
-    =es_asprintf= which implement most C99 features with the exception
-    of =wchar_t= (which should anyway not be used).  Please always use
-    them 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.
+    =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.
+  - New code shall in general use xtrymalloc or xtrycalloc and check
+    for an error (use gpg_error_from_syserror()).
   - 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.
+  - Put extra parenthesis around terms with binary operators to make
+    it clear that the binary operator was indeed intended.
+  - Use --enable-maintainer-mode with configure so that all suitable
+    warnings are enabled.
+
+** 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
 
@@ -178,6 +224,7 @@ Note that such a comment will be removed if the git commit option
   - CVE-id :: CVE id number pertaining to this commit.
   - Regression-due-to :: Commit id of the regression fixed by this commit.
   - Fixes-commit :: Commit id this commit fixes.
+  - Updates-commit :: Commit id this commit updates.
   - Reported-by :: Value is a name or mail address of a bug reporte.
   - Suggested-by :: Value is a name or mail address of someone how
                     suggested this change.
@@ -302,17 +349,17 @@ Note that such a comment will be removed if the git commit option
   - g10/mdfilter.c :: Filter to calculate hashs
   - g10/textfilter.c :: Filter to handle CR/LF and trailing white space
   - g10/cipher.c   :: En-/Decryption filter
-  - g10/misc.c     :: Utlity functions
+  - g10/misc.c     :: Utility functions
   - g10/options.h  :: Structure with all the command line options
                       and related constants
   - g10/openfile.c :: Create/Open Files
   - g10/keyserver.h :: Keyserver access dispatcher.
-  - g10/packet.h   :: Defintion of OpenPGP structures.
+  - g10/packet.h   :: Definition of OpenPGP structures.
   - g10/passphrase.c :: Passphrase handling code
 
   - g10/pubkey-enc.c :: Process a public key encoded packet.
   - g10/seckey-cert.c :: Not anymore used
-  - g10/seskey.c     :: Make sesssion keys etc.
+  - g10/seskey.c     :: Make session keys etc.
   - g10/import.c     :: Import keys into our key storage.
   - g10/export.c     :: Export keys to the OpenPGP format.
   - g10/sign.c       :: Create signature and optionally encrypt.