git.sur5r.net Git - openldap/blob - doc/devel/guidelines

   1 $OpenLDAP$
   2
   3 This document is being replaced with:
   4         http://www.openldap.org/devel/programming.html
   5 and
   6         http://www.openldap.org/devel/contributing.html
   7
   8 However, some of the info here is still useful.
   9
  10 Coding guide lines and and hints for OpenLDAP developers.
  11 =========================================================
  12
  13 Please add to this file when new points come up.
  14
  15
  16 C source
  17 --------
  18
  19 OpenLDAP requires many Standard C features to *build*.  This
  20 includes functional prototypes and offsetof macro.  It is
  21 possible to *build* OpenLDAP with a number of C translators
  22 which are not fully compliant with Standard C.
  23
  24 OpenLDAP supports compiling and linking *with* applications
  25 with most C compilers and libraries.   The installed headers
  26 are designed to provide K&R C compatiable function declarations
  27 on non-standard compilers.  In cases where the compiler does
  28 not define __STDC__ but requires prototypes (ie: MSVC), the
  29 application should define LDAP_NEEDS_PROTOTYPES.  In cases
  30 where the compiler does define __STDC__ but does not support
  31 prototypes, the application should define LDAP_NO_PROTOTYPES.
  32
  33 .c files in the OpenLDAP source tree MUST #include "portable.h" before
  34 any other include file, even system includes.  portable.h may control
  35 aspects of system includes, such as whether or not thread-safe library
  36 functions are used.  (Separate applications can't use portable.h, since
  37 it is not installed.  They can use ldap_features.h, though.)
  38
  39 .h files that are NOT INSTALLED may depend on features from portable.h.
  40 .h files that *are* installed (from include/) should not depend on it.
  41
  42 Avoid unnecessary changes, like reindenting code, even if that leaves
  43 the code a little ugly.  Often switching your editors tab stops to
  44 4 or 8 may make code easier to read.  Unnecessary changes make it
  45 harder to maintain and merge different CVS branches of the source.
  46
  47 Please follow the style of surrounding code.
  48
  49 Use feature-specific #if tests (like #ifdef HAVE_LWP) which configure
  50 can figure out, not system-specific test (like #ifdef __SunOS_5_6).
  51
  52 When available, use include files from ldap/include/ac/ to get system
  53 features or functions.  The <ac/xxx.h> files try to fix crippled system
  54 includes, and to hide #ifdef messes that portable programs need in order
  55 to find a feature.  Note that a file <ac/xxx.h> is not necessarily
  56 designed to be equivalent to standard C's <xxx.h> file.
  57
  58 Nonstatic function and variable definitions in .c files should be
  59 preceded by their declarations in .h files.  Avoid implicit function
  60 declarations.  External declarations with should be avoided.  In
  61 .c files, include the appropriate .h file to obtain the declaration.
  62 If the declaration is not available in any system header, add it
  63 to the most appropriate ac/xxx.h header.  Do NOT add extern
  64 declarations to .c files.
  65
  66 When a function returns non-void, it should return a meaningful value.
  67 Avoid implicit int.
  68
  69 It is recommended that ldap_cdef.h macros LDAP_F and LDAP_P be used
  70 even for non-installed headers.  See lber.h and ldap.h for examples.
  71
  72
  73 CVS updating
  74 ------------
  75
  76 <URL:http://www.openldap.org/software/repo.html> describes how to check out
  77 -stable.  To get the -devel (HEAD) branch, omit `-r OPENLDAP_STABLE'.
  78 You can use 'cvs status -v README' to get a list available CVS tags.
  79
  80 Core members should subscribe to the -core mailing list.  This
  81 list is for private discussions between core team members.  The
  82 openldap-devel@openldap.org mailing list is the primary developer
  83 forum for both  technical disscusions and coordinating efforts.
  84
  85 Please test patches before committing.  This should include compiling
  86 and linking the system AND running the test suite.
  87
  88 In general, a patch/bugfix should be applied to -devel and tested.
  89 When the patch is considered stable, then it can be merged into -stable.
  90 Same goes for other release engineering branches (like
  91 OPENLDAP_REL_ENG_1_1).  (-stable is rel eng 1.0).
  92 Specific procjects may get their own branches, to be merged later.
  93
  94 Log messages: Just describe the change and reason.  CVS adds your name,
  95 date, etc.
  96
  97
  98 Various tips and hints
  99 ----------------------
 100
 101 How to correct a CVS log message:
 102 Commit the unchanged files again with the `-f' flag and with a log
 103 message stating how the previous log was in error:
 104         cvs commit -f cldap.c os-ip.c
 105 Preferably, prepend a line something like this to the message:
 106 "Forced commit to correct previous log, files were not changed."
 107
 108 Modify ldapconfig.h instead of ldapconfig.h.edit.  Then `cvs commit'
 109 from the include directory won't accidentally commit your private
 110 ldapconfig.h.edit.