xmake-docs/docs/api/scripts/extension-modules/package/tools.md

package.tools

This module provides helpers for integrating common build tools in xmake-repo and custom package scripts. Each tool module (cmake, autoconf, meson, make, ninja, msbuild, xmake) provides a set of APIs for building and installing packages. Below are detailed API references and usage examples for each tool.

cmake

Import: import("package.tools.cmake")

cmake.install

Install a package using CMake. Most commonly used for CMake-based packages in xmake-repo.

Function Prototype

::: tip API

cmake.install(package: <package>, configs: <table>, opt: <table>)

:::

Parameter Description

Parameter	Description
package	Required. Package instance object
configs	Required. CMake configuration parameter list
opt	Optional. Option parameters, supports the following: - cxflags - C/C++ compile flags - cflags - C compile flags - packagedeps - Package dependencies list

Return Value

No return value

Usage

Basic usage

on_install(function (package)
    local configs = {}
    table.insert(configs, "-DBUILD_SHARED_LIBS=" .. (package:config("shared") and "ON" or "OFF"))
    table.insert(configs, "-DCMAKE_BUILD_TYPE=" .. (package:is_debug() and "Debug" or "Release"))
    import("package.tools.cmake").install(package, configs)
end)

• Use package:config("shared") to control shared/static build.
• Use package:is_debug() to control Debug/Release build.

Passing custom compile flags (cxflags/cflags)

on_install(function (package)
    local configs = {}
    table.insert(configs, "-DBUILD_SHARED_LIBS=" .. (package:config("shared") and "ON" or "OFF"))
    table.insert(configs, "-DCMAKE_BUILD_TYPE=" .. (package:is_debug() and "Debug" or "Release"))
    local cxflags = "-Wa,-mbig-obj"
    import("package.tools.cmake").install(package, configs, {cxflags = cxflags})
end)

• To pass custom C/C++ compile flags, set cflags or cxflags as a variable and pass it via the opt table to cmake.install.
• This is useful for special compiler options or platform-specific flags.

cmake.build

Build a package using CMake (without install step).

Function Prototype

::: tip API

cmake.build(package: <package>, configs: <table>, opt: <table>)

:::

Parameter Description

Parameter	Description
package	Required. Package instance object
configs	Required. CMake configuration parameter list
opt	Optional. Option parameters

Return Value

No return value

Usage

Example:

on_install(function (package)
    import("package.tools.cmake").build(package, {"-DCMAKE_BUILD_TYPE=Release"})
end)

cmake.configure

Configure a CMake project (run cmake only, no build/install).

Function Prototype

::: tip API

cmake.configure(package: <package>, configs: <table>, opt: <table>)

:::

Parameter Description

Parameter	Description
package	Required. Package instance object
configs	Required. CMake configuration parameter list
opt	Optional. Option parameters

Return Value

No return value

Usage

Basic usage

on_install(function (package)
    local configs = {}
    table.insert(configs, "-DBUILD_SHARED_LIBS=" .. (package:config("shared") and "ON" or "OFF"))
    table.insert(configs, "-DCMAKE_BUILD_TYPE=" .. (package:is_debug() and "Debug" or "Release"))
    import("package.tools.cmake").configure(package, configs)
end)

autoconf

Import: import("package.tools.autoconf")

autoconf.install

Install a package using GNU Autotools (configure/make/make install).

Function Prototype

::: tip API

autoconf.install(package: <package>, configs: <table>, opt: <table>)

:::

Parameter Description

Parameter	Description
package	Required. Package instance object
configs	Required. Configuration parameter list
opt	Optional. Option parameters, supports the following: - packagedeps - Package dependencies list

Return Value

No return value

Usage

Basic usage

on_install(function (package)
    local configs = {}
    table.insert(configs, "--enable-static=" .. (package:config("shared") and "no" or "yes"))
    table.insert(configs, "--enable-shared=" .. (package:config("shared") and "yes" or "no"))
    import("package.tools.autoconf").install(package, configs)
end)

• Use --enable-static and --enable-shared to control static/shared build. See libx11 example.

Advanced usage

on_install(function (package)
    local configs = {}
    table.insert(configs, "--enable-static=" .. (package:config("shared") and "no" or "yes"))
    table.insert(configs, "--enable-shared=" .. (package:config("shared") and "yes" or "no"))
    if package:is_debug() then
        table.insert(configs, "--enable-debug")
    end
    local packagedeps = {"zlib"}
    import("package.tools.autoconf").install(package, configs, {packagedeps = packagedeps})
end)

autoconf.build

Build a package using Autotools (configure/make).

Function Prototype

::: tip API

autoconf.build(package: <package>, configs: <table>, opt: <table>)

:::

Parameter Description

Parameter	Description
package	Required. Package instance object
configs	Required. Configuration parameter list
opt	Optional. Option parameters

Return Value

No return value

Usage

Example:

on_install(function (package)
    import("package.tools.autoconf").build(package, {"--enable-static=yes"})
end)

autoconf.configure

Run the configure script for an Autotools project.

Function Prototype

::: tip API

autoconf.configure(package: <package>, configs: <table>, opt: <table>)

:::

Parameter Description

Parameter	Description
package	Required. Package instance object
configs	Required. Configuration parameter list
opt	Optional. Option parameters

Return Value

No return value

Usage

Example:

on_install(function (package)
    import("package.tools.autoconf").configure(package, {"--prefix=/usr/local"})
end)

autoconf.make

Run make with custom arguments.

Function Prototype

::: tip API

autoconf.make(package: <package>, argv: <table>, opt: <table>)

:::

Parameter Description

Parameter	Description
package	Required. Package instance object
argv	Required. make argument list
opt	Optional. Option parameters

Return Value

No return value

Usage

Example:

on_install(function (package)
    import("package.tools.autoconf").make(package, {"install"})
end)

meson

Import: import("package.tools.meson")

meson.install

Install a package using Meson (setup/compile/install).

Function Prototype

::: tip API

meson.install(package: <package>, configs: <table>, opt: <table>)

:::

Parameter Description

Parameter	Description
package	Required. Package instance object
configs	Required. Meson configuration parameter list
opt	Optional. Option parameters, supports the following: - packagedeps - Package dependencies list

Return Value

No return value

Usage

Typical usage:

add_deps("meson", "ninja")
on_install(function (package)
    local configs = {}
    table.insert(configs, "-Ddefault_library=" .. (package:config("shared") and "shared" or "static"))
    if package:is_debug() then
        table.insert(configs, "-Dbuildtype=debug")
    else
        table.insert(configs, "-Dbuildtype=release")
    end
    local packagedeps = {"zlib"}
    if package:config("openssl") then
        table.insert(packagedeps, "openssl")
    end
    import("package.tools.meson").install(package, configs, {packagedeps = packagedeps})
end)

meson.build

Build a package using Meson (setup/compile).

Function Prototype

::: tip API

meson.build(package: <package>, configs: <table>, opt: <table>)

:::

Parameter Description

Parameter	Description
package	Required. Package instance object
configs	Required. Meson configuration parameter list
opt	Optional. Option parameters

Return Value

No return value

Usage

Example:

on_install(function (package)
    import("package.tools.meson").build(package, {"-Ddefault_library=static"})
end)

meson.generate

Generate Meson build files only (setup).

Function Prototype

::: tip API

meson.generate(package: <package>, configs: <table>, opt: <table>)

:::

Parameter Description

Parameter	Description
package	Required. Package instance object
configs	Required. Meson configuration parameter list
opt	Optional. Option parameters

Return Value

No return value

Usage

Example:

on_install(function (package)
    import("package.tools.meson").generate(package, {"-Dbuildtype=release"})
end)

make

Import: import("package.tools.make")

make.install

Build and install a package using Make (build + install).

Function Prototype

::: tip API

make.install(package: <package>, configs: <table>, opt: <table>)

:::

Parameter Description

Parameter	Description
package	Required. Package instance object
configs	Required. Configuration parameter list
opt	Optional. Option parameters, supports the following: - packagedeps - Package dependencies list

Return Value

No return value

Usage

Typical usage:

add_deps("make")
on_install(function (package)
    local configs = {}
    local packagedeps = {"zlib"}
    if package:config("openssl") then
        table.insert(packagedeps, "openssl")
    end
    import("package.tools.make").install(package, configs, {packagedeps = packagedeps})
end)

make.build

Build a package using Make.

Function Prototype

::: tip API

make.build(package: <package>, configs: <table>, opt: <table>)

:::

Parameter Description

Parameter	Description
package	Required. Package instance object
configs	Required. Configuration parameter list
opt	Optional. Option parameters

Return Value

No return value

Usage

Example:

on_install(function (package)
    import("package.tools.make").build(package, {"CC=gcc"})
end)

make.make

Run make with custom arguments.

Function Prototype

::: tip API

make.make(package: <package>, argv: <table>, opt: <table>)

:::

Parameter Description

Parameter	Description
package	Required. Package instance object
argv	Required. make argument list
opt	Optional. Option parameters

Return Value

No return value

Usage

Example:

on_install(function (package)
    import("package.tools.make").make(package, {"install"})
end)

ninja

Import: import("package.tools.ninja")

ninja.install

Build and install a package using Ninja (build + install).

Function Prototype

::: tip API

ninja.install(package: <package>, configs: <table>, opt: <table>)

:::

Parameter Description

Parameter	Description
package	Required. Package instance object
configs	Required. Configuration parameter list
opt	Optional. Option parameters, supports the following: - packagedeps - Package dependencies list

Return Value

No return value

Usage

Typical usage:

add_deps("ninja")
on_install(function (package)
    local configs = {}
    local packagedeps = {"zlib"}
    if package:config("openssl") then
        table.insert(packagedeps, "openssl")
    end
    import("package.tools.ninja").install(package, configs, {packagedeps = packagedeps})
end)

ninja.build

Build a package using Ninja.

Function Prototype

::: tip API

ninja.build(package: <package>, configs: <table>, opt: <table>)

:::

Parameter Description

Parameter	Description
package	Required. Package instance object
configs	Required. Configuration parameter list
opt	Optional. Option parameters

Return Value

No return value

Usage

Example:

on_install(function (package)
    import("package.tools.ninja").build(package)
end)

msbuild

Import: import("package.tools.msbuild")

msbuild.build

Build a package using MSBuild (Visual Studio projects).

Function Prototype

::: tip API

msbuild.build(package: <package>, configs: <table>, opt: <table>)

:::

Parameter Description

Parameter	Description
package	Required. Package instance object
configs	Required. MSBuild configuration parameter list
opt	Optional. Option parameters, supports the following: - packagedeps - Package dependencies list

Return Value

No return value

Usage

Typical usage:

on_install(function (package)
    local configs = {}
    if package:config("configuration") then
        table.insert(configs, "/p:Configuration=" .. package:config("configuration"))
    end
    local packagedeps = {"zlib"}
    if package:config("openssl") then
        table.insert(packagedeps, "openssl")
    end
    import("package.tools.msbuild").build(package, configs, {packagedeps = packagedeps})
    -- You may need to manually copy built binaries
end)

xmake

Import: import("package.tools.xmake")

xmake.install

Install a package using xmake itself. This is suitable for:

• Porting third-party libraries that cannot be built directly, by writing a xmake.lua to adapt the build.
• Building and installing projects that already maintain their own xmake.lua build script.

Function Prototype

::: tip API

xmake.install(package: <package>, opt: <table>)

:::

Parameter Description

Parameter	Description
package	Required. Package instance object
opt	Optional. Option parameters

Return Value

No return value

Usage

Usage for projects with their own xmake.lua

If the source already contains a proper xmake.lua, you can simply:

on_install(function (package)
    import("package.tools.xmake").install(package)
end)

No extra configuration is needed; xmake will handle shared/static/debug/release modes automatically.

Usage for porting a third-party library

If the source does not provide a build system, you can generate a custom xmake.lua as shown below:

on_install(function (package)
    io.writefile("xmake.lua", [[
        add_rules("mode.debug", "mode.release")
        add_requires("libpng")
        target("bpg")
            set_kind("static")
            add_files("libbpg.c")
            add_files("libavcodec/hevc_cabac.c", "libavcodec/hevc_filter.c", "libavcodec/hevc.c", "libavcodec/hevcpred.c", "libavcodec/hevc_refs.c")
            add_files("libavcodec/hevcdsp.c", "libavcodec/hevc_mvs.c", "libavcodec/hevc_ps.c", "libavcodec/hevc_sei.c")
            add_files("libavcodec/utils.c", "libavcodec/cabac.c", "libavcodec/golomb.c", "libavcodec/videodsp.c")
            add_files("libavutil/mem.c", "libavutil/buffer.c", "libavutil/log2_tab.c", "libavutil/frame.c", "libavutil/pixdesc.c", "libavutil/md5.c")
            add_includedirs(".")
            add_headerfiles("libbpg.h")
            add_defines("HAVE_AV_CONFIG_H", "USE_PRED", "USE_VAR_BIT_DEPTH")
            on_load(function (target)
                local version = io.readfile("VERSION")
                target:add("defines", "CONFIG_BPG_VERSION=" .. version)
            end)
    ]])
    import("package.tools.xmake").install(package)
end)

• This approach is useful for adapting third-party sources that lack a proper build system. See the real-world libbpg package example.

References

• xmake-repo package scripts
• Official guide: Package Distribution