KiCad uses environment variables internally for determining the base paths for libraries, templates, and other assets that can be relocated by packagers or users. More...

#include <environment.h>

Public Member Functions
	ENV_VAR_ITEM (const wxString &aValue=wxEmptyString, bool aIsDefinedExternally=false)

	ENV_VAR_ITEM (const wxString &aKey, const wxString &aValue, const wxString &aDefaultValue=wxEmptyString)

	~ENV_VAR_ITEM () throw ()

bool	GetDefinedExternally () const

void	SetDefinedExternally (bool aIsDefinedExternally=true)

bool	GetDefinedInSettings () const

void	SetDefinedInSettings (bool aDefined=true)

wxString	GetKey () const

const wxString &	GetValue () const

void	SetValue (const wxString &aValue)

wxString	GetDefault () const

wxString	GetSettingsValue () const

void	SetSettingsValue (const wxString &aValue)

bool	GetBuiltin () const

bool	IsDefault () const
	Checks if the variable matches its default value (always false for non-built-in vars) More...

Private Attributes
wxString	m_key
	The environment variable string key. More...

wxString	m_value
	The environment variable string value. More...

wxString	m_defaultValue
	The default value, for built-in variables that are always defined. More...

wxString	m_settingsValue
	The value that was originally loaded from JSON. More...

bool	m_isBuiltin
	Set to true for KiCad built-in variables that are always defined one way or another. More...

bool	m_isDefinedExternally
	Flag to indicate if the environment variable was defined externally to the process. More...

bool	m_isDefinedInSettings
	Flag to indicate if the environment variable was defined in the settings file. More...

Detailed Description

KiCad uses environment variables internally for determining the base paths for libraries, templates, and other assets that can be relocated by packagers or users.

Because setting environment variables is not user-friendly on most platforms, KiCad supports two backing stores for these internal variables: the system environment, and the settings system.

We also want to make it possible to change the names and values of environment variables over time with minimal impact to users. Since most users do not customize these variables beyond any customization provided by the packager for their platform, an easy way to get this possibility with minimal user impact is to just not store environment variables if they match the internal (compiled-in) default.

The way environment variables are resolved is (highest to lowest priority):

1) Variables set at runtime via the Configure Paths dialog 2) Variables set in the system environment 3) Variables loaded from the settings system (stored in COMMON_SETTINGS)

For all KiCad system variables, we allow users to change the values at runtime via the Configure Paths dialog. If these variables were set in the system environment, we do not persist any changes made at runtime (and warn the user about this). If the variables were not set in the environment (meaning they were either the default value, or loaded from the settings system), we persist the changes via the settings system. Any variables that match the internal default are not saved in the settings, so that the internal defaults can be changed and the change will not be overridden by an old value cached in the settings file. A simple helper class to store environment variable definitions and values. This is used to initialize the environment variables that are built-in to KiCad, and also to store any variables created by the user.

Definition at line 59 of file include/settings/environment.h.

Constructor & Destructor Documentation

◆ ENV_VAR_ITEM() [1/2]

ENV_VAR_ITEM::ENV_VAR_ITEM	(	const wxString &	aValue = `wxEmptyString`,
		bool	aIsDefinedExternally = `false`
	)

inline

Definition at line 62 of file include/settings/environment.h.

 :
 m_value( aValue ),
 m_isBuiltin( true ),
 m_isDefinedExternally( aIsDefinedExternally ),
 m_isDefinedInSettings( false )
 {
 }

◆ ENV_VAR_ITEM() [2/2]

ENV_VAR_ITEM::ENV_VAR_ITEM	(	const wxString &	aKey,
		const wxString &	aValue,
		const wxString &	aDefaultValue = `wxEmptyString`
	)

inline

Definition at line 70 of file include/settings/environment.h.

 :
 m_key( aKey ),
 m_value( aValue ),
 m_defaultValue( aDefaultValue ),
 m_isBuiltin( true ),
 m_isDefinedExternally( false ),
 m_isDefinedInSettings( false )
 {
 }

◆ ~ENV_VAR_ITEM()

ENV_VAR_ITEM::~ENV_VAR_ITEM	(	)
throw	(
	)

inline

Definition at line 81 of file include/settings/environment.h.

81{} // tell SWIG no exception

Member Function Documentation

◆ GetBuiltin()

bool ENV_VAR_ITEM::GetBuiltin ( ) const

inline

Definition at line 102 of file include/settings/environment.h.

102{ return m_isBuiltin; }

References m_isBuiltin.

◆ GetDefault()

wxString ENV_VAR_ITEM::GetDefault ( ) const

inline

Definition at line 97 of file include/settings/environment.h.

97{ return m_defaultValue; }

References m_defaultValue.

◆ GetDefinedExternally()

bool ENV_VAR_ITEM::GetDefinedExternally ( ) const

inline

Definition at line 83 of file include/settings/environment.h.

83{ return m_isDefinedExternally; }

References m_isDefinedExternally.

◆ GetDefinedInSettings()

bool ENV_VAR_ITEM::GetDefinedInSettings ( ) const

inline

Definition at line 89 of file include/settings/environment.h.

89{ return m_isDefinedInSettings; }

References m_isDefinedInSettings.

◆ GetKey()

wxString ENV_VAR_ITEM::GetKey ( ) const

inline

Definition at line 92 of file include/settings/environment.h.

92{ return m_key; }

References m_key.

◆ GetSettingsValue()

wxString ENV_VAR_ITEM::GetSettingsValue ( ) const

inline

Definition at line 99 of file include/settings/environment.h.

99{ return m_settingsValue; }

ENV_VAR_ITEM::m_settingsValue

wxString m_settingsValue

The value that was originally loaded from JSON.

Definition: include/settings/environment.h:124

References m_settingsValue.

◆ GetValue()

const wxString & ENV_VAR_ITEM::GetValue ( ) const

inline

Definition at line 94 of file include/settings/environment.h.

94{ return m_value; }

References m_value.

◆ IsDefault()

bool ENV_VAR_ITEM::IsDefault ( ) const

inline

Checks if the variable matches its default value (always false for non-built-in vars)

Returns: true if a built-in variable matches its default

Definition at line 108 of file include/settings/environment.h.

 {
 return m_isBuiltin && m_value == m_defaultValue;
 }

References m_defaultValue, m_isBuiltin, and m_value.

◆ SetDefinedExternally()

void ENV_VAR_ITEM::SetDefinedExternally ( bool aIsDefinedExternally = true )

inline

Definition at line 84 of file include/settings/environment.h.

 {
 m_isDefinedExternally = aIsDefinedExternally;
 }

References m_isDefinedExternally.

◆ SetDefinedInSettings()

void ENV_VAR_ITEM::SetDefinedInSettings ( bool aDefined = true )

inline

Definition at line 90 of file include/settings/environment.h.

90{ m_isDefinedInSettings = aDefined; }

References m_isDefinedInSettings.

◆ SetSettingsValue()

void ENV_VAR_ITEM::SetSettingsValue ( const wxString & aValue )

inline

Definition at line 100 of file include/settings/environment.h.

100{ m_settingsValue = aValue; }

References m_settingsValue.

◆ SetValue()

void ENV_VAR_ITEM::SetValue ( const wxString & aValue )

inline

Definition at line 95 of file include/settings/environment.h.

95{ m_value = aValue; }

References m_value.

Member Data Documentation

◆ m_defaultValue

wxString ENV_VAR_ITEM::m_defaultValue

private

The default value, for built-in variables that are always defined.

Definition at line 121 of file include/settings/environment.h.

Referenced by GetDefault(), and IsDefault().

◆ m_isBuiltin

bool ENV_VAR_ITEM::m_isBuiltin

private

Set to true for KiCad built-in variables that are always defined one way or another.

Definition at line 127 of file include/settings/environment.h.

Referenced by GetBuiltin(), and IsDefault().

◆ m_isDefinedExternally

bool ENV_VAR_ITEM::m_isDefinedExternally

private

Flag to indicate if the environment variable was defined externally to the process.

Definition at line 130 of file include/settings/environment.h.

Referenced by GetDefinedExternally(), and SetDefinedExternally().

◆ m_isDefinedInSettings

bool ENV_VAR_ITEM::m_isDefinedInSettings

private

Flag to indicate if the environment variable was defined in the settings file.

Definition at line 133 of file include/settings/environment.h.

Referenced by GetDefinedInSettings(), and SetDefinedInSettings().

◆ m_key

wxString ENV_VAR_ITEM::m_key

private

The environment variable string key.

Definition at line 115 of file include/settings/environment.h.

Referenced by GetKey().

◆ m_settingsValue

wxString ENV_VAR_ITEM::m_settingsValue

private

The value that was originally loaded from JSON.

Definition at line 124 of file include/settings/environment.h.

Referenced by GetSettingsValue(), and SetSettingsValue().

◆ m_value

wxString ENV_VAR_ITEM::m_value

private

The environment variable string value.

Definition at line 118 of file include/settings/environment.h.

Referenced by GetValue(), IsDefault(), and SetValue().

The documentation for this class was generated from the following file:

include/settings/environment.h

Public Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ENV_VAR_ITEM() [1/2]

◆ ENV_VAR_ITEM() [2/2]

◆ ~ENV_VAR_ITEM()

Member Function Documentation

◆ GetBuiltin()

◆ GetDefault()

◆ GetDefinedExternally()

◆ GetDefinedInSettings()

◆ GetKey()

◆ GetSettingsValue()

◆ GetValue()

◆ IsDefault()

◆ SetDefinedExternally()

◆ SetDefinedInSettings()

◆ SetSettingsValue()

◆ SetValue()

Member Data Documentation

◆ m_defaultValue

◆ m_isBuiltin

◆ m_isDefinedExternally

◆ m_isDefinedInSettings

◆ m_key

◆ m_settingsValue

◆ m_value