Editing SCons (section)

=== SConstruct commands ===

====Fetch(<file[s]>,<directory>,[options])==== 
defines a rule for downloading data files from the specified directory on an external data server (by default) or from another directory on disk. The optional parameters that control its behavior are summarized below.

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Fetch options
|-
| '''Name''' || '''Default''' || '''Meaning'''
|-
| private || None || if the data file is private
|-
| server || $RSF_DATASERVER or http://www.reproducibility.org  || remote data server (or '''local''' for local files)
|-
| top || <tt>data</tt> || name of the top data directory on the data server
|-
| dir || None || name of directory after top
|-
| usedatapath || 1 || usedatapath=1 - download to $DATAPATH with symbolic link. 
usedatapath=0 - download to pwd
|}

In the example above, '''Fetch''' specifies the rule for getting the file <tt>wz.35.H</tt>: connect to the default data sever and download the file from the [http://www.reproducibility.org/data/wz data/wz] directory.

An example to Fetch with more parameters is:
<syntaxhighlight lang="python">
Fetch('KAHU-3D-PR3177-FM.3D.Final_Migration.sgy',
	  dir='newzealand/Taranaiki_Basin/KAHU-3D',
          server='http://s3.amazonaws.com',
	  top='open.source.geoscience/open_data',
	  usedatapath=1)
</syntaxhighlight>


====Flow(<target[s]>,<source[s]>,<command>,[options])==== 
defines a rule for creating targets from sources by running the specified command through Unix shell. The optional parameters that control its behavior are summarized below.

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Flow options
|-
| '''Name''' || '''Default''' || '''Meaning'''
|-
| stdout || 1 || if output to standard out (0 for output to <tt>/dev/null</tt>, -1 for no output)
|-
| stdin || 1  || if take input from standard in (0 for no input)
|-
| rsfflow || 1 || if using <tt>Madagascar</tt> commands
|-
| suffix || '.rsf' || default suffix for output files
|-
| prefix || 'sf' || default prefix for programs
|-
| src_suffix || '.rsf' || default suffix for input files
|-
| split || [] || split the flow for data parallel processing 
|-
| reduce || 'cat' || how to reduce the output from data parallel processing
|-
| local || 0 || if execute on the local node when using data parallel processing on a cluster
|}

In the example above, there are two '''Flow''' commands. The first one involves a Unix pipe in the command definition.

On the use of parallel computing options, see [[Parallel Computing]].

====Plot(<target>,[<source[s]>],<command>,[options])==== 
is similar to '''Flow''' but generates a graphics file (Vplot file) instead of an RSF file. If the source file is not specified, it is assumed that the name of the output file (without the <tt>.vpl</tt> suffix) is the same as the name of the input file (without the <tt>.rsf</tt> suffix).

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Plot options
|-
| '''Name''' || '''Default''' || '''Meaning'''
|-
| suffix || '.vpl' || default suffix for the output file
|-
| vppen || None  || additional options to pass to <tt>vppen</tt>
|-
| view || None || if set, show the output on the screen instead of saving it in a file
|}

In the example above, there are two '''Plot''' commands.

====Result(<target>,[<source[s]>],<command>,[options])====
is similar to '''Plot''', only the output graphics file is put not in the current directory but in a separate directory (<tt>./Fig</tt> by default). The output is intended for inclusion in papers and reports.

{|class="wikitable" align="center" cellspacing="0" border="1"
|-
! colspan="3" style="background:#ffdead;"|Result options
|-
| '''Name''' || '''Default''' || '''Meaning'''
|-
| suffix || '.vpl' || default suffix for the output file
|}

In the example above, <tt>Result</tt> defines a rule that combines the results of two <tt>Plot</tt> rules into one plot by arranging them side by side. The rules for combining different figures together (which apply to both <tt>Plot</tt> and <tt>Result</tt> commands) include:
* SideBySideAniso
* OverUnderAniso
* SideBySideIso
* OverUnderIso
* TwoRows
* TwoColumns
* Overlay
* Movie

====End()==== 
takes no arguments and signals the end of data processing rules. It provides the following targets, which operate on all previously specified '''Result''' figures:
* '''scons view''' displays the resuts on the screen.
* '''scons print''' sends the results to the printer (specified with '''PSPRINTER''' environmental variable).
* '''scons lock''' copies the results to a location inside the '''DATAPATH''' tree.
* '''scons test''' compares the previously "locked" results with the current results and aborts with an error in case of mismatch.

The default target is set to be the collection of all '''Result''' figures.