Clarify the HUNTER_ROOT debugging functionality (#13)

* Minor improvements to HunterGate.cmake

* Clarify the README

README.md

@@ -15,11 +15,12 @@ The gate project will download the latest [packages archive release](https://git
 The gate project will issue `hunter_add_package` to all packages specified in `HUNTER_PACKAGES` list. For every package it will create a `hunter_config`
 in which `VERSION` and `CMAKE_ARGS` variables will be set.
 
-For manual configuration of `hunter_config` file you can set the `HUNTER_LOCAL_CONFIG`, `HUNTER_GLOBAL_CONFIG`, or `HUNTER_FILEPATH_CONFIG` variables.
+For manual configuration of the `hunter_config` file you can set the `HUNTER_LOCAL_CONFIG`, `HUNTER_GLOBAL_CONFIG`, or `HUNTER_FILEPATH_CONFIG` variables.
 
 The gate project will set `CMAKE_BUILD_TYPE` as `HUNTER_CONFIGURATION_TYPES`, so that if you're building `Release` you won't be getting a `Debug` build of the packages.
 
 The gate project will create a `HunterToolchain.cmake` file which will set up the `CMAKE_PREFIX_PATH` and `CMAKE_FIND_ROOT_PATH` variables with the installed path of the Hunter packages.
+
 If a `CMAKE_TOOLCHAIN_FILE` was used during compilation, it will be included in the `HunterToolchain.cmake` file.
 
 ## Usage
@@ -43,6 +44,7 @@ target_link_libraries(myapp PRIVATE dlib::dlib)
 ```
 
 ## Usage with custom CMake variables per package
+
 ```cmake
 set(HUNTER_pcre2_CMAKE_ARGS
   PCRE2_BUILD_PCRE2_8=OFF
@@ -54,18 +56,21 @@ set(HUNTER_PACKAGES pcre2)
 ```
 
 ## Usage with package components
+
 ```cmake
 set(HUNTER_Boost_COMPONENTS Filesystem Python)
 set(HUNTER_PACKAGES Boost)
 ```
 
 ## Usage with specific package version
+
 ```cmake
 set(HUNTER_fmt_VERSION 5.3.0)
 set(HUNTER_PACKAGES fmt)
 ```
 
-## Usage with specific Hunter Gate
+## Usage with specific Hunter archive
+
 ```cmake
 set(HUNTER_URL "https://github.com/cpp-pm/hunter/archive/v0.23.224.tar.gz")
 set(HUNTER_SHA1 "18e57a43efc435f2e1dae1291e82e42afbf940be")
@@ -146,6 +151,7 @@ cmake -DCMAKE_TOOLCHAIN_FILE=/path/to/your/3rdparty/build/HunterToolchain.cmake
 ```
 
 ## Usage with explicit config
+
 ```cmake
 file(WRITE ${CMAKE_BUILD_DIR}/HunterConfig.cmake [=[
 hunter_config(zlib VERSION 1.2.8)
@@ -178,24 +184,25 @@ add_executable(boo main.c)
 target_link_libraries(boo PRIVATE ZLIB::zlib PCRE2::PCRE2)
 ```
 
-## Usage (manual)
+## Usage (local HunterGate.cmake)
 
-* Copy file `HunterGate.cmake` to project
-* Include gate file: `include("cmake/HunterGate.cmake")`
+* Copy `cmake/HunterGate.cmake` to your project
 * Put any valid [Hunter](https://github.com/cpp-pm/hunter/releases) archive with `SHA1` hash:
 ```cmake
+include("cmake/HunterGate.cmake")
 HunterGate(
     URL "https://github.com/cpp-pm/hunter/archive/v0.23.224.tar.gz"
     SHA1 "18e57a43efc435f2e1dae1291e82e42afbf940be"
 )
 ```
 
-## Usage (custom config)
+## Usage (local HunterGate.cmake + custom config)
 
-Optionally custom [config.cmake][1] file can be specified. File may has different locations:
+Optionally custom [config.cmake](https://github.com/cpp-pm/hunter/blob/master/cmake/configs/default.cmake) file can be specified. File may has different locations:
 
 * `GLOBAL`. The one from Hunter archive:
 ```cmake
+include("cmake/HunterGate.cmake")
 HunterGate(
     URL "https://github.com/cpp-pm/hunter/archive/v0.23.224.tar.gz"
     SHA1 "18e57a43efc435f2e1dae1291e82e42afbf940be"
@@ -204,52 +211,68 @@ HunterGate(
         # default `${HUNTER_SELF}/cmake/configs/default.cmake`
 )
 ```
+
 * `LOCAL`. Default local config.
 ```cmake
+include("cmake/HunterGate.cmake")
 HunterGate(
     URL "https://github.com/cpp-pm/hunter/archive/v0.23.224.tar.gz"
     SHA1 "18e57a43efc435f2e1dae1291e82e42afbf940be"
     LOCAL # load `${CMAKE_CURRENT_LIST_DIR}/cmake/Hunter/config.cmake`
 )
 ```
+
 * `FILEPATH`. Any location.
 ```cmake
+include("cmake/HunterGate.cmake")
 HunterGate(
     URL "https://github.com/cpp-pm/hunter/archive/v0.23.224.tar.gz"
     SHA1 "18e57a43efc435f2e1dae1291e82e42afbf940be"
     FILEPATH "/any/path/to/config.cmake"
 )
 ```
 
-* [Example](https://github.com/ruslo/hunter/wiki/example.custom.config.id)
+Example custom `config.cmake`:
+
+```cmake
+hunter_config(zlib VERSION 1.2.8)
+
+hunter_config(pcre2
+  VERSION 10.13-p0
+  CMAKE_ARGS
+    PCRE2_BUILD_PCRE2_8=OFF
+    PCRE2_BUILD_PCRE2_16=ON
+    PCRE2_BUILD_PCRE2_32=OFF
+    PCRE2_SUPPORT_JIT=ON
+)
+```
+
+See the [hunter_config](https://hunter.readthedocs.io/en/latest/reference/user-modules/hunter_config.html) documentation for details.
 
-### Notes
+## Notes
 
-* If you're in process of patching Hunter and have a HUNTER_ROOT pointed to git repository location then HunterGate will not use `URL` and `SHA1` values. It means when you update `SHA1` of Hunter archive new commits/fixes will not be applied at all. In this case you have to update your git repo manually (i.e. do `git pull`)
-* You don't need to specify [hunter_config][2] command for all projects. Set version of the package you're interested in - others will be used from default `config.cmake`.
+* If you're in process of patching Hunter and have a `HUNTER_ROOT` pointed to a local copy of [Hunter](https://github.com/cpp-pm/hunter) then `HunterGate` will not use `URL` and `SHA1` values. It means when you update `SHA1` of Hunter archive new commits/fixes will not be applied at all. In this case you have to update your git repo manually (i.e. do `git pull`). This can also be useful for debugging Hunter.
+* You don't need to specify [hunter_config](https://hunter.readthedocs.io/en/latest/reference/user-modules/hunter_config.html) command for all projects. Set version of the package you're interested in - others will be used from default `config.cmake`.
 * If you want to get full control of what Hunter-SHA1 root directories you want to auto-install you can set [HUNTER_DISABLE_AUTOINSTALL](https://github.com/ruslo/hunter/wiki/CMake-Variables-%28User%29#hunter_disable_autoinstall-environment-variable) environment variable and use [HUNTER_RUN_INSTALL=YES](https://github.com/ruslo/hunter/wiki/CMake-Variables-%28User%29#hunter_run_install) CMake variable to allow installations explicitly.
 
-## Effects
+## Rough description of the inner workings
+
 * Try to detect `Hunter`:
  * test CMake variable `HUNTER_ROOT` (control, shared downloads and builds)
  * test environment variable `HUNTER_ROOT` (**recommended**: control, shared downloads and builds)
  * test directory `${HOME}/.hunter` (shared downloads and builds)
  * test directory `${SYSTEMDRIVE}/.hunter` (shared downloads and builds, windows only)
  * test directory `${USERPROFILE}/.hunter` (shared downloads and builds, windows only)
 * Set `HUNTER_GATE_*` variables
+* Try to include local Hunter master file `include("${HUNTER_ROOT}/cmake/Hunter")` (mainly for debugging)
+* Download Hunter from the specified `URL` and `SHA1`
 * Include Hunter master file `include("${HUNTER_SELF}/cmake/Hunter")`
 
 ## Flowchart (for developers)
-![flowchart](https://raw.githubusercontent.com/hunter-packages/gate/master/wiki/flowchart.png)
 
-## Examples
-* [This](https://github.com/hunter-packages/gate/blob/master/CMakeLists.txt)
-* [Simple](https://github.com/forexample/hunter-simple)
-* [Weather](https://github.com/ruslo/weather)
+![flowchart](https://raw.githubusercontent.com/hunter-packages/gate/master/wiki/flowchart.png)
 
 ## Links
-* [Hunter](https://github.com/cpp-pm/hunter)
-* [Some packages](https://github.com/ruslo/hunter/wiki/Packages)
 
-[1]: https://github.com/ruslo/hunter/blob/master/cmake/configs/default.cmake
-[2]: https://github.com/ruslo/hunter/wiki/Hunter-modules#hunter_config
+* [Hunter](https://github.com/cpp-pm/hunter)
+* [Some packages](https://hunter.readthedocs.io/en/latest/packages.html)

cmake/HunterGate.cmake

@@ -59,8 +59,9 @@ include(CMakeParseArguments) # cmake_parse_arguments
 option(HUNTER_STATUS_PRINT "Print working status" ON)
 option(HUNTER_STATUS_DEBUG "Print a lot info" OFF)
 option(HUNTER_TLS_VERIFY "Enable/disable TLS certificate checking on downloads" ON)
+set(HUNTER_ROOT "" CACHE FILEPATH "Override the HUNTER_ROOT.")
 
-set(HUNTER_ERROR_PAGE "https://docs.hunter.sh/en/latest/reference/errors")
+set(HUNTER_ERROR_PAGE "https://hunter.readthedocs.io/en/latest/reference/errors")
 
 function(hunter_gate_status_print)
   if(HUNTER_STATUS_PRINT OR HUNTER_STATUS_DEBUG)
@@ -148,42 +149,37 @@ endfunction()
 # Set HUNTER_GATE_ROOT cmake variable to suitable value.
 function(hunter_gate_detect_root)
   # Check CMake variable
-  string(COMPARE NOTEQUAL "${HUNTER_ROOT}" "" not_empty)
-  if(not_empty)
+  if(HUNTER_ROOT)
     set(HUNTER_GATE_ROOT "${HUNTER_ROOT}" PARENT_SCOPE)
     hunter_gate_status_debug("HUNTER_ROOT detected by cmake variable")
     return()
   endif()
 
   # Check environment variable
-  string(COMPARE NOTEQUAL "$ENV{HUNTER_ROOT}" "" not_empty)
-  if(not_empty)
+  if(DEFINED ENV{HUNTER_ROOT})
     set(HUNTER_GATE_ROOT "$ENV{HUNTER_ROOT}" PARENT_SCOPE)
     hunter_gate_status_debug("HUNTER_ROOT detected by environment variable")
     return()
   endif()
 
   # Check HOME environment variable
-  string(COMPARE NOTEQUAL "$ENV{HOME}" "" result)
-  if(result)
+  if(DEFINED ENV{HOME})
     set(HUNTER_GATE_ROOT "$ENV{HOME}/.hunter" PARENT_SCOPE)
     hunter_gate_status_debug("HUNTER_ROOT set using HOME environment variable")
     return()
   endif()
 
   # Check SYSTEMDRIVE and USERPROFILE environment variable (windows only)
   if(WIN32)
-    string(COMPARE NOTEQUAL "$ENV{SYSTEMDRIVE}" "" result)
-    if(result)
+    if(DEFINED ENV{SYSTEMDRIVE})
       set(HUNTER_GATE_ROOT "$ENV{SYSTEMDRIVE}/.hunter" PARENT_SCOPE)
       hunter_gate_status_debug(
           "HUNTER_ROOT set using SYSTEMDRIVE environment variable"
       )
       return()
     endif()
 
-    string(COMPARE NOTEQUAL "$ENV{USERPROFILE}" "" result)
-    if(result)
+    if(DEFINED ENV{USERPROFILE})
       set(HUNTER_GATE_ROOT "$ENV{USERPROFILE}/.hunter" PARENT_SCOPE)
       hunter_gate_status_debug(
           "HUNTER_ROOT set using USERPROFILE environment variable"