Degree of reproducibility

Instead of a single result list, GNU makefiles of SEP documents typically define three result list variables. These variables differ from other standard variables in that they are meant to be defined by the author. These variables, any of which the author may omit if empty, are RESULTSER, RESULTSCR, and RESULTSNR. The endings ER, CR, and NR indicate the degree of reproducibility to the reader:

• easily-reproducible describes result files which the reader can expect to regenerate within less than ten minutes on a standard workstation.
• non-reproducible are all the result files which a reader cannot reproduce, such as hand-drawn illustrations or scanned-in figures.
• conditionally-reproducible indicates results which require special software or a lavish amount of time for recomputation. In both cases, the author nevertheless supplies a complete set of source files and rules to ensure that the results are reproducible. However, he accompanies the conditionally-reproducible result file (e.g., myres.ps) with a warning file (myres.warning) in which he states why he classified the result as conditionally-reproducible. In applied geophysical research, many interesting results fall into this category.

The standard document command make burn removes all easily reproducible results exclusively. The invocation of make burnall removes easily and conditionally-reproducible result files. The distinction between the three types of result files enables a reader to choose his burning and rebuilding according to his computer environment's special software and his own time commitment.

The standard targets burn and jclean remove files based on naming conventions. An author needs to inspect these carefully before using them. If the GNU makefile contains RESULTSER = myres, then make burn attempts to remove a series of potential result files ${RESDIR}/myres.ps ${RESDIR}/myres.v ${RESDIR}/myres.v3, where RESDIR is set to the directory in which the result files reside. An invocation of the target jclean will remove any file ending in .H .v .v3 or any file name beginning with the phrase junk in the current directory. Consequently, if ${RESDIR} is defined as ``.'', and the makefile author uses jclean in his clean rule, make clean will accidentally remove all result files. Thus, if jclean is to be used, the result files should reside in a directory different from that of the makefile. Any author of makefiles will have to study the burn and clean rules as well as the associated naming conventions to avoid removing valuable files accidentally.

The build rule in SEP's standard include files attempts to update all result files: easily-reproducible, conditionally-reproducible, as well as non-reproducible result files. This can have the surprising effect of recomputing files which one has assumed are existing and up-to-date. Such surprising recomputations can be caused by common dependencies of rules about conditionally- and easily-reproducible result files such as,

	cr.ps : easy.v difficult.v
	er.ps : easy.v

If er.ps is built, and a secondary file easy.v is created, then cr.ps is out-of-date since its dependency easy.v is younger.