User variables¶
CMake¶
Note
All Hunter options should be set to cache and
before HunterGate so user will be able to set
his own values.
Also if package will be used as a third party project managed by Hunter, then
Hunter should be able to forward all values from by parent to child projects.
So do not set this variables with FORCE
or as INTERNAL
, and don’t
set them as a regular variables:
set(HUNTER_ENABLED ON) # BAD!
set(HUNTER_STATUS_PRINT OFF CACHE BOOL "..." FORCE) # BAD!
set(HUNTER_STATUS_DEBUG ON CACHE INTERNAL "...") # BAD!
option(HUNTER_STATUS_DEBUG "Print a lot of info" ON) # Good
# Good
set(
HUNTER_CACHE_SERVERS
"https://github.com/elucideye/hunter-cache"
CACHE
STRING
"Hunter cache servers"
)
# Good
set(HUNTER_JOBS_NUMBER 6 CACHE STRING "Hunter jobs number")
# All user options before HunterGate
HunterGate(URL "..." SHA1 "...")
HUNTER_ENABLED¶
Turn on/off Hunter package manager. If this variable is OFF
HunterGate
module will do nothing, hunter_add_package
command will have no effects. You
can add this variable as option
while experimenting to keep backward
compatibility with old package manager:
option(HUNTER_ENABLED "Enable Hunter package manager" OFF)
HunterGate(...) # ignored
if(WITH_FOO)
hunter_add_package(Foo) # ignored
find_package(Foo) # found in standard location
endif()
- Default:
ON
HUNTER_ROOT¶
- Path to Hunter root directory. Set this variable if you don’t want to install Hunter packages to default location
- You can set environment variable with the same name to avoid specifying it for every project
- See HunterGate
HUNTER_STATUS_PRINT¶
- Print current build status
- Default:
ON
HUNTER_STATUS_DEBUG¶
- Print a lot of info
- Set this variable to
ON
before submitting bugs - Default:
OFF
HUNTER_PACKAGE_LOG_BUILD¶
- Apply
LOG_BUILD 1
(see ExternalProject)
HUNTER_PACKAGE_LOG_INSTALL¶
- Apply
LOG_INSTALL 1
(see ExternalProject)
HUNTER_CONFIGURATION_TYPES¶
- Build type of the 3rd party packages
- See example
- Default:
Release
,Debug
HUNTER_JOBS_NUMBER¶
- Number of parallel builds that will be used in such native tools like
make -jN
orxcodebuild -jobs N
- For Visual Studio >= 12 2013 flag
/maxcpucount:N
will be added toMSBuild
- Set variable to
0
to disable adding any flags:HUNTER_JOBS_NUMBER=0
- Defaults to maximum of two:
HUNTER_RUN_INSTALL¶
Set this variable to ON
to run auto-install procedure if it’s disabled by
HUNTER_DISABLE_AUTOINSTALL environment variable.
HUNTER_RUN_UPLOAD¶
Set this variable to YES
to start
uploading procedure.
- Default:
NO
Note
Upload will start only after any real build triggered by Hunter.
HUNTER_DISABLE_BUILDS¶
- Set this variable to
YES
to disable building packages from sources. This may be useful in case you want to check that package can be loaded fully from local/server cache - Default:
NO
HUNTER_CACHE_SERVERS¶
- Variable contains list of servers with cache binaries
- Variable should be modified before
HunterGate
command:
set(
HUNTER_CACHE_SERVERS
"https://github.com/elucideye/hunter-cache"
CACHE
STRING
"Hunter cache servers"
)
HunterGate(URL "..." SHA1 "...")
Using two servers:
set(
HUNTER_CACHE_SERVERS
"https://github.com/elucideye/hunter-cache;https://github.com/cpp-pm/hunter-cache"
CACHE
STRING
"Hunter cache servers"
)
HunterGate(URL "..." SHA1 "...")
HUNTER_USE_CACHE_SERVERS¶
- Policy to control downloading cache from server. Possible values:
- NO - never download cache from server, use local cache or build from sources
- ONLY - never build from sources, use server/local cache
- YES - try to download from server, build from sources if not found
HUNTER_USE_CACHE_SERVERS | |||
---|---|---|---|
NO | ONLY | YES | |
Build from sources | yes | no | yes |
Download from server | no | yes | yes |
- Default is empty string. Effectively equivalent to YES.
HUNTER_PASSWORDS_PATH¶
Path to Hunter passwords file.
HUNTER_KEEP_PACKAGE_SOURCES¶
If this variable is set to YES
then Hunter will keep package sources
after finishing installation. It may be useful for navigation in code while
using debug version of libraries.
This is a workaround for issue #359 and have some usage peculiarities:
It does not work well with Hunter cache mechanism. If package binaries will be found on server, then there will be no build stage triggered, hence there will be no sources kept. Use HUNTER_USE_CACHE_SERVERS=NO for always building packages on local machine from sources.
Sources will be kept inside Hunter-ID directory. Hence even if all the packages will be using another Hunter-ID, the old Hunter-ID directory should not be removed.
Some packages use in-source build (non-CMake packages) and keep all build artifacts along with sources. Hunter will just keep directory and will not track what files was the original sources/what is temporary files for build. Combining with previous peculiarity it’s expected that much more disk space will be used than usually.
If package is already installed before
HUNTER_KEEP_PACKAGE_SOURCES
set toON
there will be no build triggered, hence there will be no sources kept. To re-trigger the build you can add some dummy parameter toCMAKE_ARGS
, for example:hunter_config(foo VERSION ${HUNTER_foo_VERSION} CMAKE_ARGS DUMMY=1)
HUNTER_DOWNLOAD_SERVER¶
Define a list of servers to download from.
We define the following packages for the examples:
- Package 1 name:
foo
- Package 1 SHA1:
49dee30c5fedd8613a144f9bf6551fb46bb69e92
- Package 1 URL:
https://foo.com/downloads/foo-1.0.tar.gz
- Package 2 name:
boo
- Package 2 SHA1:
b1ec7331baf4c9996497851bfa2c847a73cd6085
- Package 2 URL:
https://server-2.com/downloads/boo-3.0.tar.gz
If HUNTER_DOWNLOAD_SERVER
is empty nothing changes and the following URLs
are used to download the sources:
foo
:https://foo.com/downloads/foo-1.0.tar.gz
boo
:https://server-2.com/downloads/boo-3.0.tar.gz
If HUNTER_DOWNLOAD_SERVER
is a list of servers like
https://server-1.com;https://server-2.com;https://server-3.com
then the original package URL is analyzed. If the original URL matches one of the
defined servers we leave it untouched and set as a server with high priority.
For package foo
the following URLs are passed to ExternalProject_Add
(the original URL is not used):
https://server-1.com/foo/1.0/SHASUM/foo-1.0.tar.gz
https://server-2.com/foo/1.0/SHASUM/foo-1.0.tar.gz
https://server-3.com/foo/1.0/SHASUM/foo-1.0.tar.gz
For package boo
the following URLs are passed to ExternalProject_Add
(the original URL has the highest priority):
https://server-2.com/downloads/boo-3.0.tar.gz
(take priority, original URL used)https://server-1.com/boo/3.0/SHASUM/boo-3.0.tar.gz
https://server-3.com/boo/3.0/SHASUM/boo-3.0.tar.gz
Note
Multiple URLs are supported only with CMake 3.7+. For earlier versions
the first listed URL is passed to ExternalProject_Add
.
The retry logic is implemented in the CMake function ExternalProject_Add
.
To create new URLs the following template is used:
${HUNTER_DOWNLOAD_SERVER}/${PACKAGE_NAME}/${PACKAGE_VERSION}/${ARCHIVE_ID}/${filename}
- The characters
!@#$%^&*?
occurring in${filename}
are replaced with_
. ${ARCHIVE_ID}
is the first 7 characters of the package archiveSHA1
sum.
Note
This is the same structure as Hunter uses for its own Download directory.
Note
HUNTER_DOWNLOAD_SERVER
will be applied only to packages enabled with the standard
VERSION
variant of hunter_config entries, which is the case for all default
Hunter package definitions. Custom package definitions introduced with a URL
/SHA1
variant on hunter_config in a project’s local configuration, such as those included through
FILEPATH
or LOCAL
arguments to HunterGate()
, will be unaffected by this variable.
The git
variants of hunter_config, namely GIT_SUBMODULE
and GIT_SELF
, have no
transformable URL and are also unaffected by HUNTER_DOWNLOAD_SERVER
.
HUNTER_TLS_VERIFY¶
Define if
ExternalProject_Add
and
file(DOWNLOAD)
should verify the server certificate for https://
URLs.
Default: ON
HUNTER_GIT_SELF_IGNORE_UNTRACKED¶
Set this option to ON
if you want to ignore untracked files while
using GIT_SELF feature.
Default: OFF
HUNTER_NO_TOOLCHAIN_ID_RECALCULATION¶
If set to ON
Hunter will skip calculation of Toolchain-ID
if value is
already present in CMake cache.
Default: OFF
Note
Do not use this option while making a bug report.
Warning
This option is for the advanced users only. Incorrect usage of this option may lead to invalid unrecoverable cache state. Please read carefully this page before using this option.
Environment¶
HUNTER_ROOT¶
- Same as CMake’s HUNTER_ROOT variable. If both environment and CMake variables are set then CMake has a higher priority
HUNTER_BINARY_DIR¶
- Use external directory
HUNTER_BINARY_DIR
for building external projects. This variable can be used to fix “path too long” error on windows
HUNTER_DISABLE_AUTOINSTALL¶
Set this environment variable to non-empty value (e.g. HUNTER_DISABLE_AUTOINSTALL=ON
)
to disable automatic initialization of Hunter root directory by HunterGate
module. This will give you more control in some advanced usage situations, see
examples.
Set HUNTER_RUN_INSTALL=ON CMake variable each time
you want to run auto-install procedure. Note that there is no need to set any
variables if Hunter root is already installed.
HUNTER_PASSWORDS_PATH¶
Environment variable with functionality similar to CMake variable with the same name.
HUNTER_GIT_EXECUTABLE¶
Path to Git executable
HUNTER_JOBS_NUMBER¶
See HUNTER_JOBS_NUMBER CMake variable