### Install Binary Package with SDL2 Example

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

Configure xmake to directly reference and install a binary version of a package. This example demonstrates setting URLs and versions for the SDL2 development libraries on Windows.

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

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

### Install Package with Mirror Acceleration

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

Example of installing a package, demonstrating how the mirror configuration automatically redirects the download to a specified mirror site like FastGit.

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

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

### Custom Install Script Example

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

Override the default installation behavior for a target using a custom install script.

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

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

### Generate Self-Installation Package (Complete Example)

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

A comprehensive example for generating a self-installation package for xmake's own source code. It includes detailed source file inclusion and custom installation commands.

```lua
xpack("xmakesrc")
     set_formats("runself")
     set_basename("xmake-v$(version)")
     set_prefixdir("xmake-$(version)")
     before_package(function (package) 
         import("devel.git")

         local rootdir = path.join(os.tmpfile(package:basename()) .. ".dir", "repo")
         if not os.isdir(rootdir) then
             os.tryrm(rootdir)
             os.cp(path.directory(os.projectdir()), rootdir)

             git.clean({repodir = rootdir, force = true, all = true})
             git.reset({repodir = rootdir, hard = true})
             if os.isfile(path.join(rootdir, ".gitmodules")) then
                 git.submodule.clean({repodir = rootdir, force = true, all = true})
                 git.submodule.reset({repodir = rootdir, hard = true})
             end
         end

         local extraconf = {rootdir = rootdir}
         package:add("sourcefiles", path.join(rootdir, "core/**|src/pdcurses/**|src/luajit/**|src/tbox/tbox/src/demo/**"), extraconf )
         package:add("sourcefiles", path.join(rootdir, "xmake/**"), extraconf)
         package:add("sourcefiles", path.join(rootdir, "*.md"), extraconf)
         package:add("sourcefiles", path.join(rootdir, "configure"), extraconf)
         package:add("sourcefiles", path.join(rootdir, "scripts/*.sh"), extraconf)
         package:add("sourcefiles", path.join(rootdir, "scripts/man/**"), extraconf)
         package:add("sourcefiles", path.join(rootdir, "scripts/debian/**"), extraconf)
         package:add("sourcefiles", path.join(rootdir, "scripts/msys/**"), extraconf)
     end)

     on_installcmd(function (package, batchcmds) 
         batchcmds:runv("./scripts/get.sh", {"__local__"})
     end)
```

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

### List Pkgconfig Files for SFML Components

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

Example output showing pkgconfig files for various SFML components installed via a system package manager.

```sh
$ 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
```

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

### Package Repository Configuration Example

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

Example of a global xmakerc.lua file to add custom package repositories and set a global installation directory.

```lua
-- ~/.xmake/xmakerc.lua
-- Add custom package repositories
add_repositories("mycompany-repo https://github.com/mycompany/xmake-repo.git")
add_repositories("local-repo /path/to/local/repo")

-- Set global package installation directory
set_installdir("/opt/xmake/packages")
```

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

### Configure Qt Application Build

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

Example xmake.lua configuration for a Qt Quick application. This setup is standard for Qt projects managed by xmake.

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

target("demo")
    add_rules("qt.quickapp")
    add_headerfiles("src/*.h")
    add_files("src/*.cpp")
    add_files("src/qml.qrc")
```

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

### Install Package from APT Repository

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

Example of how to find and install a package directly from an APT repository using xmake's package management.

```lua
add_requires("apt::zlib1g-dev")
```

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

### Example of Previous Sublibrary Selection in Xmake

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

Demonstrates the older method of selecting sublibraries using custom configurations for each package. This approach can lead to repeated installations and increased disk space usage.

```lua
add_requires("sfml~foo", {configs = {graphics = true, window = true}})
add_requires("sfml~bar", {configs = {network = true}})

target("foo")
    set_kind("binary")
    add_packages("sfml~foo")

target("bar")
    set_kind("binary")
    add_packages("sfml~bar")
```

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

### Custom Target Installation Script

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

Implement a custom installation process for a target by overriding the `on_install` function. This example shows how to install a packaged APK file using adb.

```lua
target("test")

    -- Set up a custom installation script to automatically install apk files
    on_install(function (target)

        -- Use adb to install packaged apk files
        os.run("adb install -r ./bin/Demo-debug.apk")
    end)
```

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

### Install Library to System

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

Run `xmake install` to install the library to the system directory. Use the `-o` flag to specify a custom output directory.

```bash
$ xmake install
```

```bash
$ xmake install -o /tmp/output
```

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

### Basic Project Build Description

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/posts/api-scope.md

A minimal example demonstrating how to define a target, set its kind, and add source files. This is a common starting point for simple projects.

```lua
target("test")
    set_kind("binary")
    add_files("src/*.c")
```

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

### on_installcmd

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

Completely rewrite the installation script, handling all installation logic manually.

```APIDOC
## on_installcmd

### Description
Custom installation script.

### Function Prototype
```lua
on_installcmd(script: <function (package, batchcmds)>)
```

### Parameter Description
- **script** (function) - Install script function with package and batchcmds parameters.

### Usage
This interface completely rewrites the built-in default installation script. Users need to handle all installation logic by themselves.
```

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

### Compile and Install xmake from Source

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/posts/quickstart-1-installation.md

Compile and install xmake using make. This method requires root privileges and installs to system directories.

```bash
make build; sudo make install
```

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

### Compile and Install Qt Application on Windows

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

Compile the project and then install the Qt application. xmake automatically invokes windeployqt.exe during the install step for Windows deployment.

```bash
$ xmake
$ xmake install -o d:\installdir
```

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

### Install Package with Meson

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

Installs a package using Meson and Ninja. This example demonstrates configuring build types (debug/release) and library types (shared/static) based on package settings, and includes handling optional package dependencies.

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

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

### Basic Profiler Usage Example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/zh/posts/lua-profiler.md

Demonstrates the basic usage of the profiler by starting the profiling, performing some operations, and then stopping it to view the performance report.

```lua
-- start recording
profiler.start()

-- TODO
-- ...

-- stop recording
profiler.stop()
```

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

### on_install

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

Custom installation script for overriding default installation behavior.

```APIDOC
## on_install

### Description
Custom installation script for overriding the default installation behavior of the target being applied.

### Function Prototype
```lua
on_install(script: <function (target)>)
```

### Parameter Description
- **script** (function) - Install script function with target parameter.

### Usage Example
```lua
rule("markdown")
    on_install(function (target)
    end)
```
```

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

### Install with NMake

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

Build and install packages with nmake.

```lua
on_install(function (package)
    import("package.tools.nmake").install(package)
end)
```

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

### Binary Utilities Module Usage

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

Demonstrates how to use the `core.base.binutils` module and `utils.binary` extension for processing binary files. Includes examples for getting dependent libraries, reading symbols, and extracting static libraries.

```lua
import("utils.binary.deplibs")
import("utils.binary.readsyms")
import("utils.binary.extractlib")

-- Get dependent libraries
local deps = deplibs("/path/to/bin")

-- Read symbols
local syms = readsyms("/path/to/obj")

-- Extract static library
extractlib("/path/to/lib.a", "/path/to/outputdir")
```

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

### Add Install Files to Target

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/project-configuration/configure-targets.md

Include files to be installed with the target. Use `prefixdir` to specify the installation directory relative to the install prefix.

```lua
target("app")
    add_installfiles("assets/*.png", {prefixdir = "share/app"})  -- install resource files
    add_installfiles("config/*.conf", {prefixdir = "etc"})       -- install config files
```

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

### Custom Run Script

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

Override the default run operation for a target. This example shows how to start an installed application and capture its log output.

```lua
target("test")

    -- Set custom run script, automatically run the installed app program 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)
```

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

### Provide Installation Prompts

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

Use `set_installtips` to inform users about manual steps, license agreements, or prerequisites. This helps reduce misuse during installation.

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

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

### before_install

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

Run custom script before installing target. It does not override the default installation operation, just add some custom actions before installation.

```APIDOC
## before_install

### Description
Run custom script before installing target

### Function Prototype

::: tip API
```lua
before_install(script: <function (target)>)
```
:::


### Parameter Description

| Parameter | Description |
|-----------|-------------|
| script | Before install script function, receives target parameter |

### Usage

It does not override the default installation operation, just add some custom actions before installation.

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

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

### Custom Run Script for Target

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/zh/posts/quickstart-12-custom-scripts.md

Override the default run operation for a target to implement a custom running process. This example starts an installed application and monitors its logs using ADB.

```lua
target("test")

    -- Set custom run script to automatically run the installed app and get device output
    on_run(function (target) 
        os.run("adb shell am start -n com.demo/com.demo.DemoTest")
        os.run("adb logcat")
    end)
```

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

### Xmake Client Configuration File Example

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

Example of the client.conf file, demonstrating how to configure the server address and token for connecting to the remote cache service.

```json
{
    remote_cache = {
            connect = "127.0.0.1:9692,
            token = "590234653af52e91b9e438ed860f1a2b"
        }
    }
}

```

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

### Get Package Installation Directory

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

Retrieves the installation directory for the package. It can also be used to get a subdirectory. If the directory tree does not exist, it will be created.

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

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

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

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

### on_install

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

Override the installation process (`xmake install`) for a target to implement custom installation logic. This can be used to install generated artifacts like APKs to a specific location or device.

```APIDOC
## on_install

### Run custom install target file script

### Description
Override the installation of `xmake [i|install}` of the target target to implement a custom installation process.

### Function Prototype

::: tip API
```lua
on_install(script: <function (target)>)
```
:::


### Usage

```lua
target("test")

    -- Set up a custom installation script to automatically install apk files
    on_install(function (target) 

        -- Use adb to install packaged apk files
        os.run("adb install -r ./bin/Demo-debug.apk")
    end)
```
```

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

### Install xmake from Source on Linux/macOS

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/posts/how-to-install-xmake.md

Clone the xmake repository and run the install script. Requires root privileges for system-wide installation.

```bash
$ git clone git@github.com:waruqi/xmake.git
$ cd ./xmake
$ sudo ./install
```

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

### Xmake Server Configuration File Example

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

Example of the server.conf file, showing configuration for listening port, work directory, log file, and authentication tokens.

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

```

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

### make.install

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

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

```APIDOC
## make.install

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

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

### Parameters
#### Package
- package (package): Required. Package instance object

#### Configs
- configs (table): Required. Configuration parameter list

#### Opt
- opt (table): Optional. Option parameters

### Return Value
No return value
```

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

### Simplified Toolchain Configuration Examples

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/project-configuration/toolchain-configuration.md

Demonstrates various simplified syntaxes for configuring toolchains, including simple names, toolchains with packages, and toolchains with configurations and packages.

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

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

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

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

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

### Custom Install Script for Target

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/zh/posts/quickstart-12-custom-scripts.md

Override the default installation operation for a target to implement a custom installation process. This example installs a generated APK file using ADB.

```lua
target("test")

    -- Set custom install script to automatically install the apk file
    on_install(function (target) 

        -- Use adb to install the generated apk file
        os.run("adb install -r ./bin/Demo-debug.apk")
    end)
```

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

### Custom installation script

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

Completely rewrite the built-in default installation script using on_installcmd. Users must handle all installation logic themselves when using this function.

```lua
on_installcmd(function (package, batchcmds) 
    -- Custom installation logic here
end)
```

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

### Server Configuration with Tokens

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

Example server configuration showing listen address, work directory, and a list of authorized tokens, including a newly added one.

```lua
{
    known_hosts = { },
    logfile = "/Users/ruki/.xmake/service/server/logs.txt",
    remote_build = {
        listen = "0.0.0.0:9691",
        workdir = "/Users/ruki/.xmake/service/server/remote_build"
    },
    tokens = {
        "e438d816c95958667747c318f1532c0f",
        "7889e25402413e93fd37395a636bf942"
    }
}
```

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

### Custom Install Script

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

Override the default install operation for a target. This example demonstrates automatically installing a generated APK file using ADB.

```lua
target("test")

    -- Set custom install script, automatically install apk file
    on_install(function (target) 

        -- Use adb to install the packaged apk file
        os.run("adb install -r ./bin/Demo-debug.apk")
    end)
```

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

### Custom before_install Script

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

Implement a script to run before a custom target is installed. This hook is executed before the installation process starts.

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

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

### Complete Link Order Configuration Example

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

A comprehensive example demonstrating the configuration of targets, dependencies, packages, system libraries, frameworks, and link groups with `add_linkorders` and `add_linkgroups`.

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

add_requires("libpng")

target("bar")
     set_kind("shared")
     add_files("src/foo.cpp")
     add_linkgroups("m", "pthread", {whole = true})

target("foo")
     set_kind("static")
     add_files("src/foo.cpp")
     add_packages("libpng", {public = true})

target("demo")
     set_kind("binary")
     add_deps("foo")
     add_files("src/main.cpp")
     if is_plat("linux", "macosx") then
         add_syslinks("pthread", "m", "dl")
     end
     if is_plat("macosx") then
         add_frameworks("Foundation", "CoreFoundation")
     end
     add_linkorders("framework::Foundation", "png16", "foo")
     add_linkorders("dl", "linkgroup::syslib")
     add_linkgroups("m", "pthread", {name = "syslib", group = true})
```

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

### Platform Filtering Examples

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

Various examples demonstrating different platform filtering syntaxes.

```lua
-- `@linux`
```

```lua
-- `@linux|x86_64`
```

```lua
-- `@macosx,linux`
```

```lua
-- `android@macosx, linux`
```

```lua
-- `android|armeabi-v7a@macosx,linux`
```

```lua
-- `android|armeabi-v7a@macosx,linux|x86_64`
```

```lua
-- `android|armeabi-v7a@linux|x86_64`
```

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

### os.programdir

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

Gets the directory of the main xmake installation program.

```APIDOC
## os.programdir

### Description
Gets the directory of the main xmake installation program.

### Function Prototype
```lua
os.programdir()
```

### Parameter Description
No parameters required for this function.

### Usage
Consistent with the result of [$(programdir)](/api/description/builtin-variables#var-programdir), it is just a direct get returned to a variable, which can be maintained with subsequent strings.
```

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

### Run the application

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

Start your application, which initializes the UI, calls the `init()` method, and begins the event loop. This is the main entry point for launching the application.

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

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

### Create a New Project

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/quick-start.md

Create a new C++ project named 'hello' with default files and an xmake.lua configuration.

```sh
$ xmake create hello
```

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

### Get Installation Directory

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

Retrieve the installation directory for the target file using `target:installdir()`. This is commonly used in custom scripts for post-installation actions.

```lua
target:installdir()
```

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

### Manage Custom Project Templates with Xmake CLI

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

Command-line examples for listing available project templates and creating new projects using custom templates with xmake.

```bash
# List all available templates (repo, global, and built-in)
$ xmake create --list

# Filter templates by language
$ xmake create --list -l c++

# Create a project using a specific template
$ xmake create -t mytemplate hello
```

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

### Basic Script Execution Example

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

A simple example demonstrating a basic script execution within xmake, showing the 'on_run' function.

```lua
on_run(function (target)
    print("hello xmake!")
end)
```

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

### Get the program path of a subprocess

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

Returns the full program path that was used to start the process.

```lua
local proc = process.openv("xmake", {"lua", "print", "hello"})
print("Program:", proc:program())  -- Output: xmake
proc:close()
```

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

### Install Precompiled Binaries

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

Move artifacts into standard subdirectories during on_install. Use package:installdir() for precise placement.

```lua
os.cp("include/*", package:installdir("include"))
os.cp("lib/*.a",   package:installdir("lib"))
os.cp("bin/*",     package:installdir("bin"))
```

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

### NSIS Spec File Example

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

An example of an NSIS spec file (`.nsi`) that uses built-in xmake package variables for defining installer properties like version, product name, and copyright.

```text
VIProductVersion "${VERSION}.0"
VIFileVersion "${VERSION}.0"
VIAddVersionKey /LANG=0 ProductName "${PACKAGE_NAME}"
VIAddVersionKey /LANG=0 Comments "${PACKAGE_DESCRIPTION}"
VIAddVersionKey /LANG=0 CompanyName "${PACKAGE_COMPANY}"
VIAddVersionKey /LANG=0 LegalCopyright "${PACKAGE_COPYRIGHT}"
VIAddVersionKey /LANG=0 FileDescription "${PACKAGE_NAME} Installer - v${VERSION}"
VIAddVersionKey /LANG=0 OriginalFilename "${PACKAGE_FILENAME}"
```

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

### on_install

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

Handles the installation process for a package, including building it using specified tools like scons.

```APIDOC
## on_install

### Description
Handles the installation process for a package. This function is called during the package installation phase. It can be used to perform custom build steps or other installation-related tasks.

### Usage

```lua
on_install(function (package)
    -- Custom installation logic here
    -- Example using scons:
    import("package.tools.scons").build(package)
    -- Manually copy built binaries if needed
end)
```

### Parameters

- **package** (object) - The package object representing the current package being installed.
```

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

### Get Current Shell Information

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

Retrieves the name of the current shell being used, for example, 'pwsh' or 'cmd'.

```lua
print(os.shell())
```

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

### package:installdir

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

Gets the installation directory of the package. It can also be used to specify a subdirectory, which will be created if it doesn't exist.

```APIDOC
## package:installdir

### Description
Get 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.

### Method
```lua
package:installdir(...)
```

### Parameters
No parameters required for this function.

### Usage
```lua
-- returns the installation directory
package:installdir()
-- returns the subdirectory include inside the installation directory
package:installdir("include")
-- returns the subdirectory include/files
package:installdir("include", "files")
```
```

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

### Build for MinGW with xmake

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/posts/how-to-build-a-simple-project.md

Configure and build a project for MinGW. This example specifies the MinGW platform and the SDK path, followed by the build command.

```bash
$ xmake f -p mingw --sdk=/usr/local/i386-mingw32-4.3.0/

build ok!👌
```

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

### Add Component Installation for NSIS

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

Configure custom NSIS commands for specific components within an XPack. This example adds a component to enable long paths, executing a raw NSIS command when the component is selected during installation.

```lua
xpack("test")
     add_components("LongPath")

xpack_component("LongPath")
     set_default(false)
     set_title("Enable Long Path")
     set_description("Increases the maximum path length limit, up to 32,767 characters (before 256).")
     on_installcmd(function (component, batchcmds)
         batchcmds:rawcmd("nsis", [[ 
   ${If} $NoAdmin == "false" 
     ; Enable long path
     WriteRegDWORD ${HKLM} "SYSTEM\CurrentControlSet\Control\FileSystem" "LongPathsEnabled" 1
   ${EndIf}]]])
     end)
```

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

### Create Qt QuickApp Project with xmake

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

Quickly create a new Qt QuickApp project with QML support using the xmake create command and a predefined template.

```bash
xmake create -t qt.quickapp test
```

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

### Get the view bounds rectangle

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

Retrieves the bounds of the view as a rectangle object. The rectangle contains start and end coordinates.

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

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

### Generate Meson Build Files

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

Generates Meson build files only (setup phase). This example sets the build type to release.

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

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

### Example Build Output

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/basic-commands/build-targets.md

Illustrates the typical output when running the `xmake build` command, showing compilation and linking progress.

```sh
$ xmake build
[ 17%]: cache compiling.release src/main.cpp
[ 23%]: cache compiling.release src/foo.cpp
[ 35%]: linking.release libfoo.a
[ 71%]: linking.release test
[100%]: build ok, spent 1.173s
```

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

### Show xmake create help

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

View help information for the xmake create command to understand its options and usage.

```sh
xmake create --help
```

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

### Build and run Mac Catalyst application

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

Example output demonstrating the build process and execution of a Mac Catalyst application after configuration.

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

```bash
$ 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!
```

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

### Integrate SCons Source Library with xmake

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/package-management/using-source-code-packages.md

Use package.tools.scons to integrate SCons-maintained libraries. This example shows how to configure build options, apply platform-specific fixes, and install headers and libraries.

```lua
package("godotcpp")

    set_sourcedir(path.join(os.scriptdir(), "3rd/godotcpp"))

    add_deps("scons")

    add_includedirs("include", "include/core", "include/gen")

    on_install("linux", "windows", "macosx", "mingw", "cygwin", "iphoneos", "android", "msys", function (package)
        local configs = {"generate_bindings=yes"}
        table.insert(configs, "bits=" .. ((package:is_arch("x64") or package:is_arch("x86_64")) and "64" or "32"))
        if package:is_plat("windows") then
            io.replace("SConstruct", "/MD", "/" .. package:config("vs_runtime"), {plain = true})
        end

        - this fixes an error on ios and osx (https://godotengine.org/qa/65616/problems-compiling-gdnative-c-example-on-osx)
        if package:is_plat("macosx", "iphoneos") then
            io.replace("SConstruct", "-std=c++14", "-std=c++17", {plain = true})
        end

        - fix to use correct ranlib, @see https://github.com/godotengine/godot-cpp/issues/510
        if package:is_plat("android") then
            io.replace("SConstruct",
                [[env['AR'] = toolchain + "/bin/" + arch_info['tool_path'] + "-ar"]],
                [[env['AR'] = toolchain + "/bin/" + arch_info['tool_path'] + "-ar"
    env['RANLIB'] = toolchain + "/bin/" + arch_info['tool_path'] + "-ranlib"]], {plain = true})
        end

        import("package.tools.scons").build(package, configs)
        os.cp("bin/*." .. (package:is_plat("windows") and "lib" or "a"), package:installdir("lib"))
        os.cp("include/core/*.hpp", package:installdir("include/core"))
        os.cp("include/gen/*.hpp", package:installdir("include/gen"))
        os.cp("godot-headers/android", package:installdir("include"))
        os.cp("godot-headers/arvr", package:installdir("include"))
        os.cp("godot-headers/gdnative", package:installdir("include"))
        os.cp("godot-headers/nativescript", package:installdir("include"))
        os.cp("godot-headers/net", package:installdir("include"))
        os.cp("godot-headers/pluginscript", package:installdir("include"))
        os.cp("godot-headers/videodecoder", package:installdir("include"))
        os.cp("godot-headers/*.h", package:installdir("include"))
    end)
```

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

### Build Ascend C with SDK Override

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

Demonstrates building Ascend C projects, showing automatic SDK detection and how to manually specify the SDK path via command line arguments.

```bash
# SDK auto-detected from ASCEND_HOME_PATH — just build:
$ xmake

# Or point at a specific SDK
$ xmake f --sdk=/usr/local/Ascend/ascend-toolkit/latest
$ xmake
```

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

### Define a Remote Package Configuration

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

Define a package configuration for remote distribution, including description, license, dependencies, URLs, versions, and installation logic. This example defines the 'foo' package.

```lua
package("foo")
    set_description("The foo package")
    set_license("Apache-2.0")
    add_deps("add", "sub")

    add_urls("https://github.com/myrepo/foo.git")
    add_versions("1.0", "<shasum256 or gitcommit>")

    on_install(function (package)
        local configs = {}
        if package:config("shared") then
            configs.kind = "shared"
        end
        import("package.tools.xmake").install(package, configs)
    end)

    on_test(function (package)
        - TODO check includes and interfaces
        - assert(package:has_cfuncs("foo", {includes = "foo.h"})
    end)
```

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

### gtest Integration Example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/guide/basic-commands/run-tests.md

Configure xmake to integrate with the gtest framework for testing C++ projects. This setup defines a binary target and adds test files, specifying gtest as a required package.

```lua
add_rules("mode.debug", "mode.release")
add_requires("gtest")

target("mytest")
    set_kind("binary")
    add_files("src/*.cpp")
    for _, testfile in ipairs(os.files("tests/*.cpp")) do
        add_tests(path.basename(testfile), {
            files = testfile,
            remove_files = "src/main.cpp",
            packages = "gtest",  -- Integrate gtest package
            defines = "TEST_MAIN"
        })
    end
```

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

### on_installcmd

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

Rewrites the installation script for a component.

```APIDOC
## on_installcmd

### Description
Rewrite the installation script of the component.

### Function Prototype
```lua
on_installcmd(script: <function (component, batchcmds)>)
```

### Parameter Description
- **script** (function) - Install script function with component and batchcmds parameters

### Usage
Custom installation script for implementing specific component installation logic.

This will rewrite the entire component's installation script, similar to xpack's on_installcmd.

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

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

### Custom Target Run Script

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

Define a custom script for the run operation of a target using `on_run`. This example demonstrates automatically running an installed app and capturing device output using adb.

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

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

### Complete menu bar usage example

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

This comprehensive example demonstrates the creation and integration of a menu bar within a terminal application. It includes setting up the application, creating the menu bar and a main window, and handling window resizing.

```lua
import("core.ui.menubar")
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 menu bar
    local menubar = menubar:new("menubar", rect{1, 1, self:width() - 1, 1})
    menubar:title():text_set("Xmake Demo Application")
    menubar:title():textattr_set("red bold")
    
    -- Create main window
    local win = window:new("main", rect{1, 2, self:width() - 1, self:height() - 2}, "Main Window")
    
    -- Add to application
    self:insert(menubar)
    self:insert(win)
    
    self._menubar = menubar
    self._win = win
end

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

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

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

### Custom Package Repository Configuration Example

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/zh/guide/extras/environment-variables.md

This Lua snippet demonstrates how to add custom package repositories and set a global installation directory for packages. It's useful for managing private or local package sources.

```lua
-- ~/.xmake/xmakerc.lua
-- 添加自定义包仓库
add_repositories("mycompany-repo https://github.com/mycompany/xmake-repo.git")
add_repositories("local-repo /path/to/local/repo")

-- 设置全局包安装目录
set_installdir("/opt/xmake/packages")
```

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

### Hooking into Build Process with before_build

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

Use `target:before_xxx` scripts to hook custom logic into the build process without completely overriding default implementations. This example shows how to add logic before the build starts.

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

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

### Find CMake package LibXml2

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

This example demonstrates how to use `xmake l find_package` to get build information for the LibXml2 package from CMake. It returns the necessary linking flags, include paths, and library directories.

```sh
$ xmake l find_package cmake::LibXml2
{
  links = {
    "xml2"
  },
  includedirs = {
    "/Library/Developer/CommandLineTools/SDKs/MacOSX10.15.sdk/usr/include/libxml2"
  },
  linkdirs = {
    "/usr/lib"
  }
}
```

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

### Complete net.ping Example for Mirror Sources

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

This example demonstrates testing latency for multiple mirror sources and identifying the fastest one. It requires importing the net.ping module and iterates through results to find the minimum latency.

```lua
import("net.ping")

-- Test latency for multiple mirror sources
local mirrors = {
    "github.com",
    "gitee.com", 
    "code.csdn.net"
}

print("Testing mirror source latency...")
local results = ping(mirrors)

-- Find the mirror source with lowest latency
local best_mirror = nil
local min_time = math.maxinteger
for host, time in pairs(results) do
    print(string.format("%s: %d ms", host, math.floor(time)))
    if time < min_time then
        min_time = time
        best_mirror = host
    end
end

if best_mirror then
    print(string.format("\nFastest mirror source: %s (latency: %d ms)", best_mirror, math.floor(min_time)))
else
    print("No available mirror source found")
end
```

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

### Build for Android with xmake

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/posts/how-to-build-a-simple-project.md

Configure and build a project for Android. This example shows the command to set the platform to Android and then build the project.

```bash
$ xmake f -p android

build ok!👌
```

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

### Copying Intermediate Build Artifacts

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

Use `package:builddir()` to get the root path of the build directory when copying intermediate artifacts like `.pdb` files to the install directory. This is preferred over the older `package:buildir()` interface.

```lua
os.trycp(path.join(package:builddir(), "foo/**.pdb"), package:installdir("bin"))
```

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

### Complete Custom View Example

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

A full example demonstrating the creation and usage of a custom view, including initialization, drawing, and event handling within an application context.

```lua
import("core.ui.view")
import("core.ui.window")
import("core.ui.rect")
import("core.ui.application")
import("core.ui.event")
import("core.ui.action")

-- Define custom view
local myview = myview or view()

function myview:init(name, bounds)
    view.init(self, name, bounds)
    self:background_set("cyan")
    self:option_set("selectable", true)
end

function myview:on_draw(transparent)
    view.on_draw(self, transparent)
    
    local canvas = self:canvas()
    local textattr = curses.calc_attr({"yellow", "bold"})
    canvas:attr(textattr):move(0, 0):putstr("Custom View")
end

function myview:on_event(e)
    if e.type == event.ev_keyboard and e.key_name == "Enter" then
        print("Custom view activated")
        return true
    end
    return view.on_event(self, e)
end

-- Use custom view
local demo = application()

function demo:init()
    application.init(self, "demo")
    self:background_set("blue")
    
    -- Create window
    local win = window:new("main", rect{1, 1, self:width() - 1, self:height() - 1}, "Custom View Demo")
    
    -- Create custom view
    local custom = myview:new("custom", rect{10, 5, 40, 10})
    
    -- Add view to window panel
    local panel = win:panel()
    panel:insert(custom)
    panel:select(custom)
    
    self:insert(win)
    self._win = win
end

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

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

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

### Get Mode Configuration Value in Script

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/posts/quickstart-8-switch-build-mode.md

Retrieve the current mode configuration value using `get_config("mode")` within custom scripts or `on_load` functions. This example prints the mode when in release mode.

```lua
target("test")
    set_kind("binary")
    add_files("src/*.c")
    on_load(function (target) 
        if is_mode("release") then
            print(get_config("mode"), "$(mode)")
        end
    end)
```

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

### Basic xmake Build on Windows

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

Standard commands to navigate to the core directory, configure the build with a specific runtime, and then perform the build.

```bash
$ cd core
$ xmake f --runtime=lua
$ xmake
```

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

### Configure Mirror Source for Accelerated Downloads

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

Use a pac.lua file to configure mirror proxy rules, for example, redirecting all github.com domain accesses to hub.fastgit.org for faster downloads. This configuration is automatically applied when installing packages from GitHub.

```lua
function mirror(url)
     return url:gsub("github.com", "hub.fastgit.org")
end

```

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

### Specify Installation Platform

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

If the installation script is valid for a specific platform, specify the corresponding compilation platform. Multiple platforms can be specified.

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

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

### Configure ASN.1 Compilation with xmake

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

Use `add_requires("asn1c")` to automatically integrate the ASN.1 compiler and `add_rules("asn1c")` to process .asn1 files during the build. This example shows a basic setup for a binary target.

```lua
add_rules("mode.debug", "mode.release")
add_requires("asn1c")

target("test")
    set_kind("binary")
    add_files("src/*.c")
    add_files("src/*.asn1")
    add_rules("asn1c")
    add_packages("asn1c")
```

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

### Custom Line Hook with Source Info

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/zh/posts/lua-profiler.md

This example shows how to create a custom handler function for debug.sethook to log the source file path and line number of each executed line. It uses debug.getinfo(2).short_src to get the caller's source information.

```lua
debug.sethook(function (event, line) print(debug.getinfo(2).short_src .. ":" .. line) end, "l")
```

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

### Initialize the application

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

Initialize your custom application by providing a name and optional command-line arguments. This method is automatically called by `run()`.

```lua
function demo:init()
    application.init(self, "myapp")
    self:background_set("blue")
    
    -- Add your UI components here
    self:insert(self:main_dialog())
end
```

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

### Build and Run Project

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

Use these commands to build and run the project after generating configuration files.

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

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

### Set Installation Directory

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

Specifies a custom directory for installing project files when using 'xmake install'. Overrides the default system installation path.

```lua
set_installdir("path/to/install")
```

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

### Install Xmake Master Version using wget

Source: https://github.com/xmake-io/xmake-docs/blob/master/docs/posts/quickstart-1-installation.md

Installs the master version of Xmake using a one-click installation script via wget. Ensure you have wget installed.

```bash
Bash <(wget https://raw.githubusercontent.com/tboox/xmake/master/scripts/get.sh -O -)
```

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

### Complete text dialog example

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

Demonstrates the creation and configuration of a text dialog, including setting content, enabling scrolling, adding buttons, and handling window resizing. Requires importing `core.ui.textdialog`, `core.ui.rect`, and `core.ui.application`.

```lua
import("core.ui.textdialog")
import("core.ui.rect")
import("core.ui.application")

local demo = application()

function demo:init()
    application.init(self, "demo")
    self:background_set("blue")
    
    -- Create text dialog
    local dialog = textdialog:new("text", rect{10, 5, 60, 20}, "Text Dialog")
    
    -- Set text content
    dialog:text():text_set("This is a text dialog example.\nYou can display multi-line text content.\nWhen text content exceeds the display area, you can enable scrolling.")
    
    -- Enable scrollbar
    dialog:option_set("scrollable", true)
    
    -- Add buttons
    dialog:button_add("ok", "< OK >", function (v) self:quit() end)
    
    self:insert(dialog)
    self._dialog = dialog
end

function demo:on_resize()
    if self._dialog then
        self._dialog:bounds_set(rect{10, 5, self:width() - 20, self:height() - 10})
    end
    application.on_resize(self)
end

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