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 \f
  87 Dependencies required to build OpenAFS from source
  88 --------------------------------------------------
  89 The following packages are required to build all of the OpenAFS code
  90 from source on various operating systems:
  91
  92 On Debian:
  93 - autoconf, automake, bison, comerr-dev, cpio, flex, libkrb5-dev,
  94   libncurses5-dev, libpam0g-dev, libxml2-utils, perl, pkg-config;
  95 - libfuse-dev (for the FUSE-based user-mode client);
  96 - dblatex, docbook-xsl, doxygen, xsltproc (for documentation);
  97 - debhelper, hardening-wrapper, dkms (to build the Debian packages)
  98
  99 On FreeBSD:
 100 - autoconf, automake, libtool;
 101 - fusefs-libs, pkgconf (for the FUSE-based user-mode client);
 102 - perl, dblatex, docbook-xsl, libxslt, python, ruby, zip (for documentation)
 103
 104 In addition, FreeBSD systems require kernel sources and a configured kernel
 105 build directory (see section "FreeBSD Notes" in the README file).
 106
 107 GIT Usage
 108 =========
 109
 110 *WARNING* *WARNING* *WARNING* *WARNING* *WARNING* *WARNING* *WARNING*
 111 The Git tree may not always have code which can currently be built.
 112 While every effort is made to keep the head of the tree buildable,
 113 you may at any time find yourself between commits and hence have a tree
 114 which does not build, or worse, causes more serious problems!
 115
 116 Do not use the Git tree unless you know what you're doing.
 117
 118 Git checkouts do not include files generated by autoconf. You can
 119 run regen.sh (at the top level) to create these files. You will need
 120 to have autoconf and automake installed on your system.
 121
 122 Summary
 123 -------
 124
 125 Browse:  http://git.openafs.org/
 126 Clone:   git clone git://git.openafs.org/openafs.git
 127
 128 Step-by-step
 129 ------------
 130
 131 1. Obtain the Git software. If you are using a system with a standard
 132    software repository, Git may already be available as a package named
 133    something like git or git-core.  Otherwise, go to http://git-scm.com/
 134
 135 2. Run the command:
 136
 137    % git clone git://git.openafs.org/openafs.git
 138
 139    This will download the full repository and leave a checked-out tree in
 140    a subdirectory of the current directory named openafs. The repository
 141    itself is in the .git subdirectory of that directory.
 142
 143    WARNING: The repository is approximately 60MiB currently and will only
 144    grow, so it may take some time to download the first time over a slow
 145    network connection.
 146
 147 3. Generate the additional required files:
 148
 149    % cd openafs
 150    % ./regen.sh
 151
 152 The current development series is in the branch named master. The stable
 153 releases are on separate branches named something like
 154 openafs-stable_<version> with a separate branch for each major stable
 155 release series. Use git branch -a to see a full list of branches.
 156
 157 OpenAFS uses the Gerrit code review system to review and merge all changes
 158 to OpenAFS. More details are at:
 159
 160     http://wiki.openafs.org/GitDevelopers/
 161
 162 including more detailed Git instructions.
 163
 164 It's by far preferred to use Gerrit to submit code changes, but if you
 165 can't for whatever reason, you can instead open a bug and submit a patch
 166 that way. Do this by sending mail to openafs-bugs@openafs.org with the
 167 patch attached. But please use Gerrit if you can; patches sent in as bugs
 168 will have to be forwarded to Gerrit by someone else, and it's easier for
 169 everyone if you can enter them into Gerrit yourself.
 170
 171 Backport policy
 172 ------------
 173 All patches should land on master first, unless the patch fixes a bug
 174 that only exists in the stable branch.
 175
 176 Once a patch has been accepted into master, anyone can propose
 177 backports to stable branches.
 178
 179 When cherry-picking a commit from another branch, please append a
 180 "cherry picked from" section in your commit message. You'll also need
 181 a separate Change-ID for Gerrit to recognize this as a separate
 182 change. One workflow to do this:
 183
 184 1) Use "git cherry-pick -ex" to pick your commits onto another branch.
 185    The -x option will append the appropriate "cherry picked from"
 186    message, and the -e option will open your editor for you to edit
 187    the commit message.
 188 2) In your editor, delete the existing Change-ID line. Save and quit.
 189 3) Run "git commit --amend", saving and quitting again. Git will run
 190    the commit hook and generate a new Change-ID for Gerrit.