pigei / hunter

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

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
  • Latest patched release
  • Fix iOS bug
  • Create universal (armv7, armv7s, arm64, i386, x86_64) libraries
  • iOS toolchain

First step

• Set HUNTER_ROOT environment variable to an empty directory. This directory will be used by HunterGate module for storing packages and utility files. Using environment variable is 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 to the HUNTER_ROOT directory (it means that there is no need to clone this repository in general, see notes):

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

• Contribution

Donations

• Donations

Links

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