xmake-docs/docs/api/scripts/extension-modules/core/tool/compiler.md

core.tool.compiler

Compiler related operations, often used for plugin development.

compiler.compile

• Perform compilation

Function Prototype

::: tip API

compiler.compile(sourcefile: <string>, objectfile: <string>, depfile: <string>, opt: <table>)

:::

Parameter Description

Parameter	Description
sourcefile	Required. Source file path
objectfile	Required. Target file path
depfile	Optional. Dependency file path
opt	Optional. Option parameters, supports target

Return Value

Type	Description
boolean	Returns true on success, false on failure

Usage

For the target, link the specified object file list to generate the corresponding target file, for example:

compiler.compile("xxx.c", "xxx.o", "xxx.h.d", {target = target})

Where target is the project target, here is the specific compile option that is mainly used to get the target. For the project target object, see: core.project.project

The xxx.h.d file is used to store the header file dependency file list for this source file. Finally, these two parameters are optional. You can not pass them when compiling:

compiler.compile("xxx.c", "xxx.o")

To simply compile a source file.

compiler.compcmd

• Get the compile command line

Function Prototype

::: tip API

compiler.compcmd(sourcefile: <string>, objectfile: <string>, opt: <table>)

:::

Parameter Description

Parameter	Description
sourcefile	Required. Source file path
objectfile	Required. Target file path
opt	Optional. Option parameters, supports target and configs

Return Value

Type	Description
string	Returns compile command string

Usage

Get the command line string executed directly in compiler.compile, which is equivalent to:

local cmdstr = compiler.compcmd("xxx.c", "xxx.o", {target = target})

Note: The extension part of `target = target} is optional. If the target object is passed, the generated compile command will add the link option corresponding to this target configuration.

And you can also pass various configurations yourself, for example:

local cmdstr = compiler.compcmd("xxx.c", "xxx.o", {configs = {includedirs = "/usr/include", defines = "DEBUG"}})

With target, we can export all source file compilation commands for the specified target:

import("core.project.project")

for _, target in pairs(project.targets()) do
    for sourcekind, sourcebatch in pairs(target:sourcebatches()) do
        for index, objectfile in ipairs(sourcebatch.objectfiles) do
            local cmdstr = compiler.compcmd(sourcebatch.sourcefiles[index], objectfile, {target = target})
        end
    end
end

compiler.compargv

• Get compiled command line list

Function Prototype

::: tip API

compiler.compargv(sourcefile: <string>, objectfile: <string>, opt: <table>)

:::

Parameter Description

Parameter	Description
sourcefile	Required. Source file path
objectfile	Required. Target file path
opt	Optional. Option parameters

Return Values

Type	Description
string	Compiler program path
table	Compile arguments list

Usage

A little different from compiler.compcmd is that this interface returns a list of parameters, table representation, more convenient to operate:

local program, argv = compiler.compargv("xxx.c", "xxx.o")

compiler.compflags

• Get compilation options

Function Prototype

::: tip API

compiler.compflags(sourcefile: <string>, opt: <table>)

:::

Parameter Description

Parameter	Description
sourcefile	Required. Source file path
opt	Optional. Option parameters, supports target

Return Value

Type	Description
table	Returns compilation options list array

Usage

Get the compile option string part of compiler.compcmd without shellname and files, for example:

local flags = compiler.compflags(sourcefile, {target = target})
for _, flag in ipairs(flags) do
    print(flag)
end

The returned array of flags is an array.

compiler.has_flags

• Determine if the specified compilation option is supported

Function Prototype

::: tip API

compiler.has_flags(sourcekind: <string>, flag: <string>)

:::

Parameter Description

Parameter	Description
sourcekind	Required. Source file type, e.g., "c", "cxx"
flag	Required. Compilation option to check

Return Value

Type	Description
boolean	Returns true if supported, false otherwise

Usage

Although it can be judged by lib.detect.has_flags, but the interface is more low-level, you need to specify the compiler name. This interface only needs to specify the language type, it will automatically switch to select the currently supported compiler.

-- Determine if the c language compiler supports the option: -g
if compiler.has_flags("c", "-g") then
    -- ok
end

-- Determine if the C++ language compiler supports the option: -g
if compiler.has_flags("cxx", "-g") then
    -- ok
end

compiler.features

• Get all compiler features

Function Prototype

::: tip API

compiler.features(sourcekind: <string>, opt: <table>)

:::

Parameter Description

Parameter	Description
sourcekind	Required. Source file type, e.g., "c", "cxx"
opt	Optional. Option parameters, supports target and configs

Return Value

Type	Description
table	Returns feature list array

Usage

Although it can be obtained by lib.detect.features, but the interface is more low-level, you need to specify the compiler name. This interface only needs to specify the language type, it will automatically switch to select the currently supported compiler, and then get the current list of compiler features.

-- 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 = ".."}})

A list of all c compiler features:

Feature Name
c_static_assert
c_restrict
c_variadic_macros
c_function_prototypes

A list of all C++ compiler features:

Feature Name
cxx_variable_templates
cxx_relaxed_constexpr
cxx_aggregate_default_initializers
cxx_contextual_conversions
cxx_attribute_deprecated
cxx_decltype_auto
cxx_digit_separators
cxx_generic_lambdas
cxx_lambda_init_captures
cxx_binary_literals
cxx_return_type_deduction
cxx_decltype_incomplete_return_types
cxx_reference_qualified_functions
cxx_alignof
cxx_attributes
cxx_inheriting_constructors
cxx_thread_local
cxx_alias_templates
cxx_delegating_constructors
cxx_extended_friend_declarations
cxx_final
cxx_nonstatic_member_init
cxx_override
cxx_user_literals
cxx_constexpr
cxx_defaulted_move_initializers
cxx_enum_forward_declarations
cxx_noexcept
cxx_nullptr
cxx_range_for
cxx_unrestricted_unions
cxx_explicit_conversions
cxx_lambdas
cxx_local_type_template_args
cxx_raw_string_literals
cxx_auto_type
cxx_defaulted_functions
cxx_deleted_functions
cxx_generalized_initializers
cxx_inline_namespaces
cxx_sizeof_member
cxx_strong_enums
cxx_trailing_return_types
cxx_unicode_literals
cxx_uniform_initialization
cxx_variadic_templates
cxx_decltype
cxx_default_function_template_args
cxx_long_long_type
cxx_right_angle_brackets
cxx_rvalue_references
cxx_static_assert
cxx_extern_templates
cxx_func_identifier
cxx_variadic_macros
cxx_template_template_parameters

compiler.has_features

• Determine if the specified compiler feature is supported

Function Prototype

::: tip API

compiler.has_features(features: <string|table>, opt: <table>)

:::

Parameter Description

Parameter	Description
features	Required. Feature name or feature name list
opt	Optional. Option parameters, supports languages, target, configs

Return Value

Type	Description
boolean	Returns true if supported, false otherwise

Usage

Although it can be obtained by lib.detect.has_features, but the interface is more low-level, you need to specify the compiler name. And this interface only needs to specify the special name list that needs to be detected, it can automatically switch to select the currently supported compiler, and then determine whether the specified feature is supported in the current compiler.

if compiler.has_features("c_static_assert") then
    -- ok
end

if compiler.has_features({"c_static_assert", "cxx_constexpr"}, {languages = "cxx11"}) then
    -- ok
end

if compiler.has_features("cxx_constexpr", {target = target, defines = "..", includedirs = ".."}) then
    -- ok
end

For specific feature names, refer to compiler.features.