Add Packages
Introduction
Xmake has built-in support for package dependency integration. You can declare the required dependency packages through the add_requires interface.
Then, through the add_packages interface, bind the declared package to the required compilation target, for example:
add_requires("tbox 1.6.*", "libpng ~1.16", "zlib")
target("foo")
set_kind("binary")
add_files("src/*.c")
add_packages("tbox", "libpng")
target("bar")
set_kind("binary")
add_files("src/*.c")
add_packages("zlib")
Among them, add_requires
is a global interface, used for package configuration declaration, and Xmake will trigger search and installation based on the declared package.
Since a project may have multiple target programs, each target program may require different dependency packages, so we also need to bind the target through add_packages
.
In the above configuration example, the foo target binds the tbox and libpng packages, while the bar target binds the zlib package.
Basic Usage and Common Scenarios
add_requires("pkgname")
declares dependencies, supports version, optional, alias, etc.add_packages("pkgname")
binds packages to targets, automatically adds links, includedirs, etc.
Typical Scenarios
- Multiple targets depend on different packages
- One target depends on multiple packages
- Supports C/C++/Fortran/multi-platform
API Details
Specify Package Version
add_requires("tbox 1.6.*", "libpng ~1.16", "zlib")
Optional Package
add_requires("foo", {optional = true})
Disable System Library
add_requires("foo", {system = false})
Specify Alias
add_requires("foo", {alias = "myfoo"})
add_packages("myfoo")
Platform/Arch Limitation
add_requires("foo", {plat = "windows", arch = "x64"})
Pass Package Configs
add_requires("tbox", {configs = {small = true}})
Pass Configs to Dependencies
add_requireconfs("spdlog.fmt", {configs = {header_only = true}})
Advanced Features
- Semantic version, branch, commit support
- Debug/release package support
- Multi-repo, private repo support
- Local/system/remote package priority
- Extra build arguments
Package Instance APIs
Available in custom rules, after_install, etc.:
package:name()
get package namepackage:version_str()
get versionpackage:installdir()
get install dirpackage:get("links")
get link librariespackage:get("includedirs")
get include dirs
Typical Examples
1. Optional Dependency
add_requires("foo", {optional = true})
target("bar")
add_packages("foo")
2. Depend on Branch/Commit
add_requires("tbox master")
add_requires("zlib 1.2.11")
3. Pass Configs to Package
add_requires("spdlog", {configs = {header_only = true}})
4. Depend on Local Package
- Create a local package repository directory in your project (e.g.
local-repo/packages/foo/xmake.lua
). - Add the local repository in
xmake.lua
:
add_repositories("myrepo local-repo")
add_requires("foo")
- Local package structure example:
local-repo/
packages/
foo/
xmake.lua
- Now you can use the local package just like an official one via
add_requires("foo")
.
Best Practices
- Use
add_requires
+add_packages
for declaration and binding - Use
{optional = true}
for optional packages - Use
{plat=..., arch=...}
for precise control on multi-platform - Use
add_requireconfs
for recursive dependency config - Use
xmake require --info pkg
to query package parameters
More Information
- Official package usage: Using Official Packages
- Package dependency API: Package Dependency API
- Package instance APIs: package instance API
- Package management and search: You can also use the xrepo CLI tool to search, install, and uninstall packages.