1% Master File: project-doc.tex 2% Document Type: LaTeX 3% Document Previewer: xdvi -margins 1.5 4\documentclass{article} 5%\documentstyle[12pt]{article} 6 7\addtolength{\textheight}{0.5in} 8\addtolength{\topmargin}{-0.25in} 9\addtolength{\textwidth}{1.0in} 10\addtolength{\oddsidemargin}{-0.5in} 11\thispagestyle{empty} 12\title{%article title 13Project-File Format 14} 15\author{Robert K. Moniot} 16\date{\today} 17 18\newcommand{\OMIT}[1]{} 19 20%\pagestyle{headings} 21 22%\pagestyle{myheadings}\markright{%article running head 23%} 24 25\newcommand{\Line}[2]{\makebox[0pt][r]{#1: }\ \texttt{#2}\\} 26 27\begin{document} 28 29\maketitle 30 31\section{Introduction} 32This is a description of {\tt ftnchek} project-file format, version P3 33(for {\tt ftnchek} versions 2.11 and later). This description is 34intended for those who want to write programs or scripts that make use 35of the information in project files for other purposes. 36This document was written fairly hastily, but care has been taken that 37to make sure it is accurate, even if perhaps it is not very clear or 38well-organized. 39 40This document is {\em not} intended to describe how to use project 41files when checking Fortran programs. If that is what you are 42interested in, see the {\tt ftnchek} documentation. 43 44The description is based on the following sample program. Line 45numbers are added for reference. 46\vspace{2ex} 47 48 % Original source follows \end{document} in this file 49\noindent 50\Line{1}{C Program used as example in project-file documentation.} 51\Line{2}{C These comments are mainly to make the program not start on line 1.} 52\Line{3}{\ \ \ \ \ \ PROGRAM CALC} 53\Line{4}{\ \ \ \ \ \ INCLUDE 'projcom.f'} 54Including file projcom.f \\ 55\Line{1}{\ \ \ \ \ \ DOUBLE PRECISION BETA} 56\Line{2}{\ \ \ \ \ \ COMMON IOTA, GAMMA(3), BETA} 57Resuming file projex.f \\ 58\Line{5}{\ \ \ \ \ \ READ(*,*) NUM} 59\Line{6}{\ \ \ \ \ \ IOTA = NUM*NUM} 60\Line{7}{\ \ \ \ \ \ CALL SUMUP(NUM,GAMMA)} 61\Line{8}{\ \ \ \ \ \ WRITE(*,*) IOTA, (GAMMA(I),I=1,3)} 62\Line{9}{\ \ \ \ \ \ END} 63\Line{10}{\ \ \ \ \ \ SUBROUTINE SUMUP(M,XRAY)} 64\Line{11}{\ \ \ \ \ \ DIMENSION XRAY(M)} 65\Line{12}{\ \ \ \ \ \ XRAY(1) = 1.0} 66\Line{13}{\ \ \ \ \ \ DO 10 I=2,M} 67\Line{14}{\ \ \ \ \ \ \ \ XRAY(I) = XRAY(I-1)+I} 68\Line{15}{\ 10\ \ \ CONTINUE} 69\Line{16}{\ \ \ \ \ \ RETURN} 70\Line{17}{\ \ \ \ \ \ ENTRY SUMDOWN(M,XRAY)} 71\Line{18}{\ \ \ \ \ \ XRAY(M) = 1.0} 72\Line{19}{\ \ \ \ \ \ DO 20 I=M-1,1,-1} 73\Line{20}{\ \ \ \ \ \ \ \ XRAY(I) = XRAY(I-1)+I} 74\Line{21}{\ 20\ \ \ CONTINUE} 75\Line{22}{\ \ \ \ \ \ END} 76 77\section{Project files} 78A project file (produced when the {\tt -project} option is given) contains 79information from only one source file. A separate project file is 80created for each source file, with the extension {\tt .prj} replacing the 81source file extension {\tt .f} or {\tt .for}. 82 83The top-level routine in {\tt ftnchek} that is invoked to create a 84project file is {\tt proj\_file\_out} in file {\tt project.c}. 85Consult that routine to answer any detailed questions not treated 86here. 87 88Here is the project file produced by {\tt ftnchek} from the sample 89program. It will be explained line-by-line in the following sections. Line 90numbers have been added for reference. 91\vspace{2ex} 92 93 % Original project file follows \end{document} in this file 94\noindent 95\Line{1}{FTNCHEK\_ P3} 96\Line{2}{file projex.f} 97\Line{3}{ entries 3} 98\Line{4}{ entry CALC class 1 type 12 size 0 flags 1 0 0 0 0 0 0 0} 99\Line{5}{ defn} 100\Line{6}{ module CALC file projex.f line 3 top 3 class 1 type 12 size 0 flags 1 0 0 0} 101\Line{7}{ args 0} 102\Line{8}{ end} 103\Line{9}{ entry SUMUP class 1 type 10 size 0 flags 1 0 0 0 0 0 0 0} 104\Line{10}{ defn} 105\Line{11}{ module SUMUP file projex.f line 10 top 10 class 1 type 10 size 0 flags 1 0 0 0} 106\Line{12}{ args 2} 107\Line{13}{ arg 1 name M} 108\Line{14}{ class 0 type 1 size 0 dims 0 elts 1 cblk - cndx 0 same 0 flags 1 0 0 1 0 0 0 0} 109\Line{15}{ arg 2 name XRAY} 110\Line{16}{ class 0 type 2 size 0 dims 1 elts 0 cblk - cndx 0 same 1 flags 1 1 1 0 1 0 0 0} 111\Line{17}{ end} 112\Line{18}{ entry SUMDOWN class 1 type 10 size 0 flags 0 0 0 0 0 0 0 0} 113\Line{19}{ defn} 114\Line{20}{ module SUMUP file projex.f line 17 top 17 class 1 type 10 size 0 flags 1 0 0 0} 115\Line{21}{ args 2} 116\Line{22}{ arg 1 name M} 117\Line{23}{ class 0 type 1 size 0 dims 0 elts 1 cblk - cndx 0 same 0 flags 1 0 0 1 0 0 0 0} 118\Line{24}{ arg 2 name XRAY} 119\Line{25}{ class 0 type 2 size 0 dims 1 elts 0 cblk - cndx 0 same 1 flags 1 1 1 0 1 0 0 0} 120\Line{26}{ end} 121\Line{27}{} 122\Line{28}{ externals 1} 123\Line{29}{ external SUMUP class 1 type 10 size 0 flags 1 0 0 0 0 0 0 0} 124\Line{30}{ call} 125\Line{31}{ module CALC file projex.f line 7 top 7 class 1 type 10 size 0 flags 0 1 0 0} 126\Line{32}{ args 2} 127\Line{33}{ arg 1 name NUM} 128\Line{34}{ class 0 type 1 size 0 dims 0 elts 1 cblk - cndx 0 same 0 flags 1 1 1 0 0 0 0 0} 129\Line{35}{ arg 2 name GAMMA} 130\Line{36}{ class 0 type 2 size 0 dims 1 elts 3 cblk \%BLANK cndx 2 same 1 flags 1 1 0 0 1 0 0 0} 131\Line{37}{ end} 132\Line{38}{} 133\Line{39}{ comblocks 1} 134\Line{40}{ block \%BLANK class 2 type 11} 135\Line{41}{ module CALC file projcom.f line 2 top 4 flags 1 1 0 0} 136\Line{42}{ vars 3} 137\Line{43}{ var 1 name IOTA} 138\Line{44}{ class 0 type 1 size 0 dims 0 elts 1 flags 1 1 0 1 0 0 0 0} 139\Line{45}{ var 2 name GAMMA} 140\Line{46}{ class 0 type 2 size 0 dims 1 elts 3 flags 1 1 0 0 0 0 0 0} 141\Line{47}{ var 3 name BETA} 142\Line{48}{ class 0 type 3 size 0 dims 0 elts 1 flags 0 0 0 0 0 0 0 0} 143\Line{49}{} 144 145\section{Overall structure} 146The project file is a plain text file. It is line-oriented. Items 147on a line are not organized by columns, but simply separated by blank 148spaces. (In the example above, some lines have been broken for 149printing, but they are single lines in the original. The line numbers 150make clear where each line actually begins.) 151 152Throughout the file, lowercase letters are used for project-file 153keywords, and uppercase for the names of program identifiers. File 154names retain the case used by the operating system to refer to them. 155Most numeric items can have any value greater than or equal to 0, but 156flags can only be 0 for false and 1 for true. 157 158The project file consists of four main sections: a {\em preamble} 159(lines 1--2), an {\em entries} section (lines 3--27), an {\em 160externals} section (lines 28--38), and a {\em common block} section 161(lines 39--49). 162(These line numbers, and all line numbers in the description below, 163refer to this example. For other instances, all except the preamble 164line numbers will vary.) 165 166\section{Preamble} 167Line 1 is a magic cookie to identify the file as an {\tt ftnchek} 168project file and to indicate the project-file version number 169(currently P3). The {\tt F} is in column 1. 170If {\tt ftnchek} reads a project file with a different 171version number, it prints an error message and exits. 172 173Line 2 specifies the source file name. The keyword {\tt file} is 174unvarying. 175 176{\em Note:} Subsequent nonblank lines of the file are all indented by one 177blank space. 178 179\section{Entries section} 180This section (lines 3--27) lists the entry points of all the 181subprograms defined in the source file. The first line of this 182section (line 3) has the keyword {\tt entries} and the number of entry 183points in the following list. 184 185Then for each of the entry points, there is a sequence of lines as 186follows: 187\begin{itemize} 188 \item {\tt entry} line (lines 4, 9, 19) giving the name of the entry 189 point, its storage {\tt class} (subprograms are always class 1), 190 its data {\tt type} (see list of {\tt \#define type\_UNDECL} et 191 al.\ in {\tt symtab.h}), its type {\tt size} (usually 0 for 192 default, but may have other values from, e.g. {\tt INTEGER*8} 193 declarations), and {\tt flags}: {\tt used\_flag} (entry is 194 referenced in a {\tt CALL} or by use as a function anywhere in 195 the file), {\tt set\_flag} (function name is given a value for 196 return), {\tt invoked\_as\_func} (used as a function, i.e. in an 197 expresssion rather than a {\tt CALL} anywhere in the file), {\tt 198 declared\_external} (named in an {\tt EXTERNAL} statement 199 anywhere in the file), {\tt library\_module} (processed in {\tt 200 -library} mode). There are three additional values (all 0) to 201 allow for future flags. This information comes from the {\tt 202 Gsymtab} entry (in {\tt symtab.h}) for the entry point. 203 204 \item {\tt defn} line (lines 5, 10, 19) with just the keyword {\tt 205 defn}. 206 207 \item {\tt module} line (lines 6, 11, 20) giving name of subprogram 208 containing the entry point, the {\tt file} name (can be different from 209 line 2 if include files are used), {\tt line} number of entry point in 210 source file, line number in {\tt top}-level file (this will be the same 211 if not in an include file, otherwise it is where the outermost 212 {\tt INCLUDE} statement is located), storage {\tt class}, data 213 {\tt type} and type {\tt size} of 214 module (meanings as in {\tt entry} line, should be the same 215 values), and {\tt flags} {\tt is\_defn}, {\tt is\_call}, {\tt 216 external\_decl}, {\tt actual\_arg} identifying the nature of the 217 definition ({\tt is\_defn} is always 1, and the other flags 0 for 218 entry definitions). This information comes from the {\tt 219 ArgListHeader} (defined in {\tt symtab.h}) for this entry-point 220 definition. 221 222 \item {\tt args} line (lines 7, 12, 21) giving the number of 223 arguments (parameters) of this entry point. This line is the 224 beginning of a series (lines 7--8, 12--17, 21--26) terminated by 225 an {\tt end} line. For each argument there are two lines: 226 227 \begin{itemize} 228 229 \item {\tt arg} line (lines 13, 15, 22, 24) giving the position in 230 the argument sequence and the {\tt name} of the actual argument. 231 232 \item {\tt class} line (lines 14, 16, 23, 25) giving the storage 233 {\tt class} (see list of {\tt \#define class\_VAR} et al.\ in 234 {\tt symtab.h} for definitions), data {\tt type}, type {\tt 235 size}, number of array {\tt dims} (0 for scalars), and number 236 of array elements {\tt elts} (1 for scalars). Next come {\tt 237 cblk}, {\tt cndx}, and {\tt same} which are useful only for 238 actual arguments. For dummy arguments they are always {\tt 239 -}, {\tt 0}, and the argument's position in the argument list, 240 respectively. Last come the {\tt flags} {\tt is\_lvalue} 241 (always 1 for dummy arguments), {\tt set\_flag} (variable is 242 assigned or otherwise possibly modified, e.g.\ by being passed 243 to a subroutine), {\tt assigned\_flag} (variable is on left 244 side of an assignment statement), {\tt used\_before\_set} 245 (value is used before being possibly assigned) , {\tt 246 array\_var} (variable is an array or array element), {\tt 247 array\_element} (variable is an array element), {\tt 248 declared\_external} (argument is declared in an {\tt EXTERNAL} 249 statement), and {\tt active\_do\_var} (variable is the index 250 of a {\tt DO} loop, and call is within the range of that {\tt 251 DO}; always 0 for dummy arguments). This 252 information is taken from the {\tt 253 ArgListElement} entry (defined in {\tt symtab.h}) for the 254 argument. 255 256 \end{itemize} 257 258 \item {\tt end} line (lines 8, 17,26) marking the end of the list of 259 arguments for the entry point. 260 261\end{itemize} 262 263A blank line (line 27) marks the end of the entries section. 264 265\section{Externals section} 266This section (lines 28--38) lists the external references made from 267the subprograms in the source file. It is very similar in form to the 268entries section (in fact they are produced by the same code, differing 269only in that the keyword {\tt entry} is used instead of {\tt defn} to mark 270successive externals. 271The first line of this section (line 28) has the keyword {\tt 272externals} and the number of external references in the following 273list. 274 275This number counts \emph{separate} references to an external; that is, 276a given external can occur several times if it is referenced several 277times. However, if the external reference is resolved by a subprogram 278defined within the same source file, only one instance (or none in 279{\tt -library} mode) of a reference to that external is retained for 280the project file. If you want all the references to each external to 281be retained, compile {\tt ftnchek} with the macro {\tt PROJ\_KEEPALL} 282defined, or split the source file into separate files, one file for 283each subprogram. 284 285For each of the external references, there is a sequence of lines as 286follows. 287\begin{itemize} 288 289 \item {\tt external} line (line 29) giving the name of the external 290 and other information the same as described above for {\tt entry} lines 291 in the {\tt entries} section. 292 293 \item {\tt call} line (line 30) with just the keyword {\tt call}. 294 295 \item {\tt module} line (line 31) giving the name of the subprogram 296 containing the external reference, and other information as 297 described above for {\tt module} lines in the {\tt entries} section. 298 The difference is that for externals, the flag {\tt 299 is\_defn} is 0, and one of {\tt is\_call}, {\tt external\_decl}, 300 or {\tt actual\_arg} will be 1 to indicate how the external was 301 referenced. Here {\tt is\_call} signifies an actual {\tt 302 CALL} or the use of a function in an expression, {\tt 303 external\_decl} means the reference is in an {\tt EXTERNAL} 304 declaration, and {\tt actual\_arg} means the reference was 305 generated by passing the external as an actual argument to a 306 subprogram. 307 308 \item {\tt args} line (line 32) giving the number of actual 309 arguments of this external reference. This line is the beginning 310 of a series (lines 32--37) terminated by an {\tt end} line. For 311 each argument there are two lines: 312 313 \begin{itemize} 314 315 \item {\tt arg} line (lines 33, 35) giving the position in the 316 argument sequence and the name (or text if an expression) of 317 the actual argument. (The text may be incomplete if longer 318 than a limit {\tt MAXEXPRTEXT} set in {\tt ftnchek.h}.) 319 320 \item {\tt class} line (lines 34, 36) giving the storage class and 321 other information about the actual argument, as described 322 above for {\tt class} lines for dummy arguments in the entries 323 section. The differences are that for actual arguments that 324 are common variables, {\tt cblk} gives the name of the common 325 block containing the actual argument (the special indicator 326 {\tt -} signifies that the variable is not in common) and {\tt 327 cndx} the position in common (counting from 1 by variables, 328 not by storage location). This index is 0 for variables that 329 are not in common. Next is {\tt same} which gives the 330 position in the argument list of an argument that is aliased 331 to this one (equals its own index if no aliasing). 332 333 \end{itemize} 334 335 \item {\tt end} line (line 37) marking the end of the list of 336 arguments for the entry point. 337 338\end{itemize} 339 340A blank line (line 38) marks the end of the entries section. 341 342 343\section{Common block section} 344This section (lines 39--49) lists common block declarations in the 345source file. 346 347If there are multiple subprograms in the source file declaring the 348same common block, all of the declarations are retained, unless the 349project file is created in {\tt -library} mode, in which case only one 350instance of a declaration is retained. 351 352The first line (line 39) of this section has the keyword {\tt 353comblocks} and the number of common block declarations retained 354from the source file. (This will be just one instance of 355each block if the project file was created in library 356mode, otherwise the number will be the sum of all 357declarations of all blocks.) 358 359 360Then for each of the entry points, there is a sequence of lines as 361follows: 362\begin{itemize} 363 364 \item {\tt block} line (line 40) giving the block name, storage {\tt 365 class} (always 2) and data {\tt type} (always 11). This 366 information comes from the {\tt Gsymtab} entry for the block. 367 368 \item {\tt module} line (line 41) giving the name of the subprogram 369 declaring the block, the {\tt file} name, and location 370 information. As the example illustrates, if the declaration 371 is in an include file, the {\tt file} name on this line is the 372 include file containing the common declaration and the {\tt 373 line} number is the line of the declaration within the include 374 file, while the {\tt top} line number is the location of the 375 {\tt INCLUDE} statement in the top-level source file. After 376 the location information there are flags {\tt any\_used} 377 (any variable in the block is used), {\tt any\_set} (any 378 variable in the block is possibly assigned), {\tt saved} (the block is 379 named in a {\tt SAVE} statement), and one placeholder value 380 for a possible future flag (always 0). This information comes 381 from the {\tt ComListHeader} for the block declaration. 382 383 \item {\tt vars} line (line 42) giving the number of variables in 384 the block. An array counts as a single variable. This line 385 is the beginning of a series (lines 43--48). Unlike its 386 counterparts in the entries and externals sections, this 387 series is \emph{not} terminated by an {\tt end} line. For 388 each argument there are two lines: 389 390 \begin{itemize} 391 392 \item {\tt var} line giving the position in the block and the 393 {\tt name} of the variable. 394 395 \item {\tt class} line giving the storage {\tt class} (always 396 0), data {\tt type}, and {\tt size}, number of array 397 dimensions {\tt dims} and elements {\tt elts}, and 398 {\tt flags} {\tt used} (value is used), {\tt set} 399 (variable is assigned or otherwise possibly modified), 400 {\tt used\_before\_set} (value is used before being 401 possibly assigned), {\tt assigned} (variable 402 is on left side of an assignment statement), and four 403 placeholding zeroes for possible future flags. This 404 information is from the {\tt ComListElement} entry 405 for the variable. 406 407 \end{itemize} 408 409\end{itemize} 410The last line (line 49) of the common block section is blank. This is 411the last line of the project file. 412 413\end{document} 414 415 Original source of projex.f 416 417C Program used as example in project-file documentation. 418C These comments are mainly to make the program not start on line 1. 419 PROGRAM CALC 420 INCLUDE 'projcom.f' 421 READ(*,*) NUM 422 IOTA = NUM*NUM 423 CALL SUMUP(NUM,GAMMA) 424 WRITE(*,*) IOTA, (GAMMA(I),I=1,3) 425 END 426 SUBROUTINE SUMUP(M,XRAY) 427 DIMENSION XRAY(M) 428 XRAY(1) = 1.0 429 DO 10 I=2,M 430 XRAY(I) = XRAY(I-1)+I 431 10 CONTINUE 432 RETURN 433 ENTRY SUMDOWN(M,XRAY) 434 XRAY(M) = 1.0 435 DO 20 I=M-1,1,-1 436 XRAY(I) = XRAY(I-1)+I 437 20 CONTINUE 438 END 439 440 441 Original projex.prj file 442 443FTNCHEK_ P3 444file projex.f 445 entries 3 446 entry CALC class 1 type 12 size 0 flags 1 0 0 0 0 0 0 0 447 defn 448 module CALC file projex.f line 3 top 3 class 1 type 12 size 0 flags 1 0 0 0 449 args 0 450 end 451 entry SUMUP class 1 type 10 size 0 flags 1 0 0 0 0 0 0 0 452 defn 453 module SUMUP file projex.f line 10 top 10 class 1 type 10 size 0 flags 1 0 0 0 454 args 2 455 arg 1 name M 456 class 0 type 1 size 0 dims 0 elts 1 cblk - cndx 0 same 0 flags 1 0 0 1 0 0 0 0 457 arg 2 name XRAY 458 class 0 type 2 size 0 dims 1 elts 0 cblk - cndx 0 same 1 flags 1 1 1 0 1 0 0 0 459 end 460 entry SUMDOWN class 1 type 10 size 0 flags 0 0 0 0 0 0 0 0 461 defn 462 module SUMUP file projex.f line 17 top 17 class 1 type 10 size 0 flags 1 0 0 0 463 args 2 464 arg 1 name M 465 class 0 type 1 size 0 dims 0 elts 1 cblk - cndx 0 same 0 flags 1 0 0 1 0 0 0 0 466 arg 2 name XRAY 467 class 0 type 2 size 0 dims 1 elts 0 cblk - cndx 0 same 1 flags 1 1 1 0 1 0 0 0 468 end 469 470 externals 1 471 external SUMUP class 1 type 10 size 0 flags 1 0 0 0 0 0 0 0 472 call 473 module CALC file projex.f line 7 top 7 class 1 type 10 size 0 flags 0 1 0 0 474 args 2 475 arg 1 name NUM 476 class 0 type 1 size 0 dims 0 elts 1 cblk - cndx 0 same 0 flags 1 1 1 0 0 0 0 0 477 arg 2 name GAMMA 478 class 0 type 2 size 0 dims 1 elts 3 cblk %BLANK cndx 2 same 1 flags 1 1 0 0 1 0 0 0 479 end 480 481 comblocks 1 482 block %BLANK class 2 type 11 483 module CALC file projcom.f line 2 top 4 flags 1 1 0 0 484 vars 3 485 var 1 name IOTA 486 class 0 type 1 size 0 dims 0 elts 1 flags 1 1 0 1 0 0 0 0 487 var 2 name GAMMA 488 class 0 type 2 size 0 dims 1 elts 3 flags 1 1 0 0 0 0 0 0 489 var 3 name BETA 490 class 0 type 3 size 0 dims 0 elts 1 flags 0 0 0 0 0 0 0 0 491 492