Requirements for the Casa Settings Feature

Overview

The Jira ticket for the requirements gather is CAS-6362 and the overall ticket for the feature is CAS-5561

Goals

Nongoals

Requirements

Environmental Variables

CasaSettings will make use of a very limited set of Unix environmental variables. All other software will obtain the needed values from CasaSettings rather than by directly accessing the environmental variables. This is in keeping with principle of CasaSettings being the definitive source of such information. The few supported environmental variables will show up as predefined values (e.g., casa.root, etc.).

Accessibility

The new settings will be the single mechanism for obtaining CASA settings, etc., for all CASA applications and scripts. As such the implementation will provide uniform access to the settings from C++, Python and from the Unix shell.

1. A C++ API will be provided to access the settings.
2. A CASA tool-level API will be provided to allow accessing the settings from Python.
3. A simple application will function as a shell utility to allow accessing the values from scripts.

Checkable Keys

Compile Time Checking (C++)

A mechanism will be provided so that the keys used to access settings will be accessed via predefined constants or methods rather than free-form strings. This will allow the compiler to detect reference to a nonexistent key (debugging problems caused by typos of this nature can be frustrating).

Run Time Checking

When the various settings files are read in, the keys will be checked against those know to CASA and a warning will be generated for unknown keys. This requirement will make sure that a contents of the settings files are at least known to CASA (a common error pathway would be to misspell a keyname which would make cause it to be ignored).

Search Hierarchy

The settings for a CASA application session will be obtained from a set of setting files. Loading will start with the most general files and proceed to more specific setting files thus allowing the more specific files to override the settings contained in the more general files.

1. Installation specific file (e.g., /.../casa-4.2.1/casasettings.rc)
2. User specific file (e.g., ~/.casa/settings.casa)
3. On the command line
   1. Setting file (e.g., casapy --setting-file=aFile)
   2. Individual setting setting (e.g., casapy --setting synthesis.visiblityIterator.something=aValue)

Setting File Inclusion

A settings file may specify the import of another settings file. A settings file may only be included once; subsequent imports of the same file will be ignored and trigger a warning. The use case for this feature is if a group has a set of common settings; by using the import feature in their home settings file, the user can get use the group settings and then add any of their own.

Naming

The implementation will support the use of compound names with individual components separated by a dot ".". A naming convention will be defined so that we can group the settings (e.g., casa.aGlobalSetting or synthesis.visiblityIterator.aViSetting). The definition mechanism will provide a number of predefined module names that will be easy to use and also provide a first level of organization for the settings namespace.

Visibility

A tool will allow showing the application's current settings and how they were obtained. This will support debugging and post mortem analysis.

Mutability

The implementation will not write values back to any settings file. We could allow the current setting of a value to be set transiently (i.e., only affects the current session) by a program; this could be useful for debugging by allowing a python user to change a setting (e.g., log level) on the fly. However, there is no way to reliably force code using the settings to reaccess them, though it is likely that restarting a CASA feature will cause it to reread the new value.

Derived/Computed Values

In keeping with the single-mechanism goal of this feature, all values should be directly obtainable from CasaSettings rather than computed in other parts of the code. For example, the filesystem path to an important data file should be queried from CasaSettings rather than computed from information obtained from CasaSettings or elsewhere. This will include not only typical CasaRC settings but also information we need from the host platform; the goal here is to make sure that any important piece of information will be the same in all parts of CASA rather than computed differently.

To make this feature useful, the values of the key/value pair will be allowed to reference other keys. The first (and only?) supported scheme will be simple substitution. The syntax might follow that of Bash, etc.: "DataDirectory: ${casa.root}/data". Logic will prevent a circular reference chain from putting the read/parse logic into an infinite loop.

CasaCore Interaction

CasaCore provides the AipsRc system for handling settings. The scheme differs somewhat from what is desired for CASA. Unfortunately, some parts of the CasaCore library use the AipsRc mechanism for obtaining settings. Since it is undesirable to have two different settings schemes for CASA, this feature will have to interact with CasaCore so that settings expected by CasaCore routines can be provided where needed. This will likely require some enabling modifications to CasaCore and CASA applications will have to explicitly call an initialization routine very early in the session so that the CASA settings can be read and provided to the AipsRc facility before they are needed by CasaCore routines.

-- JimJacobs - 2016-10-19