README.DEVEL

   1 Notes on Coding Standards/Requirements for OpenAFS Source
   2 ---------------------------------------------------------
   3
   4 Do not use $< in any cross-platform dir as it requires a reasonable
   5 make that is not available on all systems.
   6
   7 Be careful with prototypes/ANSI-C in code that will be compiled for
   8 kernel source.  In general, avoid them until we have figured out
   9 exactly when/where they can be used safely.
  10
  11 Do not have build rules that build multiple targets. Make doesn't seem able
  12 to handle this, and it interferes with -j builds. (In particular, build the
  13 rxgen targets individually and not using the flags for building all the files
  14 in one shot.)
  15
  16 Try to test builds using gmake -j # MAKE="gmake -j #", it seems like a good
  17 way to find missing or order-dependent dependency rules. (Is there a better
  18 way to do this?)
  19
  20 -- Prototyping and Style --
  21 Prototypes for all source files in a given dir DDD should be placed
  22 int the file DDD/DDD_prototypes.h. All externally used (either API
  23 or used by other source files) routines and variables should be
  24 prototyped in this file.
  25
  26 The prototypes should be a full prototype, with argument and return
  27 types. (Should not generate a warning with gcc -Wstrict-prototypes.)
  28
  29 Format of the prototype files should look like:
  30
  31         Standard Copyright Notice
  32
  33         #ifndef AFS_SRC_DDD_PROTO_H
  34         #define AFS_SRC_DDD_PROTO_H
  35
  36         /* filename.c */
  37         prototypes
  38
  39         /* filename.c */
  40         prototypes
  41
  42         #endif /* AFS_SRC_DDD_PROTO_H */
  43
  44 In most of the existing prototypes, the define is DDD_PROTOTYPES_H, which is
  45 probably ok as well.
  46
  47 The declaration of the routines should be done in ANSI style. If at some
  48 later date, it is determined that prototypes don't work on some platform
  49 properly, we can use ansi2knr during the compile.
  50
  51         rettype routine(argtype arg)
  52         {
  53
  54         }
  55
  56 All routines should have a return type specified, void if nothing returned,
  57 and should have (void) if no arguments are taken.
  58
  59 Header files should not contain macros or other definitions unless they
  60 are used across multiple source files.
  61
  62 All routines should be declared static if they are not used outside that
  63 source file.
  64
  65 Compiles on gcc-using machines should strive to handle using
  66 -Wstrict-prototypes -Werror. (this may take a while)
  67
  68 Routines shall be defined in source prior to use if possible, and
  69 prototyped in block at top of file if static.
  70
  71 If you make a routine or variable static, be sure and remove it from
  72 the AIX .exp files.
  73
  74 Suggested compiler flags:
  75         gcc: -Wall -Wstrict-prototypes
  76         Solaris Workshop CC: -fd -v
  77                 (You might not want the -fd, it isn't really useful, just complains about the
  78                 K&R style functions, but -v gives useful info.)