X-Git-Url: http://git.openafs.org/?p=openafs.git;a=blobdiff_plain;f=README.DEVEL;h=3c3d2b9704d2efe162705974304d87a4a63945fd;hp=cfe27c78a7b0ae345af5e0686e47efde627b4f8b;hb=85f1ef34c2533da2f47757bb8d8a3aecb9083283;hpb=9e0300cd9735d578d084df60616ec7ec6efba8db

diff --git a/README.DEVEL b/README.DEVEL
index cfe27c7..3c3d2b9 100644
--- a/README.DEVEL
+++ b/README.DEVEL
@@ -1,9 +1,83 @@
 Notes on Coding Standards/Requirements for OpenAFS Source
 ---------------------------------------------------------
 
+We have an official style.  Please use it.  If you have gnu indent 2.2.9 or
+later you can reformat for this style with the following option:
+
+-npro -nbad -bap -nbc -bbo -br -ce -cdw -brs -ncdb -cp1 -ncs -di2 -ndj -nfc1
+-nfca -i4 -lp -npcs -nprs -psl -sc -nsob -ts8
+
 Do not use $< in any cross-platform dir as it requires a reasonable
 make that is not available on all systems.
 
-Be careful with prototypes/ANSI-C in code that will be compiled for
-kernel source.  In general, avoid them until we have figured out
-exactly when/where they can be used safely.
+Do not have build rules that build multiple targets. Make doesn't seem able
+to handle this, and it interferes with -j builds. (In particular, build the
+rxgen targets individually and not using the flags for building all the files
+in one shot.)
+
+Try to test builds using gmake -j # MAKE="gmake -j #", it seems like a good
+way to find missing or order-dependent dependency rules. (Is there a better
+way to do this?)
+
+-- Prototyping and Style --
+Prototypes for all source files in a given dir DDD should be placed
+int the file DDD/DDD_prototypes.h. All externally used (either API
+or used by other source files) routines and variables should be
+prototyped in this file.
+
+The prototypes should be a full prototype, with argument and return
+types. (Should not generate a warning with gcc -Wstrict-prototypes.)
+
+Format of the prototype files should look like:
+
+	Standard Copyright Notice
+
+	#ifndef AFS_SRC_DDD_PROTO_H
+	#define AFS_SRC_DDD_PROTO_H
+	
+	/* filename.c */
+	prototypes
+
+	/* filename.c */
+	prototypes
+
+	#endif /* AFS_SRC_DDD_PROTO_H */
+
+In most of the existing prototypes, the define is DDD_PROTOTYPES_H, which is
+probably ok as well.
+
+The declaration of the routines should be done in ANSI style. If at some
+later date, it is determined that prototypes don't work on some platform 
+properly, we can use ansi2knr during the compile.
+
+	rettype routine(argtype arg)
+	{
+
+	}
+
+All routines should have a return type specified, void if nothing returned,
+and should have (void) if no arguments are taken.
+
+Header files should not contain macros or other definitions unless they
+are used across multiple source files.
+
+All routines should be declared static if they are not used outside that 
+source file.
+
+Compiles on gcc-using machines should strive to handle using
+-Wstrict-prototypes -Werror. (this may take a while)
+
+Routines shall be defined in source prior to use if possible, and 
+prototyped in block at top of file if static.
+
+API documentation in the code should be done using Qt-style Doxygen
+comments.
+
+If you make a routine or variable static, be sure and remove it from
+the AIX .exp files.
+
+Suggested compiler flags:
+	gcc: -Wall -Wstrict-prototypes
+	Solaris Workshop CC: -fd -v
+		(You might not want the -fd, it isn't really useful, just complains about the
+		K&R style functions, but -v gives useful info.)