Repository files navigation

xrepo-cmake

CMake wrapper for Xrepo C and C++ package manager.

Support this project bybecoming a sponsor. Your logo will show up here with a link to your website. 🙏

CMake wrapper forXrepo C and C++ package manager.

This allows using CMake to build your project, while using Xrepo to managedependent packages. This project is partially inspired bycmake-conan.

Example use cases for this project:

• Existing CMake projects which want to use Xrepo to manage packages.
• New projects which have to use CMake, but want to use Xrepo to managepackages.

Note: please use CMake 3.19 or later for reliable package usage in CMake code.

xrepo.cmake providesxrepo_package function to managepackages.

xrepo_package("foo 1.2.3"    [CONFIGS feature1=true,feature2=false]    [CONFIGSpath/to/script.lua]    [DEPS]    [MODE debug|release]    [ALIAS aliasname]    [OUTPUT verbose|diagnosis|quiet]    [DIRECTORY_SCOPE])

Some of the function arguments correspond directly to Xrepo command options.

xrepo_package adds package install directory toCMAKE_PREFIX_PATH. Sofind_packagecan be used. IfCMAKE_MINIMUM_REQUIRED_VERSION >= 3.1, cmakePkgConfig will also searchfor pkgconfig files under package install directories.

After callingxrepo_package(foo), there are three ways to usefoo package:

1. Callfind_package(foo) if package provides cmake config-files.
   • Refer to CMakefind_package documentation for more details.
2. If the package does not provide cmake config files or find modules
   • Following variables can be used to use the pacakge (variable names following cmakefind modulesstandard variable names)
     • foo_INCLUDE_DIRS
     • foo_LIBRARY_DIRS
     • foo_LIBRARIES
     • foo_DEFINITIONS
   • IfDIRECTORY_SCOPE is specified,xrepo_package will run following code

     include_directories(${foo_INCLUDE_DIRS})link_directories(${foo_LIBRARY_DIRS})

3. Usexrepo_target_packages. Please refer to following section.

NoteCONFIGS path/to/script.lua is for fine control over package configs.For example:

• Exclude packages on system.
• Override dependent packages' default configs, e.g. setshared=true.

IfDEPS is specified, all dependent libraries will add toCMAKE_PREFIX_PATH, along with include,libraries being included in the four variables.

Add package includedirs and links/linkdirs to the given target.

xrepo_target_packages(target    [NO_LINK_LIBRARIES]    [PRIVATE|PUBLIC|INTERFACE]    package1 package2 ...)

• NO_LINK_LIBRARIES
  • In case a package provides multiple libs and user need to select which oneto link, passNO_LINK_LIBRARIES to disable callingtarget_link_libraries.User should calltarget_link_libraries to setup correct library linking.
• PRIVATE|PUBLIC|INTERFACE
  • The default is not specifying propagation control keyword when callingtarget_include_libraries,target_link_libraries, etc, because there's nodefault choice on this in CMake.
  • Refer to thisStack Overflow answerfor differences.

Xrepo official repository:xmake-repo

Here's an exampleCMakeLists.txt that usesgflags package version 2.2.2managed by Xrepo.

cmake_minimum_required(VERSION 3.13.0)project(foo)# Download xrepo.cmake if not exists in build directory.if(NOTEXISTS"${CMAKE_BINARY_DIR}/xrepo.cmake")    message(STATUS"Downloading xrepo.cmake from https://github.com/xmake-io/xrepo-cmake/")# mirror https://cdn.jsdelivr.net/gh/xmake-io/xrepo-cmake@main/xrepo.cmake    file(DOWNLOAD"https://raw.githubusercontent.com/xmake-io/xrepo-cmake/main/xrepo.cmake""${CMAKE_BINARY_DIR}/xrepo.cmake"TLS_VERIFYON)endif()# Include xrepo.cmake so we can use xrepo_package function.include(${CMAKE_BINARY_DIR}/xrepo.cmake)

xrepo_package("zlib")add_executable(example-bin"")target_sources(example-binPRIVATE    src/main.cpp)xrepo_target_packages(example-bin zlib)

xrepo_package("gflags 2.2.2" CONFIGS"shared=true,mt=true")add_executable(example-bin"")target_sources(example-binPRIVATE    src/main.cpp)xrepo_target_packages(example-bin gflags)

xrepo_package("gflags 2.2.2" CONFIGS"shared=true,mt=true")# `xrepo_package` add gflags install directory to CMAKE_PREFIX_PATH.# As gflags provides cmake config-files, we can now call `find_package` to find# gflags package.find_package(gflags CONFIG COMPONENTS shared)add_executable(example-bin"")target_sources(example-binPRIVATE    src/main.cpp)target_link_libraries(example-bin gflags)

We can also add custom packages in our project.

set(XREPO_XMAKEFILE${CMAKE_CURRENT_SOURCE_DIR}/packages/xmake.lua)xrepo_package("myzlib")add_executable(example-bin"")target_sources(example-binPRIVATE    src/main.cpp)xrepo_target_packages(example-bin myzlib)

Define myzlib package in packages/xmake.lua

package("myzlib")set_homepage("http://www.zlib.net")set_description("A Massively Spiffy Yet Delicately Unobtrusive Compression Library")set_urls("http://zlib.net/zlib-$(version).tar.gz","https://downloads.sourceforge.net/project/libpng/zlib/$(version)/zlib-$(version).tar.gz")add_versions("1.2.10","8d7e9f698ce48787b6e1c67e6bff79e487303e66077e25cb9784ac8835978017")on_install(function (package)-- TODOend)on_test(function (package)assert(package:has_cfuncs("inflate", {includes="zlib.h"}))end)

We can write a custom package in xmake.lua, please referDefine Xrepo package.

Following options can be speicified withcmake -D<var>=<value>.Or useset(var value) inCMakeLists.txt.

• XMAKE_CMD: string, defaults to empty string
  • Specify path toxmake command. Use this option ifxmake is not installedin standard location and can't be detected automatically.
• XREPO_PACKAGE_VERBOSE:[ON|OFF]
  • Enable verbose output for Xrepo Packages.
• XREPO_BOOTSTRAP_XMAKE:[ON|OFF]
  • IfON,xrepo.cmake will installxmake if it is not found.
• XREPO_PACKAGE_DISABLE:[ON|OFF]
  • Set this toON to disablexrepo_package function.
  • If setting this variable inCMakeLists.txt, please set it before includingxrepo.cmake.
• XREPO_BUILD_PARALLEL_JOBS:[COUNT]
  • Set parallel compilation threads num function.
  • If setting this variable inCMakeLists.txt, please set it before includingxrepo.cmake.
• XMAKE_RELEASE_LATEST:[VERSION]
  • Set xmake version.
  • If setting this variable inCMakeLists.txt, please set it before includingxrepo.cmake.

Following variables controll cross compilation. Note: to specify a different compiler other thanthe default one on system, platform must be set to "cross".

• XREPO_TOOLCHAIN: string, defaults to empty string
  • Specify toolchain name. Runxmake show -l toolchains to see available toolchains.
• XREPO_PLATFORM: string, defaults to empty string
  • Specify platform name. IfXREPO_TOOLCHAIN is specified and this is not,XREPO_PLATFORM will be set tocross.
• XREPO_ARCH: string, defaults to empty string
  • Specify architecture name.
• XREPO_XMAKEFILE: string, defaults to empty string
  • Specify Xmake script file of Xrepo package.

In addition to installing packages from officially maintained repository,Xrepo can also install packages from third-party package managers such as vcpkg/conan/conda/pacman/homebrew/apt/dub/cargo.

For the use of the command line, we can refer to the documentation:Xrepo command usage

We can also use it directly in cmake to install packages from third-party repositories, just add the repository name as a namespace. e.g.vcpkg::zlib,conan::pcre2

xrepo_package("conan::gflags/2.2.2")

xrepo_package("conda::gflags 2.2.2")

xrepo_package("vcpkg::gflags")

xrepo_package("brew::gflags")

xrepo.cmake module basically does the following tasks:

• Callxrepo install to ensure specific package is installed.
• Callxrepo fetch to get package information and setup various variables forusing the installed package in CMake.

The following section is a short introduction to using Xrepo. It helps tounderstand howxrepo.cmake works and how to specify some of the options inxrepo_package.

AssmuingXmake is installed.

Suppose we want to usegflags packages.

First, search forgflags package in Xrepo.

$ xrepo search gflagsThe package names:    gflags:      -> gflags-v2.2.2: The gflags package contains a C++ library that implements commandline flags processing. (in builtin-repo)

It's already in Xrepo, so we can use it. If it's not in Xrepo, we can create it inself-built repositories.

Let's see what configs are available for the package before using it:

$ xrepo info gflags...      -> configs:         -> mt: Build the multi-threaded gflags library. (default: false)      -> configs (builtin):         -> debug: Enable debug symbols. (default: false)         -> shared: Build shared library. (default: false)         -> pic: Enable the position independent code. (default: true)...

Suppose we want to use multi-threaded gflags shared library. We can install the package with following command:

xrepo install --mode=release --configs='mt=true,shared=true' 'gflags 2.2.2'

Only the first call to the above command will compile and install the package.To speed up cmake configuration,xrepo command will only be executed when thepackage is not installed orxrepo_package parameters have changed.

After package installation, because we are using CMake instead of Xmake, we haveto get package installation information by ourself.xrepo fetch command doesexactly this:

xrepo fetch --json --mode=release --configs='mt=true,shared=true' 'gflags 2.2.2'

The above command will print out package's include, library directory along withother information.xrepo_package uses these information to setup variables to usethe specified package.

For CMake 3.19 and later which has JSON support,xrepo_package parses the JSONoutput. For previous version of CMake,xrepo_package uses only the--cflags optionto get package include directory. Library and cmake module directory are infered from thatdirectory, so it maybe unreliable to detect the correct paths.