From a14ff8c8a2b74aef40c4c2340e6cb6fa55c332c1 Mon Sep 17 00:00:00 2001 From: Duncan Ogilvie Date: Mon, 19 Apr 2021 18:53:50 +0200 Subject: [PATCH] Clarify the HUNTER_ROOT debugging functionality (#13) * Minor improvements to HunterGate.cmake * Clarify the README --- README.md | 65 ++++++++++++++++++++++++++++-------------- cmake/HunterGate.cmake | 18 +++++------- 2 files changed, 51 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 2fe6539..5472f0c 100644 --- a/README.md +++ b/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,16 +211,20 @@ 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" @@ -221,15 +232,31 @@ HunterGate( ) ``` -* [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) @@ -237,19 +264,15 @@ HunterGate( * 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) diff --git a/cmake/HunterGate.cmake b/cmake/HunterGate.cmake index 9c82fcf..64ccde5 100644 --- a/cmake/HunterGate.cmake +++ b/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,24 +149,21 @@ 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() @@ -173,8 +171,7 @@ function(hunter_gate_detect_root) # 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" @@ -182,8 +179,7 @@ function(hunter_gate_detect_root) 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"