CHARA Technical Report - The CHARA Array of Georgia State
Contents
1. FAX 404 651 1389 Email theo chara gsu edu WWW http www chara gsu edu C This source code and its associated executable program s are copyright TR 70 15 TECHNICAL REPORT NO 70 DORR OOK OBI RIKI x kK aK Author Fill this in Date This too DORR OOK OBI RIKI x kK aK include files external function declarations defines globals Code C FUNCTION HEADER TEMPLATE The following is a template for function headers All functions must be preceded by this header Do OO OK OR OR OK KOK KK KOK aK a KK function_name Place a description of the function here This description text is the text that the em mkman utility will extract and use as the body of the manual page created for this function Therefore the better you make this description the less work you will need to do later when you are doing the documentation DRACO OOO EEE EEEE E E EEEE E OO EE E E EE E E E E E E E E E E E E E E E E E ak ak kkk D EXAMPLE SOURCE FILE DRACO OOO EEE EEEE E E EEEE E OO EE E E EE E E E E E E E E E E E E E E E E E ak ak kkk example c This is an example resource file to demonstrate coding style It does not necessarily compile but it looks nice Functions included in this file are struct smenu initialise_menu_structu2. 18 CODING PRACTICES the list auto help end quit passthree structure_file Close the menu structure file fclose structure_file Return a pointer to the main menu return mainmenu initialise_menu_structure DRACO OR OO EE EEEE EEEE E EE EEE E OOO OR E E E E E E E E E E E kk kk E E kak ak getline Reads a line from a given stream as text Leading white space is ignored A line that begins with the character is considered a comment and is ignored The new line character at the end of the string if present is replaced by a NULL Getline returns a pointer to the string or EOF if the end of the file has been reached Getline will read up to n 1 characters and then terminate DRACO OR OO EE EEEE EEEE E EE EEE E OOO OR E E E E E E E E E E E kk kk E E kak ak char getline char string Buffer for placing string int n Number of characters in buffer FILE stream Stream to get data Internal variables int c First character of string char retval Return value of function Set return value to string beginning retval string Loop until line does not start with do Skip leading white space while TR 70 19 TECHNICAL REPORT NO 70 c getc stream c t e r c n if c E
3. avoid inconsistencies Further it should ease the problems of other programmers taking over management of some area of software development 3 1 Directory Structure The software development will consist of several projects and each project should be broken into logical modules Each module should have its own directory and possibly subdirectories for large modules As detailed below each directory will have its own Makefile and CVS subdirectory Within each module directory there should be the c files and A files for that module For the project there should possibly be a directory containing project wide header files call this include and a directory containing project wide archive libraries call this lib see ar below There may well also be CHARA wide include and lib directories These lib and include directories should also be under the control of CVS and make Finally there should be a project Makefile in the project directory to assemble the whole thing The project should also have a documentation directory which can also be under the control of CVS if desired though it should be remembered that release versions of the documentation will be stored in the central file as hard copy and be placed online The total directory structure should thus look something like 3 And will soon be available as a TR TR 70 2 CODING PRACTICES chara array project1 Makefile modulel _ filel c filen c header h Ma
4. by using the cvs update command if you are inside the directory containing the code or the cvs commit command from the root directory of the code Code should be committed at least once per day Naturally it is not a good idea to commit code that doesn t actually work When code is checked back into the repository it is given a new version number and com pared to the existing code It is possible for many people to be modifying the same program and CVS is smart enough to blend all of the changes together It will fortunately warn you of any conflicting changes Many other cvs commands exist and it is highly recommended that you read the CVS man page 3 3 make make 1 is a utility that allows you to control more easily the compilation of complicated programs from several source files The information required to do the compilation is stored in a file called Makefile in the working directory make when invoked will do the minimum amount of compilation necessary to produce the program thus saving time for large program suites while ensuring that the most recent versions of files are used TR 70 4 CODING PRACTICES To make the most use of make you should divide your program into several source code files This is good programming practice in any case and will mean that when you are working on one part of the code you do not need to recompile all the other parts that already work Try to divide your program up into logical gr
5. especially with long function calls or algebraic statements Consider the following example printf The results are rather long and are as follows 4d 4d 4d argum enti argument2 argument3 WRONG printf The results are rather long and are as follows 4d 4d fd argumenti argument2 argument3 RIGHT printf The results are rather long and are as follows fd fd fd argumenti argument2 argument3 ALTERNATIVE Note that the commas appeared at the end of the lines and not the beginning An analogous system can be used for long algebraic statements Place operators at the end of lines and not beginnings Use indentation and brackets for clarity e Beware of the useful but dangerous and operators For example the statement ali i will produce unpredictable results and will depend on the compiler used e Try and use the following format for switch statements TR 70 6 CODING PRACTICES switch c getch case a do_this Action for case a break case b do_that Action for case b break case c do_such Action for case c break default panic Default action break end switch It is important that every switch contains a default case at the end if only for the sake of error trapping You will also note that each case is ended with a break It is dangerous to rely on fall through in switch statements Closing c
6. these coding practices You should of course use a bit of common sense and ignore any directives that will make your code hard to read Any deviation from these rules however should be fully documented Any further questions can be asked of TtB TR 70 11 TECHNICAL REPORT NO 70 A MAKEFILE TEMPLATE This is a template Makefile for use in a module directory that may create archive libraries and test programs AE HE FE HE HE FE HE HE FE HE HE FE HE HE FE HE HE FE HE HE HE FE HE FE FE ERE FE FE REESE HE HE FE HE HE HE FE HE HE FE HE HE FHE R ERE REE RR HE HE HE HE HE HHHH HE Makefile Example Makefile for library directories AE HE FE HE HE FE HE HE FE HE HE FE HE HE FE HE HE FE HE HE HE FE HE FE FE E FE FE E FE FE FE FE FE HE E FE HE HE FE HE HE HE FE HE HE FE HE HE FHE HE HE HE HE HE HE HE HE HE HE HE FE HE TE HE HE HE HE HE HHHH HE Center for High Angular Resolution Astronomy Georgia State University Atlanta GA 30303 3083 U S A Telephone 1 404 651 1882 Fax 1 404 651 1389 email theo chara gsu edu WWW http www chara gsu edu theo html C This source code and its associated executable program s are copyright FE TE TE HE HE TE TE TE TE TE TE TE TE TE TE TE TE TE TE TE RRR TE TE TE HE HE HE HE HE HE HE HE RRR RRR HE HE HE HE HE HE aH HH HARE HE EERE RRR HE HE RRR HE HE RES Author Theo ten Brummelaar Date 25th July 1996 FE HE AE F
7. 4 INCDIR LIBNAME h Rule for uninstalling uninstall clean rm f LIBDIR 1lib LIBNAME a rm f INCDIR LIBNAME h A Makefile for a project directory would be similar but without the library build Below is a template Makefile to reside in the project directory and recursively make all the modules libs and includes under it AE HE FE HE HE FE HE HE FE HE HE FE HE HE FE HE HE FE HE HE HE FE HE FE FE ERE FE FE REESE HE HE FE HE HE HE FE HE HE FE HE HE FHE R ERE REE RR HE HE HE HE HE HHHH HE Makefile Master makefile for libraries Based on a Makefile by AJB Sept 89 booth physics su edu au FE HE TE TE HE TE TE TE TE TE TE TE TE TE TE TE TE TE TE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE FE HE HE HE HE HE HE FE FE TE TE TE TE TE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE HE TE TE TE TE HE HEHE HE Center for High Angular Resolution Astronomy Georgia State University Atlanta GA 30303 3083 U S A Telephone 1 404 651 1882 Fax 1 404 651 1389 email theo chara gsu edu WWW http www chara gsu edu theo html C This source code and its associated executable program s are copyright FE TE TE HE HE TE TE TE TE TE TE TE TE TE TE TE TE TE TE TE RRR TE TE TE HE HE HE HE HE HE HE HE RRR RRR HE HE HE HE HE HE aH HH HARE HE EERE RRR HE HE RRR HE HE RES Author Theo ten Brummelaar Date 6 25 96 FE HE HE E HE FE FE HE HE HE HE FE F
8. CHARA TECHNICAL REPORT No 70 14 JULY 1998 Coding Practices for the CHARA Array THEO TEN BRUMMELAAR SUSI CHARA AND ANDREW Boots SUSI ABSTRACT This document slightly adapted from the manual Coding Practices for SUSI by Theo ten Brummelaar and Andrew Booth describes a standard approach for software development and layout All code written for the CHARA Array should adhere to the rules set out herein 1 INTRODUCTION This document outlines a standard for coding practices to be followed when writing software We wish to adopt this standard in order to fulfill the following objectives e to assist in the process of structured analysis and design e to assist in the debugging and maintenance of programs to assist in future updates of programs to develop and maintain run time libraries that all coders have access to to facilitate the movement of code between different programmers to assist in the development of automatic methods of hardcopy documentation and manual writing It is therefore expected that anyone writing code for the Array will accept the following standard as the definitive guide and supply code and associated documentation accordingly 2 SOURCE CODE LANGUAGE All programs in the CHARA Array software set are to be written in ANSI C or Bourne shell scripting language sh although bash will also be acceptable Proper prototyping of all functions is to be maintained Always compile code using the gcc c
9. E FE HE HE HE FE FE FE SERRE FE HE HE FE RRR HE HE FE FE E RR RSH HE HE FE FE HE HE RRR SERRE RRR HE E HE HE HE HH HE HE HE HE fill in your bits for SUBDIRS SUBDIRS module1 module2 module3 You should not have to change anything else TARGETS all clean install uninstall TR 70 14 CODING PRACTICES TARGETS should match makefile targets in all the SUBDIRS A missing target in a subdir will cause a fatal error which will be ignored KEEP_STATE TARGETS MAKE SUBDIRS TARGET SUBDIRS FORCE cd MAKE TARGET FORCE thus make all here runs make all in all the SUBDIRS subdirectories Obviously this can be recursive so running copies of itself in lower and lower subdirectories B MODULE HEADER TEMPLATE Template header for a C source file All modules are to contain this header DRACO OR OO EE EEEE EEEE E EE OO OOO OR I E E E I kk kk kx kak ak filename c Description Try and make this a valuable description including a list of the functions within this file Descriptions like This file contains the code for the filename program waists everyones time including your own Do OR OO OR OK KK ooo ooo okk Project_name The CHARA Array Center for High Angular Resolution Astronomy Georgia State University Atlanta GA 30303 3083 USA VOX 404 651 2932
10. E HE HE HE HE HE FE HE HE FE HE HE FE HE HE FE HE HE FE HE E FE FE HE FE HE HE FE HE HE FE HE HE FE HE HE FE HE FE HE HE FE HE HE HE HE HE FE E TE FE HE FE FE HE FE HE HE FE HE FE HE HE HE HE HE HEHE HE If you are going to change something it ll probably be here CC gcc CFLAGS g 0 Wall LFLAGS lc lm LIBDIR usr local lib INCDIR usr local include LIBNAME example Add any new targets here OFILES file1 o file2 o file3 o file4 o Rule for compiling and adding a unit to the library TR 70 12 CODING PRACTICES c o CC C CFLAGS c lt ar r lib LIBNAME a mkman LIBNAME lt Master target all lib LIBNAME a testprogram All routines depend on the header file OFILES LIBNAME h test routine testprogram lib LIBNAME a testprogram o CC CFLAGS o testprogram testprogram o lib LIBNAME a LFLAGS testprogram LIBNAME h Master rule for creating the library lib LIBNAME a OFILES ranlib lib LIBNAME a ranlib lib LIBNAME a Rule for cleaning up the directory clean rm f OFILES core lib LIBNAME a testprogram rm rf man Rule for installation install lib LIBNAME a LIBNAME h cp lib LIBNAME a LIBDIR 1ib LIBNAME a cp LIBNAME h CINCDIR LIBNAME h TR 70 13 TECHNICAL REPORT NO 70 ranlib LIBDIR 1ib LIBNAME a chmod 644 LIBDIR 1lib LIBNAME a chmod 64
11. OF return char EOF Put the first character into the string string c Read in the rest of the string if fgets string n 1 stream NULL return char EOF while c Replace new line character with NULL while string NULL if string n string NULL stringt Return pointer to the string return retval getline E EXAMPLE UNIX MANUAL PAGE FILE The mkman utility will create basic man pages although you will probably want to edit them before you release them The following is an example of a manual page It can be formatted using the command nroff man filename The next page contains the input file and the following page shows what nroff man will produce Note that the output of nroffis not suitable for printing To produce a postscript file use the command groff man filename which will send the postscript version of the manual page to standard output TR 70 20 CODING PRACTICES TH ENBLE_INTRPT 3 AV68K Programmer s Manual SH NAME enble_intrpt Enable interrupts SH SYNOPSIS include lt bios h gt br void enble_intprt int level oH DESCRIPTION I Enble_intrpt sets the current interrupt level to the value level Note that this means the computer will respond to interrupts of levels higher than that set Thus setting the level to 7 will turn off all interrupts This could be dangerous as it may
12. kefile CVS modulen filel c filen c header h Makefile CVS include header1 h headern h Makefile CVS libl a libn a Makefile CVS document tex CVs other project directories include header1 h headern h Makefile CVS libl a libn a CVS Makefile TR 70 3 TECHNICAL REPORT NO 70 3 2 CVS CVS stands for Concurrent Versions System and is a method of ensuring that modifications to programs are performed in a consistent way and that conflicts do not arise when more than one person is working on the same piece of software In addition it provides an easy way of retrieving previous versions of software if subsequent modifications are found to be wrong CVS works by keeping a central repository of the entire software tree used in the sys tem This is kept in a single directory chara chara cvusroot To reach this directory each programmer needs to have an environment variable pointing to it as follows for cesh setenv CVSROOT chara chara cvsroot which needs to be added to your login file Software trees are entered into the repository using the command cvs import Name CHARA Programmer where name is the name of the module Each programmer can then create his her own personal copy of the source code they are working on by issuing the command cvs checkout module_name where module_name is the name of the module they wish to work on Periodically this code can be sent back into the repository
13. le command line 3 4 ar Once you have a set of working functions that either you or others will want to use as modules in other programs you should compile them and store the compiled versions in a library archive using ar 1 Library archives should be given names starting with lib and ending in the suffix a For example to create an archive called fred containing the compiled files f1 0 2 0 use ar rev libfred a fl o f2 0 ranlib libfred a To use that library assumed stored in a directory usr local lib at load time for a program compilation use for example gcc o prog progi c prog2 o lfred TR 70 5 TECHNICAL REPORT NO 70 4 GENERAL LAYOUT AND STYLE Although the detailed layout of the program is of course up to you a number of general rules apply to standardize code for the project Appendix D contains an example of a source file that adheres to these rules Please keep the following in mind when writing code for the project e No source file should be more than about 10 pages long e Functions should not be more than about 40 lines long unless you get carried away with your commenting This is not always possible but remeber that long functions are difficult for others to read and properly comprehend e The standard tab stop is 8 characters although other tab stops will be allowed The import thing is to be consistent e Lines must not wrap beyond 80 characters This can cause some problems
14. ommand and it is strongly recommended that the Wall flag always be used Source code should produced no errors and few warnings when using this flag All code will make use of the standard libraries Center for High Angular Resolution Astronomy Georgia State University Atlanta GA 30303 3083 TEL 404 651 2932 FAX 404 651 1389 FTP ftp chara gsu edu WWW http www chara gsu edu with some SUSI CHARA translation by Bill Hartkopf TR 70 1 TECHNICAL REPORT NO 70 e charaui User interface e nrc numerical recipes in C e simpleX X interface e rwfits FITS file read write routines Other standard libraries will be added over time Man pages for all these libraries are available online Assembly code is to be avoided at all costs unless no alternative is available C is allowed for the object oriented fans but it is not recommended for use in device controllers due to the expensive overhead Furthermore many of us are yet to become familiar with C let alone C so it is best to stick with C 3 DEVELOPMENT ENVIRONMENT Development will be carried out under control of the UNIX software development tools CVS 1 and make 1 For detailed and well written descriptions of CVS facilities re fer to Version Management with CVS Per Cederqvist et al Use of these facilities will ensure that different parts of the software development can proceed in a consistent way and shared software can be easily controlled to
15. oups of functions and do not let any one file become more than about 10 pages long As a simple example of how make works and the structure of a Makefile consider a program called prog to be made from 3 source files f1 c f2 c f3 c and compiled with the standard C maths library Then make would call prog the target prog would have f1 0 2 0 and 3 0 note the o not c as dependencies and there would be a command line to compile the lot of the form em gcc o prog f1 c f2 c 3 c 1m A Makefile of the form prog fl o f2 0 f3 0 gcc o prog fl o f2 0 f3 0 lm when invoked with the command make prog will do everything required to produce prog Note the space in front of gec is a tab this is a requirement to introduce a command line Notice that you don t have to tell make to produce the o files from the c files it is intelligent enough to do this itself A slightly more sophisticated use of make makes control of larger projects more convenient and a template Makefile with comments is available see Appendix A This includes some useful extra targets such as clean and all For example make clean removes all old o files and executable files make can also control the production of archives see below of compiled functions to be included in later compilations including placing the archive library in the correct directory so that others can use it It is important to realize that any UNIX command can be put on a Makefi
16. re void char getline char string int n FILE stream TR 70 16 CODING PRACTICES DRACO OR OO EE EEEE EEEE E EE OO OOO OR I E E E I kk kk kx kak ak USER INTERFACE ROUTINES The CHARA Array Center for High Angular Resolution Astronomy Georgia State University Atlanta GA 30303 3083 USA VOX 404 651 2932 FAX 404 651 1389 Email theo chara gsu edu WWW http www chara gsu edu C This source code and its associated executable program s are copyright DOORS OOS SOOO OR SOR SS SG IG I KK KK Author Tedy the Wonder Lizard Date 29 Feb 2000 DRACO ORO EEEE EE EEEE E EEEE E E OOO OO E E E E KO E E EE E E E kk ak ak ak fk include files include lt stdio h gt include lt malloc h gt include lt string h gt include lt charaui h gt DRACO ORO EEEE EE EEEE E EEEE E E OOO E E EE E E E E E E E E E EE E E E E E ak ak E E E initialise_menu_structure This is the controlling function of the menu structure initialization See imbedded comments for a description of exactly what it does It returns a pointer to the main menu DRACO ORO EEEE EE EEEE E EEEE E E OOO E E EE E E E E E E E E E EE E E E E E ak ak E E E struct smenu initialise_menu_structure void Internal variables FILE structure_file Pointer to structure
17. s char brand 81 rest of structure definitions MENU MENU menus 10 preferred method struct tagMENU menus 10 another way of doing it DOCUMENTATION All programs should be fully documented The user manual for a program should be placed in a central file and allocated a document number They should also start with an abstract that describes the program s purpose Programmer manuals should conform to the standard UNIX manual page layout This is done using the Troff 1 man set of macros You will find an example of such a file in Appendix E The utility mkman will read a source file and create basic man pages for all functions in that file mkman will only work if you have followed the commenting practices outlined above but can save a lot of time when generating code documentation The Makefile should normally invoke mkman automatically during compile time TR 70 10 CODING PRACTICES 8 PORTABILITY You should aim to write portable code wherever possible It is also important not to rely on machine implementations of types It is a good idea to use typedefs for any variable that requires a particular internal representation While we plan on using Linux 2 0 33 as the basic development environment this may change Avoid using any functions not more generally available 9 CONCLUSION In order to maintain standards within the project it is vital that all staff members are familiar with and adhere to
18. stop the UART interrupt server at level 6 Thus the only values you should use are 0 1 2 3 4 or 5 This routine is almost always called after I set_up_intrpt SH RETURN VALUE Void oH SOURCE FILE cbhios as oH SEE ALSO set_up_intrpt oH AUTHOR Theo ten Brummelaar TR 70 21 TECHNICAL REPORT NO 70 NAME enble_intrpt Enable interrupts SYNOPSIS include lt bios h gt void enble_intprt int level DESCRIPTION Enbleintrpt sets the current interrupt level to the value level Note that this means the computer will respond to interrupts of levels higher than that set Thus setting the level to 7 will turn off all interrupts This could be dangerous as it may stop the UART interrupt server at level 6 Thus the only values you should use are 0 1 2 3 4 or 5 This routine is almost always called after setupintrpt RETURN VALUE Void SOURCE FILE cbhios as SEE ALSO setupintrpt AUTHOR Theo ten Brummelaar TR 70 22
19. text file struct smenu mainmenu Pointer to main menu returned char errorstr 81 Error message string Initialise ptcome and ptgoto to zero ptcome 0 TR 70 17 TECHNICAL REPORT NO 70 ptgoto 0 Open menu structure file for reading if structure_file fopen STRUCTFILE r NULL sprintf errorstr Can not open menu structure file fs STRUCTFILE 3 fti_error 3 errorstr First pass Find menu names and count them Check that nummenus lt MAXMENU Allocate memory space for their structure Place menu names into their structure Fill rest of structure with NULLs Set menus nummenus to NULL Rewind the menu structure file passone structure_file First check Ensure there is exactly one main menu Ensure all menu names are unique Ensure no menu names are the same as a function name Return a pointer to the main menu mainmenu checkone Second pass Read in menu data and place it in menu structures Ensure all menu references exist Ensure no menus are self referential Rewind the menu structure file passtwo structure_file Third pass Read in auto list data and fill in array autolist Check that the number of functions is lt MAXAUTO Ensure all function references exist Place NULL at end of list Ensure that the following functions are not in TR 70
20. ully commented This means that anyone should be able to read and understand your code without having to go and ask you what it is all about The following rules apply to commenting code e Each source file will begin with a standard module header which can be treated as a fill in the blanks system This is to ensure that no particular sections of header code are overlooked An example of a module header can be found in Appendix B Every function will be preceded by a standard function header An example of such a function header can be found in Appendix C Comment openers are only to appear in column 1 to designate module function head ers or to divide sections such as include files or defines line up with the code that they apply to All other comments should Each variable declaration or definition will be immediately followed by a comment describing the use of the variable TR 70 8 6 CODING PRACTICES The function name is to be repeated as a comment after the final closing brace of the function For very long switch statements or loops it is also a good idea to place a comment at the end such as end switch for clarity Multiline comments will be in the following form this is the first line of a multiline comment this is the second line of a multiline comment this is the third line of a multiline comment VARIABLE USE AND NAMING CONVENTIONS It is important that function and
21. urly braces should always be placed on lines by themselves and match the column of the statement they refer to for example for i 0 i lt 10 i do_this if the_pope_is_polish do_that and_do_something_else end loop It is also all right to place the opening curly brace on the same line as the opening statement for example for i 0 i lt 10 i do_this if the_pope_is_polish do_that and_do_something_else end loop although I have found that this is not as clear even if it does take up less space Also consider TR 70 7 TECHNICAL REPORT NO 70 if c 1 do_this do_that else if c 2 do_such do_thus else do_so end if However for short statements it is allowable to put two statements on one line for example if c 2 do_something The only braces to appear in column one are for beginning and ending functions or for structure definitions Note that these structure definitions must be at the top of the block in which they appear Where possible always leave spaces before and after operators and if it will make things clearer use more brackets than are strictly necessary Try to avoid using globals If you must it is a good idea to put them all in a single structure and declare it as a static so no conflicts can arise with other source files COMMENTING All programs are to be f
22. variable names reflect the use and purpose of the variable or function Short or cryptic names will only confuse and force you to use more comments Please keep in mind the following rules Don t shy away from long names if you think it will make your code clearer Most compilers will recognize up to 30 characters as unique in variable names For example int geab not suitable int goeatabrick better int go_eat_a_brick preferred int EatBrick alternative for pascal lovers Prototype parameters formal parameters and actual parameters should have the same name whenever possible For example char my_function char string Prototype parameter string my_function string actual parameter string TR 70 9 TECHNICAL REPORT NO 70 char my_function char string formal parameter string Function body my_function Function and variable names should in general be in lower case Capitalize all defines except function macros Capitalize all type definitions Unless otherwise specified physical quantities are to be expressed in SI units with all angles in radians All matrix and vector mathematics is to follow the Numerical Recipes in C format The entire NRC library is available globally To use it use the include file nre h and the link command lnre Use the following format for structure definitions typedef struct tagMENU int number_of_wheel
Download Pdf Manuals
Related Search