doc/README.CODING_STYLE

   1 Some things are mentioned here to help any potential gnutls coder.
   2 The rules here are not always used, although we try to stick to them.
   3
   4
   5 *** File names:
   6   All file names are usually prefixed with "gnutls_", "auth_", or
   7  "x509_", or something else that indicates the part of gnutls
   8  where this file refers to. The suffix should be more
   9  specific. I.e., "gnutls_record.c" refers to the TLS library
  10  and, more specifically, to the TLS record protocol. "auth_rsa.c"
  11  is the implementation of the RSA certificate authentication
  12  method.
  13
  14  Another way to distinguish files might be using different
  15  subdirectories. Use the lib/x509/ directory, which contains
  16  all the X.509 certificate and crl stuff.
  17
  18
  19 *** Function names:
  20   All the function names use underscore "_", to separate words,
  21  functions like gnutlsDoThat are not used. The function names
  22  usually start with "gnutls_" prefix, and the words that follow
  23  specify the exact part of gnutls that this function refers to.
  24  E.g. "gnutls_x509_crt_get_dn", refers to the X.509
  25  certificate parsing part of gnutls. Currently used prefixes are:
  26  "gnutls_x509_crt_" for the X.509 certificate part
  27  "gnutls_openpgp_key_" for the openpgp key part
  28  "gnutls_session_" for the TLS session part (but this may be omited)
  29  "gnutls_handshake_" for the TLS handshake part
  30  "gnutls_record_" for the TLS record protocol part
  31  "gnutls_alert_" for the TLS alert protocol part
  32  "gnutls_credentials_" for the credentials structures
  33  "gnutls_global_" for the global structures handling
  34  and probably more.
  35
  36  Internal functions -- that are not exported in the API -- should
  37  be prefixed with an underscore. E.g. _gnutls_handshake_begin()
  38
  39  All exported functions must be listed in gnutls.sym and gnutls-extra.sym
  40  in order to be exported. [this is not true for now]
  41
  42 *** Constructed types:
  43   The constructed types in gnutls always have the "gnutls_" prefix.
  44  Definitions, value defaults and enumerated values should be in
  45  capitals. E.g. GNUTLS_CIPHER_3DES_CBC
  46
  47  Structures should have the '_st' suffix in their name even
  48  if they are a typedef. One can use the sizeof() on types with
  49  '_st' as suffix.
  50
  51  Other constructed types should have the '_t' suffix. A pointer
  52  to a structure also has the '_t' suffix.
  53
  54 *** Function parameters:
  55   The gnutls functions accept parameters in the order:
  56   1. Input parameters
  57   2. Output parameters
  58
  59   When data and size is expected, a gnutls_datum structure should be
  60   used (or more precisely a pointer to the structure).
  61
  62 *** Callback function parameters:
  63   Callback functions should be avoided, if this is possible.
  64  Callbacks that refer to a TLS session should include the
  65  current session as a parameter, in order for the called function to
  66  be able to retrieve the data associated with the session.
  67  This is not always done though -- see the push/pull callbacks.
  68
  69 *** Return values:
  70   Functions in gnutls return an int type, when possible. In that
  71  case 0 should be returned in case of success, or maybe a positive
  72  value, if some other indication is needed.
  73
  74  A negative value always indicates failure. All the available
  75  error codes are defined in gnutls.h and a description
  76  is available in gnutls_errors.c
  77
  78 *** Indentation style:
  79   In general, use the GNU Coding Standard.  You may indent the source
  80   using GNU indent, e.g. "indent *.c".
  81
  82 *** Guile bindings:
  83
  84  Parts of the Guile bindings, such as types (aka. "SMOBs"), enum values,
  85  constants, are automatically generated.  This is handled by the modules
  86  under `guile/modules/gnutls/build/'; these modules are only used at
  87  build-time and are not installed.
  88
  89  The Scheme variables they generate (e.g., constants, type predicates,
  90  etc.) are exported to user programs through `gnutls.scm' and
  91  `gnutls/extra.scm', both of which are installed.
  92
  93  For instance, when adding/removing/renaming enumerates or constants,
  94  two things must be done:
  95
  96   1. Update the enum list in `build/enums.scm' (currently dependencies
  97      are not tracked, so you have to run "make clean all" in `guile/'
  98      after).
  99
 100   2. Update the export list of `gnutls.scm' (or `extra.scm').
 101
 102  Note that, for constants and enums, "schemefied" names are used, as
 103  noted under the "Guile API Conventions" node of the manual.