Skip to content

Clarify the HUNTER_ROOT debugging functionality #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 19, 2021
Merged

Clarify the HUNTER_ROOT debugging functionality #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
15ad86d
Minor improvements to HunterGate.cmake
mrexodia Feb 25, 2021
ad0e9e6
Clarify the README
mrexodia Feb 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 44 additions & 21 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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")
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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"
Expand All @@ -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)
18 changes: 7 additions & 11 deletions cmake/HunterGate.cmake
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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"
Expand Down