README.CODING_STYLE

Some things are mentioned here to help any potential gnutls coder.
The rules here are not always used, although we try to stick to them.


** Test suite:
   New functionality should be accompanied by a test case which verifies
 the correctness of GnuTLS' operation on successful use of the new
 functionality, as well as on fail cases. An example test suite can be seen
 in mini-x509-cas.c.  The GnuTLS test suite is run on "make check"
 on every system GnuTLS is installed.


*** File names:
  Files are split to directories according to the subsystem
 they belong to. Examples are x509/, minitasn1/, openpgp/,
 opencdk/ etc. The files in the root directory are of concern
 to the main TLS protocol implementation.


*** Indentation style:
  In general, use the Linux coding style.  You may indent the source
  using GNU indent, e.g. "indent -linux *.c".


*** Git commits:
  The original author of the changes should be the author of the commit.
The "Signed-off-by" git flag is used to indicate a commit according to
the project's DCO.


*** Function names:
  All the function names use underscore "_", to separate words,
 functions like gnutlsDoThat are not used. The exported function names
 usually start with "gnutls_" prefix, and the words that follow
 specify the exact part of gnutls that this function refers to.
 E.g. "gnutls_x509_crt_get_dn", refers to the X.509
 certificate parsing part of gnutls. Currently used prefixes are:
 "gnutls_x509_crt_" for the X.509 certificate part
 "gnutls_openpgp_key_" for the openpgp key part
 "gnutls_session_" for the TLS session part (but this may be omited)
 "gnutls_handshake_" for the TLS handshake part
 "gnutls_record_" for the TLS record protocol part
 "gnutls_alert_" for the TLS alert protocol part
 "gnutls_credentials_" for the credentials structures
 "gnutls_global_" for the global structures handling
 and probably more.

 Internal functions -- that are not exported in the API -- should
 be prefixed with an underscore. E.g. _gnutls_handshake_begin()

 Internal structures should not be exported. Especially pointers to
 internal data. Doing so harms future reorganization/rewrite of subsystems.

 All exported functions must be listed in libgnutls.map
 in order to be exported.


*** Constructed types:
  The constructed types in gnutls always have the "gnutls_" prefix.
 Definitions, value defaults and enumerated values should be in
 capitals. E.g. GNUTLS_CIPHER_3DES_CBC

 Structures should have the '_st' suffix in their name even
 if they are a typedef. One can use the sizeof() on types with 
 '_st' as suffix.

 Other constructed types should have the '_t' suffix. A pointer
 to a structure also has the '_t' suffix.


*** Function parameters:
  The gnutls functions accept parameters in the order:
  1. Input parameters
  2. Output parameters

  When data and size is expected, a gnutls_datum structure should be
  used (or more precisely a pointer to the structure).


*** Callback function parameters:
  Callback functions should be avoided, if this is possible. 
 Callbacks that refer to a TLS session should include the
 current session as a parameter, in order for the called function to
 be able to retrieve the data associated with the session.
 This is not always done though -- see the push/pull callbacks.


*** Return values:
  Functions in gnutls return an int type, when possible. In that
 case 0 should be returned in case of success, or maybe a positive
 value, if some other indication is needed.
 
 A negative value always indicates failure. All the available
 error codes are defined in gnutls.h and a description
 is available in gnutls_errors.c


*** Guile bindings:

 Parts of the Guile bindings, such as types (aka. "SMOBs"), enum values,
 constants, are automatically generated.  This is handled by the modules
 under `guile/modules/gnutls/build/'; these modules are only used at
 build-time and are not installed.

 The Scheme variables they generate (e.g., constants, type predicates,
 etc.) are exported to user programs through `gnutls.scm' and
 `gnutls/extra.scm', both of which are installed.

 For instance, when adding/removing/renaming enumerates or constants,
 two things must be done:

  1. Update the enum list in `build/enums.scm' (currently dependencies
     are not tracked, so you have to run "make clean all" in `guile/'
     after).

  2. Update the export list of `gnutls.scm' (or `extra.scm').

 Note that, for constants and enums, "schemefied" names are used, as
 noted under the "Guile API Conventions" node of the manual.