version 3.0.2

statacons¶

statacons -- calls SCons to build a project defined in an SConstruct.

The syntax of statacons follows that of scons, with a few additions and customizations. For the most commonly used options, we have adapted SCons syntax into a style more familiar to Stata users. These options are listed below. We also allow users to use the standard SCons syntax, although not a mix of the two in the same command.

In this help file, we list only the most important options. We borrow heavily from the scons help.

To see the full list of options, type statacons, help at the Stata prompt or scons -h at the appropriate shell prompt. See the SCons User Manual and SCons Man Page for more details.

Syntax¶

The syntax of statacons is:

statacons [ targets ] [, option(value)]

The SCons equivalent is:

statacons [option[=value]] [ targets ]

By default, statacons will look in the current directory for an SConstruct file, consider all targets described in that file, and then build or re-build targets if needed.

Specifying targets¶

By default, statacons will build all targets described in the SConstruct. The user can specify a target or a subset of targets using the target option on the command line:

. statacons outputs/auto-modified.dta

The SCons equivalent is identical.

Default targets can also be specified in the SConstruct with the Default() function, although targets specified at the command line override defaults specified in the SConstruct. Targets can be excluded from the default group with the Ignore() function.

Standard SCons Options¶

We list the most common options, with Stata syntax on the first line and the SCons equivalent on the second line.

Option	Description
clean	Remove specified targets and dependencies.
-c, --clean
debug(TYPE)	Print TYPE of debugging information, explain is most useful
--debug=TYPE
directory(DIRECTORY)	change directory to DIRECTORY before starting build
-C DIRECTORY
dry_run	Don't build; just print commands.
-n, --dry-run
file(FILE)	Read FILE as the top-level SConstruct file.
-f FILE, --file=FILE
help	Print SCons help message
-h, --help
q	Don't print SCons progress messages
-Q
silent	Don't print SCons actions or progress messages
-s, --silent
tree(OPTIONS)	Print a dependency tree in various formats:
--tree=OPTIONS	all, derived, prune, status, linedraw.

Custom statacons options¶

Option	Description
assume_built("target")	instruct the Stata builder to skip a task if all of its targets are listed,
--assume-built="target"	then mark those targets as up-to-date
assume_done("filename.do")	instruct the Stata builder to skip the given do-file in the current build,
--assume-done="filename.do"	then mark the associated target(s) as up-to-date
assume_done(*)	instruct the Stata builder to skip all do-files in the current build,
--assume-done=*	then mark all their targets as up-to-date
config_file(CONFIG_FILE)	specify configuration file(s)
--config-files=CONFIG_FILE
show_config	show configuration
--show-config

Return values¶

statacons will return the Python return code in r(py_rc). If non-zero, statacons will issue error 7103 "error occurs when running a Python script file or importing a Python module".

SConstruct Syntax¶

Basic SConstruct Recipe¶

import pystatacons
env = pystatacons.init_env()
task_name = env.StataBuild(
          target = ['path/to/target1.ext', 'path/to/target2.ext'],
          source = 'path/to/dofile.do'
)
Depends(task_name, ['path/to/dependency1.ext',
                        'path/to/dependency2.ext']
)

This defines a task task_name from the StataBuild method with targets path/to/target1.ext and path/to/target2.ext, source path/to/dofile.do and dependencies path/to/dependency1.ext and path/to/dependency2.ext. statacons will call Stata's batch mode to do path/to/dofile.do.

Additional Options for SConstruct Recipe¶

task_name = env.StataBuild(
          target = ['path/to/target1.ext', 'path/to/target2.ext'],
          source = 'path/to/source.ext',
          file_cmd = "command",
          params = 'arguments or options',
          depends = ['path/to/dependency1.ext', 'path/to/dependency2.ext']
)

The additional options to StataBuild are

file_cmd : the command SCons should pass to Stata's batch mode.

The default is do , but the user can specify anything that Stata can accept as a command, e.g., dyndoc, markdown, net, etc.
params : arguments or options that should follow the source in the call to Stata batch mode.

For example, a task with file_cmd of dyndoc might specify

params = ', saving(myfile.html) replace'

depends : an alternative to using the Depends() function
full_cmd : Alternatively, one can specify the full command explicitly (including any file and parameters). This will ignore the file_cmd, source, and params.

As an example,

helpFile = env.StataBuild(
        target = ['statacons.sthlp'],
        do_file = 'statacons.ado',
        file_cmd = "markdoc",
        params = ', export(statacons.sthlp) mini replace'
)

defines a task helpFile from the StataBuild method with target statacons.sthlp, source statacons.ado and params ', export(statacons.sthlp) mini replace'. statacons will call Stata in batch mode with command markdoc statacons.ado, export(sthlp) replace mini.

SConstruct Functions¶

See the SCons User Manual and SCons Man Page for functions available in SConstructs.

Configuration¶

statacons should run without configuration on most standard setups, assuming python and scons are installed properly. See utils/config_local_template.ini and config_project.ini for configuration options.

Run statacons, show_config to show current configuration.

Run utils/debugging-checklist.do to obtain useful information for debugging.

Example(s)¶

basic use

. statacons

print debugging info and build tree

. statacons,  debug(explain) tree(status,prune)

show current configuration

. statacons, show_config

build target called 'dl_original_data'

. statacons dl_original_data

mark all targets as built

. statacons, assume_built(*)

Author¶

statacons team https://github.com/bquistorff/statacons

References¶

SCons Development Team (2021a), SCons 4.3.0 Man page, https://scons.org/doc/4.3.0/PDF/scons-man.pdf

SCons Development Team (2021b), SCons 4.3.0 User Guide, https://scons.org/doc/4.3.0/PDF/scons-user.pdf

This help file was dynamically produced by MarkDoc Literate Programming package