SetProgramOptionsCMake Class Reference

The SetProgramOptionsCMake module is an extension of setprogramoptions.SetProgramOptions which adds handling for CMake specific properties.

SetProgramOptionsCMake also adds an additional generator type, cmake_fragment, to the setprogramoptions.SetProgramOptions.gen_option_list() method, enabling the ability to generate CMake fragment files.

Supported .ini File Operations

Supported Operations

Operation	Usage	Description
opt-set-cmake-var	opt-set-cmake-var VARNAME [TYPE] [FORCE] [PARENT_SCOPE]: VALUE	Sets a CMake variable.

opt-set-cmake-var

Usage: opt-set-cmake-var <varname> [TYPE] [PARENT_SCOPE] [FORCE] : <value>

A CMake variable set operation. This can be used to genrate bash command line options of the form -D<varname>[:<type>]=<value> or in a CMake fragment we may generate a set() command.

For information related to CMake Fragment generation of set() commands, see the CMake docs .

PARENT_SCOPE and FORCE are mutually exclusive options and will result in an error being thrown.

An additional thing to note is that PARENT_SCOPE should not be used with CACHE variables (i.e., typed variables). CMake will happily process this but you will likely get a result that you do not want. In a CMake fragment file:

set(FOO FOO_VALUE CACHE STRING "my docstring" PARENT_SCOPE)

Will result in the value of FOO being set to FOO_VALUE;CACHE;STRING;my docstring which is unlikely to match expectations, but that is what CMake will do. In this case, SetProgramOptionsCMake will raise a warning and will generate a string to match what CMake generates when sent to a bash options generator (i.e., -DFOO="FOO_VALUE;CACHE;STRING;my docstring"). When sent through the cmake fragment generator the output will be the equivalent set() call.

Useful Links

• Sphinx docstrings reference

• Google docstrings reference

• CMake set() reference

API Documentation

SetProgramOptionsCMake

SetProgramOptionsCMake is a subclass of the SetProgramOptions that adds CMake-specific handlers for the following .ini file operations:

Operation: opt-set-cmake-var

The opt-set-cmake-var operation can have the following format:

opt-set-cmake-var <varname> [<type>] [FORCE] [PARENT_SCOPE] : <value>

This command can result in a generated bash output that might look like: -DVAR_NAME:BOOL=ON using the SetProgramOptions method gen_option_list with the bash generator.

When using the BASH generator to generate command line arguments, CMake uses the syntax -D<VARNAME>[:<TYPE>]=<VALUE>. The TYPE field is optional and if left out CMake will default to a STRING type. Further, all CMake variables set via the command line using -D will be CACHE variables and each -D operation should be considered a FORCE operation too. For example, -DFOO:STRING=BAR is roughly equivalent to the CMake command: set(FOO CACHE STRING "docstring" FORCE).

The PARENT_SCOPE option applies only to non-cache variables and its presence will instruct CMake to make that variable non-cache. Care should be taken when using PARENT_SCOPE as combining it with the usual CACHE operations results in CMake creating a non-cached variable whose contents are the list containing <varname>;CACHE;<type>;doc string. As a result, the BASH generator issues warnings with no generated command line arguments when either 1. PARENT_SCOPE OR 2. solely a variable name AND variable value are passed in to opt-set-cmake-var.

See CMake documentation on the set() command for more information on how fragment file entries are generated.

We do not support the environment variable variation of set() at this time.

Authors:

• William C. McLendon III <wcmclen@sandia.gov>

• Evan Harvey <eharvey@sandia.gov>

Public API

class setprogramoptions.SetProgramOptionsCMake(filename=None)

Bases: SetProgramOptions

Extends SetProgramOptions to add in CMake option support.

• Adds a new .ini file command: opt-set-cmake-var which can have the format: opt-set-cmake-var VARNAME [TYPE] : VALUE

• Adds a new back-end generator for cmake_fragment files for the setprogramoptions.SetProgramOptions.gen_option_list() method.

__init__(filename=None)

Constructor

Parameters:

filename (str,Path,list) – The .ini file or files to be loaded. If a str or Path is provided then we load only the one file. A list of strings or Path s can also be provided, which will be loaded by ConfigParser’s read() method.

Private API

Handlers

SetProgramOptionsCMake.handler_initialize(section_name, handler_parameters)

SetProgramOptionsCMake._handler_opt_set_cmake_var(section_name, handler_parameters)

Helpers

SetProgramOptionsCMake._helper_opt_set_cmake_var_parse_parameters(params: list)

Processes the list of parameters to detect the existence of flags for variables. This is consumed when generating option lists because the relevance of some options depends on the back-end generator. For example, PARENT_SCOPE is relevant to a cmake_fragment generator but does not get used for a bash option that would be provided to the cmake application on the command line.

Called By:

• _program_option_handler_opt_set_cmake_var_bash()

• _program_option_handler_opt_set_cmake_var_cmake_fragment()

Parameters:

params (list of str) – The list of parameters pulled out of the .ini file entry.

Returns:

A dictinary object that captures the existence or omission of flags that are applicable to a CMake Cache variable operation.

Return type:

dict

Program Option Handlers

SetProgramOptionsCMake._program_option_handler_opt_set_cmake_fragment(params: list, value: str) → str

cmake fragment line-item handler for opt-set entries. Sine we don’t care about that for a CMake fragment this can be a noop.

Including this function prevents an exception_control_event warning from being generated in setprogramoptions.SetProgramOptions.

This method is essentially a noop but we can keep it in case someone ever turns exception_control_level (ecl) to max. This is because if this function isn’t defined a “SILENT” exception_control_event will get tripped in SetProgramOptions. Normally this would just pass on by but since SILENT events are treated as WARNINGS with respect to raising an exception, removing this would trigger an exception when ecl is 5.

That said, keeping this method around could still be seen as optional in that removing it will not affect application behaviour under normal use.

Called By: setprogramoptions.SetProgramOptions._gen_option_entry() using method name scheme: _program_option_handler_<operation>_<generator>()

Parameters:

• params (list) – The list of parameter entries extracted from the .ini line item.

• value (str) – The value portion from the .ini line item.

Returns:

None

SetProgramOptionsCMake._program_option_handler_opt_set_cmake_var_cmake_fragment(params: list, value: str) → str

cmake fragment line-item generator for opt-set-cmake-var entries when the generator requests a cmake_fragment entry.

The generated output for this command should be valid according to the CMake set() command.

Valid formats for set() are:

• set(<variable> <value> [FORCE] [PARENT_SCOPE])

• set(<variable> <value> CACHE <type> <docstring> [FORCE] [PARENT_SCOPE])

We do not support the set(ENV{<variable>} [<value>]) variant.

Called By: setprogramoptions.SetProgramOptions._gen_option_entry() using method name scheme: _program_option_handler_<operation>_<generator>()

Note

It’s ok to modify params and value here without concern of side-effects since setprogramoptions.SetProgramOptions._gen_option_entry() performs a deep-copy of these parameters prior to calling this. Any changes we make are ephemeral.

SetProgramOptionsCMake._program_option_handler_opt_set_cmake_var_bash(params: list, value: str) → str

Line-item generator for opt-set-cmake-var entries when the generator is set to bash.

Called By: setprogramoptions.SetProgramOptions._gen_option_entry() using method name scheme: _program_option_handler_<operation>_<generator>()

Note

It’s ok to modify params and value here without concern of side-effects since setprogramoptions.SetProgramOptions._gen_option_entry() performs a deep-copy of these parameters prior to calling this. Any changes we make are ephemeral.

Parameters:

• params (list) – The parameters of the operation.

• value (str) – The value of the option that is being assigned.

Raises:

ValueError – This can potentially raise a ValueError if exception_control_level is set to 5 if there are operations that are skipped in Bash generation. If ecl is less than 5 then warnings are generated to note the exclusion.