Xmake

https://github.com/xmake-io/xmake-docs
Admin
Xmake is a lightweight, cross-platform build utility based on Lua scripting, featuring a built-in...
Tokens:1,107,673
Snippets:9,692
Trust Score:7.7
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install xmake-harness and run setup

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/extensions/addons/official/xmake-harness.md

Installs the xmake-harness addon and runs the interactive setup wizard, which prompts for a provider, API key, and model choices.

```sh
$ xmake addon --install xmake-harness
$ xmake ai --setup
```

--------------------------------

### application:run usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/ui/application.md

Example of starting an application. It initializes the UI, calls init(), and starts the event loop.

```lua
local demo = application()

function demo:init()
    application.init(self, "demo")
    self:background_set("blue")
    self:insert(self:main_dialog())
end

-- Start the application
demo:run()
```

--------------------------------

### package:sourcehash usage example - setup

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/package-instance.md

Example showing how to provide a checksum for a URL alias using add_urls and add_versions. This is the setup for the sourcehash retrieval example.

```lua
add_urls("https://example.com/library-$(version).zip", {alias = "example"})
add_versions("example:2.4.1", "29f9983cc7196e882c4bc3d23d7492f9c47574c7cf658afafe7d00c185429941")
```

--------------------------------

### on_install usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/custom-rule.md

Example usage of on_install to define a custom installation script for a rule. This overrides the default installation behavior of the applied target.

```lua
rule("markdown")
    on_install(function (target)
    end)
```

--------------------------------

### make.make usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/package/tools.md

Example usage of make.make. It runs make with the argument 'install'.

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

--------------------------------

### package:get usage examples

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/package-instance.md

Examples of using package:get to retrieve dependencies, links, and defined macros.

```lua
-- get the dependencies
package:get("deps")
-- get the links
package:get("links")
-- get the defined macros
package:get("defines")
```

--------------------------------

### after_install usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/project-target.md

Example usage of after_install to run a custom script after installing a target. It does not override the default installation operation, just adds custom actions.

```lua
target("test")
    after_install(function (target)
        print("")
    end)
```

--------------------------------

### on_installcmd usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/xpack-component-interfaces.md

Example usage of on_installcmd to rewrite the entire component's installation script, similar to xpack's on_installcmd. Use it to implement specific component installation logic.

```lua
xpack_component("test")
     on_installcmd(function (component, batchcmds)
         -- TODO
     end)
```

--------------------------------

### xrepo install auto-completion example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/posts/xmake-update-v2.7.6.md

Demonstrates the new xrepo install command auto-completion feature. Typing `xrepo install libp` triggers a search of the xmake-repo repository and displays matching package names.

```bash
$ xrepo install libp
libpaper libpfm libpng libpqxx libpthread-stubs
libpcap libplist libpq libpsl
```

--------------------------------

### Usage of autoconf.make

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/package/tools.md

Runs make with the given arguments. Example passes 'install' to run make install.

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

--------------------------------

### Example output of xmake addon --list

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/extensions/addons/installation.md

Example output of `xmake addon --list` showing installed and available addons.

```sh
$ xmake addon --list
the installed addons:
  -> esp32-devel v1.0.5: The ESP32 development addon ... (toolchains, rules, modules, includes, templates)
  -> serial-tools v1.0.3: The serial port toolkit ... (plugins, modules)
the available addons: (run `xmake addon --install <name>` to install)
  -> avr-devel v1.0.0: The AVR development addon ... (in xmake-repo)
```

--------------------------------

### Install header files by subdirectory with add_headerfiles

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/project-target.md

Example showing how to install header files by subdirectory using parentheses in the source path. The prefixdir option is set to "include".

```lua
target("test")
    add_headerfiles("src/(tbox/*.h)", {prefixdir = "include"})
```

--------------------------------

### Build and Run Basic Example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/examples/configuration/add_configfiles.md

Commands to build and run the project after configuring add_configfiles.

```bash
$ xmake
$ xmake run
```

--------------------------------

### scheduler.co_count() usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/base/scheduler.md

Example showing how to get the total number of active coroutines in the current scheduler, including counts before, during, and after starting tasks.

```lua
-- Coroutine counting example
print("Initial count:", scheduler.co_count())

for i = 1, 5 do
    scheduler.co_start(function()
        print("Task", i, "started, count:", scheduler.co_count())
        scheduler.co_sleep(1000)
        print("Task", i, "finished, count:", scheduler.co_count())
    end)
end

print("After starting tasks:", scheduler.co_count())
```

--------------------------------

### Get view bounds

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/ui/view.md

Usage example for view:bounds(). It retrieves the bounds and prints the start and end coordinates.

```lua
local bounds = v:bounds()
print(bounds:sx(), bounds:sy(), bounds:ex(), bounds:ey())
```

--------------------------------

### Custom run script for target

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/project-target.md

Overrides the running operation of the target's `xmake [r|run}` to implement a custom running process. This example runs an installed APK and gets device output.

```lua
target("test")

    -- Set custom run scripts, automatically run the installed app, and automatically get device output information
    on_run(function (target)

        os.run("adb shell am start -n com.demo/com.demo.DemoTest")
        os.run("adb logcat")
    end)
```

--------------------------------

### before_install usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/custom-rule.md

Example usage of before_install to implement a pre-installation script for a custom target.

```lua
rule("markdown")
    before_install(function (target)
    end)
```

--------------------------------

### add_frameworks and add_frameworkdirs usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/project-target.md

Example showing how to add a third-party framework and its search directory.

```lua
target("test")
    add_frameworks("MyFramework")
    add_frameworkdirs("/tmp/frameworkdir", "/tmp/frameworkdir2")
```

--------------------------------

### Install binary package with URLs and versions

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/package-management/package-distribution.md

Define a binary package by setting its download URL and version hash, then copy the necessary files into the package installation directory in on_install. This example shows how to handle a Windows binary package.

```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)
```

--------------------------------

### Set installation tips with set_installtips

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/best-practices/package-spec.md

Provides installation tips for toolchain or binary distribution packages, such as license confirmation or manual download steps.

```lua
set_installtips("This package requires manual EULA acceptance before first use.")
```

--------------------------------

### Example: starting named threads

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/base/thread.md

Example showing how to start named threads with a callback that prints progress and sleeps. The main function starts two threads and waits for them to complete.

```lua
import("core.base.thread")

function callback(id)
    import("core.base.thread")
    print("%s: %d starting ..", thread.running(), id)
    for i = 1, 10 do
        print("%s: %d", thread.running(), i)
        os.sleep(1000)
    end
    print("%s: %d end", thread.running(), id)
end

function main()
    local t0 = thread.start_named("thread_0", callback, 0)
    local t1 = thread.start_named("thread_1", callback, 1)
    t0:wait(-1)
    t1:wait(-1)
end
```

--------------------------------

### List Qt project templates with xmake create --help

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/posts/quickstart-6-build-qt-project.md

Shows the xmake create help menu, listing available Qt project templates: qt.console, qt.quickapp, qt.quickapp_static, qt.shared, qt.static, qt.widgetapp, and qt.widgetapp_static.

```bash
$ xmake create --help
Usage: $xmake create [options] [target]

Create a new project.

Options: 
    -t TEMPLATE, --template=TEMPLATE       Select the project template id or 
                                           name of the given language. 
                                           (default: console)
                                               - console: c++, go, dlang, cuda, 
                                           rust, swift, objc, c, objc++
                                               - qt.console: c++
                                               - qt.quickapp: c++
                                               - qt.quickapp_static: c++
                                               - qt.shared: c++
                                               - qt.static: c++
                                               - qt.widgetapp: c++
                                               - qt.widgetapp_static: c++
```

--------------------------------

### scheduler.co_start usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/base/scheduler.md

Usage example for scheduler.co_start. Starts a coroutine with arguments and demonstrates a coroutine group using co_group_begin and co_group_wait. The coroutine starts executing immediately unless the scheduler is not yet started.

```lua
-- Start coroutine with arguments
local co = scheduler.co_start(function(name, id)
    print("Task", name, "with id", id, "started")
end, "worker", 123)

-- Coroutine group example
local count = 0
scheduler.co_group_begin("test", function()
    for i = 1, 100 do
        scheduler.co_start(function()
            count = count + 1
        end)
    end
end)
scheduler.co_group_wait("test")
print("Completed", count, "tasks")
```

--------------------------------

### Toolchain configuration examples

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/posts/xmake-update-v3.0.5.md

Demonstrates various set_toolchains calls: simple, with package, with configs, and with additional options.

```lua
-- Simple toolchain
set_toolchains("clang")

-- Toolchain with package
set_toolchains("clang@llvm-10")
set_toolchains("@musclcc")
set_toolchains("zig")

-- Toolchain with configs and package
set_toolchains("mingw[clang]@llvm-mingw")
set_toolchains("msvc[vs=2025]")

-- Multiple configs
set_toolchains("mingw[clang]", {sdk = "/path/to/llvm-mingw"})
```

--------------------------------

### semver:get usage example with output

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/base/semver.md

Example of using semver:get to retrieve the major version and the internal information table. The output shows the full information table and the result of get("major").

```lua
local version = semver.new("v2.1.0+build")
print(version["_INFO"])
print(version:get("major"))
```

```text
{
  prerelease = { },
  build = {
    "build"
  },
  version = "v2.1.0+build",
  raw = "v2.1.0+build",
  patch = 0,
  minor = 1,
  major = 2
}

2
```

--------------------------------

### Web UI startup output

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/extensions/addons/official/xmake-harness.md

Example output from the web UI server, showing the URL with a token and the project path.

```text
  web ui  http://127.0.0.1:9736/?token=e07091070…
  project /path/to/your/project
```

--------------------------------

### after_installcmd usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/xpack-component-interfaces.md

Example of using after_installcmd to add a script after component installation. The script is executed after the component is installed, similar to xpack's after_installcmd.

```lua
xpack_component("test")
     after_installcmd(function (component, batchcmds)
         -- TODO
     end)
```

--------------------------------

### Complete xpack configuration example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/extensions/builtin-plugins.md

Complete xpack configuration example that includes the builtin xpack module, defines a binary target, and configures an xpack rule with multiple formats, metadata, install files, source files, and custom install/uninstall commands.

```lua
set_version("1.0.0")
add_rules("mode.debug", "mode.release")

includes("@builtin/xpack")

target("test")
     set_kind("binary")
     add_files("src/*.cpp")

xpack("test")
     set_formats("nsis", "zip", "targz", "runself")
     set_title("hello")
     set_author("ruki")
     set_description("A test installer.")
     set_homepage("https://xmake.io")
     set_licensefile("LICENSE.md")
     add_targets("test")
     add_installfiles("src/(assets/*.png)", {prefixdir = "images"})
     add_sourcefiles("(src/**)")
     set_iconfile("src/assets/xmake.ico")

     after_installcmd(function (package, batchcmds)
         batchcmds:mkdir(package:installdir("resources"))
         batchcmds:cp("src/assets/*.txt", package:installdir("resources"), {rootdir = "src"})
         batchcmds:mkdir(package:installdir("stub"))
     end)

     after_uninstallcmd(function (package, batchcmds)
         batchcmds:rmdir(package:installdir("resources"))
         batchcmds:rmdir(package:installdir("stub"))
     end)
```

--------------------------------

### package:installdir() - Get installation directory

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/package-instance.md

Returns the installation directory of the package. Can also be used to get a subdirectory; if the given directory tree does not exist it will be created.

```lua
package:installdir()
```

```lua
package:installdir("include")
```

```lua
package:installdir("include", "files")
```

--------------------------------

### Usage: dialog:show_help()

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/ui/mconfdialog.md

Usage example for showing help information for the currently selected configuration item, typically triggered by pressing the '?' key.

```lua
-- This is typically triggered by pressing '?' key
dialog:show_help()
```

--------------------------------

### winos.registry_query usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/builtin-modules/winos.md

Usage example for winos.registry_query. It gets the value under the specified registry path; if no value name is specified, it gets the default value of the key path.

```lua
local value, errors = winos.registry_query("HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug")
local value, errors = winos.registry_query("HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug;Debugger")
```

--------------------------------

### Configure set_prefixdir in xpack

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/xpack-interfaces.md

Example configuration that sets the installation prefix directory to 'prefix'. All installation files will be installed under 'installdir/prefix'.

```lua
xpack("xmake")
     set_prefixdir("prefix")
```

--------------------------------

### on_install with platform and architecture

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/package-dependencies.md

Installation script restricted to specific platform and architecture combinations.

```lua
on_install("linux|x86_64", "iphoneos|arm64", function (package)
    -- TODO
end)
```

--------------------------------

### tty.term_mode usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/base/tty.md

Usage example for tty.term_mode. It imports the tty module, gets the current mode for stdout, and then sets a new mode. The old mode is returned by the get call.

```lua
import("core.base.tty")

-- Get current mode
local oldmode = tty.term_mode("stdout")

-- Set new mode
tty.term_mode("stdout", newmode)
```

--------------------------------

### Install Qt SDK via apt and build

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/examples/cpp/graphics/qt.md

Install the Qt SDK using Ubuntu's apt package manager and then build the project. After installation, xmake automatically detects the Qt SDK.

```sh
$ sudo apt install -y qtcreator qtbase5-dev
$ xmake
```

--------------------------------

### cpu.march() usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/base/cpu.md

Example usage of cpu.march() to get and print the CPU micro-architecture.

```lua
import("core.base.cpu")

local march = cpu.march()
print("CPU Architecture:", march)  -- Output: "Skylake", "Zen 2", etc.
```

--------------------------------

### Complete status bar usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/ui/statusbar.md

A complete example showing how to create an application with a status bar and a main window, handle resizing, and run the application.

```lua
import("core.ui.statusbar")
import("core.ui.window")
import("core.ui.rect")
import("core.ui.application")

local demo = application()

function demo:init()
    application.init(self, "demo")
    self:background_set("blue")
    
    -- Create status bar
    local statusbar = statusbar:new("status", rect{1, self:height() - 1, self:width() - 1, 1})
    statusbar:info():text_set("Ready")
    statusbar:info():textattr_set("blue bold")
    
    -- Create main window
    local win = window:new("main", rect{1, 2, self:width() - 1, self:height() - 3}, "Main Window")
    
    -- Add to application
    self:insert(win)
    self:insert(statusbar)
    
    self._statusbar = statusbar
    self._win = win
end

function demo:on_resize()
    self._win:bounds_set(rect{1, 2, self:width() - 1, self:height() - 3})
    self._statusbar:bounds_set(rect{1, self:height() - 1, self:width() - 1, 1})
    application.on_resize(self)
end

function main(...)
    demo:run(...)
end
```

--------------------------------

### cpu.features() usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/base/cpu.md

Example usage of cpu.features() to get and print CPU features.

```lua
import("core.base.cpu")

local features = cpu.features()
print("CPU Features:", features)
```

--------------------------------

### string.startswith usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/builtin-modules/string.md

Example usage of string.startswith to check if a string starts with a prefix.

```lua
local s = "hello xmake"
if s:startswith("hello") then
    print("match")
end
```

--------------------------------

### Using a toolchain package example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/package-dependencies.md

Shows how to use a toolchain package with set_toolchains and add_requires to automatically download and bind the toolchain.

```lua
add_rules("mode.debug", "mode.release")
add_requires("llvm 14.0.0", {alias = "llvm-14"})

target("test")
    set_kind("binary")
    add_files("src/*.c")
    set_toolchains("llvm@llvm-14")
```

--------------------------------

### meson.install

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/package/tools.md

Installs a package using Meson by running setup, compile, and install steps.

```APIDOC
## meson.install

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

### Function Prototype
```lua
meson.install(package: <package>, configs: <table>, opt: <table>)
```

### Parameters
- **package** (package) - Required - Package instance object
- **configs** (table) - Required - Meson configuration parameter list
- **opt** (table) - Optional - Option parameters, supports the following:
  - `packagedeps` - Package dependencies list

### Return Value
No return value

### Usage
```lua
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)
```
```

--------------------------------

### git.init usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/devel/git.md

Usage example for git.init. Corresponds to the git init command. Initialize in the current directory or specify a repository directory with the repodir option.

```lua
import("devel.git")

-- Initialize in current directory
git.init()

-- Initialize in specified directory
git.init({repodir = "/tmp/new_project"})
```

--------------------------------

### compiler.features usage examples

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/tool/compiler.md

Usage examples for compiler.features. The first gets all features of the current C compiler. The second gets C++ features with C++11 standard enabled via configs. The third passes project target configuration to get features with defines and includedirs.

```lua
-- Get all the features of the current c compiler
local features = compiler.features("c")

-- Get all the features of the current C++ language compiler, enable the C++11 standard, otherwise you will not get the new standard features.
local features = compiler.features("cxx", {configs = {cxxflags = "-std=c++11"}})

-- Get all the features of the current C++ language compiler, pass all configuration information of the project target
local features = compiler.features("cxx", {target = target, configs = {defines = "..", includedirs = ".."}})
```

--------------------------------

### cpu.model_name() usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/base/cpu.md

Example usage of cpu.model_name() to get and print the CPU model name.

```lua
import("core.base.cpu")

local name = cpu.model_name()
print("CPU Name:", name)
```

--------------------------------

### Install with custom bindir and libdir

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/basic-commands/install-and-uninstall.md

Configures installation directories for different file types using --bindir and --libdir flags.

```sh
$ xmake install -o /tmp/usr --bindir=mybin --libdir=mylib
```

--------------------------------

### Mac Catalyst: build and run example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/posts/xmake-update-v2.7.1.md

Build and run the iosapp_with_framework test project. The output shows the build steps and program output.

```bash
$ xmake
[ 36%]: processing.xcode.release src/framework/Info.plist
[ 40%]: cache compiling.release src/framework/test.m
[ 44%]: linking.release test
[ 48%]: generating.xcode.release test.framework
[ 56%]: compiling.xcode.release src/app/Assets.xcassets
[ 56%]: processing.xcode.release src/app/Info.plist
[ 60%]: cache compiling.release src/app/ViewController.m
[ 60%]: cache compiling.release src/app/SceneDelegate.m
[ 60%]: cache compiling.release src/app/main.m
[ 60%]: cache compiling.release src/app/AppDelegate.m
[ 60%]: compiling.xcode.release src/app/Base.lproj/LaunchScreen.storyboard
[ 60%]: compiling.xcode.release src/app/Base.lproj/Main.storyboard
[ 88%]: linking.release demo
[ 92%]: generating.xcode.release demo.app
[100%]: build ok!
$ xmake run
2022-08-26 15:11:03.581 demo[86248:9087199] add(1, 2): 3
2022-08-26 15:11:03.581 demo[86248:9087199] hello xmake!
```

--------------------------------

### Example server.conf configuration

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/extras/distributed-compilation.md

This is the generated server.conf file. Edit it to change the listening port and other settings.

```lua
{
    distcc_build = {
        listen = "0.0.0.0:9693",
        workdir = "/Users/ruki/.xmake/service/server/distcc_build"
    },
    known_hosts = { },
    logfile = "/Users/ruki/.xmake/service/server/logs.txt",
    tokens = {
        "590234653af52e91b9e438ed860f1a2b"
    }
}
```

--------------------------------

### Use installed library with pkg-config

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/package-management/distribute-private-libraries.md

Pkg-config usage to get compiler flags and libraries for the installed package.

```bash
pkg-config --cflags --libs foo
```

--------------------------------

### dialog:button usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/ui/dialog.md

Example of getting a specific button from the dialog using dialog:button.

```lua
local quit_btn = dialog:button("quit")
```

--------------------------------

### Get command-line help for xmake commands

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/best-practices/faq.md

Use these commands to display help information for the main command, the configuration command, or a specific action or plugin. The last example shows how to get help for the 'run' action.

```sh
$ xmake [-h|--help]
```

```sh
$ xmake f [-h|--help]
```

```sh
$ xmake [action|plugin] [-h|--help]
```

```sh
$ xmake run --help
```

--------------------------------

### Disable header file installation with install = false

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/project-target.md

Example showing how to disable default header file installation for a specific header using the {install = false} parameter. Both files appear in the VS project, but only foo.h is installed.

```lua
add_headerfiles("src/foo.h")
add_headerfiles("src/test.h", {install = false})
```

--------------------------------

### xmake.install

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/package/tools.md

Documentation for the xmake.install function, including its prototype, parameters, return value, and usage examples.

```APIDOC
## xmake.install

### Description
Installs a package using xmake itself. Suitable for porting third-party libraries that cannot be built directly, or for building and installing projects that already maintain their own xmake.lua build script.

### Function Prototype
```lua
xmake.install(package: <package>, opt: <table>)
```

### Parameters
- **package** (package) - Required - Package instance object
- **opt** (table) - 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:
```lua
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:
```lua
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](https://github.com/xmake-io/xmake-repo/blob/23766d5855508e69f4cb1a4375ab3b865295fcb3/packages/l/libbpg/xmake.lua).
```

--------------------------------

### set_default Usage Example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/xpack-component-interfaces.md

Example of using set_default to disable the component by default, requiring user opt-in during installation.

```lua
xpack_component("LongPath")
     set_default(false)
     set_title("Enable Long Path")
```

--------------------------------

### on_install with host platform

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/package-dependencies.md

Installation script limited to the mingw platform on Windows host.

```lua
on_install("mingw@windows", function (package)
    -- TODO
end)
```

--------------------------------

### Default on_install for all platforms

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/package-dependencies.md

Default installation script that applies to all platforms when no platform filtering is specified.

```lua
on_install(function (package)
    -- TODO
end)
```

--------------------------------

### Get view attribute with v:attr

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/ui/view.md

Usage example for getting the view attribute. Retrieves the 'background' attribute.

```lua
local bg = v:attr("background")
```

--------------------------------

### Get application instance and quit

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/ui/view.md

Usage example showing how to get the application instance and call its quit method.

```lua
local app = v:application()
app:quit()
```

--------------------------------

### wdk.static rule example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/builtin-rules.md

Configures a target to build a static library using the wdk.static rule and the wdk.env.kmdf environment rule. Adds tracewpp flags and applies the wdk.tracewpp rule to driver C files.

```lua
target("nonpnp")

    -- add rules
    add_rules("wdk.static", "wdk.env.kmdf")

    -- add flags for rule: wdk.tracewpp
    add_values("wdk.tracewpp.flags", "-func:TraceEvents(LEVEL,FLAGS,MSG,...)", "-func:Hexdump((LEVEL,FLAGS,MSG,...))")

    -- add files
    add_files("driver/*.c", {rules = "wdk.tracewpp"})

```

--------------------------------

### Initialize Xpack and define simple package

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/xpack-interfaces.md

Initializes the Xpack plugin by including the builtin xpack moduleebb. Then defines an xpack target named 'test' with version, homepage, and install files. This is the basic setup for creating an installation package.

```lua
includes("@builtin/xpack")

xpack("test")
     set_version("1.0")
     set_homepage("https://xmake.io")
     add_installfiles("...")
```

--------------------------------

### table.wrap_unlock usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/builtin-modules/table.md

Usage example showing how to lock and unlock a table, then unwrap it to get the original value.

```lua
local t = {1}
table.wrap_lock(t)
table.wrap_unlock(t)
print(table.unwrap(t))  -- Result: 1
```

--------------------------------

### table.values usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/builtin-modules/table.md

Example usage of table.values to get all values of a table. The order of the returned values is not guaranteed.

```lua
local vals = table.values({a = 1, b = 2, c = 3})
-- Result: {1, 2, 3} (order is not guaranteed)
```

--------------------------------

### on_install with xmake configuration parameters

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/package-dependencies.md

Passes unique compilation configuration parameters to the xmake install tool.

```lua
on_install(function (package)
     import("package.tools.xmake").install(package, {"--xxx=y"})
end)
```

--------------------------------

### table.keys usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/builtin-modules/table.md

Example usage of table.keys to get all keys of a table. The order of the returned keys is not guaranteed.

```lua
local keys = table.keys({a = 1, b = 2, c = 3})
-- Result: {"a", "b", "c"} (order is not guaranteed)
```

--------------------------------

### Install basic-templates addon

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/extensions/addons/official/basic-templates.md

Installs the basic-templates addon and lists the templates it adds to xmake create.

```sh
$ xmake addon --install basic-templates
$ xmake create --list                        # the templates it added show up here
```

--------------------------------

### libc.ptraddr usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/base/libc.md

Usage example for libc.ptraddr. It allocates memory with libc.malloc, gets the pointer address, and prints it.

```lua
import("core.base.libc")

local data = libc.malloc(1024)
local addr = libc.ptraddr(data)
print("Pointer address:", addr)
```

--------------------------------

### on_install for specific platforms

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/package-dependencies.md

Installation script valid for specific compilation platforms, here linux and macosx.

```lua
on_install("linux", "macosx", function (package)
    -- TODO
end)
```

--------------------------------

### task.run example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/plugin-and-task.md

Shows how to run a task with parameters and options using task.run.

```lua
task.run("hello", {color="red"}, arg1, arg2, arg3)

```

--------------------------------

### Install libpng with mirror proxy

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/package-management/network-optimization.md

Example of installing a package with xrepo and the resulting curl command that uses the mirror domain.

```sh
$ xrepo install libpng
> curl https://hub.fastgit.org/glennrp/libpng/archive/v1.6.37.zip -o v1.6.37.zip
```

--------------------------------

### semver:patch usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/base/semver.md

Example of using semver:patch to get the patch version number, returning 0.

```lua
semver.new("v2.1.0"):patch() -- return 0
```

--------------------------------

### semver:minor usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/base/semver.md

Example of using semver:minor to get the minor version number, returning 1.

```lua
semver.new("v2.1.0"):minor() -- return 1
```

--------------------------------

### semver:major usage example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/extension-modules/core/base/semver.md

Example of using semver:major to get the major version number, returning 2.

```lua
semver.new("v2.1.0"):major() -- return 2
```

--------------------------------

### Show help menu with xmake f --help

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/posts/custom-option.md

Command to display the help menu, which now includes the hello option.

```bash
$ xmake f --help
```

--------------------------------

### table.slice usage examples

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/scripts/builtin-modules/table.md

Example usages of table.slice with different start, stop, and step arguments, showing the resulting slices.

```lua
-- Extract all elements after the 4th element, resulting in: {4, 5, 6, 7, 8, 9}
table.slice({1, 2, 3, 4, 5, 6, 7, 8, 9}, 4)

-- Extract the 4th-8th element and the result: {4, 5, 6, 7, 8}
table.slice({1, 2, 3, 4, 5, 6, 7, 8, 9}, 4, 8)

-- Extract the 4th-8th element with an interval of 2, resulting in: {4, 6, 8}
table.slice({1, 2, 3, 4, 5, 6, 7, 8, 9}, 4, 8, 2)
```

--------------------------------

### wdk.binary rule example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/api/description/builtin-rules.md

Configures a target to build an executable using the wdk.binary rule and the wdk.env.umdf environment rule. Adds C++ source files from the 'exe' directory.

```lua
-- add target
target("app")

    -- add rules
    add_rules("wdk.binary", "wdk.env.umdf")

    -- add files
    add_files("exe/*.cpp")

```
Tokens:
Raw