CODING

   1 Notes on Coding Standards/Requirements for OpenAFS Source
   2 ---------------------------------------------------------
   3
   4 We have an official style.  Please use it.  If you have gnu indent 2.2.9 or
   5 later you can reformat for this style with the following option:
   6
   7 -npro -nbad -bap -nbc -bbo -br -ce -cdw -brs -ncdb -cp1 -ncs -di2 -ndj -nfc1
   8 -nfca -i4 -lp -npcs -nprs -psl -sc -nsob -ts8
   9
  10 Do not use $< for non-pattern rules in any cross-platform dir as it
  11 requires a reasonable make that is not available on all systems.
  12
  13 Do not have build rules that build multiple targets. Make doesn't seem able
  14 to handle this, and it interferes with -j builds. (In particular, build the
  15 rxgen targets individually and not using the flags for building all the files
  16 in one shot.)
  17
  18 Try to test builds using gmake -j # MAKE="gmake -j #", it seems like a good
  19 way to find missing or order-dependent dependency rules. (Is there a better
  20 way to do this?)
  21
  22 -- Prototyping and Style --
  23 Prototypes for all source files in a given dir DDD should be placed
  24 in the file DDD/DDD_prototypes.h. All externally used (either API
  25 or used by other source files) routines and variables should be
  26 prototyped in this file.
  27
  28 The prototypes should be a full prototype, with argument and return
  29 types. (Should not generate a warning with gcc -Wstrict-prototypes.)
  30
  31 Format of the prototype files should look like:
  32
  33         Standard Copyright Notice
  34
  35         #ifndef AFS_SRC_DDD_PROTO_H
  36         #define AFS_SRC_DDD_PROTO_H
  37
  38         /* filename.c */
  39         prototypes
  40
  41         /* filename.c */
  42         prototypes
  43
  44         #endif /* AFS_SRC_DDD_PROTO_H */
  45
  46 In most of the existing prototypes, the define is DDD_PROTOTYPES_H, which is
  47 probably ok as well.
  48
  49 The declaration of the routines should be done in ANSI style. If at some
  50 later date, it is determined that prototypes don't work on some platform
  51 properly, we can use ansi2knr during the compile.
  52
  53         rettype
  54         routine(argtype arg)
  55         {
  56
  57         }
  58
  59 All routines should have a return type specified, void if nothing returned,
  60 and should have (void) if no arguments are taken.
  61
  62 Header files should not contain macros or other definitions unless they
  63 are used across multiple source files.
  64
  65 All routines should be declared static if they are not used outside that
  66 source file.
  67
  68 Compiles on gcc-using machines should strive to handle using
  69 -Wstrict-prototypes -Werror. (this may take a while)
  70
  71 Routines shall be defined in source prior to use if possible, and
  72 prototyped in block at top of file if static.
  73
  74 API documentation in the code should be done using Qt-style Doxygen
  75 comments.
  76
  77 If you make a routine or variable static, be sure and remove it from
  78 the AIX .exp files.
  79
  80 Suggested compiler flags:
  81         gcc: -Wall -Wstrict-prototypes
  82         Solaris Workshop CC: -fd -v
  83                 (You might not want the -fd, it isn't really useful, just complains about the
  84                 K&R style functions, but -v gives useful info.)
  85
  86 Multiple line comment blocks should begin with only /* on one line and end with
  87 only */ on one line.
  88
  89 Example:
  90
  91         /*
  92          * Multiple line comment blocks should be formatted
  93          * like this example.
  94          */
  95
  96 \f
  97 Dependencies required to build OpenAFS from source
  98 --------------------------------------------------
  99 The following packages are required to build all of the OpenAFS code
 100 from source on various operating systems:
 101
 102 On Debian:
 103 - autoconf, automake, bison, comerr-dev, cpio, flex, libkrb5-dev,
 104   libncurses5-dev, libpam0g-dev, libxml2-utils, perl, pkg-config;
 105 - libfuse-dev (for the FUSE-based user-mode client);
 106 - dblatex, docbook-xsl, doxygen, xsltproc (for documentation);
 107 - debhelper, hardening-wrapper, dkms (to build the Debian packages)
 108
 109 On FreeBSD:
 110 - autoconf, automake, libtool;
 111 - fusefs-libs, pkgconf (for the FUSE-based user-mode client);
 112 - perl, dblatex, docbook-xsl, libxslt, python, ruby, zip (for documentation)
 113
 114 In addition, FreeBSD systems require kernel sources and a configured kernel
 115 build directory (see section "FreeBSD Notes" in the README file).
 116
 117 GIT Usage
 118 =========
 119
 120 *WARNING* *WARNING* *WARNING* *WARNING* *WARNING* *WARNING* *WARNING*
 121 The Git tree may not always have code which can currently be built.
 122 While every effort is made to keep the head of the tree buildable,
 123 you may at any time find yourself between commits and hence have a tree
 124 which does not build, or worse, causes more serious problems!
 125
 126 Do not use the Git tree unless you know what you're doing.
 127
 128 Git checkouts do not include files generated by autoconf. You can
 129 run regen.sh (at the top level) to create these files. You will need
 130 to have autoconf and automake installed on your system.
 131
 132 Summary
 133 -------
 134
 135 Browse:  http://git.openafs.org/
 136 Clone:   git clone git://git.openafs.org/openafs.git
 137
 138 Step-by-step
 139 ------------
 140
 141 1. Obtain the Git software. If you are using a system with a standard
 142    software repository, Git may already be available as a package named
 143    something like git or git-core.  Otherwise, go to http://git-scm.com/
 144
 145 2. Run the command:
 146
 147    % git clone git://git.openafs.org/openafs.git
 148
 149    This will download the full repository and leave a checked-out tree in
 150    a subdirectory of the current directory named openafs. The repository
 151    itself is in the .git subdirectory of that directory.
 152
 153    WARNING: The repository is approximately 60MiB currently and will only
 154    grow, so it may take some time to download the first time over a slow
 155    network connection.
 156
 157 3. Generate the additional required files:
 158
 159    % cd openafs
 160    % ./regen.sh
 161
 162 The current development series is in the branch named master. The stable
 163 releases are on separate branches named something like
 164 openafs-stable_<version> with a separate branch for each major stable
 165 release series. Use git branch -a to see a full list of branches.
 166
 167 OpenAFS uses the Gerrit code review system to review and merge all changes
 168 to OpenAFS. More details are at:
 169
 170     http://wiki.openafs.org/GitDevelopers/
 171
 172 including more detailed Git instructions.
 173
 174 It's by far preferred to use Gerrit to submit code changes, but if you
 175 can't for whatever reason, you can instead open a bug and submit a patch
 176 that way. Do this by sending mail to openafs-bugs@openafs.org with the
 177 patch attached. But please use Gerrit if you can; patches sent in as bugs
 178 will have to be forwarded to Gerrit by someone else, and it's easier for
 179 everyone if you can enter them into Gerrit yourself.
 180
 181 Backport policy
 182 ------------
 183 All patches should land on master first, unless the patch fixes a bug
 184 that only exists in the stable branch.
 185
 186 Once a patch has been accepted into master, anyone can propose
 187 backports to stable branches.
 188
 189 When cherry-picking a commit from another branch, please append a
 190 "cherry picked from" section in your commit message. You'll also need
 191 a separate Change-ID for Gerrit to recognize this as a separate
 192 change. One workflow to do this:
 193
 194 1) Use "git cherry-pick -ex" to pick your commits onto another branch.
 195    The -x option will append the appropriate "cherry picked from"
 196    message, and the -e option will open your editor for you to edit
 197    the commit message.
 198 2) In your editor, delete the existing Change-ID line. Save and quit.
 199 3) Run "git commit --amend", saving and quitting again. Git will run
 200    the commit hook and generate a new Change-ID for Gerrit.
 201
 202 Warnings
 203 ========
 204
 205 OpenAFS Warning detection
 206 -------------------------
 207
 208 There's been a concerted effort over the last few years, by many developers,
 209 to reduce the number of warnings in the OpenAFS tree. In an attempt to
 210 prevent warnings from creeping back in, we now have the ability to break the
 211 build when new warnings appear.
 212
 213 This is only available for systems with gcc 4.2 or later or clang 3.2 or
 214 later, and is disabled unless the --enable-checking option is supplied to
 215 configure. Because we can't remove all of the warnings, we permit file by
 216 file (and warning by warning) disabling of specific warnings. The
 217 --enable-checking=all option prevents
 218 this, and errors for any file containing a warning.
 219
 220 Disabling warnings
 221 ------------------
 222
 223 If warnings are unavoidable in a particular part of the build, they may be
 224 disabled in an number of ways.
 225
 226 You can disable a single warning type in a particular file by using GCC
 227 pragmas. If a warning can be disabled with a pragma, then the switch to use
 228 will be listed in the error message you receive from the compiler. Pragmas
 229 should be wrapped in IGNORE_SOME_GCC_WARNINGS, so that they aren't used
 230 with non-gcc compilers, and can be disabled if desired. For example:
 231   #ifdef IGNORE_SOME_GCC_WARNINGS
 232   # pragma GCC diagnostic warning "-Wold-style-definition"
 233   #endif
 234
 235 It would appear that when built with -Werror, the llvm clang compiler will
 236 still upgrade warnings that are suppresed in this way to errors. In this case,
 237 the fix is to mark that warning as ignored, but only for clang. For example:
 238   #ifdef IGNORE_SOME_GCC_WARNINGS
 239   # ifdef __clang__
 240   #  pragma GCC diagnostic ignored "-Wdeprecated-declarations"
 241   # else
 242   #  pragma GCC diagnostic warning "-Wdeprecated-declarations"
 243   # endif
 244   #endif
 245
 246 If a pragma isn't available for your particular warning, you will need to
 247 disable all warnings for the file in question. You can do this by supplying
 248 the autoconf macro @CFLAGS_NOERROR@ in the build options for the file. For
 249 example:
 250   lex.yy.o : lex.yy.c y.tab.c
 251          ${CC} -c ${CFLAGS} @CFLAGS_NOERROR@ lex.yy.c
 252
 253 If you add a new warning inhibition, please also add it to the list below.
 254
 255 Inhibited warnings
 256 ------------------
 257
 258 afs/afs_syscall.c    : old-style
 259                      : strict-proto
 260                      : all (ukernel) : syscall pointer issues
 261 afsd/afsd_kernel.c   : deprecated    : daemon() marked as deprecated on Darwin
 262 auth/ktc.c           : all (ukernel) : call_syscall doesn't have a prototype
 263 bozo/bosserver.c     : deprecated    : daemon() marked as deprecated on Darwin
 264 bucoord/ubik_db_if.c : strict-proto  : Ubik_Call
 265 bucoord/commands.c   : all           : Ubik_Call
 266                                      : signed vs unsigned for dates
 267 butc/tcudbprocs.c    : all           : ubik_Call
 268 external/heimdal/hcrypto/validate.c: all: statement with empty body
 269 kauth/admin_tools.c  : strict-proto  : ubik_Call
 270 kauth/authclient.c   : strict-proto  : ubik_Call nonsense
 271 libadmin/kas/afs_kasAdmin.c: strict-proto : ubik_Call nonsense
 272 libadmin/samples/rxstat_query_peer.c : all : util_RPCStatsStateGet types
 273 libadmin/samples/rxstat_query_process.c : all : util_RPCStatsStateGet types
 274 libadmin/test/client.c : all         : util_RPCStatsStateGet types
 275 ubik/ubikclient.c    : strict-protos : ubik_Call
 276 volser/vol-dump.c    : format        : afs_sfsize_t
 277