Update extra-iput configure argument description
[openafs.git] / 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.
191
192 Warnings
193 ========
194
195 OpenAFS Warning detection
196 -------------------------
197
198 There's been a concerted effort over the last few years, by many developers,
199 to reduce the number of warnings in the OpenAFS tree. In an attempt to
200 prevent warnings from creeping back in, we now have the ability to break the
201 build when new warnings appear.
202
203 This is only available for systems with gcc 4.2 or later or clang 3.2 or
204 later, and is disabled unless the --enable-checking option is supplied to
205 configure. Because we can't remove all of the warnings, we permit file by
206 file (and warning by warning) disabling of specific warnings. The
207 --enable-checking=all option prevents
208 this, and errors for any file containing a warning.
209
210 Disabling warnings
211 ------------------
212
213 If warnings are unavoidable in a particular part of the build, they may be
214 disabled in an number of ways.
215
216 You can disable a single warning type in a particular file by using GCC
217 pragmas. If a warning can be disabled with a pragma, then the switch to use
218 will be listed in the error message you receive from the compiler. Pragmas
219 should be wrapped in IGNORE_SOME_GCC_WARNINGS, so that they aren't used
220 with non-gcc compilers, and can be disabled if desired. For example:
221   #ifdef IGNORE_SOME_GCC_WARNINGS
222   # pragma GCC diagnostic warning "-Wold-style-definition"
223   #endif
224
225 It would appear that when built with -Werror, the llvm clang compiler will
226 still upgrade warnings that are suppresed in this way to errors. In this case,
227 the fix is to mark that warning as ignored, but only for clang. For example:
228   #ifdef IGNORE_SOME_GCC_WARNINGS
229   # ifdef __clang__
230   #  pragma GCC diagnostic ignored "-Wdeprecated-declarations"
231   # else
232   #  pragma GCC diagnostic warning "-Wdeprecated-declarations"
233   # endif
234   #endif
235
236 If a pragma isn't available for your particular warning, you will need to
237 disable all warnings for the file in question. You can do this by supplying
238 the autoconf macro @CFLAGS_NOERROR@ in the build options for the file. For
239 example:
240   lex.yy.o : lex.yy.c y.tab.c
241          ${CC} -c ${CFLAGS} @CFLAGS_NOERROR@ lex.yy.c
242
243 If you add a new warning inhibition, please also add it to the list below.
244
245 Inhibited warnings
246 ------------------
247
248 afs/afs_syscall.c    : old-style
249                      : strict-proto
250                      : all (ukernel) : syscall pointer issues
251 afsd/afsd_kernel.c   : deprecated    : daemon() marked as deprecated on Darwin
252 auth/ktc.c           : all (ukernel) : call_syscall doesn't have a prototype
253 bozo/bosserver.c     : deprecated    : daemon() marked as deprecated on Darwin
254 bucoord/ubik_db_if.c : strict-proto  : Ubik_Call
255 bucoord/commands.c   : all           : Ubik_Call
256                                      : signed vs unsigned for dates
257 butc/tcudbprocs.c    : all           : ubik_Call
258 external/heimdal/hcrypto/validate.c: all: statement with empty body
259 kauth/admin_tools.c  : strict-proto  : ubik_Call
260 kauth/authclient.c   : strict-proto  : ubik_Call nonsense
261 libadmin/kas/afs_kasAdmin.c: strict-proto : ubik_Call nonsense
262 libadmin/samples/rxstat_query_peer.c : all : util_RPCStatsStateGet types
263 libadmin/samples/rxstat_query_process.c : all : util_RPCStatsStateGet types
264 libadmin/test/client.c : all         : util_RPCStatsStateGet types
265 ubik/ubikclient.c    : strict-protos : ubik_Call
266 volser/vol-dump.c    : format        : afs_sfsize_t
267