KiCad PCB EDA Suite
Loading...
Searching...
No Matches
env_vars.cpp
Go to the documentation of this file.
1/*
2 * This program source code file is part of KiCad, a free EDA CAD application.
3 *
4 * Copyright The KiCad Developers, see AUTHORS.txt for contributors.
5 *
6 * This program is free software: you can redistribute it and/or modify it
7 * under the terms of the GNU General Public License as published by the
8 * Free Software Foundation, either version 3 of the License, or (at your
9 * option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program. If not, see <https://www.gnu.org/licenses/>.
18 */
19
20#include <build_version.h>
21#include <env_vars.h>
23#include <core/kicad_algo.h>
24
25#include <algorithm>
26#include <map>
27
28#include <wx/regex.h>
29#include <wx/translation.h>
30#include <wx/utils.h>
31
38static const std::vector<wxString> predefinedEnvVars = {
39 wxS( "KIPRJMOD" ),
40 ENV_VAR::GetVersionedEnvVarName( wxS( "SYMBOL_DIR" ) ),
41 ENV_VAR::GetVersionedEnvVarName( wxS( "3DMODEL_DIR" ) ),
42 ENV_VAR::GetVersionedEnvVarName( wxS( "FOOTPRINT_DIR" ) ),
43 ENV_VAR::GetVersionedEnvVarName( wxS( "TEMPLATE_DIR" ) ),
44 wxS( "KICAD_USER_TEMPLATE_DIR" ),
45 wxS( "KICAD_PTEMPLATES" ),
46 wxS( "KICAD_LTSPICE_LIB" ),
47 ENV_VAR::GetVersionedEnvVarName( wxS( "3RD_PARTY" ) ),
48};
49
50
51bool ENV_VAR::IsEnvVarImmutable( const wxString& aEnvVar )
52{
53 for( const wxString& s : predefinedEnvVars )
54 {
55 if( s == aEnvVar )
56 return true;
57 }
58
59 return false;
60}
61
62
63const std::vector<wxString>& ENV_VAR::GetPredefinedEnvVars()
64{
65 return predefinedEnvVars;
66}
67
68
69void ENV_VAR::GetEnvVarAutocompleteTokens( wxArrayString* aVars )
70{
71 for( const wxString& var : ENV_VAR::GetPredefinedEnvVars() )
72 {
73 if( !alg::contains( *aVars, var ) )
74 aVars->push_back( var );
75 }
76}
77
78
79wxString ENV_VAR::GetVersionedEnvVarName( const wxString& aBaseName )
80{
81 int version = 0;
82 std::tie(version, std::ignore, std::ignore) = GetMajorMinorPatchTuple();
83
84 return wxString::Format( "KICAD%d_%s", version, aBaseName );
85}
86
87
88bool ENV_VAR::IsVersionedEnvVar( const wxString& aName, const wxString& aBaseName )
89{
90 static const wxString prefix = wxS( "KICAD" );
91 const wxString suffix = wxS( "_" ) + aBaseName;
92
93 if( !aName.StartsWith( prefix ) || !aName.EndsWith( suffix ) )
94 return false;
95
96 wxString version = aName.Mid( prefix.length(), aName.length() - prefix.length() - suffix.length() );
97
98 return !version.IsEmpty()
99 && std::all_of( version.begin(), version.end(),
100 []( wxUniChar c ) { return wxIsdigit( c ); } );
101}
102
103
104std::optional<wxString> ENV_VAR::GetVersionedEnvVarValue( const ENV_VAR_MAP& aMap,
105 const wxString& aBaseName )
106{
107 wxString exactMatch = ENV_VAR::GetVersionedEnvVarName( aBaseName );
108
109 if( aMap.count( exactMatch ) )
110 return aMap.at( exactMatch ).GetValue();
111
112 for( const auto& [k, v] : aMap )
113 {
114 if( ENV_VAR::IsVersionedEnvVar( k, aBaseName ) )
115 return v.GetValue();
116 }
117
118 return std::nullopt;
119}
120
121
122static void initialiseEnvVarHelp( std::map<wxString, wxString>& aMap )
123{
124 // Set up dynamically, as we want to be able to use _() translations,
125 // which can't be done statically
126 aMap[ENV_VAR::GetVersionedEnvVarName( wxS( "FOOTPRINT_DIR" ) )] =
127 _( "The base path of locally installed system footprint libraries (.pretty folders)." );
128
129 aMap[ENV_VAR::GetVersionedEnvVarName( wxS( "3DMODEL_DIR" ) )] =
130 _( "The base path of system footprint 3D shapes (.3Dshapes folders)." );
131
132 aMap[ENV_VAR::GetVersionedEnvVarName( wxS( "SYMBOL_DIR" ) )] =
133 _( "The base path of the locally installed symbol libraries." );
134
135 aMap[ENV_VAR::GetVersionedEnvVarName( wxS( "TEMPLATE_DIR" ) )] =
136 _( "A directory containing project templates installed with KiCad." );
137
138 aMap[wxS( "KICAD_USER_TEMPLATE_DIR" )] =
139 _( "Optional. Can be defined if you want to create your own project templates folder." );
140
141 aMap[wxS( "KICAD_LTSPICE_LIB" )] =
142 _( "Optional. The LTspice library folder, which holds the sub and sym folders, used when importing "
143 "LTspice schematics." );
144
145 aMap[ENV_VAR::GetVersionedEnvVarName( wxS( "3RD_PARTY" ) )] =
146 _( "A directory containing 3rd party plugins, libraries and other downloadable content." );
147
148 aMap[wxS( "KIPRJMOD" )] =
149 _( "Internally defined by KiCad (cannot be edited) and is set to the absolute path of the currently "
150 "loaded project file. This environment variable can be used to define files and paths relative "
151 "to the currently loaded project. For instance, ${KIPRJMOD}/libs/footprints.pretty can be "
152 "defined as a folder containing a project specific footprint library named footprints.pretty." );
153
154 aMap[ENV_VAR::GetVersionedEnvVarName( wxS( "SCRIPTING_DIR" ) )] =
155 _( "A directory containing system-wide scripts installed with KiCad." );
156
157 aMap[ENV_VAR::GetVersionedEnvVarName( wxS( "USER_SCRIPTING_DIR" ) )] =
158 _( "A directory containing user-specific scripts installed with KiCad." );
159
160 // Deprecated vars
161#define DEP( var ) wxString::Format( _( "Deprecated version of %s." ), var )
162
163 aMap[wxS( "KICAD_PTEMPLATES" )] = DEP( ENV_VAR::GetVersionedEnvVarName( wxS( "TEMPLATE_DIR" ) ) );
164 aMap[wxS( "KISYS3DMOD" )] = DEP( ENV_VAR::GetVersionedEnvVarName( wxS( "3DMODEL_DIR" ) ) );
165 aMap[wxS( "KISYSMOD" )] = DEP( ENV_VAR::GetVersionedEnvVarName( wxS( "FOOTPRINT_DIR" ) ) );
166 aMap[wxS( "KICAD_SYMBOL_DIR" )] = DEP( ENV_VAR::GetVersionedEnvVarName( wxS( "SYMBOL_DIR" ) ) );
167
168#undef DEP
169}
170
171
172wxString ENV_VAR::LookUpEnvVarHelp( const wxString& aEnvVar )
173{
174 static std::map<wxString, wxString> envVarHelpText;
175
176 if( envVarHelpText.size() == 0 )
177 initialiseEnvVarHelp( envVarHelpText );
178
179 return envVarHelpText[ aEnvVar ];
180}
181
182
183template<>
184std::optional<double> ENV_VAR::GetEnvVar( const wxString& aEnvVarName )
185{
186 wxString env;
187
188 if( wxGetEnv( aEnvVarName, &env ) )
189 {
190 double value;
191
192 if( env.ToDouble( &value ) )
193 return value;
194 }
195
196 return std::nullopt;
197}
198
199
200template<>
201std::optional<wxString> ENV_VAR::GetEnvVar( const wxString& aEnvVarName )
202{
203 std::optional<wxString> optValue;
204 wxString env;
205
206 if( wxGetEnv( aEnvVarName, &env ) )
207 optValue = env;
208
209 return optValue;
210}
const std::tuple< int, int, int > & GetMajorMinorPatchTuple()
Get the build version numbers as a tuple.
#define _(s)
static void initialiseEnvVarHelp(std::map< wxString, wxString > &aMap)
Definition env_vars.cpp:122
#define DEP(var)
static const std::vector< wxString > predefinedEnvVars
List of pre-defined environment variables.
Definition env_vars.cpp:38
Functions related to environment variables, including help functions.
std::map< wxString, ENV_VAR_ITEM > ENV_VAR_MAP
KICOMMON_API wxString LookUpEnvVarHelp(const wxString &aEnvVar)
Look up long-form help text for a given environment variable.
Definition env_vars.cpp:172
KICOMMON_API void GetEnvVarAutocompleteTokens(wxArrayString *aVars)
Return autocomplete tokens for environment variables for Scintilla.
Definition env_vars.cpp:69
KICOMMON_API std::optional< VAL_TYPE > GetEnvVar(const wxString &aEnvVarName)
Get an environment variable as a specific type, if set correctly.
KICOMMON_API bool IsVersionedEnvVar(const wxString &aName, const wxString &aBaseName)
Test whether a name is a versioned KiCad environment variable for the given base, i....
Definition env_vars.cpp:88
KICOMMON_API std::optional< wxString > GetVersionedEnvVarValue(const std::map< wxString, ENV_VAR_ITEM > &aMap, const wxString &aBaseName)
Attempt to retrieve the value of a versioned environment variable, such as KICAD8_TEMPLATE_DIR.
Definition env_vars.cpp:104
KICOMMON_API const std::vector< wxString > & GetPredefinedEnvVars()
Get the list of pre-defined environment variables.
Definition env_vars.cpp:63
KICOMMON_API wxString GetVersionedEnvVarName(const wxString &aBaseName)
Construct a versioned environment variable based on this KiCad major version.
Definition env_vars.cpp:79
KICOMMON_API bool IsEnvVarImmutable(const wxString &aEnvVar)
Determine if an environment variable is "predefined", i.e.
Definition env_vars.cpp:51
bool contains(const _Container &__container, _Value __value)
Returns true if the container contains the given value.
Definition kicad_algo.h:96