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 Do not use braces on one-line if and loop statements.
  97
  98 Use:
  99
 100         if (some_condition)
 101             do_some_action();
 102         else
 103             do_something_else();
 104
 105         while (some_condition)
 106             do_something();
 107
 108 Instead of:
 109
 110         if (some_condition) {
 111             do_some_action();
 112         }
 113
 114         while (some_condition) {
 115             do_something();
 116         }
 117
 118 In switch statements, to fall through from one case statement to another, use
 119 AFS_FALLTHROUGH to mark the intentional fall through.  Do not use fall through
 120 comments (e.g. /* fallthrough */), as some compilers do not recognize them and
 121 will flag the case statement with an implied fallthrough warning.
 122
 123 Use:
 124
 125     switch (x) {
 126     case 1:
 127         do_something();
 128         AFS_FALLTHROUGH;
 129     case 2:
 130         do_something_else();
 131         AFS_FALLTHROUGH;
 132     default:
 133         do_some_action();
 134     }
 135
 136 Instead of using fallthrough comments:
 137
 138     switch (x) {
 139     case 1:
 140         do_something();
 141         /* fallthrough */
 142     case 2:
 143         do_something_else();
 144         /* fallthrough */
 145     default:
 146         do_some_action();
 147     }
 148
 149 Or not marking the fall through:
 150
 151    switch (x) {
 152     case 1:
 153         do_something();
 154     case 2:
 155         do_something_else();
 156     default:
 157         do_some_action();
 158     }
 159
 160 Dependencies required to build OpenAFS from source
 161 --------------------------------------------------
 162 The following packages are required to build all of the OpenAFS code
 163 from source on various operating systems:
 164
 165 On Debian:
 166 - autoconf, automake, bison, comerr-dev, cpio, flex, libkrb5-dev,
 167   libncurses5-dev, libpam0g-dev, libxml2-utils, perl, pkg-config;
 168 - libfuse-dev (for the FUSE-based user-mode client);
 169 - dblatex, docbook-xsl, doxygen, xsltproc (for documentation);
 170 - debhelper, hardening-wrapper, dkms (to build the Debian packages)
 171
 172 On FreeBSD:
 173 - autoconf, automake, libtool;
 174 - fusefs-libs, pkgconf (for the FUSE-based user-mode client);
 175 - perl, dblatex, docbook-xsl, libxslt, python, ruby, zip (for documentation)
 176
 177 In addition, FreeBSD systems require kernel sources and a configured kernel
 178 build directory (see section "FreeBSD Notes" in the README file).
 179
 180 GIT Usage
 181 =========
 182
 183 *WARNING* *WARNING* *WARNING* *WARNING* *WARNING* *WARNING* *WARNING*
 184 The Git tree may not always have code which can currently be built.
 185 While every effort is made to keep the head of the tree buildable,
 186 you may at any time find yourself between commits and hence have a tree
 187 which does not build, or worse, causes more serious problems!
 188
 189 Do not use the Git tree unless you know what you're doing.
 190
 191 Git checkouts do not include files generated by autoconf. You can
 192 run regen.sh (at the top level) to create these files. You will need
 193 to have autoconf and automake installed on your system.
 194
 195 Summary
 196 -------
 197
 198 Browse:  http://git.openafs.org/
 199 Clone:   git clone git://git.openafs.org/openafs.git
 200
 201 Step-by-step
 202 ------------
 203
 204 1. Obtain the Git software. If you are using a system with a standard
 205    software repository, Git may already be available as a package named
 206    something like git or git-core.  Otherwise, go to http://git-scm.com/
 207
 208 2. Run the command:
 209
 210    % git clone git://git.openafs.org/openafs.git
 211
 212    This will download the full repository and leave a checked-out tree in
 213    a subdirectory of the current directory named openafs. The repository
 214    itself is in the .git subdirectory of that directory.
 215
 216    WARNING: The repository is approximately 60MiB currently and will only
 217    grow, so it may take some time to download the first time over a slow
 218    network connection.
 219
 220 3. Generate the additional required files:
 221
 222    % cd openafs
 223    % ./regen.sh
 224
 225 The current development series is in the branch named master. The stable
 226 releases are on separate branches named something like
 227 openafs-stable_<version> with a separate branch for each major stable
 228 release series. Use git branch -a to see a full list of branches.
 229
 230 OpenAFS uses the Gerrit code review system to review and merge all changes
 231 to OpenAFS. More details are at:
 232
 233     http://wiki.openafs.org/GitDevelopers/
 234
 235 including more detailed Git instructions.
 236
 237 It's by far preferred to use Gerrit to submit code changes, but if you
 238 can't for whatever reason, you can instead open a bug and submit a patch
 239 that way. Do this by sending mail to openafs-bugs@openafs.org with the
 240 patch attached. But please use Gerrit if you can; patches sent in as bugs
 241 will have to be forwarded to Gerrit by someone else, and it's easier for
 242 everyone if you can enter them into Gerrit yourself.
 243
 244 Backport policy
 245 ------------
 246 All patches should land on master first, unless the patch fixes a bug
 247 that only exists in the stable branch.
 248
 249 Once a patch has been accepted into master, anyone can propose
 250 backports to stable branches.
 251
 252 When cherry-picking a commit from another branch, please append a
 253 "cherry picked from" section in your commit message. You'll also need
 254 a separate Change-ID for Gerrit to recognize this as a separate
 255 change. One workflow to do this:
 256
 257 1) Use "git cherry-pick -ex" to pick your commits onto another branch.
 258    The -x option will append the appropriate "cherry picked from"
 259    message, and the -e option will open your editor for you to edit
 260    the commit message.
 261 2) In your editor, delete the existing Change-ID line. Save and quit.
 262 3) Run "git commit --amend", saving and quitting again. Git will run
 263    the commit hook and generate a new Change-ID for Gerrit.
 264
 265 Warnings
 266 ========
 267
 268 OpenAFS Warning detection
 269 -------------------------
 270
 271 There's been a concerted effort over the last few years, by many developers,
 272 to reduce the number of warnings in the OpenAFS tree. In an attempt to
 273 prevent warnings from creeping back in, we now have the ability to break the
 274 build when new warnings appear.
 275
 276 This is only available for systems with gcc 4.2 or later or clang 3.2 or
 277 later, and is disabled unless the --enable-checking option is supplied to
 278 configure. Because we can't remove all of the warnings, we permit file by
 279 file (and warning by warning) disabling of specific warnings. The
 280 --enable-checking=all option prevents
 281 this, and errors for any file containing a warning.
 282
 283 Disabling warnings
 284 ------------------
 285
 286 If warnings are unavoidable in a particular part of the build, they may be
 287 disabled in an number of ways.
 288
 289 You can disable a single warning type in a particular file by using GCC
 290 pragmas. If a warning can be disabled with a pragma, then the switch to use
 291 will be listed in the error message you receive from the compiler. Pragmas
 292 should be wrapped in IGNORE_SOME_GCC_WARNINGS, so that they aren't used
 293 with non-gcc compilers, and can be disabled if desired. For example:
 294   #ifdef IGNORE_SOME_GCC_WARNINGS
 295   # pragma GCC diagnostic warning "-Wold-style-definition"
 296   #endif
 297
 298 It would appear that when built with -Werror, the llvm clang compiler will
 299 still upgrade warnings that are suppresed in this way to errors. In this case,
 300 the fix is to mark that warning as ignored, but only for clang. For example:
 301   #ifdef IGNORE_SOME_GCC_WARNINGS
 302   # ifdef __clang__
 303   #  pragma GCC diagnostic ignored "-Wdeprecated-declarations"
 304   # else
 305   #  pragma GCC diagnostic warning "-Wdeprecated-declarations"
 306   # endif
 307   #endif
 308
 309 If the source cannot be changed to add a pragma, you might be abe to use the
 310 autoconf function AX_APPEND_COMPILE_FLAGS to create a new macro that disables
 311 the warning and then use macro for the build options for that file. For an
 312 example, see how the autoconf macro CFLAGS_NOIMPLICIT_FALLTHROUGH is defined and
 313 used.
 314
 315 Finally if there isn't a way to disable the specific warning, you will need to
 316 disable all warnings for the file in question. You can do this by supplying
 317 the autoconf macro @CFLAGS_NOERROR@ in the build options for the file. For
 318 example:
 319   lex.yy.o : lex.yy.c y.tab.c
 320          ${CC} -c ${CFLAGS} @CFLAGS_NOERROR@ lex.yy.c
 321
 322 If you add a new warning inhibition, please also add it to the list below.
 323
 324 Inhibited warnings
 325 ------------------
 326 uss/lex.i            : fallthrough   : clang fallthrough, flex generated code
 327 comerr/et_lex.lex.l  : fallthrough   : clang fallthrough, flex generated code
 328                                        pragma set to ignored where included in
 329                                        error_table.y
 330 afs/afs_syscall.c    : old-style
 331                      : strict-proto
 332                      : all (ukernel) : syscall pointer issues
 333 afsd/afsd_kernel.c   : deprecated    : daemon() marked as deprecated on Darwin
 334 bozo/bosserver.c     : deprecated    : daemon() marked as deprecated on Darwin
 335 bucoord/ubik_db_if.c : strict-proto  : ubik_Call_SingleServer
 336 bucoord/commands.c   : all           : signed vs unsigned for dates
 337 external/heimdal/hcrypto/validate.c: all: statement with empty body
 338 external/heimdal/hcrypto/evp.c:      cast-function-type
 339              : Linux kernel build uses -Wcast-function-type
 340 external/heimdal/hcrypto/evp-algs.c: cast-function-type
 341              : Linux kernel build uses -Wcast-function-type
 342 kauth/admin_tools.c  : strict-proto  : ubik_Call
 343 kauth/authclient.c   : strict-proto  : ubik_Call nonsense
 344 libadmin/kas/afs_kasAdmin.c: strict-proto : ubik_Call nonsense
 345 libadmin/samples/rxstat_query_peer.c : all : util_RPCStatsStateGet types
 346 libadmin/samples/rxstat_query_process.c : all : util_RPCStatsStateGet types
 347 libadmin/test/client.c : all         : util_RPCStatsStateGet types
 348 ubik/ubikclient.c    : strict-protos : ubik_Call
 349 volser/vol-dump.c    : format        : afs_sfsize_t
 350 rxkad/ticket5.c      : format-truncation : inside included file v5der.c in the
 351                                        function _heim_time2generalizedtime, the
 352                                        two snprintf calls raise
 353                                        format-truncation warnings due to the
 354                                        arithmetic on tm_year and tm_mon fields
 355 lwp/process.c        : dangling-pointer : Ignore the legitimate use of saving
 356                                        the address of a stack variable