Skip to content

usr.adding.new.package

Ruslan Baratov edited this page Oct 12, 2015 · 20 revisions

If package is CMake project without third party dependencies which installed using cmake --build <dir> --target install then integration is pretty easy. Here is a step-by-step tutorial for a tiny package example-A. Other tutorials:

01. Test it manually

Install/verify project using Wget, OpenSSL and CMake:

> wget https://github.com/forexample/example-A/archive/v1.0.1.tar.gz
> openssl sha1 v1.0.1.tar.gz 
SHA1(v1.0.1.tar.gz)= 48179067d11828dc347f98fc148654f88766529d
> tar xf v1.0.1.tar.gz
> cd example-A-1.0.1/
> cmake -H. -B_builds -DCMAKE_INSTALL_PREFIX=`pwd`/_install
> cmake --build _builds/ --target install
> ls _install/*
_install/libexample_A.a

_install/example_A:
foo.hpp

02. Test it using ExternalProject_Add

> cat CMakeLists.txt
cmake_minimum_required(VERSION 2.8)

include(ExternalProject) # ExternalProject_Add

ExternalProject_Add(
    Example
    URL https://github.com/forexample/example-A/archive/v1.0.1.tar.gz
    URL_HASH SHA1=48179067d11828dc347f98fc148654f88766529d
    CMAKE_ARGS
    "-DCMAKE_INSTALL_PREFIX=${CMAKE_CURRENT_LIST_DIR}/_install"
)
> cmake -H. -B_builds
> cmake --build _builds/
> ls _install/*
_install/libexample_A.a

_install/example_A:
foo.hpp

03. Add new package

First, new hunter.cmake file need to be add to projects directory

> cd ${HUNTER_ROOT}
> mkdir cmake/projects/Example
> cat cmake/projects/Example/hunter.cmake
# This is a header-like file, so include guards needed
if(DEFINED HUNTER_CMAKE_PROJECTS_EXAMPLE_HUNTER_CMAKE_)
  return()
else()
  set(HUNTER_CMAKE_PROJECTS_EXAMPLE_HUNTER_CMAKE_ 1)
endif()

# Load used modules
include(hunter_add_version)
include(hunter_download)
include(hunter_pick_scheme)

# List of versions here...
hunter_add_version(
    PACKAGE_NAME
    Example
    VERSION
    "1.0.1"
    URL
    "https://github.com/forexample/example-A/archive/v1.0.1.tar.gz"
    SHA1
    48179067d11828dc347f98fc148654f88766529d
)

hunter_add_version(
    PACKAGE_NAME
    Example
    VERSION
    "1.0.0"
    URL
    "https://github.com/forexample/example-A/archive/v1.0.0.tar.gz"
    SHA1
    d9b25aeadde5a5b1b60ba2dd39ed1a7a4846589a
)

# Probably more versions for real packages...

# Pick a download scheme
hunter_pick_scheme(DEFAULT url_sha1_cmake) # use scheme for cmake projects

# Download package.
# Two versions of library will be build by default:
#     * libexample_A.a
#     * libexample_Ad.a
hunter_download(PACKAGE_NAME Example)

Second, specify version in default config:

> grep Example cmake/config/default.cmake 
hunter_config(Example VERSION 1.0.1)

Note

Package configuration can be also be performed at a project level, e.g. customization can be performed within ${CMAKE_CURRENT_LIST_DIR}/cmake/Hunter/config.cmake. See customizing external packages for more detailed information.

04. Using

That's all! Now package can be used (see next section for testing):

> cat CMakeLists.txt
cmake_minimum_required(VERSION 3.0)

include("cmake/HunterGate.cmake")

HunterGate(
    URL "https://url/to/your/hunter-archive.tar.gz"
    SHA1 "put-archive-sha1-here"
)

hunter_add_package(Example)

Library can be found by EXAMPLE_ROOT cmake variable:

find_library(
    example_release
    example_A
    ${EXAMPLE_ROOT}
)

find_library(
    example_debug
    example_A${CMAKE_DEBUG_POSTFIX}
    ${EXAMPLE_ROOT}
)

message("Release: ${example_release}")
message("Debug: ${example_debug}")

Note that for real packages there will be more code like searching for EXAMPLE_INCLUDE_DIR or setting EXAMPLE_COMPILE_DEFINITIONS.

Important!

Note that CMake modern-style packages can automatically produce and install CMake configs for find_package commands. This helps to avoid manually writing/supporting and distributing endless list of Find<Package>.cmake modules. Also, what is very important for Hunter, it's the one of the painless ways to support relocation. I.e. only config-mode packages (native or emulated) with imported targets can be cached and downloaded as prebuilt binary archive from build servers. Plus only imported targets works nicely with non standard build types like MinSizeRel or RelWithDebInfo. It is highly recommended to have such feature. Read this overview if you want to have code:

find_package(Example CONFIG REQUIRED)

instead of bunch of find_library in snipped from previous paragraph.

If your package is already relocatable use command hunter_cacheable to allow caching.

05. Test

Let's test it (see how to do it nicely):

> cmake -H. -B_builds
-- [hunter] HUNTER_ROOT: /.../Hunter
-- [hunter] [ Hunter-ID: 7912489 | Config-ID: f1ec619 | Toolchain-ID: f8714ae ]
...
-- [hunter] EXAMPLE_ROOT: /.../Hunter/_Base/7912489/f1ec619/f8714ae/Install (ver.: 1.0.1)
-- [hunter] Building Example
...
-- downloading...
...
     src='https://github.com/forexample/example-A/archive/v1.0.1.tar.gz'
-- [download 100% complete]
Install the project...
-- Install configuration: "Release"
...
-- Install configuration: "Debug"
...
Release: /.../Hunter/_Base/7912489/f1ec619/f8714ae/Install/libexample_A.a
Debug: /.../Hunter/_Base/7912489/f1ec619/f8714ae/Install/libexample_Ad.a

Extra

Defaults

CMake options

Note that it doesn't make sense to include in build such stuff like examples, tests or documentation. Please check that your package has CMake option to disable it and apply extra variables to all versions (if options is not disabled by default) using hunter_cmake_args function:

# bottom of cmake/projects/Foo/hunter.cmake
...

hunter_cmake_args(
    Foo
    CMAKE_ARGS
        FOO_BUILD_EXAMPLES=OFF
        FOO_BUILD_TESTS=OFF
        FOO_BUILD_DOCUMENTATION=OFF
)

hunter_pick_scheme(DEFAULT url_sha1_cmake)
hunter_download(PACKAGE_NAME Foo)

Build types

Default build type(s) can be set by hunter_configuration_types:

hunter_configuration_types(Foo CONFIGURATION_TYPES Release)
hunter_download(PACKAGE_NAME Foo)

User can overwrite this default by using custom hunter_config parameters.

Default behaviour

Please check that your package respect (i.e. doesn't rewrite) such CMake variables like:

Clone this wiki locally