configure_file.py tool¶

The tools/configure_file.py script is a tool invoked by the build system.

The tool is intended to be used to generate files that are treated as part of the codebase and that hold configuration values set by the build-system. In short, it acts as an alternative to repeatedly passing long lists of configuration options to the compiler for every source file.

It’s instructive to consider the structure of a typical invocation of the tool:

configure_file.py --input=<template-file> --output=<output> [-D<var>[=<value>]]...

The snippet illustrates that the tool recieves 3 kinds of information:

The input to the template file read by the tool
The path to the output file to be produced by the tool
A variable number of options for specifying configuration variables. -D<var> defines a configuration variable <var> without a value while -D<var>=<value> associates the variable with the value <value>

Aside: a complete overview of all available options is provided later

Essentially, the tool reads template file, performs transformations based upon configuration variables and write out the result.

Analogous functionality is implemented by various build systems such as autotools, CMake, and Meson. **This tool is closely modelled after the confiure_file commands provided by CMake and Meson.

Transformations¶

The tool performs 2 type of tranformations.

The first transformation type is straightforward variable substitution. The tool replaces tokens enclosed in a pair of @ symbols with the value of the configuration variable matching the token. The tool aborts with an error if the configuration variable isn’t defined or doesn’t have an associated value. Let’s consider 2 examples:

Consider a template file with the line
```
const char* git_hash = "@GIT_HASH@";
```
If the tool is passed -DGIT_HASH=f4ac1200c2fa21f72a9f160f38f5924f440d19508 the corresponding line in the output file will read:
```
const char* git_hash = "f4ac1200c2fa21f72a9f160f38f5924f440d19508";
```
Consider a template file with the line
```
#define PRECISION @PRECISION@
```
If the tool is passed -DPRECISION=2 the corresponding line in the output file will read:
```
#define PRECISION 2
```

We refer the second type of transformation as a define-transfrom. This occurs for a line in the input file of the form:

#configurefile_define CONFVAR

where CONFVAR is a placehold the name of any configuration variable. The corresponding line of the output file has 3 possible forms:

If -DCONFVAR was passed to the tool, then the output line is
```
#define CONFVAR
```
If -DCONFVAR=42 was passed to the tool, then the output line is:
```
#define CONFVAR 42
```
In this scenario, 42 is intended as an arbitrary choice for the associated value
If CONFVAR is not the name of a configuration variable, the output becomes
```
/* #undef CONFVAR */
```

Note

The analogous transformations in CMake and Meson replace lines that start with #cmakedefine and #mesondefine.

Detailed Help Output¶

usage: configure_file.py [-h] [--variable-use-file-contents VAR=path/to/file]
                         [-D VAR=VAL] -i INPUT -o OUTPUT [--clobber]
                         [--literal-linenos [LITERAL_LINENOS ...]]

A simple tool for configuring template files. It is modelled after the
functions with the same name in CMake and Meson. Detailed documentation is
maintained at
https://cholla.readthedocs.io/en/latest/Development/configure_file.html.

options:
  -h, --help            show this help message and exit
  --variable-use-file-contents VAR=path/to/file
                        associates the (possibly multi-line) contents
                        contained by the specified file with VAR
  -D VAR=VAL            associates the value, VAL, with the specified
                        variable, VAR
  -i INPUT, --input INPUT
                        path to input template file
  -o OUTPUT, --output OUTPUT
                        path to output file
  --clobber             overwrite the output file if it already exists
  --literal-linenos [LITERAL_LINENOS ...]
                        line numbers corresponding to lines that are treated
                        as literals (i.e. no variable substitution is
                        performed)