xmake
/
xmake-docs
mirror da https://github.com/xmake-io/xmake-docs


			
				
					
						
						
							1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051
							<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>xmake</title>
  <link rel="icon" href="/assets/img/favicon.ico">
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
  <meta name="description" content="Description">
  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
  <link href="/assets/npm/github-markdown/github-markdown.min.css" rel="stylesheet">
  <style>
	.markdown-body {
		box-sizing: border-box;
		min-width: 200px;
		max-width: 980px;
		margin: 0 auto;
		padding: 45px;
	}

	@media (max-width: 767px) {
		.markdown-body {
			padding: 15px;
		}
	}
  </style>
</head>
<body>
<article class="markdown-body">
<h4>This is a mirror page, please see the original page: </h4><a href="https://xmake.io/#/package/remote_package">https://xmake.io/#/package/remote_package</a>
<div id="wwads-panel" class="wwads-cn wwads-vertical wwads-sticky" data-id="239" style="max-width:180px;bottom:20px;right:20px;width:200px;height:260px;background:#fff;position:fixed"></div>
</br>
    <script type="text/javascript" charset="UTF-8" src="https://cdn.wwads.cn/js/makemoney.js" async></script>
<script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?serve=CE7I52QU&placement=xmakeio" id="_carbonads_js"></script>
<style>
#carbonads {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu,
  Cantarell, "Helvetica Neue", Helvetica, Arial, sans-serif;
}

#carbonads {
  display: flex;
  max-width: 330px;
  background-color: hsl(0, 0%, 98%);
  box-shadow: 0 1px 4px 1px hsla(0, 0%, 0%, .1);
}

#carbonads a {
  color: inherit;
  text-decoration: none;
}

#carbonads a:hover {
  color: inherit;
}

#carbonads span {
  position: relative;
  display: block;
  overflow: hidden;
}

#carbonads .carbon-wrap {
  display: flex;
}

.carbon-img {
  display: block;
  margin: 0;
  line-height: 1;
}

.carbon-img img {
  display: block;
}

.carbon-text {
  font-size: 13px;
  padding: 10px;
  line-height: 1.5;
  text-align: left;
}

.carbon-poweredby {
  display: block;
  padding: 8px 10px;
  background: repeating-linear-gradient(-45deg, transparent, transparent 5px, hsla(0, 0%, 0%, .025) 5px, hsla(0, 0%, 0%, .025) 10px) hsla(203, 11%, 95%, .4);
  text-align: center;
  text-transform: uppercase;
  letter-spacing: .5px;
  font-weight: 600;
  font-size: 9px;
  line-height: 1;
}
</style>
    <p>This has been initially supported after the 2.2.2 version, the usage is much simpler, just set the corresponding dependency package, for example:</p>
<pre><code class="lang-lua">add_requires("tbox 1.6.*", "libpng ~1.16", "zlib")

target("test")
    set_kind("binary")
    add_files("src/*.c")
    add_packages("tbox", "libpng", "zlib")
</code></pre>
<p>The above <code>add_requires</code> is used to describe the dependencies required by the current project, and <code>add_packages</code> is used to apply dependencies to the test target. Only settings will automatically add links, linkdirs, includedirs, etc.</p>
<p>Then directly compile:</p>
<pre><code class="lang-console">$ xmake
</code></pre>
<p>xmake will remotely pull the relevant source package, then automatically compile and install, finally compile the project, and link the dependency package. The specific effect is shown in the following figure:</p>
<p><img src="/assets/img/index/package_manage.png" width="80%" /></p>
<p>For more information and progress on package dependency management see the related issues: <a href="https://github.com/xmake-io/xmake/issues/69">Remote package management</a></p>
<h2 id="currentlysupportedfeatures">Currently Supported Features</h2>
<ul>
<li>Semantic version support, for example: ">= 1.1.0 < 1.2", "~1.6", "1.2.x", "1.*"</li>
<li>Provide multi-repository management support such as official package repository, self-built private repository, project built-in repository, etc.</li>
<li>Cross-platform package compilation integration support (packages of different platforms and different architectures can be installed at the same time, fast switching use)</li>
<li>Debug dependency package support, source code debugging</li>
</ul>
<h2 id="dependencypackageprocessingmechanism">Dependency Package Processing Mechanism</h2>
<p>Here we briefly introduce the processing mechanism of the entire dependency package:</p>
<p><div align="center"><br><img src="/assets/img/index/package_arch.png" width="80%" /><br></div>

</p>
<ol>
<li>Priority check for the current system directory, whether there is a specified package under the third-party package management, if there is a matching package, then you do not need to download and install (of course you can also set the system package)</li>
<li>Retrieve the package matching the corresponding version, then download, compile, and install (Note: installed in a specific xmake directory, will not interfere with the system library environment)</li>
<li>Compile the project, and finally automatically link the enabled dependencies</li>
</ol>
<h2 id="semanticversionsettings">Semantic Version Settings</h2>
<p>Xmake&#39;s dependency package management fully supports semantic version selection, for example: "~1.6.1". For a detailed description of the semantic version, see: <a href="https://semver.org/">https://semver.org/</a></p>
<p>Some semantic versions are written:</p>
<pre><code class="lang-lua">add_requires("tbox 1.6.*", "pcre 1.3.x", "libpng ^1.18")
add_requires("libpng ~1.16", "zlib 1.1.2 || >=1.2.11 <1.3.0")
</code></pre>
<p>The semantic version parser currently used by xmake is the <a href="https://github.com/uael/sv">sv</a> library contributed by <a href="https://github.com/uael">uael</a>, which also has a description of the version. For detailed instructions, please refer to the following: <a href="https://github.com/uael/sv#versions">Version Description</a></p>
<p>Of course, if we have no special requirements for the current version of the dependency package, then we can write directly:</p>
<pre><code class="lang-lua">add_requires("tbox", "libpng", "zlib")
</code></pre>
<p>This will use the latest version of the package known, or the source code compiled by the master branch. If the current package has a git repo address, we can also specify a specific branch version:</p>
<pre><code class="lang-lua">add_requires("tbox master")
add_requires("tbox dev")
</code></pre>
<h2 id="extrapackageinformationsettings">Extra Package Information Settings</h2>
<h3 id="optionalpackagesettings">Optional Package Settings</h3>
<p>If the specified dependency package is not supported by the current platform, or if the compilation and installation fails, then xmake will compile the error, which is reasonable for some projects that must rely on certain packages to work.<br>However, if some packages are optional dependencies, they can be set to optional packages even if they are not compiled properly.</p>
<pre><code class="lang-lua">add_requires("tbox", {optional = true})
</code></pre>
<h3 id="disablesystemlibrary">Disable System Library</h3>
<p>With the default settings, xmake will first check to see if the system library exists (if no version is required). If the user does not want to use the system library and the library provided by the third-party package management, then you can set:</p>
<pre><code class="lang-lua">add_requires("tbox", {system = false})
</code></pre>
<h3 id="usingthedebugversionofthepackage">Using the debug version of the package</h3>
<p>If we want to debug the dependencies at the same time, we can set them to use the debug version of the package (provided that this package supports debug compilation):</p>
<pre><code class="lang-lua">add_requires("tbox", {debug = true})
</code></pre>
<p>If the current package does not support debug compilation, you can submit the modified compilation rules in the repository to support the debug, for example:</p>
<pre><code class="lang-lua">package("openssl")
    on_install("linux", "macosx", function (package)
        os.vrun("./config %s --prefix=\"%s\"", package:debug() and "--debug" or "", package:installdir())
        os.vrun("make -j4")
        os.vrun("make install")
    end)
</code></pre>
<h3 id="passingadditionalcompilationinformationtothepackage">Passing additional compilation information to the package</h3>
<p>Some packages have various compile options at compile time, and we can pass them in. Of course, the package itself supports:</p>
<pre><code class="lang-lua">add_requires("tbox", {configs = {small=true}})
</code></pre>
<p>Pass <code>--small=true</code> to the tbox package so that compiling the installed tbox package is enabled.</p>
<p>We can get a list of all configurable parameters and descriptions of the specified package by executing <code>xmake require --info tbox</code> in the project directory.</p>
<p>such as:</p>
<pre><code class="lang-console">xmake require --info spdlog
    require(spdlog):
      -> requires:
         -> plat: macosx
         -> arch: x86_64
         -> configs:
            -> header_only: true
            -> shared: false
            -> vs_runtime: MT
            -> debug: false
            -> fmt_external: true
            -> noexcept: false
      -> configs:
         -> header_only: Use header only (default: true)
         -> fmt_external: Use external fmt library instead of bundled (default: false)
         -> noexcept: Compile with -fno-exceptions. Call abort() on any spdlog exceptions (default: false)
      -> configs (builtin):
         -> debug: Enable debug symbols. (default: false)
         -> shared: Enable shared library. (default: false)
         -> cflags: Set the C compiler flags.
         -> cxflags: Set the C/C++ compiler flags.
         -> cxxflags: Set the C++ compiler flags.
         -> asflags: Set the assembler flags.
         -> vs_runtime: Set vs compiler runtime. (default: MT)
            -> values: {"MT","MD"}
</code></pre>
<p>Among them, configs is the configurable parameters provided by the spdlog package itself, and the configs part with builtin below is the built-in configuration parameters that all packages will have.<br>The top required section is the current configuration value of the project.</p>
<p>!> <code>vs_runtime</code> is the setting for vs runtime under msvc. In v2.2.9, it also supports automatic inheritance of all static dependencies. That is to say, if spdlog is set to MD, then the fmt package it depends on will also inherit automatically. Set the MD.</p>
<p>It can be seen that we have been able to customize the required packages very conveniently, but each package may have a lot of dependencies. If these dependencies are also customized, what should I do?</p>
<h3 id="installanyversionofthepackage">Install any version of the package</h3>
<p>By default, <code>add_requires("zlib >1.2.x")</code> can only select the package version that exists in the <code>xmake-repo</code> repository, because each version of the package will have a sha256 check value. Use To check the integrity of the package.</p>
<p>Therefore, there is no check value for packages of unknown version, and xmake will not let you choose to use it by default, which is not safe.</p>
<p>What if the package version we need cannot be selected for use? There are two ways, one is to submit a pr to <a href="https://github.com/xmake-io/xmake-repo">xmake-repo</a>, add the new version of the specified package and the corresponding sha256, for example:</p>
<pre><code class="lang-lua">package("zlib")
    add_versions("1.2.10", "8d7e9f698ce48787b6e1c67e6bff79e487303e66077e25cb9784ac8835978017")
    add_versions("1.2.11", "c3e5e9fdd5004dcb542feda5ee4f0ff0744628baf8ed2dd5d66f8ca1197cb1a1")
</code></pre>
<p>In addition, there is another way that the user passes <code>{verify = false}</code> configuration to <code>add_requires</code> to force the file integrity check of the package to be ignored, so that the sha256 value is not needed, so any version of the package can be installed.</p>
<p>Of course, there will be a certain degree of security and the risk of incomplete packages, which requires users to choose and evaluate.</p>
<pre><code class="lang-lua">add_requires("zlib 1.2.11", {verify = false})
</code></pre>
<h3 id="disableexternalheaderfilesearchpath">Disable external header file search path</h3>
<p>By default, packages installed through <code>add_requires</code> will use <code>-isystem</code> or <code>/external:I</code> to refer to the header file path inside, which can usually avoid the unmodifiable warning messages introduced by some package header files.<br>However, we can still disable external header files by setting <code>{external = false}</code> and switch back to the use of <code>-I</code>.</p>
<p>The compilation flags for external header files are enabled by default as follows:</p>
<pre><code class="lang-console">-isystem /Users/ruki/.xmake/packages/z/zlib/1.2.11/d639b7d6e3244216b403b39df5101abf/include
</code></pre>
<p>Manually turn off the compilation flags of external external header files as follows:</p>
<pre><code class="lang-lua">add_requires("zlib 1.x", {external = false})
</code></pre>
<pre><code class="lang-console">-I /Users/ruki/.xmake/packages/z/zlib/1.2.11/d639b7d6e3244216b403b39df5101abf/include
</code></pre>
<h2 id="installthirdpartypackages">Install third-party packages</h2>
<p>After version 2.2.5, xmake supports support for dependency libraries in third-party package managers, such as: conan, brew, vcpkg, clib and etc.</p>
<h3 id="addhomebrewdependencypackage">Add homebrew dependency package</h3>
<pre><code class="lang-lua">add_requires("brew::zlib", {alias = "zlib"})
add_requires("brew::pcre2/libpcre2-8", {alias = "pcre2"})

target("test")
    set_kind("binary")
    add_files("src/*.c")
    add_packages("pcre2", "zlib")
</code></pre>
<h3 id="addvcpkgdependencypackage">Add vcpkg dependency package</h3>
<pre><code class="lang-lua">add_requires("vcpkg::zlib", "vcpkg::pcre2")

target("test")
    set_kind("binary")
    add_files("src/*.c")
    add_packages("vcpkg::zlib", "vcpkg::pcre2")
</code></pre>
<p>We can also add a package alias name to simplify the use of <code>add_packages</code>:</p>
<pre><code class="lang-lua">add_requires("vcpkg::zlib", {alias = "zlib"})
add_requires("vcpkg::pcre2", {alias = "pcre2"})

target("test")
    set_kind("binary")
    add_files("src/*.c")
    add_packages("zlib", "pcre2")
</code></pre>
<p>If the vcpkg package has optional features, we can also directly use the vcpkg syntax format <code>packagename[feature1,feature2]</code> to install the package.</p>
<p>e.g:</p>
<pre><code class="lang-lua">add_requires("vcpkg::boost[core]")
</code></pre>
<p>After v2.6.3, xmake supports the new manifest mode of vcpkg, through which we can support version selection of vcpkg package, for example:</p>
<pre><code class="lang-lua">add_requires("vcpkg::zlib 1.2.11")
add_requires("vcpkg::fmt >=8.0.1", {configs = {baseline = "50fd3d9957195575849a49fa591e645f1d8e7156"}})
add_requires("vcpkg::libpng", {configs = {features = {"apng"}}})

target("test")
     set_kind("binary")
     add_files("src/*.cpp")
     add_packages("vcpkg::zlib", "vcpkg::fmt", "vcpkg::libpng")
</code></pre>
<p>After v2.6.8 it is also possible to additionally configure private repositories, which is only available in manifest mode.</p>
<pre><code class="lang-lua">local registries = {
    {
        kind = "git",
        repository = "https://github.com/SakuraEngine/vcpkg-registry",
        baseline = "e0e1e83ec66e3c9b36066f79d133b01eb68049f7",
        packages = {
            "skrgamenetworkingsockets"
        }
    }
}
add_requires("vcpkg::skrgamenetworkingsockets >=1.4.0+1", {configs = {registries = registries}})
</code></pre>
<h3 id="addconandependencypackage">Add conan dependency package</h3>
<pre><code class="lang-lua">add_requires("conan::zlib/1.2.11", {alias = "zlib", debug = true})
add_requires("conan::openssl/1.1.1g", {alias = "openssl",
    configs = {options = "OpenSSL:shared=True"}})

target("test")
    set_kind("binary")
    add_files("src/*.c")
    add_packages("openssl", "zlib")
</code></pre>
<p>After executing xmake to compile:</p>
<pre><code class="lang-console">ruki:test_package ruki$ xmake
checking for the architecture ... x86_64
checking for the Xcode directory ... /Applications/Xcode.app
checking for the SDK version of Xcode ... 10.14
note: try installing these packages (pass -y to skip confirm)?
  -> conan::zlib/1.2.11 (debug)
  -> conan::openssl/1.1.1g
please input: y (y/n)

  => installing conan::zlib/1.2.11 .. ok
  => installing conan::openssl/1.1.1g .. ok

[  0%]: cache compiling.release src/main.c
[100%]: linking.release test
</code></pre>
<p>Custom conan/settings:</p>
<pre><code class="lang-lua">add_requires("conan::poco/1.10.0", {alias = "poco",
    configs = {settings = {"compiler=gcc", "compiler.libcxx=libstdc++11"}}})
</code></pre>
<p>Some other conan related configuration items:</p>
<pre><code>{
    build          = {description = "use it to choose if you want to build from sources.", default = "missing", values = {"all", "never", "missing", "outdated"}},
    remote         = {description = "Set the conan remote server."},
    options        = {description = "Set the options values, e.g. OpenSSL:shared=True"},
    imports        = {description = "Set the imports for conan."},
    settings       = {description = "Set the build settings for conan."},
    build_requires = {description = "Set the build requires for conan.", default = "xmake_generator/0.1.0@bincrafters/testing"}
}
</code></pre><h3 id="addcondadependencypackage">Add conda dependency package</h3>
<pre><code class="lang-lua">add_requires("conda::zlib 1.2.11", {alias = "zlib"})

target("test")
     set_kind("binary")
     add_files("src/*.c")
     add_packages("zlib")
</code></pre>
<h3 id="addpacmandependencypackage">Add pacman dependency package</h3>
<p>We support not only the installation and integration of the pacman package on archlinux, but also the installation and integration of the mingw x86_64/i386 package of pacman on msys2.</p>
<pre><code class="lang-lua">add_requires("pacman::zlib", {alias = "zlib"})
add_requires("pacman::libpng", {alias = "libpng"})

target("test")
     set_kind("binary")
     add_files("src/*.c")
     add_packages("zlib", "libpng")
</code></pre>
<p>On archlinux:</p>
<pre><code class="lang-console">xmake
</code></pre>
<p>To install the mingw package on msys2, you need to specify the mingw platform:</p>
<pre><code class="lang-console">xmake f -p mingw -a [x86_64|i386]
xmake
</code></pre>
<h3 id="addclibdependencypackage">Add clib dependency package</h3>
<p>Clib is a source-based dependency package manager. The dependent package is downloaded directly to the corresponding library source code, integrated into the project to compile, rather than binary library dependencies.</p>
<p>It is also very convenient to integrate in xmake. The only thing to note is that you need to add the source code of the corresponding library to xmake.lua, for example:</p>
<pre><code class="lang-lua">add_requires("clib::clibs/[email protected]", {alias = "bytes"})

target("test")
    set_kind("binary")
    add_files("clib/bytes/*.c")
    add_files("src/*.c")
    add_packages("bytes")
</code></pre>
<h3 id="adddubdlangdependencypackage">Add dub/dlang dependency package</h3>
<p>xmake also supports dlang&#39;s dub package manager and integrates dlang&#39;s dependent packages to use.</p>
<pre><code class="lang-lua">add_rules("mode.debug", "mode.release")

add_requires("dub::log 0.4.3", {alias = "log"})
add_requires("dub::dateparser", {alias = "dateparser"})
add_requires("dub::emsi_containers", {alias = "emsi_containers"})
add_requires("dub::stdx-allocator", {alias = "stdx-allocator"})
add_requires("dub::mir-core", {alias = "mir-core"})

target("test")
     set_kind("binary")
     add_files("src/*.d")
     add_packages("log", "dateparser", "emsi_containers", "stdx-allocator", "mir-core")
</code></pre>
<h3 id="adddependencypackageofubuntuapt">Add dependency package of ubuntu/apt</h3>
<p>After v2.5.4 support the use of apt to integrate dependent packages, and will also automatically find packages that have been installed on the ubuntu system.</p>
<pre><code class="lang-lua">add_requires("apt::zlib1g-dev", {alias = "zlib"})

target("test")
     set_kind("binary")
     add_files("src/*.c")
     add_packages("zlib")
</code></pre>
<h3 id="addgentooportagedependencypackage">Add gentoo/portage dependency package</h3>
<p>After v2.5.4 support the use of Portage integrated dependency packages, and will also automatically find packages already installed on the Gentoo system.</p>
<pre><code class="lang-lua">add_requires("portage::libhandy", {alias = "libhandy"})

target("test")
     set_kind("binary")
     add_files("src/*.c")
     add_packages("libhandy")
</code></pre>
<h3 id="addnimblesdependencypackage">Add nimble&#39;s dependency package</h3>
<p>After v2.5.8, it supports the integration of packages in the nimble package manager, but it is currently only used for nim projects, because it does not provide binary packages, but directly installed nim code packages.</p>
<pre><code class="lang-lua">add_requires("nimble::zip >1.3")

target("test")
     set_kind("binary")
     add_files("src/main.nim")
     add_packages("nimble::zip")
</code></pre>
<h3 id="addcargosdependencypackage">Add cargo&#39;s dependency package</h3>
<p>Cargo dependency packages are mainly used for rust project integration, for example:</p>
<pre><code class="lang-lua">add_rules("mode.release", "mode.debug")
add_requires("cargo::base64 0.13.0")
add_requires("cargo::flate2 1.0.17", {configs = {features = "zlib"}})

target("test")
     set_kind("binary")
     add_files("src/main.rs")
     add_packages("cargo::base64", "cargo::flate2")
</code></pre>
<p>However, we can also use cxxbridge in C++ to call the Rust library interface to reuse all Rust packages in disguise.</p>
<p>For a complete example, see: <a href="https://github.com/xmake-io/xmake/tree/dev/tests/projects/rust/cxx_call_rust_library">Call Rust in C++</a></p>
<h3 id="addnugetdependencypackages">Add NuGet dependency packages</h3>
<p>After 2.9.7, we also support getting native libraries from dotnet/nuget and quickly integrating them.</p>
<pre><code class="lang-lua">add_requires("nuget::zlib_static", {alias = "zlib"})

target("test")
set_kind("binary")
add_files("src/*.cpp")
add_packages("zlib")
</code></pre>
<h2 id="usingselfbuiltprivatepackagerepository">Using self-built private package repository</h2>
<p>If the required package is not in the official repository <a href="https://github.com/xmake-io/xmake-repo">xmake-repo</a>, we can submit the contribution code to the repository for support.<br>But if some packages are only for personal or private projects, we can create a private repository repo. The repository organization structure can be found at: <a href="https://github.com/xmake-io/xmake-repo">xmake-repo</a></p>
<p>For example, now we have a private repository repo:<a href="mailto:`[email protected]">`[email protected]</a>:myrepo/xmake-repo.git`</p>
<p>We can add the repository with the following command:</p>
<pre><code class="lang-console">$ xmake repo --add myrepo [email protected]:myrepo/xmake-repo.git
</code></pre>
<p>Starting with v2.2.3, support for adding repos for specified branches, for example:</p>
<pre><code class="lang-console">$ xmake repo --add myrepo [email protected]:myrepo/xmake-repo.git dev
</code></pre>
<p>Or we write directly in xmake.lua:</p>
<pre><code class="lang-lua">add_repositories("my-repo [email protected]:myrepo/xmake-repo.git")
add_repositories("my-repo [email protected]:myrepo/xmake-repo.git dev")
</code></pre>
<p>If we just want to add one or two private packages, this time to build a git repo is too big, we can directly put the package repository into the project, for example:</p>
<pre><code>projectdir
  - myrepo
    - packages
      - t/tbox/xmake.lua
      - z/zlib/xmake.lua
  - src
    - main.c
  - xmake.lua
</code></pre><p>The above myrepo directory is your own private package repository, built into your own project, and then add this repository location in xmake.lua:</p>
<pre><code class="lang-lua">add_repositories("my-repo myrepo")
</code></pre>
<p>This can be referred to <a href="https://github.com/tboox/benchbox">benchbox</a> project, which has a built-in private repository.</p>
<p>We can even build a package without directly building a package description into the project xmake.lua, which is useful for relying on one or two packages, for example:</p>
<pre><code class="lang-lua">package("libjpeg")

    set_urls("http://www.ijg.org/files/jpegsrc.$(version).tar.gz")

    add_versions("v9c", "650250979303a649e21f87b5ccd02672af1ea6954b911342ea491f351ceb7122")

    on_install("windows", function (package)
        os.mv("jconfig.vc", "jconfig.h")
        os.vrun("nmake -f makefile.vc")
        os.cp("*.h", package:installdir("include"))
        os.cp("libjpeg.lib", package:installdir("lib"))
    end)

    on_install("macosx", "linux", function (package)
        import("package.tools.autoconf").install(package)
    end)

package_end()

add_requires("libjpeg")

target("test")
    set_kind("binary")
    add_files("src/*.c")
    add_packages("libjpeg")
</code></pre>
<h2 id="packagemanagementcommand">Package Management Command</h2>
<p>The package management command <code>$ xmake require</code> can be used to manually display the download, install, uninstall, retrieve, and view package information.</p>
<h3 id="xrepocommand">xrepo command</h3>
<p><code>xmake require</code> is only used for the current project. We also provide a more convenient independent <code>xrepo</code> package manager command to install, uninstall, find and manage packages globally.</p>
<p>For detailed documentation, see: <a href="https://xrepo.xmake.io/#/getting_started">Getting Started with Xrepo Commands</a></p>
<h3 id="installthespecifiedpackage">Install the specified package</h3>
<pre><code class="lang-console">$ xmake require tbox
</code></pre>
<p>Install the specified version package:</p>
<pre><code class="lang-console">$ xmake require tbox "~1.6"
</code></pre>
<p>Force a re-download of the installation and display detailed installation information:</p>
<pre><code class="lang-console">$ xmake require -f -v tbox "1.5.x"
</code></pre>
<p>Pass additional setup information:</p>
<pre><code class="lang-console">$ xmake require --extra="{debug=true,config={small=true}}" tbox
</code></pre>
<p>Install the debug package and pass the compilation configuration information of <code>small=true</code> to the package.</p>
<h3 id="uninstallthespecifiedpackage">Uninstall the specified package</h3>
<pre><code class="lang-console">$ xmake require --uninstall tbox
</code></pre>
<p>This will completely uninstall the removal package file.</p>
<h3 id="showpackageinformation">Show package information</h3>
<pre><code class="lang-console">$ xmake require --info tbox
</code></pre>
<h3 id="searchforpackagesinthecurrentrepository">Search for packages in the current repository</h3>
<pre><code class="lang-console">$ xmake require --search tbox
</code></pre>
<p>This is to support fuzzy search and lua pattern matching search:</p>
<pre><code class="lang-console">$ xmake require --search pcr
</code></pre>
<p>Will also search for pcre, pcre2 and other packages.</p>
<h3 id="listthecurrentlyinstalledpackages">List the currently installed packages</h3>
<pre><code class="lang-console">$ xmake require --list
</code></pre>
<h2 id="repositorymanagementcommand">Repository Management Command</h2>
<p>As mentioned above, adding a private repository is available (supporting local path addition):</p>
<pre><code class="lang-console">$ xmake repo --add myrepo [email protected]:myrepo/xmake-repo.git
</code></pre>
<p>We can also remove a repository that has already been installed:</p>
<pre><code class="lang-console">$ xmake repo --remove myrepo
</code></pre>
<p>Or view all the added repositories:</p>
<pre><code class="lang-console">$ xmake repo --list
</code></pre>
<p>If the remote repository has updates, you can manually perform a repository update to get more and the latest packages:</p>
<pre><code class="lang-console">$ xmake repo -u
</code></pre>
<h2 id="remotepackagedownloadoptimization">Remote package download optimization</h2>
<p>If the download package is slow or fails due to an unstable network, we can use the following methods to resolve it.</p>
<h3 id="manualdownload">Manual download</h3>
<p>By default, xmake will call curl, wget and other tools to download, users can also manually download with their own downloader (you can also use an agent), put the downloaded package in their own directory, for example: <code>/download/packages/zlib -v1.0.tar.gz</code></p>
<p>Then use the following command to set the search directory for package download:</p>
<pre><code class="lang-console">$ xmake g --pkg_searchdirs="/download/packages"
</code></pre>
<p>Then re-execute xmake to compile, xmake will first look for the source package from <code>/download/packages</code>, and then use it directly, no longer download it yourself.</p>
<p>As for the package name you are looking for, you can check it by the following command:</p>
<pre><code class="lang-console">$ xmake require --info zlib
-> searchdirs: /download/packages
-> searchnames: zlib-1.2.11.tar.gz
</code></pre>
<p>We can see the corresponding search directory and the searched package name.</p>
<h3 id="proxydownload">Proxy download</h3>
<p>If manual downloading is still troublesome, we can also let xmake go directly to the agent.</p>
<pre><code class="lang-console">$ xmake g --proxy="socks5://127.0.0.1:1086"
$ xmake g --help
    -x PROXY, --proxy=PROXY Use proxy on given port. [PROTOCOL://]HOST[:PORT]
                                 e.g.
                                 -xmake g --proxy=&#39;http://host:port&#39;
                                 -xmake g --proxy=&#39;https://host:port&#39;
                                 -xmake g --proxy=&#39;socks5://host:port&#39;
</code></pre>
<p>The <code>--proxy</code> parameter specifies the proxy protocol and address. The specific syntax can refer to curl. Usually, it can support http, https, socks5 and other protocols, but the actual support depends on curl, wget and git. For example, wget does not support the socks5 protocol.</p>
<p>We can use the following parameters to specify which hosts go to the proxy. If not set, the default is to go global.</p>
<pre><code class="lang-console">--proxy_hosts=PROXY_HOSTS Only enable proxy for the given hosts list, it will enable all if be unset,
                             and we can pass match pattern to list:
                                 e.g.
                                 -xmake g --proxy_hosts=&#39;github.com,gitlab.*,*.xmake.io&#39;
</code></pre>
<p>If the hosts list is set, then the matching hosts in this list will go to the proxy. .</p>
<p><code>--proxy_host</code> supports multiple hosts settings, separated by commas, and supports basic pattern matching *.github.com, and other lua pattern matching rules are also supported</p>
<p>If we feel that the above hosts mode configuration is not flexible enough, we can also follow pac&#39;s automatic proxy configuration rules:</p>
<pre><code class="lang-console">--proxy_pac=PROXY_PAC Set the auto proxy configuration file. (default: pac.lua)
                                     e.g.
                                     -xmake g --proxy_pac=pac.lua (in /Users/ruki/.xmake or absolute path)
                                     -function main(url, host)
                                           if host ==&#39;github.com&#39; then
                                                return true
                                           end
                                       end
</code></pre>
<p>!> If there are proxy_hosts, the host configuration is preferred, otherwise, the pac configuration can be used.</p>
<p>The default path of pac: ~/.xmake/pac.lua, if --proxy is set, and this file exists, it will automatically go to pac. If it does not exist, and there are no hosts, then the proxy will take effect globally.</p>
<p>You can also manually specify the pac full path</p>
<pre><code class="lang-console">$ xmake g --proxy_pac=/xxxx/xxxxx_pac.lua
</code></pre>
<p>Configuration rule description:</p>
<pre><code class="lang-lua">function main(url, host)
    if host:find("bintray.com") then
        return true
    end
end
</code></pre>
<p>If it returns true, then the url and host are the proxy to go, not to return or return false, it is not to proxy.</p>
<p>For specific details of this piece, see: <a href="https://github.com/xmake-io/xmake/issues/854">https://github.com/xmake-io/xmake/issues/854</a></p>
<h4 id="mirroragent">Mirror Agent</h4>
<p>After v2.5.4, mirroring proxy rules can also be configured in the pac.lua configuration. For example, access to all github.com domain names is switched to the hub.fastgit.org domain name to achieve accelerated downloading of packages.</p>
<pre><code class="lang-lua">function mirror(url)
      return url:gsub("github.com", "hub.fastgit.org")
end
</code></pre>
<pre><code class="lang-console">$ xrepo install libpng
> curl https://hub.fastgit.org/glennrp/libpng/archive/v1.6.37.zip -o v1.6.37.zip
</code></pre>
<h2 id="submitpackagestotheofficialrepository">Submit packages to the official repository</h2>
<h3 id="packagestructureinrepository">Package structure in repository</h3>
<p>Before making our own package, we need to understand the structure of the next package repository, whether it is the official package repository or the self-built private package repository, the structure is the same:</p>
<pre><code>xmake-repo
   - packages
     - t/tbox/xmake.lua
     - z/zlib/xmake.lua
</code></pre><p>Through the above structure, you can see that each package will have a xmake.lua to describe its installation rules, and according to the <code>z/zlib</code> two-level sub-category storage, convenient for quick retrieval.</p>
<h3 id="packagedescription">Package Description</h3>
<p>The description rules for the package are basically done in its xmake.lua, which is similar to the xmake.lua description in the project project. The difference is that the description field only supports <code>package()</code>.</p>
<p>However, in the project xmake.lua, you can also directly add <code>package()</code> to the built-in package description, and even the package warehouse is saved, sometimes it will be more convenient.</p>
<p>First, let&#39;s take a look at zlib&#39;s description rules first. This rule can be found at <a href="https://github.com/xmake-io/xmake-repo/blob Found under /master/packages/z/zlib/xmake.lua">xmake-repo/z/zlib/xmake.lua</a>.</p>
<pre><code>package("zlib")

    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")
    add_versions("1.2.11", "c3e5e9fdd5004dcb542feda5ee4f0ff0744628baf8ed2dd5d66f8ca1197cb1a1")

    on_install("windows", function (package)
        io.gsub("win32/Makefile.msc", "%-MD", "-" .. package:config("vs_runtime"))
        os.vrun("nmake -f win32\\Makefile.msc zlib.lib")
        os.cp("zlib.lib", package:installdir("lib"))
        os.cp("*.h", package:installdir("include"))
    end)

    on_install("linux", "macosx", function (package)
        import("package.tools.autoconf").install(package, {"--static"})
    end)

    on_install("iphoneos", "android@linux,macosx", "mingw@linux,macosx", function (package)
        import("package.tools.autoconf").configure(package, {host = "", "--static"})
        io.gsub("Makefile", "\nAR=.-\n",      "\nAR=" .. (package:build_getenv("ar") or "") .. "\n")
        io.gsub("Makefile", "\nARFLAGS=.-\n", "\nARFLAGS=cr\n")
        io.gsub("Makefile", "\nRANLIB=.-\n",  "\nRANLIB=\n")
        os.vrun("make install -j4")
    end)

    on_test(function (package)
        assert(package:has_cfuncs("inflate", {includes = "zlib.h"}))
    end)
</code></pre><p>This package rule adds installation rules to windows, linux, macosx, iphoneos, mingw and other platforms. Basically, it has achieved full platform coverage, and even some cross-compilation platforms, which is a typical example.</p>
<p>Of course, some packages rely on source code implementation and are not completely cross-platform, so you only need to set the installation rules for the platforms it supports.</p>
<p>For more detailed package configuration API descriptions see: <a href="/mirror/manual/package_dependencies.html">Package Interface Documentation</a></p>
<h3 id="extendedconfigurationparameters">Extended configuration parameters</h3>
<p>See: <a href="/mirror/manual/package_dependencies.html#packageadd_configs">add_configs</a> for details.</p>
<h3 id="builtinconfigurationparameters">Built-in configuration parameters</h3>
<p>In addition to setting some extended configuration parameters via <a href="/mirror/manual/package_dependencies.html#packageadd_configs">add_configs</a>, xmake also provides some built-in configuration parameters that can be used.</p>
<h4 id="enabledebugpackage">Enable debug package</h4>
<pre><code class="lang-lua">add_requires("xxx", {debug = true})
</code></pre>
<p>There must be relevant processing in the package description to support:</p>
<pre><code class="lang-lua">on_install(function (package)
    Local configs = {}
    if package:debug() then
        Table.insert(configs, "--enable-debug")
    end
    import("package.tools.autoconf").install(package)
end)
</code></pre>
<h4 id="settingupthemsvcruntimelibrary">Setting up the msvc runtime library</h4>
<pre><code class="lang-lua">add_requires("xxx", {configs = {vs_runtime = "MT"}})
</code></pre>
<p>Normally, packages installed by built-in tool scripts such as <code>import("package.tools.autoconf").install</code> are automatically processed internally by vs_runtime.</p>
<p>But if it is a special source package, the build rules are special, then you need to handle it yourself:</p>
<pre><code class="lang-lua">on_install(function (package)
    io.gsub("build/Makefile.win32.common", "%-MD", "-" .. package:config("vs_runtime"))
end)
</code></pre>
<h3 id="addingenvironmentvariables">Adding environment variables</h3>
<p>For some libraries, there are also executable tools. if you need to use these tools in the integration package, you can also set the corresponding PATH environment variable:</p>
<pre><code class="lang-lua">package("luajit")
    on_load(function (package)
        if is_plat("windows") then
            Package:addenv("PATH", "lib")
        end
        Package:addenv("PATH", "bin")
    end)
</code></pre>
<p>In the project project, the corresponding environment variables will only take effect after the corresponding package is integrated by <code>add_packages</code>.</p>
<pre><code class="lang-lua">add_requires("luajit")
target("test")
    set_kind("binary")
    add_packages("luajit")
    after_run(function (package)
        os.exec("luajit --version")
    end)
</code></pre>
<h3 id="installingbinarypackages">Installing binary packages</h3>
<p>Xmake also supports direct reference to the binary version package, which is used directly for installation, for example:</p>
<pre><code class="lang-lua">if is_plat("windows") then
    set_urls("https://www.libsdl.org/release/SDL2-devel-$(version)-VC.zip")
    add_versions("2.0.8", "68505e1f7c16d8538e116405411205355a029dcf2df738dbbc768b2fe95d20fd")
end

on_install("windows", function (package)
    os.cp("include", package:installdir())
    os.cp("lib/$(arch)/*.lib", package:installdir("lib"))
    os.cp("lib/$(arch)/*.dll", package:installdir("lib"))
end)
</code></pre>
<h3 id="localtest">Local test</h3>
<p>If you have added and created a new package in the local xmake-repo repository, you can run the test locally and pass it. If the test passes, you can submit the pr to the official repository and request the merge.</p>
<p>We can execute the following script to test the specified package:</p>
<pre><code class="lang-bash">cd xmake-repo
xmake l scripts/test.lua -v -D zlib
</code></pre>
<p>The above command will force the download and installation of the zlib package to test whether the entire installation process is ok, plus <code>-v -D</code> is to see the complete detailed log information and error information, which is convenient for debugging analysis.</p>
<p>If the network environment is not good, do not want to re-download all dependencies every time, you can add the <code>--shallow</code> parameter to execute, this parameter tells the script, just re-decompress the local cached zlib source package, re-execute the installation command, but Will not download various dependencies.</p>
<pre><code class="lang-bash">cd xmake-repo
xmake l scripts/test.lua -v -D --shallow zlib
</code></pre>
<p>If we want to test the package rules of other platforms, such as: android, iphoneos and other platforms, you can specify by <code>-p/--plat</code> or <code>-a/--arch</code>.</p>
<pre><code class="lang-bash">cd xmake-repo
xmake l scripts/test.lua -v -D --shallow -p iphoneos -a arm64 zlib
xmake l scripts/test.lua -v -D --shallow -p android --ndk=/xxxx zlib
</code></pre>
<h2 id="submitpackagetotheofficialrepository">Submit package to the official repository</h2>
<p>If you need a package that is not supported by the current official repository, you can commit it to the official repository after local tuning: <a href="https://github.com/xmake-io/xmake-repo">xmake-repo</a></p>
<p>For detailed contribution descriptions, see: <a href="https://github.com/xmake-io/xmake-repo/blob/master/CONTRIBUTING.md">CONTRIBUTING.md</a></p>
<p>For how to make your own package, you can look at the above: <a href="#submit-packages-to-the-official-repository">Submit packages to the official repository</a>.</p>
<h2 id="dependentpackagelockandupgrade">Dependent package lock and upgrade</h2>
<p>After v2.5.7, version locks of dependent packages have been added, similar to npm&#39;s package.lock and cargo&#39;s cargo.lock.</p>
<p>For example, if we quote some packages, by default, if the version is not specified, xmake will automatically pull the latest version of the package for integrated use each time, for example:</p>
<pre><code class="lang-lua">add_requires("zlib")
</code></pre>
<p>However, if the upstream package warehouse is updated and changed, for example, zlib adds a new version 1.2.11, or the installation script is changed, the user&#39;s dependent packages will change.</p>
<p>This can easily lead to some projects that were originally compiled and passed, and there may be some unstable factors due to changes in dependent packages, and the compilation may fail, etc.</p>
<p>In order to ensure that the package used by the user&#39;s project is fixed each time, we can enable the package dependency lock through the following configuration.</p>
<pre><code class="lang-lua">set_policy("package.requires_lock", true)
</code></pre>
<p>This is a global setting and must be set to the global root scope. If enabled, xmake will automatically generate a <code>xmake-requires.lock</code> configuration file after executing package pull.</p>
<p>It contains all the packages that the project depends on, as well as the current package version and other information.</p>
<pre><code class="lang-lua">{
    __meta__ = {
        version = "1.0"
    },
    ["macosx|x86_64"] = {
        ["cmake#31fecfc4"] = {
            repo = {
                branch = "master",
                commit = "4498f11267de5112199152ab030ed139c985ad5a",
                url = "https://github.com/xmake-io/xmake-repo.git"
            },
            version = "3.21.0"
        },
        ["glfw#31fecfc4"] = {
            repo = {
                branch = "master",
                commit = "eda7adee81bac151f87c507030cc0dd8ab299462",
                url = "https://github.com/xmake-io/xmake-repo.git"
            },
            version = "3.3.4"
        },
        ["opengl#31fecfc4"] = {
            repo = {
                branch = "master",
                commit = "94d2eee1f466092e04c5cf1e4ecc8c8883c1d0eb",
                url = "https://github.com/xmake-io/xmake-repo.git"
            }
        }
    }
}
</code></pre>
<p>Of course, we can also execute the following command to force the upgrade package to the latest version.</p>
<pre><code class="lang-console">$ xmake require --upgrade
upgrading packages ..
  zlib: 1.2.10 -> 1.2.11
1 package is upgraded!
</code></pre>
<h2 id="distributingandusingcustompackagerules">Distributing and using custom package rules</h2>
<p>Since version 2.7.2 we have been able to add custom build rule scripts to the package management repository to enable dynamic distribution and installation following packages.</p>
<p>We need to place the custom rules in the <code>packages/x/xxx/rules</code> directory of the repository and it will follow the package as it is installed.</p>
<p>But it has also some limits:</p>
<ul>
<li>For in-package rules, we cannot add <code>on_load</code>, <code>after_load</code> scripts, but we can usually use <code>on_config</code> instead.</li>
</ul>
<h3 id="addingpackagerules">Adding package rules</h3>
<p>We need to add the rules script to the rules fixed directory, for example: packages/z/zlib/rules/foo.lua</p>
<pre><code class="lang-lua">rule("foo")
    on_config(function (target)
        print("foo: on_config %s", target:name())
    end)
</code></pre>
<h3 id="applyingpackagerules">Applying package rules</h3>
<p>The rules are used in a similar way as before, the only difference being that we need to specify which package&#39;s rules to access by prefixing them with <code>@packagename/</code>.</p>
<p>The exact format: <code>add_rules("@packagename/rulename")</code>, e.g.: <code>add_rules("@zlib/foo")</code>.</p>
<pre><code class="lang-lua">add_requires("zlib", {system = false})
target("test")
    set_kind("binary")
    add_files("src/*.cpp")
    add_packages("zlib")
    add_rules("@zlib/foo")
</code></pre>
<h3 id="referencingrulesbypackagealias">Referencing rules by package alias</h3>
<p>If a package alias exists, xmake will give preference to the package alias to get the rules.</p>
<pre><code class="lang-lua">add_requires("zlib", {alias = "zlib2", system = false})
target("test")
    set_kind("binary")
    add_files("src/*.cpp")
    add_packages("zlib2")
    add_rules("@zlib2/foo")
</code></pre>
<h3 id="addingpackageruledependencies">Adding package rule dependencies</h3>
<p>We can use <code>add_deps("@bar")</code> to add additional rules relative to the current package directory.</p>
<p>However, we cannot add rule dependencies from other packages, they are completely isolated and we can only refer to rules from other packages imported by <code>add_requires</code> in the user project.</p>
<p>packages/z/zlib/rules/foo.lua</p>
<pre><code class="lang-lua">rule("foo")
    add_deps("@bar")
    on_config(function (target)
        print("foo: on_config %s", target:name())
    end)
</code></pre>
<p>packages/z/zlib/rules/bar.lua</p>
<pre><code class="lang-lua">rule("bar")
    on_config(function (target)
        print("bar: on_config %s", target:name())
    end)
</code></pre>
<h2 id="usingxrepospackagemanagementincmake">Using Xrepo&#39;s package management in CMake</h2>
<p>CMake wrapper for <a href="https://xrepo.xmake.io/">Xrepo</a> C and C++ package manager.</p>
<p>This allows using CMake to build your project, while using Xrepo to manage<br>dependent packages. This project is partially inspired by<br><a href="https://github.com/conan-io/cmake-conan">cmake-conan</a>.</p>
<p>Example use cases for this project:</p>
<ul>
<li>Existing CMake projects which want to use Xrepo to manage packages.</li>
<li>New projects which have to use CMake, but want to use Xrepo to manage<br>packages.</li>
</ul>
<h3 id="apis">Apis</h3>
<h4 id="xrepo_package">xrepo_package</h4>
<p><a href="./xrepo.cmake"><code>xrepo.cmake</code></a> provides <code>xrepo_package</code> function to manage<br>packages.</p>
<pre><code class="lang-cmake">xrepo_package(
    "foo 1.2.3"
    [CONFIGS feature1=true,feature2=false]
    [CONFIGS path/to/script.lua]
    [DEPS]
    [MODE debug|release]
    [ALIAS aliasname]
    [OUTPUT verbose|diagnosis|quiet]
    [DIRECTORY_SCOPE]
)
</code></pre>
<p>Some of the function arguments correspond directly to Xrepo command options.</p>
<p><code>xrepo_package</code> adds package install directory to <code>CMAKE_PREFIX_PATH</code>. So <code>find_package</code><br>can be used. If <code>CMAKE_MINIMUM_REQUIRED_VERSION</code> >= 3.1, cmake <code>PkgConfig</code> will also search<br>for pkgconfig files under package install directories.</p>
<p>After calling <code>xrepo_package(foo)</code>, there are three ways to use <code>foo</code> package:</p>
<ol>
<li>Call <code>find_package(foo)</code> if package provides cmake config-files.<ul>
<li>Refer to CMake <a href="https://cmake.org/cmake/help/latest/command/find_package.html"><code>find_package</code></a> documentation for more details.</li>
</ul>
</li>
<li>If the package does not provide cmake config files or find modules<ul>
<li>Following variables can be used to use the pacakge (variable names following cmake<br>find modules <a href="https://cmake.org/cmake/help/latest/manual/cmake-developer.7.html#standard-variable-names">standard variable names</a>)<ul>
<li><code>foo_INCLUDE_DIRS</code></li>
<li><code>foo_LIBRARY_DIRS</code></li>
<li><code>foo_LIBRARIES</code></li>
<li><code>foo_DEFINITIONS</code></li>
</ul>
</li>
<li>If <code>DIRECTORY_SCOPE</code> is specified, <code>xrepo_package</code> will run following code<pre><code class="lang-cmake">include_directories(${foo_INCLUDE_DIRS})
link_directories(${foo_LIBRARY_DIRS})
</code></pre>
</li>
</ul>
</li>
<li>Use <code>xrepo_target_packages</code>. Please refer to following section.</li>
</ol>
<p>Note <code>CONFIGS path/to/script.lua</code> is for fine control over package configs.<br>For example:</p>
<ul>
<li>Exclude packages on system.</li>
<li>Override dependent packages&#39; default configs, e.g. set <code>shared=true</code>.</li>
</ul>
<p>If <code>DEPS</code> is specified, all dependent libraries will add to <code>CMAKE_PREFIX_PATH</code>, along with include,<br>libraries being included in the four variables.</p>
<h4 id="xrepo_target_packages">xrepo_target_packages</h4>
<p>Add package includedirs and links/linkdirs to the given target.</p>
<pre><code class="lang-cmake">xrepo_target_packages(
    target
    [NO_LINK_LIBRARIES]
    [PRIVATE|PUBLIC|INTERFACE]
    package1 package2 ...
)
</code></pre>
<ul>
<li><code>NO_LINK_LIBRARIES</code><ul>
<li>In case a package provides multiple libs and user need to select which one<br>to link, pass <code>NO_LINK_LIBRARIES</code> to disable calling <code>target_link_libraries</code>.<br>User should call <code>target_link_libraries</code> to setup correct library linking.</li>
</ul>
</li>
<li><code>PRIVATE|PUBLIC|INTERFACE</code><ul>
<li>The default is not specifying propagation control keyword when calling<br><code>target_include_libraries</code>, <code>target_link_libraries</code>, etc, because there&#39;s no<br>default choice on this in CMake.</li>
<li>Refer to this <a href="https://stackoverflow.com/a/26038443">Stack Overflow answer</a><br>for differences.</li>
</ul>
</li>
</ul>
<h3 id="usepackagefromofficialrepository">Use package from official repository</h3>
<p>Xrepo official repository: <a href="https://github.com/xmake-io/xmake-repo">xmake-repo</a></p>
<p>Here&#39;s an example <code>CMakeLists.txt</code> that uses <code>gflags</code> package version 2.2.2<br>managed by Xrepo.</p>
<h4 id="integratexrepocmake">Integrate xrepo.cmake</h4>
<pre><code class="lang-cmake">cmake_minimum_required(VERSION 3.13.0)

project(foo)

# Download xrepo.cmake if not exists in build directory.
if(NOT EXISTS "${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_VERIFY ON)
endif()

# Include xrepo.cmake so we can use xrepo_package function.
include(${CMAKE_BINARY_DIR}/xrepo.cmake)
</code></pre>
<h4 id="addbasicpackages">Add basic packages</h4>
<pre><code class="lang-cmake">xrepo_package("zlib")

add_executable(example-bin "")
target_sources(example-bin PRIVATE
    src/main.cpp
)
xrepo_target_packages(example-bin zlib)
</code></pre>
<h4 id="addpackageswithconfigs">Add packages with configs</h4>
<pre><code class="lang-cmake">xrepo_package("gflags 2.2.2" CONFIGS "shared=true,mt=true")

add_executable(example-bin "")
target_sources(example-bin PRIVATE
    src/main.cpp
)
xrepo_target_packages(example-bin gflags)
</code></pre>
<h4 id="addpackageswithcmakemodules">Add packages with cmake modules</h4>
<pre><code class="lang-cmake">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.
# Refer to https://cmake.org/cmake/help/latest/command/find_package.html#search-modes
find_package(gflags CONFIG COMPONENTS shared)

add_executable(example-bin "")
target_sources(example-bin PRIVATE
    src/main.cpp
)
target_link_libraries(example-bin gflags)
</code></pre>
<h4 id="addcustompackages">Add custom packages</h4>
<p>We can also add custom packages in our project.</p>
<pre><code class="lang-cmake">set(XREPO_XMAKEFILE ${CMAKE_CURRENT_SOURCE_DIR}/packages/xmake.lua)
xrepo_package("myzlib")

add_executable(example-bin "")
target_sources(example-bin PRIVATE
    src/main.cpp
)
xrepo_target_packages(example-bin myzlib)
</code></pre>
<p>Define myzlib package in packages/xmake.lua</p>
<pre><code class="lang-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)
      -- TODO
    end)

    on_test(function (package)
        assert(package:has_cfuncs("inflate", {includes = "zlib.h"}))
    end)
</code></pre>
<p>We can write a custom package in xmake.lua, please refer <a href="https://xmake.io/#/package/remote_package?id=package-description">Define Xrepo package</a>.</p>
<h3 id="optionsandvariablesforxrepocmake">Options and variables for <code>xrepo.cmake</code></h3>
<p>Following options can be speicified with <code>cmake -D<var>=<value></code>.<br>Or use <code>set(var value)</code> in <code>CMakeLists.txt</code>.</p>
<ul>
<li><code>XMAKE_CMD</code>: string, defaults to empty string<ul>
<li>Specify path to <code>xmake</code> command. Use this option if <code>xmake</code> is not installed<br>in standard location and can&#39;t be detected automatically.</li>
</ul>
</li>
<li><code>XREPO_PACKAGE_VERBOSE</code>: <code>[ON|OFF]</code><ul>
<li>Enable verbose output for Xrepo Packages.</li>
</ul>
</li>
<li><code>XREPO_BOOTSTRAP_XMAKE</code>: <code>[ON|OFF]</code><ul>
<li>If <code>ON</code>, <code>xrepo.cmake</code> will install <code>xmake</code> if it is not found.</li>
</ul>
</li>
<li><code>XREPO_PACKAGE_DISABLE</code>: <code>[ON|OFF]</code><ul>
<li>Set this to <code>ON</code> to disable <code>xrepo_package</code> function.</li>
<li>If setting this variable in <code>CMakeLists.txt</code>, please set it before including<br><code>xrepo.cmake</code>.</li>
</ul>
</li>
</ul>
<h3 id="switchingcompilerandcrosscompilation">Switching compiler and cross compilation</h3>
<p>Following variables controll cross compilation. Note: to specify a different compiler other than<br>the default one on system, platform must be set to "cross".</p>
<ul>
<li><code>XREPO_TOOLCHAIN</code>: string, defaults to empty string<ul>
<li>Specify toolchain name. Run <code>xmake show -l toolchains</code> to see available toolchains.</li>
</ul>
</li>
<li><code>XREPO_PLATFORM</code>: string, defaults to empty string<ul>
<li>Specify platform name. If <code>XREPO_TOOLCHAIN</code> is specified and this is not,<br><code>XREPO_PLATFORM</code> will be set to <code>cross</code>.</li>
</ul>
</li>
<li><code>XREPO_ARCH</code>: string, defaults to empty string<ul>
<li>Specify architecture name.</li>
</ul>
</li>
<li><code>XREPO_XMAKEFILE</code>: string, defaults to empty string<ul>
<li>Specify Xmake script file of Xrepo package.</li>
</ul>
</li>
</ul>
<h3 id="usepackagefrom3rdrepository">Use package from 3rd repository</h3>
<p>In addition to installing packages from officially maintained repository,<br>Xrepo can also install packages from third-party package managers such as vcpkg/conan/conda/pacman/homebrew/apt/dub/cargo.</p>
<p>For the use of the command line, we can refer to the documentation: <a href="https://xrepo.xmake.io/#/getting_started?id=install-packages-from-third-party-package-manager">Xrepo command usage</a></p>
<p>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. <code>vcpkg::zlib</code>, <code>conan::pcre2</code></p>
<h4 id="conan">Conan</h4>
<pre><code class="lang-cmake">xrepo_package("conan::gflags/2.2.2")
</code></pre>
<h4 id="conda">Conda</h4>
<pre><code class="lang-cmake">xrepo_package("conda::gflags 2.2.2")
</code></pre>
<h4 id="vcpkg">Vcpkg</h4>
<pre><code class="lang-cmake">xrepo_package("vcpkg::gflags")
</code></pre>
<h4 id="homebrew">Homebrew</h4>
<pre><code class="lang-cmake">xrepo_package("brew::gflags")
</code></pre>
<h2 id="howdoesitwork">How does it work?</h2>
<p><a href="./xrepo.cmake"><code>xrepo.cmake</code></a> module basically does the following tasks:</p>
<ul>
<li>Call <code>xrepo install</code> to ensure specific package is installed.</li>
<li>Call <code>xrepo fetch</code> to get package information and setup various variables for<br>using the installed package in CMake.</li>
</ul>
<p>The following section is a short introduction to using Xrepo. It helps to<br>understand how <code>xrepo.cmake</code> works and how to specify some of the options in<br><code>xrepo_package</code>.</p>
<h3 id="xrepoworkflow">Xrepo workflow</h3>
<p>Assmuing <a href="https://github.com/xmake-io/xmake/">Xmake</a> is installed.</p>
<p>Suppose we want to use <code>gflags</code> packages.</p>
<p>First, search for <code>gflags</code> package in Xrepo.</p>
<pre><code>$ xrepo search gflags
The package names:
    gflags:
      -> gflags-v2.2.2: The gflags package contains a C++ library that implements commandline flags processing. (in builtin-repo)
</code></pre><p>It&#39;s already in Xrepo, so we can use it. If it&#39;s not in Xrepo, we can create it in<br><a href="https://xrepo.xmake.io/#/getting_started?id=suppory-distributed-repository">self-built repositories</a>.</p>
<p>Let&#39;s see what configs are available for the package before using it:</p>
<pre><code>$ 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)
...
</code></pre><p>Suppose we want to use multi-threaded gflags shared library. We can install the package with following command:</p>
<pre><code>xrepo install --mode=release --configs=&#39;mt=true,shared=true&#39; &#39;gflags 2.2.2&#39;
</code></pre><p>Only the first call to the above command will compile and install the package.<br>To speed up cmake configuration, <code>xrepo</code> command will only be executed when the<br>package is not installed or <code>xrepo_package</code> parameters have changed.</p>
<p>After package installation, because we are using CMake instead of Xmake, we have<br>to get package installation information by ourself. <code>xrepo fetch</code> command does<br>exactly this:</p>
<pre><code>xrepo fetch --json --mode=release --configs=&#39;mt=true,shared=true&#39; &#39;gflags 2.2.2&#39;
</code></pre><p>The above command will print out package&#39;s include, library directory along with<br>other information. <code>xrepo_package</code> uses these information to setup variables to use<br>the specified package.</p>
<p>For CMake 3.19 and later which has JSON support, <code>xrepo_package</code> parses the JSON<br>output. For previous version of CMake, <code>xrepo_package</code> uses only the <code>--cflags</code> option<br>to get package include directory. Library and cmake module directory are infered from that<br>directory, so it maybe unreliable to detect the correct paths.</p>
</article>
</body>
</html>