This is a mirror page, please see the original page:

Packaging interface

xpack is provided as a plug-in, and all its APIs need to be introduced through includes("@builtin/xpack").

includes("@builtin/xpack")

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

xpack:set_version

Set package version

This interface is used to set the version of the generated installation package:

xpack("test")
     set_version("1.0")
     --...

If we do not set it, but bind the installed target program through set_targets, the version configuration in target will also be used.

target("foo")
     set_version("1.0")

xpack("test")
     set_targets("foo")
     --...

We can also use the global project version if no targets are bound.

set_version("1.0")

xpack("xmake")
     --...

xpack:set_homepage

Set homepage information

xpack("xmake")
     set_homepage("https://xmake.io")

xpack:set_title

Set title information

A simple description usually used to configure the installation package, shorter than set_description.

xpack("xmake")
     set_title("Xmake build utility ($(arch))")

xpack:set_description

Set detailed description

This interface can set more detailed description information of the installation package. You can use one or two sentences to describe the package in detail.

xpack("xmake")
     set_description("A cross-platform build utility based on Lua.")

xpack:set_author

Set author information

We can set the email address, name, etc. to describe the author of this package.

xpack("xmake")
     set_author("waruqi@gmail.com")

xpack:set_maintainer

Set maintainer information

We can set the email address, name, etc. to describe the maintainer of this package.

The maintainer and author may or may not be the same person.

xpack("xmake")
     set_maintainer("waruqi@gmail.com")

xpack:set_copyright

Set the copyright information of the package

xpack("xmake")
     set_copyright("Copyright (C) 2015-present, TBOOX Open Source Group")

xpack:set_license

Set the package licence

Currently used by packages like srpm/rpm/deb to set the licence name.

set_license("Apache-2.0")

xpack:set_licensefile

Set the license file of the package

We can set the file path where LICENSE is located, like the NSIS installation package, it will also additionally display the LICENSE page to the installation user.

xpack("xmake")
     set_licensefile("../LICENSE.md")

xpack:set_company

Set the company to which the package belongs

We can use this interface to set the company and organization name to which the package belongs.

xpack("xmake")
     set_company("tboox.org")

xpack:set_inputkind

Set the packaged input source type

This is an optional interface that can be used to identify the currently packaged input source type.

• binary: package from binary files as input source, usually using add_installfiles
• source: Start packaging from a source file as an input source, usually using add_sourcefiles

This is generally used for custom packaging formats, and for built-in formats, such as: nsis, zip, srczip, etc.,
In fact, it can be determined whether the currently packaged input source is packaged from the source code or directly from the binary source.

Therefore, unless necessary (such as customizing the packaging format), we usually do not need to set it.

In the script domain, we can also use package:from_source() and package:from_binary() to determine the current input source.

xpack("test")
     set_formats("nsis", "zip", "targz", "srczip", "srctargz", "runself")
     add_installfiles("src/(assets/*.png)", {prefixdir = "images"})
     add_sourcefiles("(src/**)")
     on_load(function (package)
         if package:from_source() then
             package:set("basename", "test-$(plat)-src-v$(version)")
         else
             package:set("basename", "test-$(plat)-$(arch)-v$(version)")
         end
     end)

If the above packaging configuration is an nsis package, the binary file will be used as the input source for packaging by default, and the files configured by add_installfiles will be packaged.

srczip, srctargz and runself start packaging from the source file, will package the files in add_sourcefiles, and then execute the packaging script.

xpack:set_formats

Set packaging format

Configure the packaging format that needs to be generated by the current XPack package. Multiple formats can be configured at the same time. The xmake pack command will generate them all at once.

!> Some formats will be automatically ignored if the current platform does not support generation.

xpack("test")
     set_formats("nsis", "zip", "targz", "srczip", "srctargz", "runself")

We can also specify to generate some of the formats through commands instead of generating them all at once.

$ xmake pack -f "nsis,zip"

Separated by commas, specify to generate NSIS and zip packages, and ignore other format packages for the time being.

Currently supported formats are:

xpack:set_basename

Set package file name

Set the file name of the generated package, but do not include the suffix.

xpack("xmake")
     set_basename("xmake-v$(version)")

We can also configure variables such as $(version), $(plat), $(arch) and so on.

In addition, if you want more flexible configuration, you can configure it in the on_load script.

xpack("xmake")
     on_load(function (package)
         package:set("basename", "xmake-v" .. package:version())
     end)

xpack:set_extension

Set the extension of the installation package

Usually we do not need to modify the extension of the generated package, because after specifying nsis, zip and other formats, there will be a default suffix name, such as: .exe, .zip.

However, if we are customizing the package format and need to generate a custom package, then we may need to configure it.

xpack("mypack")
     set_format("myformat")
     set_extension(".myf")
     on_package(function (package)
         local outputfile = package:outputfile()
         -- TODO
     end)

For example, here we customize a myformat package format, using the custom suffix name of .myf, and then we can generate it in on_package,

The package output file name returned by package:outputfile() will contain this suffix.

xpack:add_targets

Associated target program

We can use this interface to configure the associated target that needs to be installed.

target("foo")
     set_kind("shared")
     add_files("src/*.cpp")
     add_headerfiles("include/(*.h)")

xpack("test")
     set_formats("nsis")
     add_targets("foo")

When the test installation package is generated, the executable program and dynamic library of the associated foo target will be packaged and installed together.
In addition, the custom installation files configured through add_headerfiles and add_installfiles in the target will also be included in the installation package and installed together.

And we can also use on_installcmd, after_installcmd and other custom packaging installation scripts in the target and its rules, which will also be executed together.

xpack:add_components

Add installation package components

We also support adding custom components to the installation package and selecting and installing them according to the component mode. Currently, only NSIS packages have comparative support effects.

We can define a component domain through xpack_component(), and then use add_components() to add the specified component and associate it with the package.

In the component, we can write some custom installation scripts through on_installcmd(), and the installation will only be executed when the component is enabled.

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)

Here, we use batchcmds:rawcmd("nsis", "...") to add an nsis-specific installation command to enable long path support. The effect is as follows:

It will only be enabled when we check LongPath. Of course, we can also configure whether the component is enabled by default through set_default().

Except for the NSIS package, although other packages do not have complete support for components, they will also execute the scripts in the components to implement packaging, but may not be able to display the corresponding component UI and check boxes.

xpack:set_bindir

Set the binary installation directory of the package

Usually the generated installation package will have an installation root directory, and we can specify the bin directory location under the installation directory through this configuration.

If not specified, defaults to installdir/bin.

If configured

xpack("xmake")
     set_bindir("mybin")

Then the executable file will be installed under installdir/mybin. If it is an NSIS package, this path will be automatically set to %PATH% after installation.

xpack:set_libdir

Set the library installation directory of the package

Usually the generated installation package will have an installation root directory, and we can specify the lib directory location under the installation directory through this configuration.

If not specified, defaults to installdir/lib.

If configured

xpack("xmake")
     set_libdir("mylib")

Then the static library files will be installed under installdir/mylib.

xpack:set_includedir

Set the package header file installation directory

Usually the generated installation package will have an installation root directory, and we can specify the include directory location under the installation directory through this configuration.

If not specified, defaults to installdir/include.

If configured

xpack("xmake")
     set_includedir("myinc")

Then the header files will be installed under installdir/myinc.

xpack:set_prefixdir

Set the installation prefix directory of the package

If configured

xpack("xmake")
     set_prefixdir("prefix")

Then all installation files will be installed under installdir/prefix, for example:

installdir
   - prefix
     - include
     - lib
     - bin

xpack:set_specfile

Set package spec file path

The generation of some package formats requires the generation of specific spec files before calling third-party packaging tools to generate packages.

For example, for NSIS packages, you need to first generate an NSIS-specific .nsi configuration file through xmake based on the xpack configuration, and then xmake will call makensis.exe to generate the NSIS package based on this .nsi file.

Packages such as deb/rpm have specific spec files.

xmake will automatically generate a spec file by default when packaging, but if we want to more deeply customize the configuration of some unique packages, we can use this interface,

Configure a spec file of your own, in which the user maintains some package configuration definitions, and then define some ${PACKAGE_NAME}, ${VERSION} package-specific built-in variables in it to realize package information replacement.

xpack("xmake")
     set_formats("nsis")
     set_specfile("makensis.nsi")

makensis.nsi

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}"

Here are some built-in commonly used package variables:

In addition to built-in variables, we can also configure some custom template variables through the set_specvar interface.

xpack:set_specvar

Set custom variables in the package spec file

Usually used together with the set_specfile interface to set some custom package variables in a custom spec template file.

xpack("xmake")
     set_formats("nsis")
     set_specfile("makensis.nsi")
     set_specvar("FOO", "hello")

makensis.nsi

VIAddVersionKey /LANG=0 ProductName "${FOO}"

Before generating the package, xmake will replace ${FOO} with hello, and then call the makensis.exe command to generate the NSIS installation package based on this file.

xpack:set_iconfile

Set icon file path

We can additionally configure an ico icon file, which can be used to set the icon of some installation packages such as NSIS that support icon customization.

xpack("xmake")
     set_iconfile("xmake.ico")

xpack:add_sourcefiles

Add source files

This is usually used for source packages, that is, pure source packages such as srczip, srctargz, and source code installation packages in the runself format.

If it is a custom package format, we need to configure set_inputkind("source") to open the source package.

Through this interface, you can customize which source files need to be included in the package for later compilation and installation.

Its detailed usage is similar to add_installfiles, you can refer to its documentation description.

xpack:add_installfiles

Add binary files

This is usually used for binary packages, that is, packages in nsis, deb, etc. formats, which install binary files directly.

Therefore, we can use this interface to configure additional binary files that need to be installed, such as executable files, resource files, etc.

For example, we can specify to install various types of files to the installation directory:

xpack("test")
     add_installfiles("src/*.h")
     add_installfiles("doc/*.md")

We can also specify to install to a specific subdirectory:

xpack("test")
     add_installfiles("src/*.h", {prefixdir = "include"})
     add_installfiles("doc/*.md", {prefixdir = "share/doc"})

For the above settings, we will install them to installdir/include/*.h, installdir/share/doc/*.md.

Note: The default installation will not retain the directory structure and will be fully expanded. Of course, we can also use () to extract the subdirectory structure in the source file for installation, for example:

xpack("test")
     add_installfiles("src/(tbox/*.h)", {prefixdir = "include"})
     add_installfiles("doc/(tbox/*.md)", {prefixdir = "share/doc"})

xpack:add_buildrequires

Add package build dependencies

This is usually used for some source packages, such as srpm. Before installing these source code packages, you need to build the source code first, and building the source code may require the use of some other dependency packages.

We can configure them through this interface.

xpack("test")
     set_formats("srpm")
     on_load(function (package)
         local format = package:format()
         if format == "srpm" then
             package:add("buildrequires", "make")
             package:add("buildrequires", "gcc")
             package:add("buildrequires", "gcc-c++")
         end
     end)
     on_buildcmd(function (package, batchcmds)
         batchcmds:runv("make")
     end)

Since different installation packages have some differences in their dependent package names, we need to configure them for different package formats in the on_load script domain.

xpack:on_load

Custom loading script

If the configuration in the description field cannot meet our needs, we can further flexibly configure the package in the on_load custom script field.

This interface will be called during the initial loading of each XPack package, and you can make some basic configurations in it.

For example, dynamically modify the package file name in it:

xpack("test")
     on_load(function (package)package:set("basename", "test-" .. package:version())
     end)

xpack:before_package

Customize the script before packaging

We can configure custom scripts before packaging through this interface.

xpack("test")
     before_package(function (package)
         -- TODO
     end)

xpack:on_package

Custom packaging script

We can configure packaging custom scripts through this interface, which will rewrite the entire built-in packaging logic. Typically used for custom package formats.

xpack("test")
     set_formats("xxx")
     on_package(function (package)
         -- TODO
     end)

xpack:after_package

Customize the script after packaging

We can configure the custom script after packaging through this interface.

xpack("test")
     after_package(function (package)
         -- TODO
     end)

xpack:on_buildcmd

Custom build script

For some source code build packages, we need to build the source code first before installation, such as srpm packages.

Therefore, we can customize the build script through this interface, for example:

xpack("test")
     set_formats("srpm")
     add_sourcefiles("src/*.c")
     add_sourcefiles("./configure")
     on_buildcmd(function (package, batchcmds)
         batchcmds:runv("./configure")
         batchcmds:runv("make")
     end)

If we associate target programs through add_targets, xpack will execute the xmake build command by default to build them even if we do not configure on_buildcmd.

xpack("test")
     set_formats("srpm")
     add_sourcefiles("src/*.c")
     add_sourcefiles("./xmake.lua")

In addition, we can also use add_buildrequires to configure some build dependencies.

xpack:before_buildcmd

Customize pre-build scripts

Through this interface, we can configure pre-build scripts.

xpack("test")
     set_formats("srpm")
     before_buildcmd(function (package, batchcmds)
         -- TODO
     end)

xpack:after_buildcmd

Customize the script after the build

Through this interface, we can configure the script after the build.

xpack("test")
     set_formats("srpm")
     after_buildcmd(function (package, batchcmds)
         -- TODO
     end)

xpack:before_installcmd

Add script before installation

It will not rewrite the entire installation script, but will add some custom installation scripts before the existing installation scripts are executed:

xpack("test")
     before_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)

It should be noted that the cp, mkdir and other commands added through batchcmds will not be executed immediately, but will only generate a command list. When the package is actually generated later, these commands will be translated into packaging commands.

xpack:on_installcmd

Custom installation script

This time, the built-in default installation script is completely rewritten, including the internal automatic installation of files configured with add_installfiles. Users need to handle all the installation logic by themselves.

xpack:after_installcmd

Add post-installation scripts

It will not rewrite the entire installation script, but will add some custom installation scripts after the existing installation scripts are executed:

xpack("test")
     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)

It should be noted that the cp, mkdir and other commands added through batchcmds will not be executed immediately, but will only generate a command list. When the package is actually generated later, these commands will be translated into packaging commands.

xpack:before_uninstallcmd

Add script before uninstallation

Similar to before_installcmd, please refer to before_installcmd description.

xpack:on_uninstallcmd

Custom uninstall script

Similar to on_installcmd, please refer to on_installcmd description.

xpack:after_uninstallcmd

Add script after uninstallation

Similar to after_installcmd, please refer to after_installcmd description.

xpack:set_nsis_displayicon

Set the display icon of NSIS

This is an NSIS proprietary API that can be used to configure NSIS display icons:

xpack("test")
     set_nsis_displayicon("bin/foo.exe")

We need to configure the executable file path with an icon so that the icon displayed in the installation package is consistent with it.

This is an optional configuration. Even if we do not configure it, xmake will use the icon in the executable file in the associated target by default.

Component interface

xpack_component:set_title

Set a brief description of the package components

xpack_component("LongPath")
     set_title("Enable Long Path")

xpack_component:set_description

Set detailed description of package components

xpack_component("LongPath")
     set_description("Increases the maximum path length limit, up to 32,767 characters (before 256).")

xpack_component:set_default

Set the default enabled state of package components

Usually the package component is enabled by default, but we can also use this interface to disable this component by default. Only when the user chooses to check this component when installing the package will it be enabled for installation.

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

xpack_component:on_load

Custom loading script

We can further flexibly configure package components in the on_load custom script field.

xpack_component("test")
     on_load(function (component)
         local package = component:package()
         -- TODO
     end)

xpack_component:before_installcmd

Add script before component installation

It will not rewrite the entire installation script, but will add some custom installation scripts before the existing installation scripts are executed:

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

It should be noted that the cp, mkdir and other commands added through batchcmds will not be executed immediately, but will only generate a command list. When the package is actually generated later, these commands will be translated into packaging commands.

It is exactly the same as xpack's before_installcmd. The only difference is that the installation script here will only be executed when this component is enabled.

xpack_component:on_installcmd

Rewrite the installation script of the component

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

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

xpack_component:after_installcmd

Add script after component installation

After the component is installed, the script here will be executed, similar to xpack's after_installcmd.

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

xpack_component:before_uninstallcmd

Add script before component uninstallation

After the component is installed, the script here will be executed, similar to xpack's before_uninstallcmd.

xpack_component("test")
     before_uninstallcmd(function (component, batchcmds)
         -- TODO
     end)

xpack_component:on_uninstallcmd

Rewrite the script for component uninstallation

This will rewrite the entire component's uninstall script, similar to xpack's on_uninstallcmd.

xpack_component("test")
     on_uninstallcmd(function (component, batchcmds)
         -- TODO
     end)

xpack_component:after_uninstallcmd

Add script after component uninstallation

After the component is uninstalled, the script here will be executed, similar to xpack's before_uninstallcmd.

xpack_component("test")
     before_uninstallcmd(function (component, batchcmds)
         -- TODO
     end)

xpack_component:add_sourcefiles

Add component source file

This is similar to xpack's add_sourcefiles, but here only when the component is enabled, these source files will be added to the installation package.

xpack_component:add_installfiles

Add component binary installation file

This is similar to xpack's add_installfiles, but here only the binaries are added to the installation package when the component is enabled.