Centralise utilities for env variables.

This puts generic logic for KiCad environment vars in
one place.

Also updates the DIALOG_CONFIGURE_PATHS help to document
the new KICAD_USER_TEMPLATE_DIR and KICAD_TEMPLATE_DIR.

common/CMakeLists.txt

@@ -271,6 +271,7 @@ set( COMMON_SRCS
     eda_pattern_match.cpp
     eda_size_ctrl.cpp
     env_paths.cpp
+    env_vars.cpp
     exceptions.cpp
     executable_names.cpp
     filename_resolver.cpp

common/dialogs/dialog_configure_paths.cpp

@@ -29,6 +29,7 @@
 #include <validators.h>
 #include <html_messagebox.h>
 #include <filename_resolver.h>
+#include <env_vars.h>
 #include <widgets/wx_grid.h>
 #include <widgets/grid_text_button_helpers.h>
 
@@ -549,29 +550,21 @@ void DIALOG_CONFIGURE_PATHS::OnHelp( wxCommandEvent& event )
                       "level.  Environment variables defined at the system or user level "
                       "take precedence over the ones defined in this table.  This means the "
                       "values in this table are ignored." );
-    msg << wxT( "<br><br><b>" );
+    msg << "<br><br><b>";
     msg << _( "To ensure environment variable names are valid on all platforms, the name field "
               "will only accept upper case letters, digits, and the underscore characters." );
-    msg << wxT( "</b><br><br>" );
+    msg << "</b>";
-    msg << _( "<b>KICAD_SYMBOL_DIR</b> is the base path of the locally installed symbol libraries." );
+
-    msg << wxT( "<br><br>" );
+    for( const auto& var: GetPredefinedEnvVars() )
-    msg << _( "<b>KIGITHUB</b> is used by KiCad to define the URL of the repository "
+    {
-              "of the official KiCad footprint libraries." );
+        msg << "<br><br><b>" << var << "</b>";
-    msg << wxT( "<br><br>" );
+
-    msg << _( "<b>KISYS3DMOD</b> is the base path of system footprint 3D "
+        const auto desc = LookUpEnvVarHelp( var );
-              "shapes (.3Dshapes folders)." );
+
-    msg << wxT( "<br><br>" );
+        if( desc.size() > 0 )
-    msg << _( "<b>KISYSMOD</b> is the base path of locally installed system "
+            msg << ": " << desc;
-              "footprint libraries (.pretty folders)." );
+
-    msg << wxT( "<br><br>" );
+    }
-    msg << _( "<b>KIPRJMOD</b> is internally defined by KiCad (cannot be edited) and is set "
-              "to the absolute path of the currently loaded project file.  This environment "
-              "variable can be used to define files and paths relative to the currently loaded "
-              "project.  For instance, ${KIPRJMOD}/libs/footprints.pretty can be defined as a "
-              "folder containing a project specific footprint library named footprints.pretty." );
-    msg << wxT( "<br><br>" );
-    msg << _( "<b>KICAD_PTEMPLATES</b> is optional and can be defined if you want to "
-              "create your own project templates folder." );
 
     HTML_MESSAGE_BOX dlg( GetParent(), _( "Environment Variable Help" ) );
     dlg.SetDialogSizeInDU( 400, 250 );
@@ -579,30 +572,3 @@ void DIALOG_CONFIGURE_PATHS::OnHelp( wxCommandEvent& event )
     dlg.AddHTML_Text( msg );
     dlg.ShowModal();
 }
-
-
-bool DIALOG_CONFIGURE_PATHS::IsEnvVarImmutable( const wxString aEnvVar )
-{
-    /*
-     * TODO - Instead of defining these values here,
-     * extract them from elsewhere in the program
-     * (where they are originally defined)
-     */
-
-    static const wxString immutable[] = {
-            "KIGITHUB",
-            "KISYS3DMOD",
-            "KISYSMOD",
-            "KIPRJMOD",
-            "KICAD_PTEMPLATES",
-            "KICAD_SYMBOL_DIR"
-    };
-
-    for( const auto& ii : immutable )
-    {
-        if( aEnvVar.Cmp( ii ) == 0 )
-            return true;
-    }
-
-    return false;
-}

common/env_vars.cpp

@@ -0,0 +1,105 @@
+/*
+ * This program source code file is part of KiCad, a free EDA CAD application.
+ *
+ * Copyright (C) 2018 KiCad Developers, see AUTHORS.txt for contributors.
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the
+ * Free Software Foundation, either version 3 of the License, or (at your
+ * option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <env_vars.h>
+
+#include <map>
+
+#include <common.h>
+
+using STRING_MAP = std::map<wxString, wxString>;
+
+/*
+ * List of pre-defined environment variables
+ *
+ * TODO - Instead of defining these values here,
+ * extract them from elsewhere in the program
+ * (where they are originally defined)
+ */
+static const ENV_VAR_LIST predefined_env_vars = {
+    "KIPRJMOD",
+    "KICAD_SYMBOL_DIR",
+    "KISYS3DMOD",
+    "KISYSMOD",
+    "KIGITHUB",
+    "KICAD_TEMPLATE_DIR",
+    "KICAD_USER_TEMPLATE_DIR",
+    "KICAD_PTEMPLATES",
+};
+
+
+bool IsEnvVarImmutable( const wxString& aEnvVar )
+{
+    for( const auto& s: predefined_env_vars )
+    {
+        if( s == aEnvVar )
+            return true;
+    }
+
+    return false;
+}
+
+
+const ENV_VAR_LIST& GetPredefinedEnvVars()
+{
+    return predefined_env_vars;
+}
+
+
+void initialiseEnvVarHelp( STRING_MAP& aMap )
+{
+    // Set up dynamically, as we want to be able to use _() translations,
+    // which can't be done statically
+    aMap["KISYSMOD"] =
+        _( "The base path of locally installed system "
+            "footprint libraries (.pretty folders).");
+    aMap["KISYS3DMOD"] =
+        _( "The base path of system footprint 3D shapes (.3Dshapes folders).");
+    aMap["KICAD_SYMBOL_DIR"] =
+        _( "The base path of the locally installed symbol libraries.");
+    aMap["KIGITHUB"] =
+        _( "Used by KiCad to define the URL of the repository "
+            "of the official KiCad footprint libraries.");
+    aMap["KICAD_TEMPLATE_DIR"] =
+        _( "A directory containing project templates installed with KiCad.");
+    aMap["KICAD_USER_TEMPLATE_DIR"] =
+        _( "Optional. Can be defined if you want to create your own project "
+           "templates folder.");
+    aMap["KIPRJMOD"] =
+        _("Internally defined by KiCad (cannot be edited) and is set "
+          "to the absolute path of the currently loaded project file.  This environment "
+          "variable can be used to define files and paths relative to the currently loaded "
+          "project.  For instance, ${KIPRJMOD}/libs/footprints.pretty can be defined as a "
+          "folder containing a project specific footprint library named footprints.pretty." );
+
+    // Deprecated vars
+    aMap["KICAD_PTEMPLATES"] =
+        _( "Deprecated version of KICAD_TEMPLATE_DIR.");
+}
+
+
+wxString LookUpEnvVarHelp( const wxString& aEnvVar )
+{
+    static STRING_MAP env_var_help_text;
+
+    if( env_var_help_text.size() == 0 )
+        initialiseEnvVarHelp( env_var_help_text );
+
+    return env_var_help_text[aEnvVar];
+}

include/dialog_configure_paths.h

@@ -62,11 +62,6 @@ protected:
     void AppendEnvVar( const wxString& aName, const wxString& aPath, bool isExternal );
     void AppendSearchPath( const wxString& aName, const wxString& aPath, const wxString& aDesc );
 
-    /**
-     * Determine if a particular ENV_VAR is protected
-     */
-    bool IsEnvVarImmutable( const wxString aEnvVar );
-
 private:
     wxString            m_errorMsg;
     wxGrid*             m_errorGrid;

include/env_vars.h

@@ -0,0 +1,59 @@
+/*
+ * This program source code file is part of KiCad, a free EDA CAD application.
+ *
+ * Copyright (C) 2018 KiCad Developers, see AUTHORS.txt for contributors.
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License as published by the
+ * Free Software Foundation, either version 3 of the License, or (at your
+ * option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+/**
+ * @file env_vars.h
+ * Functions to provide helpful hints about what environment vars do
+ */
+
+#ifndef ENV_VARS_H
+#define ENV_VARS_H
+
+#include <wx/string.h>
+#include <vector>
+
+using ENV_VAR_LIST = std::vector<wxString>;
+
+/**
+ * Determine if an environment variable is "predefined", i.e. if the
+ * name of the variable is special to KiCad, and isn't just a user-specified
+ * substitution name.
+ * @param  aEnvVar the variable to check
+ * @return         true if predefined
+ */
+bool IsEnvVarImmutable( const wxString& aEnvVar );
+
+/**
+ * Get the list of pre-defined environment variables.
+ */
+const ENV_VAR_LIST& GetPredefinedEnvVars();
+
+/**
+ * Look up long-form help text for a given environment variable.
+ *
+ * This is intended for use in more verbose help resources (as opposed to
+ * tooltip text)
+ *
+ * @param  aEnvVar The variable to look up
+ * @return         A string with help for that variable. Empty if
+ *                 no help available for this variable.
+ */
+wxString LookUpEnvVarHelp( const wxString& aEnvVar );
+
+#endif /* ENV_VARS_H */