From: Michael Meffie Date: Mon, 31 Mar 2014 17:06:03 +0000 (-0400) Subject: readme: rename README.DEVEL to CODING X-Git-Tag: upstream/1.8.0_pre1^2~693 X-Git-Url: https://git.michaelhowe.org/gitweb/?a=commitdiff_plain;h=04c7ed855ef78e1d1a15821ffff5fe0f26b9d0c4;p=packages%2Fo%2Fopenafs.git readme: rename README.DEVEL to CODING Rename the developer's readme file to CODING as a home for developer related information. Change-Id: I8c2cf70258671387b926ef3d666f6476056ef06e Reviewed-on: http://gerrit.openafs.org/10973 Reviewed-by: Chas Williams - CONTRACTOR Tested-by: BuildBot Reviewed-by: D Brashear --- diff --git a/CODING b/CODING new file mode 100644 index 000000000..7ad817078 --- /dev/null +++ b/CODING @@ -0,0 +1,105 @@ +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 $< for non-pattern rules in any cross-platform dir as it +requires a reasonable make that is not available on all systems. + +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 +in 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.) + + +Dependencies required to build OpenAFS from source +-------------------------------------------------- +The following packages are required to build all of the OpenAFS code +from source on various operating systems: + +On Debian: +- autoconf, automake, bison, comerr-dev, cpio, flex, libkrb5-dev, + libncurses5-dev, libpam0g-dev, libxml2-utils, perl, pkg-config; +- libfuse-dev (for the FUSE-based user-mode client); +- dblatex, docbook-xsl, doxygen, xsltproc (for documentation); +- debhelper, hardening-wrapper, dkms (to build the Debian packages) + +On FreeBSD: +- autoconf, automake, libtool; +- fusefs-libs, pkgconf (for the FUSE-based user-mode client); +- perl, dblatex, docbook-xsl, libxslt, python, ruby, zip (for documentation) + +In addition, FreeBSD systems require kernel sources and a configured kernel +build directory (see section "FreeBSD Notes" in the README file). diff --git a/README.DEVEL b/README.DEVEL deleted file mode 100644 index 7ad817078..000000000 --- a/README.DEVEL +++ /dev/null @@ -1,105 +0,0 @@ -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 $< for non-pattern rules in any cross-platform dir as it -requires a reasonable make that is not available on all systems. - -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 -in 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.) - - -Dependencies required to build OpenAFS from source --------------------------------------------------- -The following packages are required to build all of the OpenAFS code -from source on various operating systems: - -On Debian: -- autoconf, automake, bison, comerr-dev, cpio, flex, libkrb5-dev, - libncurses5-dev, libpam0g-dev, libxml2-utils, perl, pkg-config; -- libfuse-dev (for the FUSE-based user-mode client); -- dblatex, docbook-xsl, doxygen, xsltproc (for documentation); -- debhelper, hardening-wrapper, dkms (to build the Debian packages) - -On FreeBSD: -- autoconf, automake, libtool; -- fusefs-libs, pkgconf (for the FUSE-based user-mode client); -- perl, dblatex, docbook-xsl, libxslt, python, ruby, zip (for documentation) - -In addition, FreeBSD systems require kernel sources and a configured kernel -build directory (see section "FreeBSD Notes" in the README file).