If you do not set this configuration, [is_mode](#is_mode) can also be used normally.
### set_project #### Set project name Set the whole project name, we can set it at the beginning of `xmake.lua`. ```lua -- set project name set_project("tbox") -- set project version set_version("1.5.1") ``` ### set_version #### Set project version Set the whole project version, we can set it at the beginning of `xmake.lua`. ```lua set_version("1.5.1") ``` We can set build version in v2.1.7 version: ```lua set_version("1.5.1", {build = "%Y%m%d%H%M"}) ``` We can also add version to the config header files, @see [add_configfiles](/manual/project_target?id=add-template-configuration-files) ### set_xmakever #### Set minimal xmake version If the current xmake version less than the required version, it will prompt an error. ```lua -- the current xmake version must be larger than 2.1.0 set_xmakever("2.1.0") ``` ### add_subdirs #### Add sub-project directoriesFor xmake 2.x and above, try to use the [includes](#includes) interface, which is a generic version of add_subdirs and add_subfiles, and supports some built-in extensions.
This interface will add sub-project directories to the current `xmake.lua`, it will load the `xmake.lua` file of the sub-directories. For example, assume we have the following project directory tree: ``` ./tbox ├── src │ ├── demo │ │ └── xmake.lua │ └── tbox │ └── xmake.lua └── xmake.lua ```` We can add sub-project `tbox` and `demo` directories to the root `xmake.lua`. ```lua add_subdirs("src/tbox") if is_option("demo") then add_subdirs("src/demo") end ``` By default, xmake will compile all targets. If you only want to compile a specific target, you can do: ```bash # only build `tbox` target $ xmake build tbox ``` ### add_subfiles #### Add sub-project filesFor xmake 2.x and above, try to use the [includes](#includes) interface, which is a generic version of add_subdirs and add_subfiles, and supports some built-in extensions.
`add_subfiles` is similar to [add_subdirs](#add_subdirs). The only difference is that this interface specifies the path to the 'xmake.lua' file directly, rather than a directory. for example: ```lua add_subfiles("src/tbox/xmake.lua") ``` ### add_moduledirs #### Add module directories The builtin modules are placed in the 'xmake/modules' directory, but for user-defined modules for a specific project, you can configure additional module directories in the 'xmake.lua` file. ```lua add_moduledirs("$(projectdir)/modules") ``` xmake will load the given module in the given directory when calling `import`. ### add_plugindirs #### Add plugin directories The builtin plugins are placed in the 'xmake/plugins' directory, but for user-defined plugins for a specific project, you can configure additional plugin directories in the 'xmake.lua` file. ```lua add_plugindirs("$(projectdir)/plugins") ``` xmake will load all plugins in the given directory. ### add_packagedirs #### Add package directories By setting up a dependency package directory, you can easily integrate some third-party dependent libraries. Taking the tbox project as an example, its package directory is as follows: ``` tbox.pkg - base.pkg - zlib.pkg - polarssl.pkg - openssl.pkg - mysql.pkg - pcre.pkg - ... ``` If you want the current project to load these packages, first specify the package directory path, for example: ```lua add_packagedirs("pkg") ``` Then, please add these packages to the given target by [add_packages](#add_packages): ```lua target("tbox") add_packages("zlib", "polarssl", "pcre", "mysql") ``` xmake will check these packages automatically and link with them if they exist, and we can disable them manually. ```bash $ xmake f --openssl=n ``` ### get_config #### Get the configuration value This interface is introduced from version 2.2.2 to get the configuration value from the given name. ```lua if get_config("myconfig") == "xxx" then add_defines("HELLO") end ``` ### set_config #### Set the default configuration value This interface is introduced from version 2.2.2 to set the default configuration value in xmake.lua. Many previous configurations, including the build toolchain, build directory, etc. We can only be configured by `$xmake f --name=value`. If we want to write a default value in xmake.lua, we can use the following method: ```lua set_config("name", "value") set_config("buildir", "other/buildir") set_config("cc", "gcc") set_config("ld", "g++") ``` However, we can still modify the default configuration in xmake.lua by `$xmake f --name=value`. ### add_requires #### Add package dependencies Xmake's dependency package management fully supports semantic version selection, for example: "~1.6.1". For a detailed description of semantic versioning, see: [https://semver.org/](https://semver.org/) Some examples: ```lua add_requires("tbox 1.6.*", "pcre 1.3.x", "libpng ^1.18") add_requires("libpng ~1.16", "zlib 1.1.2 || >=1.2.11 <1.3.0") ``` The semantic version parser currently used by xmake is the [sv](https://github.com/uael/sv) library contributed by [uael](https://github.com/uael), which also has a description of the version. For detailed instructions, please refer to the following: [Version Description](https://github.com/uael/sv#versions) Of course, if we have no special requirements for the version of the dependency package, we can omit the version: ```lua add_requires("tbox", "libpng", "zlib") ``` This will use the latest known version of the package, or the source code compiled from the master branch. If the current package has a git repository address we can also specify a specific branch version: ```lua add_requires("tbox master") add_requires("tbox dev") ``` If the specified dependency package is not supported by the current platform, or if the compilation and installation fails, then xmake will exit with an error, which is reasonable for some projects that must rely on certain packages to work. However, if some packages are optional dependencies, they can be set to optional packages even if they are not compiled properly. ```lua add_requires("tbox", {optional = true}) ``` With the default settings, xmake will first check to see if the system library exists (if no version is required). If the user does not want to use the system library and the library is provided by a third-party package manager, then you can set: ```lua add_requires("tbox", {system = false}) ``` If we want to debug the dependencies at the same time, we can set them to use the debug version of the package (provided that this package supports debug compilation): ```lua add_requires("tbox", {debug = true}) ``` If the current package does not support debug compilation, you can submit the modified compilation rules in the repository to support the debug, for example: ```lua package("openssl") on_install("linux", "macosx", function (package) os.vrun("./config %s --prefix=\"%s\"", package:debug() and "--debug" or "", package:installdir()) os.vrun("make -j4") os.vrun("make install") end) ``` Some packages have various compile options at compile time, and we can pass them in. Of course, the package itself supports: ```lua add_requires("tbox", {config = {small=true}}) ``` Pass `--small=true` to the tbox package so that compiling the installed tbox package is enabled. After v2.2.3, you can control whether you need to add a dependency package in your own definition configuration option parameter by [option](#option) and [has_config](#has_config): ```lua option("luajit") set_default(false) set_showmenu(true) set_category("option") set_description("Enable the luajit runtime engine.") option_end() if has_config("luajit") then add_requires("luajit") else add_requires("lua") end ``` We can switch dependencies by `$xmake f --luajit=y`. And we also added the group parameter to group the dependencies, all the dependencies under the same group, only one can be enabled, the order of the dependencies is the same as the order in which they were added by `add_requires`: ```lua add_requires("openssl", {group = "ssl", optional = true}) add_requires("mbedtls", {group = "ssl", optional = true}) target("test") add_packages("openssl", "mbedtls") ``` After version 2.2.5, xmake supports third-party package managers, such as: conan, brew, vcpkg, etc. Add a homebrew dependency package: ```lua add_requires("brew::zlib", {alias = "zlib"}}) add_requires("brew::pcre2/libpcre2-8", {alias = "pcre2"}}) target("test") set_kind("binary") add_files("src/*.c") add_packages("pcre2", "zlib") ``` Add a dependency package for vcpkg: ```lua add_requires("vcpkg::zlib", "vcpkg::pcre2") target("test") set_kind("binary") add_files("src/*.c") add_packages("vcpkg::zlib", "vcpkg::pcre2") ``` Add a conan dependency package: ```lua add_requires("CONAN::zlib/1.2.11@conan/stable", {alias = "zlib", debug = true}) add_requires("CONAN::OpenSSL/1.0.2n@conan/stable", {alias = "openssl", configs = {options = "OpenSSL:shared=True"}}) target("test") set_kind("binary") add_files("src/*.c") add_packages("openssl", "zlib") ``` After executing xmake to compile: ```console ruki:test_package ruki$ xmake checking for the architecture ... x86_64 checking for the Xcode directory ... /Applications/Xcode.app checking for the SDK version of Xcode ... 10.14 note: try installing these packages (pass -y to skip confirm)? -> CONAN::zlib/1.2.11@conan/stable (debug) -> CONAN::OpenSSL/1.0.2n@conan/stable please input: y (y/n) => installing CONAN::zlib/1.2.11@conan/stable .. ok => installing CONAN::OpenSSL/1.0.2n@conan/stable .. ok [ 0%]: ccache compiling.release src/main.c [100%]: linking.release test ``` We can see https://github.com/xmake-io/xmake/issues/339 to know more details. Add a clib dependency package: Clib is a source-based dependency package manager. The dependent package is downloaded directly to the corresponding library source code, integrated into the project to compile, rather than binary library dependencies. It is also very convenient to integrate in xmake. The only thing to note is that you need to add the source code of the corresponding library to xmake.lua, for example: ```lua add_requires("clib::clibs/bytes@0.0.4", {alias = "bytes"}) target("xmake-test") set_kind("binary") add_files("clib/bytes/*.c") add_files("src/*.c") add_packages("bytes") ``` ### add_repositories #### Add 3rd package repositories If the required package is not in the official repository [xmake-repo](https://github.com/xmake-io/xmake-repo), we can submit the contribution code to the repository for support. But if some packages are only for personal or private projects, we can create a private repository repo. The repository organization structure can be found at: [xmake-repo](https://github.com/xmake-io/xmake-repo) For example, now we have a private repository repo:`git@github.com:myrepo/xmake-repo.git` We can add through this interface: ```lua add_repositories("my-repo git@github.com:myrepo/xmake-repo.git") ``` If we just want to add one or two private packages, this time to build a git repository is too big, we can directly put the package repository into the project, for example: ``` projectdir - myrepo - packages - t/tbox/xmake.lua - z/zlib/xmake.lua - src - main.c - xmake.lua ``` The above myrepo directory is your own private package repository, built into your own project, and then add this repository location in xmake.lua: ```lua add_repositories("my-repo myrepo") ``` This can be referred to [benchbox](https://github.com/tboox/benchbox) project, which has a built-in private repository.