envSetting.h File Reference

#include "pxr/pxr.h"
#include "pxr/base/arch/hints.h"
#include "pxr/base/tf/registryManager.h"
#include <atomic>
#include <string>

Include dependency graph for envSetting.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	TfEnvSetting< T >
struct	TfEnvSetting< std::string >

Macros
#define	TF_DEFINE_ENV_SETTING(envVar, defValue, description)

Functions
template<class T >
void	Tf_InitializeEnvSetting (TfEnvSetting< T > *)
template<class T >
T const &	TfGetEnvSetting (TfEnvSetting< T > &setting)
bool	Tf_ChooseEnvSettingType (bool)
int	Tf_ChooseEnvSettingType (int)
std::string	Tf_ChooseEnvSettingType (char const *)

Detailed Description

Environment setting variable.

A TfEnvSetting<T> is used to access an environment variable that controls program execution according to the value set in the environment. Currently, the legal types for T are bool, int, and string.

The TfEnvSetting facility is used to enable new features in the code that are still in "experimental" mode, and warn the user and/or QA that they are pushing the edge of the envelope by setting a non-standard value for these variables. Accordingly, the TfEnvSetting construct should be used as sparingly as possible in code.

In contrast, a variable that allows the user to customize program execution but is not an in-development code path should simply use TfGetenv() to access the variable. An example would be supplying a variable to override a default font or fontsize, for users who don't like the default program choice (and when there is no other way to set the preference).

Here is how to use the TfEnvSetting facility.

1. First, define your variable in a single .cpp file:

#include "pxr/base/tf/envSetting.h"

TF_DEFINE_ENV_SETTING(TDS_FILE_VERSION, 12,
                      "Default file format to use");

The first argument is the name of your variable; it is also the name for the variable you can set in your shell to set the value at runtime. The second argument is the default value. To create a bool variable, pass either true or false. To create a string variable, pass an explicit string(), i.e.

TF_DEFINE_ENV_SETTING(TDS_FILE_SUFFIX, string(".tid"),
                      "Default file-name suffix");

1. If you need to access this variable outside the .cpp file that defines the variable, put the following in a common header file:

extern TfEnvSetting<int> TDS_FILE_VERSION;
extern TfEnvSetting<string> TDS_FILE_SUFFIX;

1. At runtime, access your variable using TfGetEnvSetting(). For example:

int version = TfGetEnvSetting(TDS_FILE_VERSION);
string const& suffix =TfGetEnvSetting(TDS_FILE_SUFFIX);

You can also access a variable's value from Python:

from pxr import Tf
suffix = Tf.GetEnvSetting("TDS_FILE_SUFFIX")

Tf.GetEnvSetting() returns the value for the TfEnvSetting variable, or None if no such variable is defined in the currently loaded C++ code.

If a user's environment has a value for a TfEnvSetting variable that differs from the default, when the program starts or the module defining the TfEnvSetting variable is loaded, a warning messages is printed.

Additionally, at program startup time (or when lib/tf is first loaded), the environment variable PIXAR_TF_ENV_SETTING_FILE is examined. If this variable indicates a file that can be read, then the file is parsed, and should contain lines of the form key=value. For each line read, the environment variable key is set to value. For example:

$ setenv PIXAR_TF_ENV_SETTING_FILE /usr/anim/<UNIT>/admin/env-settings

$ cat /usr/anim/<UNIT>/admin/env-settings
TDS_DEF_VERSION=30
TDS_BLAH=
TDS_LONG_STRING=i am some long string with spaces

Blank lines in the file and lines where the first character is '#' are ignored. If the file itself cannot be read, no error is printed; however, if the file is malformed, errors are printed to stderr.

Definition in file envSetting.h.

Macro Definition Documentation

#define TF_DEFINE_ENV_SETTING	(		envVar,
			defValue,
			description
	)

Define an env setting named envVar with default value defValue and a descriptive string description.

Definition at line 179 of file envSetting.h.

Function Documentation

bool Tf_ChooseEnvSettingType

(

bool

)

int Tf_ChooseEnvSettingType

(

int

)

std::string Tf_ChooseEnvSettingType

(

char const *

)

template<class T >

void Tf_InitializeEnvSetting

(

TfEnvSetting< T > *

)

template<class T >

T const& TfGetEnvSetting ( TfEnvSetting< T > &  setting )

inline

Returns the value of the specified env setting, registered using TF_DEFINE_ENV_SETTING.

Definition at line 158 of file envSetting.h.