Aa 92d&HH $ dR     doFootnote TableFootnote**. . / -  ]2 ] !"LOT TableTitle!"LOFFigure6TOC!1Heading2Heading3Heading # Umen  V rie W He ca Xymb Ti Y- egu Z egu [   \egu  ]ue tal ^  _     G          +32813: 1Heading: 5 Configuration Management ,72045: 2Heading: 4.2 Machine-Dependent Files 281667: Appendix Head: Appendix I Makefile Examples K79404: Appendix Head: Appendix II Proposal for a C-language coding standardM U e ` 3 U  V Aa W  X d Y  Z  [  \  ]  ^  _  +32813: 1Heading: 5 Configuration Management ,72045: 2Heading: 4.2 Machine-Dependent Fileso e 281667: Appendix Head: Appendix I Makefile Examples K79404: Appendix Head: Appendix II Proposal for a C-language coding standardlLO <$marker1>TO <$marker2>ea <$paratext[Title]>  <$paratext[1Heading]> <$curpagenum> X<$lastpagenum><$monthname> <$daynum>, <$year>\ (Continued)+ (Sheet <$tblsheetnum> of <$tblsheetcount>)Pagepage<$pagenum>Heading & Page <$paratext> on page<$pagenum>Section & Page<$paranumonly>See Heading & Page%See <$paratext> on page<$pagenum>.i Table & Page'Table<$paranumonly> on page<$pagenum>x Figure & Pages(Figure<$paranumonly> on page<$pagenum>I Headinga<$paranumonly>ngSectioneSection<$paranumonly> !  ``A bb ee ff2A: hhngu kkn mnA2 pp4 M sstil TOC281 eLOFppe  LOTles IX YeA    rop a Cag ingar LO  er ma >ea ate > $pa ead  pag   (tpa  )thn 9ynu (r>\ *(Co 9 +et 9tnu ,bls ->) 0 1age 2m> Tdin ^ < .> /$pa 3 4 & 5ara 6 7din 8%Se tex1ge Yenu I Ta e'2ara ly>3<$p m>x4ure ges5<$p mon p $paI He anung Se onnu >   `  b '3.1.1 %f23.1h  gu %k3.3  n %3.2  s    $ %e4.1 $  $ $  A  $ %ag4.2ar $   =er =maea =te = =$pa = $ $ %(5.1 %)5.3ynu  (  * $9 <+ $9 %,5.2>)  0 <1 $2 $T $^ $. /  $ & $ara $ $din >%Se Mtex Appendix Iu >I > >2 >ly> ><$p > > >5 >mon > >I > >anu > > > >> > > > >b >' > > > >h > > > > > > > > > > > > > > > !> "> #> $> %> &>ar '> (> )> *>ma +>= ,>te -> .>$pa />= 0> 1> 2> 3> 4> 5> 6>ynu 7> 8> 9> :> ;> <> =>>) >M Appendix II ?>$ @>$ A>$ B> C> D%4.3$ E> F> G> H> I> J>dix K>I L> M>2 N>ly> O><$p P> Q> R>5 S>mon T> U>I V> W>anu X> Y> Z> [>> \> ]> ^> _>b `>' a> b> c> d>h e> f> g> h> i> j> k> l> m> n> o> p> q> r> s> t> u> v> w> x> y>ar z> {> |> }>ma ~>= >te > >$pa >= > > > > > > >ynu > > > > > > >>) > >ppe >?> >@> >A> >B> >C> >D% > >E> >F> >G> >H> >I> >J> >K> >L> >M> >N> >O> >P> >Q> >R> >S> >T> >U> >V> >W> >X> >Y> >Z> >[> >\> >]> >^> >_> >`> >a> >b> >c> >d> >e> >f> >g> >h> >i> >j> >k> >l> >m> >n> >o> >p> >q> >r> >s> >t> >u> >v> >w> >x> >y> >z> >{> >|> >}> >~> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >> >>  > $>AZLdA>`e>dB>fk>dC>DD>6h\V0DC >6h\V0F  >UU n>Uage and Distribution System, and Analysis System). The degree of support for other >UU n>[operating systems is simply a reflection of the extent of use of the SOI software on those >UU@ nLsystems: an attempt is made to use standards consistent with blah blah blah >B` u>Hardware Architectures >ZUU n>[As with operating systems, several architectures are supported to various extents, meaning >fUU@ n*weve tried out something or may someday: xUU` n>DECqn MIPSqn UU` nDECqn Alphaqn >UU` nDECqn VAXq UU` n>"Silicon Graphicsqn X (IP7) UU` n#Silicon Graphicsqn Y (IP20) >êUU` n#Silicon Graphicsqn Z (IP22) >ҪUU` n&Sunqn SPARCqn 2 (sun4c) ᪞UU` n'Sunqn SPARCqn 10 (sun4m) UU` nNeXTqn ` uDiLanguages and Standards ly6UU` vegProgramming Languages FUU n XAll programs to date have been written in C, with reasonable attempts made to be compat tRUU nUU[ible with the ANSI standard, whatever it is. It is our stated goal to support and use ANSI ^UU nwaOC++. We may support some version of FORTRAN, presumably FORTRAN-77, if we have itejUU@ nedto. ri` wngC-Language Coding Standards e UU ng YA proposal for uniform coding standards, with the aims of enhancing readability and ease EUU nqdof maintenance, is given in Appendix n II . It is only a proposal. If coding standards are (IUU@ n Padopted, they replace it. If not, this section is deleted from future editions. ĪUU` v>Software Tools nԪUU` nRCOracle. 2 쪒UU` nUU+Parallel Virtual Machine (PVM 3.xn) 4m)UU` n TAE. e"UU` vData Representations 2UU nWWe support things like IEEE internal representation for floating-point numbers and the een>UU@ nh )FITS and CDF standards for data formats. dESIFF iHh\V0FE t Hh\V0GGDI  W#su` u oFile Names and Paths OUU nvemA system virtual user soin is assumed, with a home directory ~soin, as the root of all paths p+UU@ nod@to files containing SOI software, data, and miscellaneous junk. CUU nofvSOI software exists in up to three concurrent versions, qan, qbn, and qgn, all residing in parallel OUU nplkdirectory trees under ~soin. The subdirectories are named (respectively) ~soi/newn, ~soi/[UU lenbetan, and ~soi/what?n. The release philosophy is discussed under n Section5 . Under each gUU nrefrelease directory there are parallel trees, referred to as ~soi/(version)n . Both machine-indesUU nenYpendent files (source code, data, and documentation) and machine-dependent files (executUU@ nF[able images and libraries, and compilation instructions) are contained within these trees. UU` v Machine-Independent Files UU nvegThere are 3 release subdirectories containing machine-independent files: includen, mann, patUU n cand srcn. The contents of these directories are more fully described in Programming in the twaŪUU@ n t*SOI Analysis Environment, SOI TN 93-106. ݪUU` n aTThe includen directory contains (surprise!) include files and not much else. suUU namkThe mann directory contains 3 subdirectories, man1n for command-level programs, man3n eleUU ndipfor library functions, and psn containing PostScriptqn images of the mann pages for people reUE UTUU nsolwho forget the simple sequence for printing a formatted roffn page . To reference the mann aUDUU nnt^pages online one must use a system-dependent command (different Unixqn systems love to (UCUU@ nn galter the switches and behaviour of mann for some reason): under Ultrixqn the command is su:UBUU` nin#man -P ~soi/(version)/man name cluRUAUU n,dTo use the default mann command the contents of the mann directory in the appropriate in^U@UU nheqrelease level (qbn?) should be linked into /usr/local/mann, which is in turn a link to /usr/man/tjU?UU@ rihmanln (not man1n!) Note that the extensions of the links have to be changed from 1 or 3 to l. ctU>UU n dNot surprisingly the srcn directories contain source code. Despite the name of this section,  U=UU nipTeach source directory contains one or more subdirectories for machine-dependent cometU<UU nce[piled code used in supporting mutiple architectures. In general though, these sub-subdirec U;UU n oVtories only contain 0-length markers indicating times of compilation for the relevant U:UU nr Qmachine. They follow the same naming scheme as the subdirectories of the machine-hU9UU@ nUB!dependent files: _XXX.bn. iU8UU nluaThe srcn directories should also contain, but do not yet (except for libsds.d way to go oU7UU@ natXKatie!), small data sets used specifically in the testing and verification of software. maU6UUh v t Machine-Dependent Files U?U5UU nmaiTwo release directories hold machine-dependent files: binn and libn. The idea is that on a >U4UU nNoYnormal machine all the executables and linkable libraries be stored directly under these c(U3UU nUUZheadings. However, on the development platform it is necessary to subdivide each of these HGE deHF ( Ira nb-S/usr/bin/troff -man -F/usr/local/lib/ps/troff.font/Times/ftXX -t ~soi/new/man/man3/es @ n tBfindkey.3 | /usr/local/lib/ps/pscat | lpr -Pqms, for example.x dH tIIUU6h\V0IH X.6h\V0FK n&ctUU ncoZdirectories into subdirectories for each supported architecture. These subdirectories are UU@ necbnamed _XXXn, where XXXn is one of the following codes for particular architectures: $UU` nUUi386Intel 80386 (PC clones) e3UU` nenmipsDEC RISC (MIPS) BUU` nhe NEXTNeXT QUU` nUUsgiSilicon Graphics e`UU` nessun4Sun SPARC raroUU` nct vaxDEC VAX cUU` DvUUData Locations er,UU nt cThere is a directory ~soi/datan containing the data catalogues and subdirectories with both UU nFZpermanent and temporary datasets on them. Most of these data subdirectories are. links to UU nw/Zdirectories on scratch file systems and may move around physically. The pathname ~soi/UU@ Ldata/dsnamen should be used when referring to a particular data set. h u0 Configuration Management UU` n SWe dont have any. Every once in a while we take a snapshot and call it a release. torUU nUUqAs remarked above, SOI software releases are at three levels, qan, qbn, and qg. an software is !UU nIXuncontrolled and unsupported, with the assumption that it is only being used by a close-NE-UU nUUbknit group of developers who can yell at each other from down the hall. qbn software should 9UU nUUWbe in regular use by advanced and experienced users; it is expected to have moderately conEUU natYaccurate documentation and a fairly high level of support, meaning bug reports are taken eQUU nf eseriously. qgn software, which does not yet exist, will be used in the production pipeline and a]UU nic[should be used by inexperienced or casual users; it is assumed to be production quality, erriUU nr Wmeaning that we have enough confidence to tell users to read and believe the documentadonuUU n oVtion and bug reports are greeted with skepticism or downright incredulity. The normal UU nofbmigration path is that qan software is occasionally reviewed for substantial changes, redunUU nllhdancies, and accurate documentation and then frozen as a qbn release. When a qbn release gU; UTUU n w_has been in use for a sufficient time (TBD; O [10-0.5n yr]) without serious problems it in U:UU@ nanEmigrates to a qgn release with little change and much fanfare. U9UU nra[From time to time new modules may be added to a qbn release, but no module should be UUU8UU@ ny.#changed once it has been released. et U7UU` vd Makefiles and Make Conventions ]U6UU nshWMakefiles depend on the environmental variable MKROOT to determine the location of all errU5UU nr Ytargets. The value of MKROOT determines the release level: at Stanford, for example, setnU4UU n osting MKROOT to ~soi/newn will make files at the qan level, while setting it to ~soi/betan will on U3UU namake at the qbn level; of course it is also necessary to invoke the Makefile in the proper a*U2UU@ nnt directory. n BU1UU nXOur architecture-independent Makefiles also depend on the existence of a string for the ieNU0UU n0Wvariable MACHINE uniquely specifying the class for binary compatibility. Some systems ndJucKKUUHh\V0KJ duHh\V0IM ut'duUU nU8`(DEC Ultrix and NeXT) run a version of maken that automatically sets this variable. For onUU n[other systems, it is necessary to place the appropriate string in the environment variable ofUU nUUbMACHINE. There is a script ~soi/(version)/bin/whatrun that returns the correct string for *UU n oVknown systems, using various system-provided calls or a locally-written function cpu_6UU@ na+type (if it exists). Typical use would be: HUU` nco*setenv MACHINE `~soi/$RELEASE/bin/whatru` `UU n aZThe keynames for the supported systems/architectures are the same as the binary directory lUUH nn "names listed in Sec.  4.2 . UU n0XThe make system is designed to support multiple platforms from a single set of sources. nUU nWThis is achieved by having a common Makefile in all directories that simply includes a V0UU n]generic Makefile in the directory ~soi/(version)/src/genmake.dn. The generic Makefile aUU nth_includes a file nMakevars_MACHINE.mk in the same directory that sets variable values on stUU nnm^a machine-dependent basis: for example, the make variable CC might be set to ccn on an UU nhe`architecture whose native C compiler we like, but to gccn on a system whose native C comlo̪UU ntiYpiler fails to support parameter typing. (There is, however, no evidence that these MakeتUU nNEbvars files are being consulted at present.) The actual dependencies and maken instructions 䪚UU n t[appropriate to the files in the particular directory are then contained in the file Makelon0UU nisZcal.mk in the particular source directory. Builds and dependency checks take place within UU n bRmachine-dependent binary subdirectories of the source directory named _MACHINE.b. UU nMa[When modules are installed in their targets, 0-length placeholders should be placed in the UUUU n aobinary subdirectories for time dependence checks. The usual maken targets alln and cleann ach UU ns:\are generally supported. Note that a make will only affect files in the appropriate machine it,UU ne Ydirectories. Examples of each of the files necessary for the make procedure are given in i8UUH nupAppendix  I . (VUU` v nVersion Numbering fUU nUUUAll program modules should contain a software version number consisting of major and arUU ns [minor parts in their revision history and also as a defined variable (as a pretend float). in~UU@ n0QInclude (header) files should have unique version number variables, e.gn. nUU` nce"#define SOI_SDS_VERSION_NUM(0.7) UU n sRwhile actual programs and functions should always use the predefined variable VERUU@ ned SION_NUM: ƪUU` nac#define VERSION_NUM(0.7) ުUU nUUUPrograms should provide mechanisms for reporting their version number to calling proeꪉUU@ n ;grams or obtaining the version numbers of called programs. . NUU nll]The first numbered qbn release of Sep. 1993 is 0.7. All programs and modules within it eUU n Tshould have a common number. Individual modules may then migrate to higher numbered (UU n n]releases depending on their level of maturity and testing. At the time of a software release &UU nofVonly modules with version numbers greater than or equal to the release version number 2UU@ n aZwill be included. This guarantees continuing review of all parts of the software release. dLMMin6h\V0ML 6h\V0KO ncshUU` ve Revision Control System UU` nSIBWe should use RCS at theq bn and qgn levels at least. .UU n sUWe also ought to have some established mechanisms for not clobbering each other when U:UU n o_we are modifying software at the qan level. Presumably as the software matures this will bFUU@ n 1Ebecome less of a problem than it is now, and so far we are managing. h^UU n niThe utilities locksoin and unlocksoin provide a certain degree of control at the directory jUU nurZlevel. Originally designed to protect temporary data directories against accidents or misvUU neaZuse, they do provide a simple mechanism for locking directories. In order to add, modify, UU nuicor remove a file from a locked directory, unlocksoin must be run on the directory. Only one UU n0[person or process at a time can have a directory unlocked, but while it is unlocked anyone ReUU nte\may make changes within it. It is thus important to relock the directory when the change is UU nWeVcomplete. The locking and unlocking processes both automatically set the owner of the UU nwegdirectory in question to soin, and the group ownership to SOIn, so only members of group UUUU@ es)SOIn can make use of these utilities. edNOOckHh\V0ON idHh\V0MQ to1h ule Makefile Examples UU` ar2*** Local Makefile (always looks like this) *** (UU`  t 4UU` e !# @(#)Makefile SOI 0.79/21/93 I@UU` di LUU` ui)include $(MKROOT)/src/genmake.d/Makefile XUU` mu bdUU` to# Revision History: pUU` on# |UU` ca# Rev DateName locUU` is-# 0.793.09.21R Bogartcreated this file aUU` it tUU`  t-*** generic Makefile included by above *** UU` co eUU` d "# @(#)MakefileSOI 0.7 9/21/93 ĪUU` f  ЪUU` we# ܪUU` n G# MKROOT should be set in the Shell environment to /home/soi/(version) f g誙UU` UU)# where version is new, beta, or gamma lUU` # UU` #  UU` ck # MACHINE should be set by make idUU` =#Currently vax, mips, or NEXT are set by make automatically i$UU` A#sun4, i386, or sgi must be set by setting MACHINE in the Shell 0UU`  #environment <UU` le# HUU` 5# allows .DEFAULT: to triggers instead of .?.? rules OTUU` Ma# `UU`  .SUFFIXES: lUU` vi.SUFFIXES: .z xUU` on UU` ca# UU` oc)# Generic variable and macro definitions gUU` fi# UU` it7include $(MKROOT)/src/genmake.d/Makevars_$(MACHINE).mk byUU`  UUU`  MAKERULE=$@ # ̪UU`  0# تUU` UU# "make all" is the default we䪄UU`  # UU` !beall: UU` "en($(CD) _$(MACHINE).b;\ gUU` #UU$(MAKECMD) all) UU` $am l UU` % .DEFAULT: ,~UU` &($(CD) _$(MACHINE).b;\ E 8}UU` 'ak$(MAKECMD) $@) D|UU` va mP{UU` )et dP QQ s6h\V0QP in6h\V0OS nm2UU` *# 6*** extracts from a generic Makevars_MACHINE.mk *** UU` ( O UU` # -# @(#)Makevars_mips.mkSOI 0.7 9/21/93 U*UU` +S: 6UU` ,on# BUU` -ca2# generic variable and macro definitions for mips NUU` .# ZUU` :# fUU` ;ud5# DESTROOT is the root directory of where to install rUU` < U# ~UU` =MADESTROOT =$(MKROOT) UUU` I# UU` Jal# ar - archive weUU` K  # ranlib UU` L # UU` M(ARFLAGS =crv ƪUU` NUU AR =ar $ҪUU` ORANLIB =ranlib lުUU` P DꪗUU` QUUARFILE =noarfile MACUU` ROBJS = akUU` Z # UU` [ m# cc - C compiler UU` \# &UU` ] CDEBUG =-g 2UU` ^0CDEFINES =-DBETA 6>UU` _#CFLAGS =-O JUU` `$CINCLUDES =-I -I$(MKROOT)/include neVUU` aNE CC =cc bUU` b ?CCCMD =$(CC) -c $(CDEBUG) $(CFLAGS) $(CDEFINES) $(CINCLUDES)  UnUU` dS: HFILES = zUU` e CFILES = -UU` wri eUU` io# UU` UU# make # UU` # UU` ud VPATH =.. s ªUU`  o MAKEDEFS =DESTROOT=$(DESTROOT) <ΪUU` UU MAKEFLAGS = ROڪUU`  MAKERULE = 檂UU`  J MAKE =make cUU` UU/MAKECMD =$(MAKE) -$(MAKEFLAGS) $(MAKEDEFS) \ UU` AG0GMAKEVARS=$(GMAKEVARS) MAKERULE=$(MAKERULE) \ UU UU` r-f ../$(MAKELOCAL) P~UU` UU Q"}UU` ar;GMAKEVARS =$(MKROOT)/src/genmake.d/Makevars_$(MACHINE).mk # .|UU`  m2GMAKERULES =$(MKROOT)/src/genmake.d/Makerules.mk :{UU` UG=INCLUDEVARS =$(MKROOT)/src/genmake.d/Makevars_$(MACHINE).mk UFzUU` =4INCLUDERULES =$(MKROOT)/src/genmake.d/Makerules.mk inRyUU` UUMAKELOCAL =Makelocal.mk dRCDSSINHh\V0SR dHh\V0QU ES&UU`  eMAKEFILE =Makefile # UU` UU"MAKEFILES =$(MAKELOCAL) Makefile UU` /ud P*UU` 1 *** a sample Makelocal.mk *** $(6UU` 0 UBUU` 2S "# Makelocal.mk : ../src/examples NUU` 3 -# Modules for analysis of image data series MZUU` 4KE/# Revision history is at the end of the file. MAKfUU` 5 M# rUU` 6UU;# Be very explicit about include and library directories! UU~UU` 7  rUU` 8RO CC =cc -O ke.UU` 9NE!DEST =$(MKROOT)/bin/_$(MACHINE) RUU` ?rc.INC = -I -I$(MKROOT)/include -I/usr/include UU` @OT.MAIN =$(MKROOT)/src/cmd/_$(MACHINE).b/main.o UU` AUD#LIBD =-L$(MKROOT)/lib/_$(MACHINE) rulƪUU` BUULIBS =$(LIBD) -lsoi aҪUU` C LDFL =-s ުUU` E ꪗUU` Fall:example0 UU` G \UU` Hexample0:../mymodule.c UU` SMA/$(CC) -o $@ $? $(MAIN) $(INC) $(LIBS) $(LDFL) ES UU` Tefmv $@ $(DEST) ` /&UU` UUU touch $@ 2UU` Voc m>UU` WUUdcat:../dcat.c JUU` Xak $(CC) $(INC) $? -o ../$@ -O -s VUU` Yod sbUU` cmaclean: erinUU` f 4rm * zUU` gis UU` he.# UU` i M# Revision History: UUUU` jci# UU` k P# Rev DateName ~UU` n r1# 0.71993/08/13R S Bogartcreated this file 9ªUU` OO bdTrcUUT)6h\V0UT UU6h\V0SW IN1aih >u A. Proposal for a C-language coding standard UU` mLI9Proposed SOI C-language coding standards 93.06.17 (UU` o!Revised93.08.10, 93.09.09 4UU` p \ @UU` qexNThis is primarily for target practice. Some of it is motherhood, some states LUU` rLthe obvious, some reflects my own silly prejudices; a little of it might be UUXUU` sIhelpful. I welcome counter and supplementary proposals. I suggest that .dUU tOafter reviewing whatever is placed on the table, as many code standards as are pUU@ tNdesired be adopted by majority vote of those charged with writing SOI release |UU` uUULcode plus anyone else willing to supply programs and abide by the decision. ogUU` vfi 9UU` xOOCReference is made to the attached sample program for illustration. h\UU` y UU` z0K1. All programs should begin with a Comment section starting on the first C-lUU` {ndLline, containing the following pieces of information in order, as relevant: 6.ĪUU` | o ЪUU` }.0J 1a. program name (file name) and a full pathname for the program, with ܪUU` ~ctI appropriate symbolic representations, such as ~ and (version). ALWAYS u誙UU` y  illUU` ttJ 1b. a brief description of the purpose or intended use of the program. UU` alE For files containing several functions of a library, a list of all l UU`  aK functions contained with very brief descriptions (same line if possible) ajoUU`  cL should go here, and the sections (1d) and (1e) deferred to comments under ll$UU` raJ the individual functions. Reference to appropriate man pages should be 0UU` e  at this point. p<UU` us on.HUU`  yH 1c. the name and electronic mail address of a person responsible for sTUU`  tG maintaining the program (not necessarily the original author or most f i`UU` r, recent modifier. ALWAYS ` |lUU` UU .0xUU` amG 1d. a Usage or Synopsis section, showing the syntax for calling the ctUU` mbF program, if it involves a library function, or for invoking it from UU` , the command line if it is a main program. e UU` d  f tUU` E 1e. an Arguments section describing the meaning of each argument. lUU`  ` UU` coN 1f. a Bugs section describing known bugs, or limitations, or restrictions, ̪UU` heN or design features depending on your attitude. I prefer to call them bugs. تUU` duM The existence of such a section is of tremendous importance, so I would be 䪄UU`  pL inclined to suggest that it ALWAYS be present, even if there are no known icUU`  pN bugs, if that is conceivable. It is the only thing that shows that someone UU` na2 thought critically about how the program works. UU`  | UU` .0I 1g. a Planned Updates section suggesting lines of future development. x UU` ct ,~UU` ogN 1h. a statement to the effect that a Revision History will be found at the 8}UU` d  end of the file. proD|UU` UU P{UU` OIt should go without saying, but won't, that comments should be truthful, i.e. . ldVWW BHh\V0WV oHh\V0UY UU2heUU` urMthat they apply to the actual code and are not simply fossilized transplants uUU` ofof some skeleton program. UU` o  o*UU` UUK2. To the extent that it is feasible, out-of-program lines should precede no 6UU` UUOprogram declarators (to some degree this is necessary) in the following order: omeBUU`   aNUU` al? 2a. #include <> statements referencing standard directories ZUU` .  annfUU`  sC 2b. #include "" statements referencing non-standard directories ,~rUU`   a s~UU` fe- 2c. #define statements defining constants UU` d  nd UU` |0 2d. typedefs, global and extern declarations d UU`  b n'tUU` ou 2e. macro definitions UU`  ƪUU`  2f. function prototypes ҪUU` \ V0ުUU` N Blank lines should come between major sections, e.g. between #include's and ꪗUU` iz #define's. uUU` of fUU` grP3. The body of the main (or principal) function should come first, followed by siUU` m Hsubsidiary or incidental functions. When several library functions are dUU` ssOcollected in a single file, the ordering should be as listed in the index (1b) a. &UU` meMand should be something "natural", e.g. alphabetical, typical calling order, U2UU` in4input before output, creation before deletion, etc. es>UU`   JUU` UUL4. All function declarations should begin in column 1 (the first character VUU`  Kfollowing a newline character). No characters of any statement or comment  bUU`  Lshould occur later than column 78 or so. Tabs should be treated as filling nUU` pr&columns up to the next multiple of 8. zUU`  UU`  cI5. Function declarations should contain prototype declarations of their zUU`  arguments. ofUU`   rUU` thM6. Braces enclosing bodies of code should be placed on lines by themselves, UU` r Lindented by the same amount as the preceding line of code (0 for the braces ssªUU` inenclosing the function body). ΪUU` in ڪUU` UUO7. All lines of code within pairs of braces should be indented N columns with rde檂UU`  Hrespect to the enclosing braces, where N is a small integer like 2 or 3 UU` UU?(constant throughout the file), with the following exceptions: (thUU`    UU` foO 7a. Primary statements (those enclosed only within the braces enclosing the ~UU` ld) entire function) need not be indented. o"}UU` fi .|UU` prI 7b. Continuations of statements on 2nd and additional lines should be U:{UU` tiK indented more than the beginning of the statement, and not less than the ` FzUU` of previous line. RyUU`   M6.dXshYYs 6h\V0YX r 6h\V0W di+e UU`  bJ 7c. Preprocessor statements must begin in column 1. Some precompilers UU` UU require this. liUU`  p s*UU` beL8. When a single statement follows a control statement (if, while, for...) ce6UU` alLon a seperate line without braces, it should be indented N columns from the wiBUU` xccontrol statement. UUNUU`  UZUU` riN9. With the exceptions of single statements following control statements and fUU` tiOvery short parallel constructions, no more than one statement should appear on prrUU` ioa single line. on ~UU`  l sUU` K10. Spaces should appear around assignment equal signs ' = ', before open ss UU` =parentheses ' (', and after commas ', ' and semicolons '; '. UU`  UU` YF11. Blank lines should separate functions and major sections of code UU` diIwithin functions. The opportunity to fill such blank lines with helpful cƪUU` co#comments should not be overlooked. re ҪUU` UU ުUU` UUK12. Some reasonable attempt at descriptive variable names should be made. foꪗUU` UUGNames of variables should generally be in lower case; names of defined mnsUU` Hconstants should be in upper case. Globally defined symbols other than UU`  eJfunction names, if used, should be long and/or obscure, preferably mixing UU` rtupper and lower case. UU` st m&UU` onJ13. A comment section containing a revision history should appear at the 2UU`  SJend of the file. Each non-trivial revision of the program since at least >UU` paKits last major release should be reflected by at least one line giving the JUU`  Ldate of the revision, the name of the revisor, and a general description of VUU` wi(the nature and purpose of the revision. ucbUU`  h fnUU`  N14. If version numbering exists for a program (and it should be encouraged), zUU` e Ja VERSION_NUM floating-point constant should be defined early in the file UU` s %equal to the current version number. eUU` ef dUU`  OSeparate but related standards should apply to .h files. For these, reference UU` fuJshould be made to the template .h file ~soi/(release)/include/template.h. UU` upOBasically, all of items 1, 2, 13, and 14 apply to .h files, as well as general secªUU` reformat style. ΪUU` e  ڪUU` enL15. Every .h file should be enclosed within a preprocessor #ifndef testing 檂UU` laNwhether a constant describing inclusion of that .h file is defined. The last UU`  oOstatement before the enclosing #endif should be a definition of that constant. UUUU` lre d6h\V0`aA 6h\V0  IioUU` n f a6)Ra`bAge, 6)R)RUM 6.%1'bacA de6.%1' s l h wsi Hardware Architectures   d6AcbdA rat6AAile6̬\dceAUU6̬\̬\emp6 = KedA e/6 = K y,f h vd X 2 w ofv  12 w The SOI Program Development Environment  UUHh\V0fgB 15Hh\V0 ocUU` nin H)RgfhBnsntH)R.)RfilH.%1'hgiB UUH.%1' enouh w o File Names and Paths  HAihjBaHA.AH̬\jikBUU H̬\.̬\AH = KkjB H = K h wT The SOI Program Development Environment v 3 w of v 12  dlatmsc_mnl ec_n mpUU` n HhXnmol HhXm   H)Ronpl H)R.)RiroH0%~poql gH0%~ h w September 22, 1993  H[RqprlRH[R.[R1'H̬\rqsl1'H̬\.̬\H = Ksrl ndH = K h v  1 w of v 12  dt\uHA3K ^uvt HHFootnoteH-vuxt wwFootnoteEnwv Hxv{tyz 1Heading Rulee;_yzx;; ;~zyx;~;HvSNd ^{x|t pHH 1Heading RuleH1 |{~tq}} Chapter Rule }| HX-J ^~|t H(oH(o Chapter RuleHd~t Table Top_~ ~ DRv8 ^t D[D[ Table TopH,t TableFootnote;w;;HvRb ^t HH TableFootnotedH~6 H~6 ;UU` n"<$paranum><$paratext><$pagenum> ` m^"<$paranum><$paratext><$pagenum> )US UT`  R"<$paranum><$paratext><$pagenum> HnVbC ^ RuHwHwTable of Contents Specification HR- ^HR- teUU` n"<$paranum><$paratext><$pagenum> HP> ^ HHList of Figures SpecificationHR6 HR6  vUU` n"<$paranum><$paratext><$pagenum> HP>Jh ^ HHList of Tables Specificationd;H~ H~ e` x1, 23 ` x$<$symbols><$numerics><$alphabetics> ` x Level3IX &` x Level2IX 0` x$p Level1IX pC` wLSymbols[\ ];Numerics[0];A;B;C;D;E;F;G;H;I;J;K;L;M;N;O;P;Q;R;S;T;U;V;W;X;Y;Z $pL` x> <$pagenum> ^HlAmN ^ HuHueIndex SpecificationHdc_ UUc_ > P> ` o(The SOI Program Development Environment Fi(` pn!R. S. Bogart & J. Aloise et al.? BUU` vSOI Technical Note TN-93-106 v`UU nVThis note proposes a programming environment to be used for the development, testing, mUU nTaKand use of SOI Project software. We describe the required operating system zUU nWenvironment, supported architectures, languages and standards, required file names and 1UU@ n%paths, and configuration management. eHhX l3HhXD  ` uOperating Systems UU n[0bThe SOI software has been or is anticipated to be run on several flavors of Unixqn to vari+UU@ n ous extents: =UU` nInUltrixqn 4.2 LUU nMThe primary development environment to date. Anything that works should work XUU@ nYhere on a RISC architecture, using either the MIPSqn or GNU{n C compilers. gUU` nR.OSF X vUU` nalTIf the DECqn Alphaqn ever takes off and this is the system of choice. e UU` nmiIRIXqn 4.0.5 seUU` nen@The secondary development environment so far. Many things work. WUU` nuiIRIXqn 5.1-ALPHA-142 UU nroQThe anticipated future development environment. We dont even have a running ver1UU@ n"sion of the operating system yet. ͪUU` nSunOSqn 4.1.[2-3] ܪUU` nA number of things work. 몜UU` nOpSolarisqn 2.x UU` nSO*Possible future support. Not running yet.  UU` nvoNeXTstepqn 3.0 UU n \This is just BSD 4.3 with the GNU{n C compiler. A few utilities have been tried out, ar$UU@ nrobut not much. <UU n sSThe issue of support for operating systems is dependent on demand. We must support qHUU nnZrelease levels on as many operating systems as constitute the SOI Science Support Center, TUU ns Wwhich could be as few as one or as many as three (Pipeline Execution System, Data Stor dAveLeftdBnyRight rkdluiFirstdt ReferencerodreTOCldonIXn dFirst@ dCatdEUUdH.1dJdL dNridPUUdRsudT dV dX  i?>f xe buFootnotef SEm  as e1Step Step Number S:.\tStep_Rf HQe  ipe~ti S D 2HeadingH:\t.\t FirstBodye_R f HQ  ce~  e3HeadingH:\t..\t FirstBody~~f nDE  FirstBodyJBody~;fuHQ  duT~1Heading 1Heading Ruled H:\t\t FirstBodyf   oBullet Bullet Symbol\tf 1SCBulletpfz  eBullet Bullet Symbol \tafn  CBulletf@n Abstract1HeadingfJ CellBodyf ing CellHeading>f CStepBu fE EquationEquation Number E:(EQ )f Extract fFA  Figure Table Top Step NumberF:FIGURE .\tBody~~ f Bodyf CeFootnote.f@   CePurpose FirstBodyfS  Step Step Number S:.\tfq n+> TableFootnoteffT  TableTitle Table Top Step NumberT:TABLE .\tf @ < ~TitleAuthorf!y  CellHeadingf"xe .CellBodyf#Te  TableTitle Table Top Step NumberT:TABLE .\t~~ f$n Body_Rf%vHQ  ~ f 2HeadingH:\t.\t FirstBody~~f&D  FirstBodyBody_R f'wHQ  ~ f 3HeadingH:\t..\t FirstBodyf(w  headerf)w  Te footer leftf*w   footer rightf+w   header firstf,wH  dy footer firstf-n BoR  3HeadingTOCf.m H:\t FirstBodyf<n 6xDCBulletf=zf  Bullet Bullet Symbolu\teXf>@ 0axIG f%VQAppendixAppendix~;f?AU  u~ Appendix HeadA: \tAppendix \tAppendixfIn@ Abstract1Heading~;fMuAU  5u\tFi~y Appendix HeadA: \tAppendix \tAppendix$ fQ@  AuthorTNTagfTo@< t STitleeAuthor$ fYp@  AuthorTNTag$ f\@d  TNTagAbstract$ f^v@  R+>TNTagxAbstractmf m  n <o ; p  Mu q  r ppe Bullet SymbolsCallout= t Emphasis u  v  w  x  y  z  Bullet Symbol {  | $Equation Number }  dRun-In Heading ~  Step Numbert=   Subscript=   Superscript    Step Number         Emphasis    lou   @@5E:5Thin6Medium7Double8Thick@9 Very Thin ) 9 )#6!"!6!"!6!"!a6!"!Format A9#6!"!6!"!6!"!6!"!Format B a q a  Comment Courier Helvetica Symbol Times-RegularRegular BoldRegularObliqueItalicc_1LE1tvljoQό݇΢~w‘-zwal-N Yv4z3K}$ܟV>V"5Lyk9@$25 !_G,c*^7f̤`@k׌SG |NF0Av03k۞ R'/_KK74)Dsm %@kwC=!ĈʖCeLn