Respect KICAD_DOCS when searching for help files

On Linux, the documentation and help files are potentially installed to
a non-standard location (i.e., outside of /usr/share/doc/kicad/). This
can be the case when, e.g., multiple versions of KiCad are installed in
parallel. Making KICAD_DOCS available at run-time is the only viable
solution to allow the applications to find the help files in this case.

Fixes https://gitlab.com/kicad/code/kicad/issues/7874

CMakeLists.txt

@@ -1,7 +1,7 @@
 #
 #  This program source code file is part of KICAD, a free EDA CAD application.
 #
-#  Copyright (C) 2007-2020 Kicad Developers, see AUTHORS.txt for contributors.
+#  Copyright (C) 2007-2021 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
@@ -556,9 +556,13 @@ if( NOT APPLE )
     if( NOT IS_ABSOLUTE ${CMAKE_INSTALL_DATADIR} )
         set( KICAD_DATA ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_DATADIR}/kicad
             CACHE STRING "Location of KiCad data files." )
+        set( KICAD_DOCS ${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_DATADIR}/doc/kicad
+            CACHE STRING "Location of KiCad documentation files." )
     else()
         set( KICAD_DATA ${CMAKE_INSTALL_DATADIR}/kicad
             CACHE STRING "Location of KiCad data files." )
+        set( KICAD_DOCS ${CMAKE_INSTALL_DATADIR}/doc/kicad
+            CACHE STRING "Location of KiCad documentation files." )
     endif()
 
     set( KICAD_LIBRARY_DATA ${KICAD_DATA}
@@ -584,8 +588,6 @@ if( NOT APPLE )
             CACHE PATH "Location of KiCad user-loaded plugins" )
     endif()
 
-    set( KICAD_DOCS ${CMAKE_INSTALL_DATADIR}/doc/kicad
-        CACHE PATH "Location of KiCad documentation files." )
     set( KICAD_DEMOS ${KICAD_DATA}/demos
         CACHE PATH "Location of KiCad demo files." )
     set( KICAD_TEMPLATE ${KICAD_LIBRARY_DATA}/template

CMakeModules/config.h.cmake

@@ -89,6 +89,9 @@
 /// directory to be referenced by the program code.
 #define KICAD_LIBRARY_DATA              "@KICAD_LIBRARY_DATA@"
 
+/// Allows documentation install directory to be referenced by the program code.
+#define KICAD_DOCS                      "@KICAD_DOCS@"
+
 // Plugins directory
 #define KICAD_PLUGINDIR                 "@CMAKE_INSTALL_FULL_LIBDIR@"
 

common/paths.cpp

@@ -240,6 +240,22 @@ wxString PATHS::GetUserCachePath()
 }
 
 
+wxString PATHS::GetDocumentationPath()
+{
+    wxString path;
+
+#if defined( __WXMAC__ )
+    path = GetOSXKicadDataDir();
+#elif defined( __WXMSW__ )
+    path = Pgm().GetExecutablePath() + "../share/doc/kicad";
+#else
+    path = wxString::FromUTF8Unchecked( KICAD_DOCS );
+#endif
+
+    return path;
+}
+
+
 bool PATHS::EnsurePathExists( const wxString& aPath )
 {
     wxFileName path( aPath );

common/searchhelpfilefullpath.cpp

@@ -21,6 +21,7 @@
 
 #include <common.h>
 #include <pgm_base.h>
+#include <paths.h>
 #include <systemdirsappend.h>
 #include <trace_helpers.h>
 
@@ -33,7 +34,10 @@ wxString SearchHelpFileFullPath( const wxString& aBaseName )
     SEARCH_STACK basePaths;
     wxString     helpFile;
 
-    // the documentation is expected to be located in one of the system directories
+    // help files are most likely located in the documentation install path
+    basePaths.Add( PATHS::GetDocumentationPath() );
+
+    // just in case, add all known system directories to the search stack
     SystemDirsAppend( &basePaths );
 
 #if defined( DEBUG )

include/paths.h

@@ -98,6 +98,11 @@ public:
      */
     static wxString GetUserCachePath();
 
+    /**
+     * Gets the documentation path, which is the base path for help files
+     */
+    static wxString GetDocumentationPath();
+
     /**
      * Attempts to create a given path if it does not exist
      */