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:

xmake.lua

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.

For more detailed package management usage, see the Package Management Guide. For the complete custom package description API, see Package Dependencies API.

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 name
• package:version_str() get version
• package:installdir() get install dir
• package:get("links") get link libraries
• package: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

1. Create a local package repository directory in your project (e.g. local-repo/packages/foo/xmake.lua).
2. Add the local repository in xmake.lua:

add_repositories("myrepo local-repo")
add_requires("foo")

3. Local package structure example:

local-repo/
  packages/
    foo/
      xmake.lua

4. Now you can use the local package just like an official one via add_requires("foo").

Best Practices

1. Use add_requires + add_packages for declaration and binding
2. Use {optional = true} for optional packages
3. Use {plat=..., arch=...} for precise control on multi-platform
4. Use add_requireconfs for recursive dependency config
5. 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.