Skip to content

usr.adding.new.package

Ruslan Baratov edited this page Apr 16, 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_release_debug # For separate release/debug generators, like Makefile
    COMBINED url_sha1_combined_release_debug # For Xcode and Visual Studio
)

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

Second, specify version in default config.cmake:

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

04. Using

That's all! Now package can be used:

> 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}")

Or if you library is really cool, by find_package:

find_package(Example CONFIG REQUIRED)

Note: see CMAKE_PREFIX_PATH

05. Test

Let's test it:

> 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

Default 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_release_debug
    COMBINED url_sha1_combined_release_debug
)

hunter_download(PACKAGE_NAME Foo)

Default behaviour

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

Clone this wiki locally