Hunter

• Cross-platform package manager for C++ (based on CMake ExternalProject)
• Supported platforms: Linux, Mac, Windows, iOS, Android, Raspberry Pi

What is it?

Every Hunter release archive is a meta-package with build instructions and URLs of real packages:

Hunter (0.4.2) = {
    Boost (1.55.0, 1.56.0, 1.57.0),
    GTest (1.7.0),
    OpenCV (3.0.0-beta, 2.4.11, 2.4.10),
    OpenSSL (1.0.2a, 0.9.8y),
    ...
}

• Default build versions can be found in default.cmake file and are customizable (see Config-ID)
• Per package versions are available in corresponding hunter.cmake file (e.g. GTest). You can pick one version that already exists or add a new one

Features

• Automatic dependencies download
• List of dependencies is a part of CMake code of the project
• No emerge, apt-get, brew etc. needed before build, now it's simply cmake --build
• Express install instructions in terms of CMake commands instead of raw README text or other script
• Reusable ExternalProject_Add recipies (DRY principle)
• Once written formula (build scheme) can be used by other projects, subprojects etc. without copying of collection of superbuild files. Just change 2 lines of code: input parameters SHA1/URL of HunterGate command
• Several levels of build customization:
• Hunter-ID - list of packages and mapping version-url-sha1
• Config-ID - version of package to build and build options
• Toolchain-ID - compiler and flags
• Build type (e.g. Release/Debug)
• Shareable root directory with build synchronization
• Any number of projects can use root directory and add new packages simultaneously
• Manage anything that can be downloaded by URL and checked with SHA1 hash:
• C++ packages
• CMake modules
• Additional sources
• Resources (pictures, data for testing, ...)
• Backward compatibility. Turn Hunter off by adding one option HUNTER_ENABLED=OFF to use your old settings
• No other dependencies - just CMake and your environment/IDE (no need for Git or Python or anything)
• Works everywhere: CMake-GUI, Qt Creator, Visual Studio, Xcode, Cygwin, MinGW, Jenkins, Travis etc.

Notes about version of CMake

• 3.0.0 Minimum required
  • Buggy, see PR #198
  • Interface header-only libraries
  • Sub-option VERSION for command project
  • New MSVC generator names
• 3.1.0
  • Buggy, see issue #105
  • Retry download on hash mismatch (change)
  • New CMP0054 (best CMake policy! See this SO question)
• 3.2.0
  • New synchronization command file(LOCK ...) (change)
  • HUNTER_SKIP_LOCK
• iOS. Patched (workaround) version of CMake
  • Patched releases
  • Fix iOS bug
  • Create universal (armv7, armv7s, arm64, i386, x86_64) libraries
  • iOS toolchain

First step

• Set HUNTER_ROOT environment variable (recommended but not mandatory, see other options)

• Set minimum CMake version:

cmake_minimum_required(VERSION 3.0)

• Copy gate module to your project and include it:

include("cmake/HunterGate.cmake")

• This module will download archive automatically from URL that you provide:

HunterGate(
    URL "https://github.com/ruslo/hunter/archive/v0.10.9.tar.gz"
    SHA1 "53b198e364dc7bc8360fc545f798563229bd7e20"
)

• Now project can be started:

project(Foo)

• Let's download and install boost.{regex,system,filesystem}:

hunter_add_package(Boost COMPONENTS regex system filesystem)

• Hunter part is done, now well known CMake-style kung-fu (see pkg.boost):

find_package(Boost CONFIG REQUIRED regex system filesystem)

add_executable(foo foo.cpp)
target_link_libraries(foo PUBLIC Boost::regex Boost::system Boost::filesystem)

• Summarize:

cmake_minimum_required(VERSION 3.0)

include("cmake/HunterGate.cmake")
HunterGate(
    URL "https://github.com/ruslo/hunter/archive/v0.10.9.tar.gz"
    SHA1 "53b198e364dc7bc8360fc545f798563229bd7e20"
)

project(Foo)

hunter_add_package(Boost COMPONENTS regex system filesystem)
find_package(Boost CONFIG REQUIRED regex system filesystem)

add_executable(foo foo.cpp)
target_link_libraries(foo PUBLIC Boost::regex Boost::system Boost::filesystem)

• Build it:

> cmake -H. -B_builds -DHUNTER_STATUS_DEBUG=ON -DCMAKE_BUILD_TYPE=Release
> cmake --build _builds --config Release

• Tiny project with GTest

Usage

• List of packages and usage instructions for each package can be found in wiki sidebar
• List of global control variables
• How to add a new CMake project
• How to add a new custom-build project
• Multiple HunterGate commands (e.g. projects subprojects)

Hunter-ID

First level of customization. Hunter-ID is the first 7 digits of SHA1 of Hunter archive. I.e. each Hunter-ID contains list of projects that you can build and list of versions. Each version has it's unique URL and SHA1. Several Hunter-ID can coexists in same HUNTER_ROOT directory. HunterGate command will control your choice:

• 1eae623
• Hunter 0.8.3
• Foo 1.0.0 -> http://mysite.com/Foo-1.0.0.tar.gz
• Boo 2.0.0 -> http://mysite.com/Boo-2.0.0.tar.gz
• Roo 1.2.3 -> http://mysite.com/Roo-1.2.3.tar.gz
• -> ${HUNTER_ROOT}/_Base/1eae623/...
• e07a124
• Hunter 0.8.4
• Awesome 1.0.0 -> http://example.com/Awesome-1.0.0.tar.gz
• Best 2.0.0 -> http://example.com/Best-2.0.0.tar.gz
• Foo 1.0.0 -> http://example.com/Foo-1.0.0-patch-1.tar.gz # yep, different URL/SHA1
• -> ${HUNTER_ROOT}/_Base/e07a124/...

Message in logs:

-- [hunter] [ Hunter-ID: 1eae623 | Config-ID: ... | Toolchain-ID: ... ]
-- [hunter] [ Hunter-ID: e07a124 | Config-ID: ... | Toolchain-ID: ... ]

• Releases

Config-ID

Second level of customization. Config-ID is the first 7 digits of SHA1 of the file with hunter_config commands (internal unified representation). This level can be customized with HunterGate options: GLOBAL, LOCAL and FILEPATH. Same Hunter-ID can be built with different versions of packages and different CMake arguments:

• 0fa873a
• Foo 1.0.0
• Boo 2.0.0 with option BOO_WITH_SOMETHING=YES
• -> ${HUNTER_ROOT}/_Base/1eae623/0fa873a
• e9da39c
• Foo 2.1.0 with option FOO_SUPER_MODE=YES
• Boo 3.0.0 with option BUILD_SHARED_LIBS=ON
• -> ${HUNTER_ROOT}/_Base/1eae623/e9da39c

Message in logs:

-- [hunter] [ Hunter-ID: 1eae623 | Config-ID: 0fa873a | Toolchain-ID: ... ]
-- [hunter] [ Hunter-ID: 1eae623 | Config-ID: e9da39c | Toolchain-ID: ... ]

• Example

Toolchain-ID

Third level of customization. Each build can be run with different toolchain. In general the result is completely different root lib/include directories. For example on Windows you can simultaniously build Visual Studio (32/64), NMake, Cygwin and MinGW projects, on Linux GCC/Clang, on Mac Xcode, Makefile, iOS. Or choose different clang tools like static analyzer/sanitizers and other platforms like Android/Raspberry Pi. Each toolchain file will be forwarded to external project so if you create toolchain with compiler g++ and flag -std=c++11 all dependent projects will be built by g++ -std=c++11. Information about toolchain has some internal representation (toolchain.info) and user can see first 7 digits (ID) of SHA1 hash of this file.

• d46ea0b
• gcc
• -> ${HUNTER_ROOT}/_Base/1eae623/0fa873a/d46ea0b
• c018e63
• clang
• -> ${HUNTER_ROOT}/_Base/1eae623/0fa873a/c018e63
• c39da39
• clang -std=c++11
• -> ${HUNTER_ROOT}/_Base/1eae623/0fa873a/c39da39

Message in logs:

-- [hunter] [ Hunter-ID: 1eae623 | Config-ID: 0fa873a | Toolchain-ID: d46ea0b ]
-- [hunter] [ Hunter-ID: 1eae623 | Config-ID: 0fa873a | Toolchain-ID: c018e63 ]
-- [hunter] [ Hunter-ID: 1eae623 | Config-ID: 0fa873a | Toolchain-ID: c39da39 ]

• Collection of toolchains
• Android example

Uninstall

All directories inside ${HUNTER_ROOT}/_Base are reconstructible. You can remove all temps (downloads, unpacked directories, installed directories etc.) by command:

rm -rf "${HUNTER_ROOT}/_Base"

or remove particular Hunter-ID by command:

rm -rf "${HUNTER_ROOT}/_Base/62422b8" # remove installed libraries
rm -rf "${HUNTER_ROOT}/_Base/Download/Hunter/0.8.3/62422b8" # remove Hunter itself

Questions?

Feel free to open new issue if you want to ask any questions.

Contribution

Read wiki before making changes. Please send a patch as a pull request against the branch develop. After successfull build this branch will be merged to master automatically.

Links

• Gate to hunter packages
• Simple project example
• Bigger one
• Toolchain examples
• Travis CI build example