This is a mirror page, please see the original page:
https://xmake.io/#/manual/package_dependenciespackage
Define package configuration
The repository depends on the package definition description, the package() related interface definition, etc. There will be time to elaborate, so stay tuned. .
Please refer to the existing package description in the official repository: xmake-repo
Here is a more representative example for reference:
package("libxml2")
set_homepage("http://xmlsoft.org/")
set_description("The XML C parser and toolkit of Gnome.")
set_urls("https://github.com/GNOME/libxml2/archive/$(version).zip", {excludes = {"*/result/*", "*/test/*"}})
add_versions("v2.9.8", "c87793e45e66a7aa19200f861873f75195065de786a21c1b469bdb7bfc1230fb")
add_versions("v2.9.7", "31dd4c0e10fa625b47e27fd6a5295d246c883f214da947b9a4a9e13733905ed9")
if is_plat("macosx", "linux") then
add_deps("autoconf", "automake", "libtool", "pkg-config")
end
on_load(function (package)
package:add("includedirs", "include/libxml2")
package:add("links", "xml2")
end)
if is_plat("windows") and winos.version():gt("winxp") then
on_install("windows", function (package)
os.cd("win32")
os.vrun("cscript configure.js iso8859x=yes iconv=no compiler=msvc cruntime=/MT debug=%s prefix=\"%s\"", package:debug() and "yes" or "no", Package:installdir())
os.vrun("nmake /f Makefile.msvc")
os.vrun("nmake /f Makefile.msvc install")
end)
end
on_install("macosx", "linux", function (package)
import("package.tools.autoconf").install(package, {"--disable-dependency-tracking", "--without-python", "--without-lzma"})
end)
package:set_homepage
Set package homepage
Set the official page address of the project where the package is located.
package:set_description
Set package description
Set the package description information, generally see the relevant package information through xmake require --info zlib.
package:set_kind
Set package kind
Set the package type. For the dependent library, you don't need to set it. If it is an executable package, you need to set it to binary.
package("cmake")
set_kind("binary")
set_homepage("https://cmake.org")
set_description("A cross-platform family of tool designed to build, test and package software")
package:set_urls
Set package urls
Set the source package or git repository address of the package. Unlike add_urls, this interface is the override setting, and add_urls is the additional setting. Other usage methods are similar. This is chosen according to different needs.
package:add_urls
Add package urls
Add the source package of the package or the git repository address. This interface is generally paired with add_version to set the version of each source package and the corresponding sha256 value.
!> You can add multiple urls as the mirror source, xmake will automatically detect the fastest url for download, and if the download fails, try other urls.
add_urls("https://github.com/protobuf-c/protobuf-c/releases/download/v$(version)/protobuf-c-$(version).tar.gz")
add_versions("1.3.1", "51472d3a191d6d7b425e32b612e477c06f73fe23e07f6a6a839b11808e9d2267")
The $(version) built-in variable in urls will be adapted according to the version selected during the actual installation, and the version number is selected from the list of versions specified in add_versions.
If there is a more complicated version string for urls and there is no direct correspondence with add_versions, you need to customize the conversion in the following way:
add_urls("https://sqlite.org/2018/sqlite-autoconf-$(version)000.tar.gz",
{version = function (version) return version:gsub("%.", "") end})
add_versions("3.24.0", "d9d14e88c6fb6d68de9ca0d1f9797477d82fc3aed613558f87ffbdbbc5ceb74a")
add_versions("3.23.0", "b7711a1800a071674c2bf76898ae8584fc6c9643cfe933cfc1bc54361e3a6e49")
Of course, we can only add the git source address:
add_urls("https://gitlab.gnome.org/GNOME/libxml2.git")
If the source code package sha256 corresponding to multiple mirror addresses is different, we can set them separately by means of alias:
add_urls("https://ffmpeg.org/releases/ffmpeg-$(version).tar.bz2", {alias = "home"})
add_urls("https://github.com/FFmpeg/FFmpeg/archive/n$(version).zip", {alias = "github"})
add_versions("home:4.0.2", "346c51735f42c37e0712e0b3d2f6476c86ac15863e4445d9e823fe396420d056")
add_versions("github:4.0.2", "4df1ef0bf73b7148caea1270539ef7bd06607e0ea8aa2fbf1bb34062a097f026")
We can also set the http headers for the specified urls:
add_urls("https://github.com/madler/zlib/archive/$(version).tar.gz", {
http_headers = {"TEST1: foo", "TEST2: bar"}
})
package:add_versions
Add package versions
Used to set the version of each source package and the corresponding sha256 value, as described in add_urls
package:add_versionfiles
Adding a list of package versions
Normally we can add package versions through the add_versions interface, but if there are more and more versions, the package configuration will be too bloated, at this time, we can use the add_versionfiles interface to store a list of all the versions in a separate file to maintain.
For example:
package("libcurl")
add_versionfiles("versions.txt")
8.5.0 ce4b6a6655431147624aaf582632a36fe1ade262d5fab385c60f78942dd8d87b
8.4.0 e5250581a9c032b1b6ed3cf2f9c114c811fc41881069e9892d115cc73f9e88c6
8.0.1 9b6b1e96b748d04b968786b6bdf407aa5c75ab53a3d37c1c8c81cdb736555ccf
7.87.0 5d6e128761b7110946d1276aff6f0f266f2b726f5e619f7e0a057a474155f307
7.31.0 a73b118eececff5de25111f35d1d0aafe1e71afdbb83082a8e44d847267e3e08
...
package:add_patches
Add package patches
This interface is used for the source code package. Before compiling and installing, firstly set the corresponding patch package, compile it, and support multiple patches at the same time.
if is_plat("macosx") then
add_patches("1.15", "https://raw.githubusercontent.com/Homebrew/patches/9be2793af/libiconv/patch-utf8mac.diff",
"e8128732f22f63b5c656659786d2cf76f1450008f36bcf541285268c66cabeab")
end
For example, the above code, when compiled for macosx, is marked with the corresponding patch-utf8mac.diff patch, and each patch is also set to the value of sha256 to ensure integrity.
package:add_links
Add package links
By default, xmake will automatically detect the installed libraries and set the link relationship, but sometimes it is not very accurate. If you want to manually adjust the link order and the link name, you can set it through this interface.
add_links("mbedtls", "mbedx509", "mbedcrypto")
package:add_syslinks
Add system library links
Add some system library links. When some packages integrate links, you also need to rely on some system libraries to link them. This time you can attach them to the package description.
if is_plat("macosx") then
add_frameworks("CoreGraphics", "CoreFoundation", "Foundation")
elseif is_plat("windows") then
add_defines("CAIRO_WIN32_STATIC_BUILD=1")
add_syslinks("gdi32", "msimg32", "user32")
else
add_syslinks("pthread")
end
package:add_linkorders
Adjust the link order within the package
For specific details, please see the target's internal documentation for add_linkorders, target/add_linkorders.
package("libpng")
add_linkorders("png16", "png", "linkgroup::foo")
add_linkgroups("dl", {name = "foo", group = true})
package:add_linkgroups
Configure the link group of the package
For specific details, please see the target's internal documentation for add_linkgroups, target/add_linkgroups.
package("libpng")
add_linkorders("png16", "png", "linkgroup::foo")
add_linkgroups("dl", {name = "foo", group = true})
package:add_frameworks
Add frameworks
Add a dependent system frameworks link.
See for example: add_syslinks
package:add_linkdirs
Add link directories
The package's link library search directory can also be adjusted, but it is usually not needed, unless some libraries are not installed under prefix/lib, but in the lib subdirectory, the default search is not available.
package:add_includedirs
Add include directories
Add another header file search directory.
package:add_bindirs
Add executable file directory
By default, if set_kind("binary") or set_kind("toolchain") is configured as an executable package.
Then, it will use the bin directory as an executable directory by default and automatically add it to the PATH environment variable.
If you want to open some of the compiled executable tools in the library package to users, you need to configure package:addenv("PATH", "bin") in the package.
If you use this interface to configure add_bindirs("bin"), bin will be automatically added to PATH, and you no longer need to configure PATH separately. In addition, this also provides a way to modify the executable directory.
package:add_defines
Add definition
Some specific definition options can be exported to the integrated package.
package:add_configs
Add package configs
We can add the external output configuration parameters of each package through this interface:
package("pcre2")
set_homepage("https://www.pcre.org/")
set_description("A Perl Compatible Regular Expressions Library")
add_configs("bitwidth", {description = "Set the code unit width.", default = "8", values = {"8", "16", "32"}})
on_load(function (package)
local bitwidth = package:config("bitwidth") or "8"
package:add("links", "pcre2-" .. bitwidth)
package:add("defines", "PCRE2_CODE_UNIT_WIDTH=" .. bitwidth)
end)
In the engineering project, we can also view a list of configurable parameters and values for a particular package:
$ xmake require --info pcre2
The package info of project:
require(pcre2):
-> description: A Perl Compatible Regular Expressions Library
-> version: 10.31
...
-> configs:
-> bitwidth:
-> description: Set the code unit width.
-> values: {"8","16","32"}
-> default: 8
Then in the project, enable these configurations and compile the package with the specific configuration:
add_requires("pcre2", {configs = {bitwidth = 16}})
package:add_extsources
Add external package sources
Starting from version 2.5.2, we have also added two configuration interfaces add_extsources and on_fetch, which can better configure xmake to search for system libraries during the process of installing C/C++ packages.
As for the specific background, we can give an example. For example, we added a package of package("libusb") to the xmake-repo repository .
Then users can directly integrate and use it in the following ways:
add_requires("libusb")
target("test")
set_kind("binary")
add_files("src/*.c")
add_packages("libusb")
If libusb is not installed on the user's system, xmake will automatically download the libusb library source code, automatically compile, install and integrate, and there is no problem.
But if the user installs the libusb library to the system through apt install libusb-1.0, then xmake should automatically search for the libusb package installed by the user in the system environment first, and use it directly, avoiding additional download, compilation and installation.
But here comes the problem, xmake internally passes find_package("libusb") and fails to find it. Why is that? Because the package name of libusb installed via apt is libusb-1.0, not libusb.
We can only find it through pkg-config --cflags libusb-1.0, but the default find_package logic inside xmake doesn't know the existence of libusb-1.0, so it can't be found.
Therefore, in order to better adapt to the search of system libraries in different system environments, we can use add_extsources("pkgconfig::libusb-1.0") to let xmake improve the search logic, for example:
package("libusb")
add_extsources("pkgconfig::libusb-1.0")
on_install(function (package)
- ...
end)
In addition, we can also use this method to improve the search for packages installed by other package managers such as homebrew/pacman, for example: add_extsources("pacman::libusb-1.0").
package:add_deps
Add package dependencies
This interface allows us to automatically install all dependencies of a package when we install it by configuring the dependencies between packages.
Also, by default, cmake/autoconf will automatically find the libraries and headers of all dependent packages as soon as we have configured the dependencies.
Of course, if for some special reason the cmake script for the current package does not find the dependencies properly, then we can also force the dependencies to be typed in with {packagedeps = "xxx"}.
Example.
package("foo")
add_deps("cmake", "bar")
on_install(function (package)
local configs = {}
import("package.tools.cmake").install(package, configs)
end)
The foo package is maintained using CMakeLists.txt and it relies on the bar package during installation, so xmake will install bar first and have cmake.install automatically find the bar installed library when it calls cmake.
However, if foo's CMakeLists.txt still does not automatically find bar, then we can change it to the following configuration to force bar's includedirs/links etc. to be passed into foo by way of flags.
package("foo")
add_deps("cmake", "bar")
on_install(function (package)
local configs = {}
import("package.tools.cmake").install(package, configs, {packages = "bar"})
end)
packages:add_components
Add package components
This is a new interface added in 2.7.3 to support componentized configuration of packages, see: #2636 for details.
With this interface we can configure the list of components that are actually available for the current package.
package("sfml")
add_components("graphics")
add_components("audio", "network", "window")
add_components("system")
On the user side, we can use package specific components in the following way.
add_requires("sfml")
target("test")
add_packages("sfml", {components = "graphics")
!> Note: In addition to configuring the list of available components, we also need to configure each component in detail for it to work properly, so it is usually used in conjunction with the on_component interface.
A full example of the configuration and use of package components can be found at: components example
package:set_base
Inherit package configuration
This is a newly added interface in 2.6.4, through which we can inherit all the configuration of an existing package, and then rewrite some of the configuration on this basis.
This is usually in the user's own project, it is more useful to modify the built-in package of the xmake-repo official repository, such as: repairing and changing urls, modifying the version list, installation logic, etc.
For example, modify the url of the built-in zlib package to switch to your own zlib source address.
package("myzlib")
set_base("zlib")
set_urls("https://github.com/madler/zlib.git")
package_end()
add_requires("myzlib", {system = false, alias = "zlib"})
target("test")
set_kind("binary")
add_files("src/*.c")
add_packages("zlib")
We can also use it to simply add an alias package.
package("onetbb")
set_base("tbb")
We can install the tbb package through add_requires("onetbb") integration, but the package name is different.
package:on_load
Load package configuration
This is an optional interface. If you want to be more flexible and dynamically judge various platform architectures, you can do it in this way, for example:
on_load(function (package)
Local bitwidth = package:config("bitwidth") or "8"
package:add("links", "pcre" .. (bitwidth ~= "8" and bitwidth or ""))
If not package:config("shared") then
package:add("defines", "PCRE_STATIC")
end
end)
The pcre package needs to do some judgment on the bitwidth to determine the name of the link library for external output. It also needs to add some defines to the dynamic library. This time, it is more flexible when set in on_load. To find out what methods are available to package look here.
package:on_fetch
Fetch package libraries
This is an optional configuration. After 2.5.2, if the system libraries installed under different systems only have different package names, then using add_extsources to improve the system library search is sufficient, simple and convenient.
However, if some packages are installed in the system, the location is more complicated. To find them, some additional scripts may be needed. For example: access to the registry under windows to find packages, etc. At this time, we can use on_fetchFully customized search system library logic.
Let's take libusb as an example. Instead of add_extsources, we can use the following method to achieve the same effect. Of course, we can do more things in it.
package("libusb")
on_fetch("linux", function(package, opt)
if opt.system then
return find_package("pkgconfig::libusb-1.0")
end
end)
To find out what methods are available to package look here.
package:on_check
Check whether the package supports the current platform
Sometimes, simply using on_install("windows", "android", function () end) cannot properly limit the package's support for the current platform.
For example, it is also compiled using msvc on windows, but it only supports using the vs2022 tool chain. Then we cannot simply restrict the installation of packages by disabling the windows platform.
Because each user's compilation tool chain environment may be different. At this time, we can configure on_check to do more detailed detection to determine whether the package supports the current tool chain environment.
If the package is not supported, it will prompt the user earlier before the package is downloaded and installed. It can also avoid some unsupported ci job tests on the ci of xmake-repo.
For example, the following configuration can determine whether the current msvc provides the corresponding vs sdk version. If the version is not satisfied, the package cannot be compiled and installed, and the user will see a more readable unsupported error message.
package("test")
on_check("windows", function (package)
import("core.tool.toolchain")
import("core.base.semver")
local msvc = toolchain.load("msvc", {plat = package:plat(), arch = package:arch()})
if msvc then
local vs_sdkver = msvc:config("vs_sdkver")
assert(vs_sdkver and semver.match(vs_sdkver):gt("10.0.19041"), "package(cglm): need vs_sdkver > 10.0.19041.0")
end
end)
For example, we can also use it to determine the current compiler's support for c++20, if it does not support std::input_iterator, which is only available in c++20. Then there is no need to continue downloading, compiling and installing this package.
Users will see a Require at least C++20. error to prompt them to upgrade their compiler.
package("test")
on_check(function (package)
assert(package:check_cxxsnippets({test = [[
#include
#include
struct SimpleInputIterator {
using difference_type = std::ptrdiff_t;
using value_type = int;
int operator*() const;
SimpleInputIterator& operator++();
void operator++(int) { ++*this; }
};
static_assert(std::input_iterator);
]]}, {configs = {languages = "c++20"}}), "Require at least C++20.")
end)
package:on_install
Installation package
This interface is mainly used to add installation scripts. The previous string parameters are used to set supported platforms. Other script fields such as on_load, on_test are also supported.
Platform filtering
The complete filtering syntax is as follows: plat|arch1,arch2@host|arch1,arch2
It looks very complicated, but it is actually very simple. Each stage is optional and can be partially omitted, corresponding to: Compilation platform|Compilation architecture@Host platform|Host architecture
If you do not set any platform filter conditions, all platforms will be supported by default, and the scripts inside will take effect on all platforms, for example:
on_install(function (package)
-- TODO
end)
If the installation script is effective for a specific platform, then directly specify the corresponding compilation platform. You can specify multiple ones at the same time:
on_install("linux", "macosx", function (package)
-- TODO
end)
If you need to subdivide it into a specific architecture to take effect, you can write like this:
on_install("linux|x86_64", "iphoneos|arm64", function (package)
-- TODO
end)
If you also want to limit the execution host environment platform and architecture, you can append @host|arch behind, for example:
on_install("mingw@windows", function (package)
-- TODO
end)
This means that it only takes effect when compiling the mingw platform under windows.
We can also not specify which platform and architecture, but only set the host platform and architecture. This is usually used to describe some dependency packages related to compilation tools, which can only be run in the host environment.
For example, the package we compile depends on cmake and needs to add the cmake package description. Then the compilation and installation environment can only be the host platform:
on_install("@windows", "@linux", "@macosx", function (package)
-- TODO
end)
Some other examples:
-- `@linux`
-- `@linux|x86_64`
-- `@macosx,linux`
-- `android@macosx,linux`
-- `android|armeabi-v7a@macosx,linux`
-- `android|armeabi-v7a@macosx,linux|x86_64`
-- `android|armeabi-v7a@linux|x86_64`
In 2.8.7, we have improved pattern matching support and added the ability to exclude specific platforms and architectures, such as:
!plat|!arch@!subhost|!subarch
@!linux
@!linux|x86_64
@!macosx,!linux
!android@macosx,!linux
android|!armeabi-v7a@macosx,!linux
android|armeabi-v7a,!iphoneos@macosx,!linux|x86_64
!android|armeabi-v7a@!linux|!x86_64
!linux|*
At the same time, a built-in native architecture is also provided to match the local architecture of the current platform, mainly used to specify or exclude cross-compilation platforms.
on_install("macosx|native", ...)
The above configuration, if used on a macOS x86_64 device, will only match the local architecture compilation of xmake f -a x86_64.
If it is cross-compiled with xmake f -a arm64, it will not be matched.
In the same way, if you only want to match cross-compilation, you can use macosx|!native to negate and exclude.
In version 2.9.1, we have continued to improve it and added support for conditional logic judgments:
For example:
on_install("!wasm|!arm* and !cross|!arm*", function (package)
end)
To describe the arm architecture excluding the wasm and cross platforms.
Moreover, it also supports nested logic described by (), a and b or (a and (c or d)).
Compilation tools
We have built-in scripts for installing common compilation tools to provide convenient architecture support for build tool chains with different source code dependencies, such as: autoconf, cmake, meson, etc.
xmake
If it is a dependency package based on xmake, it is very simple to integrate it. xmake has very good built-in integration support for it, and can directly support cross-platform compilation. Generally, you only need:
on_install(function (package)
import("package.tools.xmake").install(package)
end)
If you want to pass some unique compilation configuration parameters:
on_install(function (package)
import("package.tools.xmake").install(package, {"--xxx=y"})
end)
cmake
If it is a package based on cmake, it is very simple to integrate. Usually you only need to set some configuration parameters, but you also need to add the cmake dependency first:
add_deps("cmake")
on_install(function (package)
import("package.tools.cmake").install(package, {"-Dxxx=ON"})
end)
autoconf
If it is an autoconf-based package, the integration method is similar to cmake, except that the configuration parameters passed are different. However, usually, Unix systems have built-in autoconf series tools, so it is fine without adding related dependencies.
on_install(function (package)
import("package.tools.autoconf").install(package, {"--enable-shared=no"})
end)
However, some source code packages may not be fully satisfied by the system's built-in autoconf, so you can add the autoconf series dependencies to build them:
add_deps("autoconf", "automake", "libtool", "pkg-config")
on_install(function (package)
import("package.tools.autoconf").install(package, {"--enable-shared=no"})
end)
meson
If it is meson, you also need to add ninja dependencies to execute the build.
add_deps("meson", "ninja")
on_install(function (package)
import("package.tools.meson").install(package, {"-Dxxx=ON"})
end)
package:on_download
Custom download package
The download logic of the custom package, which is a new interface added in 2.6.4, is usually not used, and it is enough to use the built-in download of Xmake.
If the user builds a private repository and has a more complex authentication mechanism and special processing logic for the download of the package, the internal download logic can be rewritten to achieve this.
on_download(function (package, opt)
local url = opt.url
local sourcedir = opt.sourcedir
-- download url to the current directory
-- and extract it's source code to sourcedir
-- ...
end)
In the opt parameter, you can get the destination source directory opt.sourcedir of the downloaded package. We only need to get the package address from opt.url and download it.
Then, add some custom processing logic as needed. In addition, you can add download cache processing and so on.
The following is an example of custom downloading a tar.gz file, and implementing caching and decompression of source file directories, you can refer to the following:
package("zlib")
add_urls("https://github.com/madler/zlib/archive/$(version).tar.gz")
add_versions("v1.2.10", "42cd7b2bdaf1c4570e0877e61f2fdc0bce8019492431d054d3d86925e5058dc5")
on_download(function (package, opt)
import("net.http")
import("utils.archive")
local url = opt.url
local sourcedir = opt.sourcedir
local packagefile = path.filename(url)
local sourcehash = package:sourcehash(opt.url_alias)
local cached = true
if not os.isfile(packagefile) or sourcehash ~= hash.sha256(packagefile) then
cached = false
-- attempt to remove package file first
os.tryrm(packagefile)
http.download(url, packagefile)
-- check hash
if sourcehash and sourcehash ~= hash.sha256(packagefile) then
raise("unmatched checksum, current hash(%s) != original hash(%s)", hash.sha256(packagefile):sub(1, 8), sourcehash:sub(1, 8))
end
end
-- extract package file
local sourcedir_tmp = sourcedir .. ".tmp"
os.rm(sourcedir_tmp)
if archive.extract(packagefile, sourcedir_tmp) then
os.rm(sourcedir)
os.mv(sourcedir_tmp, sourcedir)
else
-- if it is not archive file, we need only create empty source file and use package:originfile()
os.tryrm(sourcedir)
os.mkdir(sourcedir)
end
-- save original file path
package:originfile_set(path.absolute(packagefile))
end)
Custom download requires the user to fully control the download logic, which will be more complicated, and is not recommended unless necessary.
If you just want to add custom http headers to obtain download authorization, you can see Set http headers when downloading package
Platform Filtering
The complete filtering syntax is as follows: plat|arch1,arch2@host|arch1,arch2
It looks very complicated, but it is very simple. Each stage is optional and can be partially omitted. Corresponding: `Compile Platform|Compile Architecture@Host Platform|Host Architecture
If you do not set any platform filtering conditions, then the default full platform support, the script inside is effective for all platforms, for example:
on_install(function (package)
-- TODO
end)
If the installation script is valid for a specific platform, then directly specify the corresponding compilation platform, you can specify more than one at the same time:
on_install("linux", "macosx", function (package)
-- TODO
end)
If you want to break down to the specified architecture to take effect, you can write:
on_install("linux|x86_64", "iphoneos|arm64", function (package)
-- TODO
end)
If you want to limit the execution of the host environment platform and architecture, you can append @host|arch to the end, for example:
on_install("mingw@windows", function (package)
-- TODO
end)
This means that only the mingw platform is valid for Windows.
We can also specify the host platform and architecture without specifying a platform and architecture. This is usually used to describe some dependencies related to the build tool and can only be run in the host environment.
For example, the package we compiled depends on cmake, we need to add the package description of cmake, then the compiler installation environment can only be the host platform:
on_install("@windows", "@linux", "@macosx", function (package)
-- TODO
end)
Some other examples:
-- `@linux`
-- `@linux|x86_64`
-- `@macosx,linux`
-- `android@macosx, linux`
-- `android|armeabi-v7a@macosx,linux`
-- `android|armeabi-v7a@macosx,linux|x86_64`
-- `android|armeabi-v7a@linux|x86_64`
Compilation Tools
We have built-in scripts for installing common build tools for convenient build support for different source code-dependent build toolchains, such as autoconf, cmake, meson, etc.
xmake
If it is a xmake-based dependency package, then the integration is very simple, xmake has very good built-in integration support, you can directly support it for cross-platform compilation, generally only need to:
on_install(function (package)
import("package.tools.xmake").install(package)
end)
If you want to pass some unique build configuration parameters:
on_install(function (package)
import("package.tools.xmake").install(package, {"--xxx=y"})
end)
cmake
If it is a cmake-based package, the integration is also very short-answered. Usually you only need to set some configuration parameters, but you need to add the cmake dependency first:
add_deps("cmake")
on_install(function (package)
import("package.tools.cmake").install(package, {"-Dxxx=ON"})
end)
autoconf
If it is based on autoconf package, the integration method is similar to cmake, but the configuration parameters are different. However, under normal circumstances, the Unix system has built-in autoconf series tools, so it is fine without any dependencies.
on_install(function (package)
import("package.tools.autoconf").install(package, {"--enable-shared=no"})
end)
However, some source packages may not be fully satisfied with the system's built-in autoconf, so you can add autoconf family dependencies and build them:
add_deps("autoconf", "automake", "libtool", "pkg-config")
on_install(function (package)
import("package.tools.autoconf").install(package, {"--enable-shared=no"})
end)
meson
If it is meson, you need to add ninja's dependencies to perform the build.
add_deps("meson", "ninja")
on_install(function (package)
import("package.tools.meson").install(package, {"-Dxxx=ON"})
end)
gn
If it is a GN project, you can build and install it using the following methods. Make sure to also add ninja as a dependency.
add_deps("gn", "ninja")
on_install(function (package)
import("package.tools.gn").install(package)
end)
make
You can also build and install projects using makefiles.
add_deps("make")
on_install(function (package)
import("package.tools.make").install(package)
end)
msbuild
If the package uses Visual Studio projects you can build them using msbuild.
on_install(function (package)
import("package.tools.msbuild").build(package)
-- you then have to copy the built binaries manually
end)
ninja
You can also build and install packages with ninja.
add_deps("ninja")
on_install(function (package)
import("package.tools.ninja").install(package)
end)
nmake
You can build and install packages with nmake
on_install(function (package)
import("package.tools.nmake").install(package)
end)
scons
You can build packages using scons.
add_deps("scons")
on_install(function (package)
import("package.tools.scons").build(package)
-- you then need to manually copy the built binaries
end)
package:on_test
Test package
After installation, you need to set the corresponding test script, perform some tests to ensure the reliability of the installation package, if the test does not pass, the entire installation package will be revoked.
on_test(function (package)
assert(package:has_cfuncs("inflate", {includes = "zlib.h"}))
end)
The above script calls the built-in has_cfuncs interface to detect whether the zlib.h header file exists in the installed package, and whether the interface function inflate exists in the library and header files.
Xmake will try to compile the link for testing, has_cfuncs for detecting c functions, and has_cxxfuncs for detecting c++ library functions.
And include multiple header files in include, for example: includes = {"xxx.h", "yyy.h"}
We can also pass some of our own compilation parameters into the detection, for example:
on_test(function (package)
assert(package:has_cxxfuncs("func1", {includes = "xxx.h", configs = {defines = "c++14", cxflags = "-Dxxx"}}))
end)
We can also detect a code snippet with check_csnippets and check_cxxsnippets:
on_test(function (package)
assert(package:check_cxxsnippets({test = [[
#include
#include
#include
#include
using namespace boost::algorithm;
using namespace std;
static void test() {
string str("a,b");
vector strVec;
split(strVec, str, is_any_of(","));
assert(strVec.size()==2);
assert(strVec[0]=="a");
assert(strVec[1]=="b");
}
]]}, {configs = {languages = "c++14"}}))
end)
if it is an executable package, it can also be detected by trying to run:
on_test(function (package)
os.run("xxx --help")
end)
if the run fails, the test will not pass.
package:on_component
Define package component
This is a new interface added in 2.7.3 to support component-based configuration of packages, see: #2636 for details.
Through this interface we can configure the current package, specifying component details such as links to components, dependencies etc.
Configuring component link information
package("sfml")
add_components("graphics")
add_components("audio", "network", "window")
add_components("system")
on_component("graphics", function (package, component)
local e = package:config("shared") and "" or "-s"
component:add("links", "sfml-graphics" ... e)
if package:is_plat("windows", "mingw") and not package:config("shared") then
component:add("links", "freetype")
component:add("syslinks", "opengl32", "gdi32", "user32", "advapi32")
end
end)
on_component("window", function (package, component)
local e = package:config("shared") and "" or "-s"
component:add("links", "sfml-window" ... e)
if package:is_plat("windows", "mingw") and not package:config("shared") then
component:add("syslinks", "opengl32", "gdi32", "user32", "advapi32")
end
end)
...
On the user side, we can use package specific components in the following way.
add_requires("sfml")
target("test")
add_packages("sfml", {components = "graphics")
!> Note: In addition to configuring the component information, we also need to configure the list of available components in order to use it properly, so it is usually used in conjunction with the add_components interface.
A full example of the configuration and use of package components can be found at: components example
Configuring compilation information for components
We can configure not only the linking information for each component, but also the compilation information for includedirs, defines etc. We can also configure each component individually.
package("sfml")
on_component("graphics", function (package, component)
package:add("defines", "TEST")
end)
Configuring component dependencies
package("sfml")
add_components("graphics")
add_components("audio", "network", "window")
add_components("system")
on_component("graphics", function (package, component)
component:add("deps", "window", "system")
end)
The above configuration tells the package that our graphics component will have additional dependencies on the window and system components.
So, on the user side, our use of the graphics component can be done from the
add_packages("sfml", {components = {"graphics", "window", "system"})
Simplified to.
add_packages("sfml", {components = "graphics")
Because, as soon as we turn on the graphics component, it will also automatically enable the dependent window and system components.
Alternatively, we can configure component dependencies with add_components("graphics", {deps = {"window", "system"}}).
Finding components from the system library
We know that configuring add_extsources in the package configuration can improve package discovery on the system, for example by finding libraries from system package managers such as apt/pacman.
Of course, we can also make it possible for each component to prioritise finding them from the system repositories via the extsources configuration as well.
For example, the sfml package, which is actually also componentized in homebrew, can be made to find each component from the system repository without having to install them in source each time.
$ ls -l /usr/local/opt/sfml/lib/pkgconfig
-r--r--r-- 1 ruki admin 317 10 19 17:52 sfml-all.pc
-r--r--r-- 1 ruki admin 534 10 19 17:52 sfml-audio.pc
-r--r--r-- 1 ruki admin 609 10 19 17:52 sfml-graphics.pc
-r--r--r-- 1 ruki admin 327 10 19 17:52 sfml-network.pc
-r--r--r-- 1 ruki admin 302 10 19 17:52 sfml-system.pc
-r--r--r-- 1 ruki admin 562 10 19 17:52 sfml-window.pc
`
We just need, for each component, to configure its extsources: the
if is_plat("macosx") then
add_extsources("brew::sfml/sfml-all")
end
on_component("graphics", function (package, component)
-- ...
component:add("extsources", "brew::sfml/sfml-graphics")
end)
Default global component configuration
In addition to configuring specific components by specifying component names, if we don't specify a component name, the default is to globally configure all components.
package("sfml")
on_component(function (package, component)
-- configure all components
end)
Of course, we could also specify the configuration of the graphics component and the rest of the components would be configured via the default global configuration interface in the following way.
package("sfml")
add_components("graphics")
add_components("audio", "network", "window")
add_components("system")
on_component("graphics", function (package, component)
-- configure graphics
end)
on_component(function (package, component)
-- component audio, network, window, system
end)