xmake
/
xmake-docs
mirror of https://github.com/xmake-io/xmake-docs


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199
							<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>xmake</title>
  <link rel="icon" href="/assets/img/favicon.ico">
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
  <meta name="description" content="Description">
  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
  <link href="/assets/npm/github-markdown/github-markdown.min.css" rel="stylesheet">
  <style>
	.markdown-body {
		box-sizing: border-box;
		min-width: 200px;
		max-width: 980px;
		margin: 0 auto;
		padding: 45px;
	}

	@media (max-width: 767px) {
		.markdown-body {
			padding: 15px;
		}
	}
  </style>
</head>
<body>
<article class="markdown-body">
<h4>This is a mirror page, please see the original page: </h4><a href="https://xmake.io/#/manual/builtin_modules">https://xmake.io/#/manual/builtin_modules</a>
<div id="wwads-panel" class="wwads-cn wwads-vertical wwads-sticky" data-id="239" style="max-width:180px;bottom:20px;right:20px;width:200px;height:260px;background:#fff;position:fixed"></div>
</br>
    <script type="text/javascript" charset="UTF-8" src="https://cdn.wwads.cn/js/makemoney.js" async></script>
<script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?serve=CE7I52QU&placement=xmakeio" id="_carbonads_js"></script>
<style>
#carbonads {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu,
  Cantarell, "Helvetica Neue", Helvetica, Arial, sans-serif;
}

#carbonads {
  display: flex;
  max-width: 330px;
  background-color: hsl(0, 0%, 98%);
  box-shadow: 0 1px 4px 1px hsla(0, 0%, 0%, .1);
}

#carbonads a {
  color: inherit;
  text-decoration: none;
}

#carbonads a:hover {
  color: inherit;
}

#carbonads span {
  position: relative;
  display: block;
  overflow: hidden;
}

#carbonads .carbon-wrap {
  display: flex;
}

.carbon-img {
  display: block;
  margin: 0;
  line-height: 1;
}

.carbon-img img {
  display: block;
}

.carbon-text {
  font-size: 13px;
  padding: 10px;
  line-height: 1.5;
  text-align: left;
}

.carbon-poweredby {
  display: block;
  padding: 8px 10px;
  background: repeating-linear-gradient(-45deg, transparent, transparent 5px, hsla(0, 0%, 0%, .025) 5px, hsla(0, 0%, 0%, .025) 10px) hsla(203, 11%, 95%, .4);
  text-align: center;
  text-transform: uppercase;
  letter-spacing: .5px;
  font-weight: 600;
  font-size: 9px;
  line-height: 1;
}
</style>
    <p>Used in script code such as custom scripts, plug-in scripts, task scripts, platform extensions, template extensions, etc., that is, in code blocks like the following, you can use these module interfaces:</p>
<pre><code class="lang-lua">on_run(function (target)
    print("hello xmake!")
end)
</code></pre>
<p>!> In order to ensure that the description scope of the outer layer is as simple and secure as possible, it is generally not recommended to use the interface and module operation api in this domain. Therefore, most module interfaces can only be used in the script domain to implement complex functions. </br><br>Of course, a small number of read-only built-in interfaces can still be used in the description scope, as shown in the following table:</p>
<p>An example of using an interface call in a description scope is as follows, generally only for conditional control:</p>
<pre><code class="lang-lua">-- Scan all subdirectories under the current xmake.lua directory, defining a task task with the name of each directory
for _, taskname in ipairs(os.dirs("*"), path.basename) do
    task(taskname)
        on_run(function ()
        end)
end
</code></pre>
<p>The script scope and description scope mentioned above mainly refer to:</p>
<pre><code class="lang-lua">-- description scope
target("test")

    -- description scope
    set_kind("static")
    add_files("src/*.c")

    on_run(function (target)
        -- Script domain
    end)

-- description scope
</code></pre>
<h3 id="import">import</h3>
<h4 id="importingextensionblocks">Importing extension blocks</h4>
<p>Import is mainly used to import xmake&#39;s extension class library and some custom class library modules, generally used to:</p>
<ul>
<li>Custom script (<a href="/mirror/manual/project_target.html#targeton_build">on_build</a>, <a href="/mirror/manual/project_target.html#targeton_run">on_run</a> ..)</li>
<li>Plugin development</li>
<li>Template development</li>
<li>Platform extension</li>
<li>Custom task task</li>
</ul>
<p>The import mechanism is as follows:</p>
<ol>
<li>Import from the current script directory first</li>
<li>Import from the extended class library</li>
</ol>
<p>Imported grammar rules:</p>
<p>Class library path rules based on <code>.</code>, for example:</p>
<p>Import core core extension module</p>
<pre><code class="lang-lua">import("core.base.option")
import("core.base.task")

function main()

    -- Get parameter options
    print(option.get("version"))

    -- Run tasks and plugins
    task.run("hello")
end
</code></pre>
<p>Import the custom module in the current directory:</p>
<p>Directory Structure:</p>
<pre><code>Plugin
  - xmake.lua
  - main.lua
  - modules
    - hello1.lua
    - hello2.lua
</code></pre><p>Import modules in main.lua</p>
<pre><code class="lang-lua">import("modules.hello1")
import("modules.hello2")
</code></pre>
<p>After importing, you can directly use all the public interfaces inside. The private interface is marked with the <code>_</code> prefix, indicating that it will not be exported and will not be called externally. .</p>
<p>In addition to the current directory, we can also import libraries in other specified directories, for example:</p>
<pre><code class="lang-lua">import("hello3", {rootdir = "/home/xxx/modules"})
</code></pre>
<p>To prevent naming conflicts, you can also specify an alias after import:</p>
<pre><code class="lang-lua">import("core.platform.platform", {alias = "p"})

function main()

    -- So we can use p to call the plats interface of the platform module to get a list of all the platforms supported by xmake.
    utils.dump(p.plats())
end
</code></pre>
<p>Import can not only import the class library, but also import and import as inheritance, realize the inheritance relationship between modules.</p>
<pre><code class="lang-lua">import("xxx.xxx", {inherit = true})
</code></pre>
<p>This is not a reference to the module, but all the public interfaces of the module imported, so that it will be merged with the interface of the current module to achieve inheritance between modules.</p>
<p>Version 2.1.5 adds two new properties: `import("xxx.xxx", {try = true, anonymous = true}).</p>
<p>If the try is true, the imported module does not exist, only return nil, and will not interrupt xmake after throwing an exception.<br>If anonymous is true, the imported module will not introduce the current scope, only the imported object reference will be returned in the import interface.</p>
<h4 id="customextensionmodule">Custom extension module</h4>
<p>Through import, we can import not only many built-in extension modules of xmake, but also user-defined extension modules.</p>
<p>Just put your own module in the project directory and import it according to the import method described above.</p>
<p>So, what if you want to define a module? xmake has a set of convention rules for module writing specifications, and does not follow Lua&#39;s native require import mechanism, and there is no need to use return in the module to return it globally.</p>
<p>If we have a module file foo.lua, its content is as follows:</p>
<pre><code class="lang-lua">function _foo(a, b)
    return a + b
end

function add(a, b)
    _foo(a, b)
end

function main(a, b)
    add(a, b)
end
</code></pre>
<p>Among them main is the entry function, optional, if set, the module foo can be called directly, for example:</p>
<pre><code class="lang-lua">import("foo")
foo(1, 2)
</code></pre>
<p>Or directly like this:</p>
<pre><code class="lang-lua">import("foo")(1, 2)
</code></pre>
<p>Others without underscore are public module interface functions, such as add.</p>
<pre><code class="lang-lua">import("foo")
foo.add(1, 2)
</code></pre>
<p>The underscore prefixed <code>_foo</code> is a private function that is used internally by the module and is not exported, so users cannot call it outside.</p>
<h3 id="inherit">inherit</h3>
<h4 id="importandinheritbaseclassmodules">Import and inherit base class modules</h4>
<p>This is equivalent to the <code>inherit</code> mode of the <a href="#import">import</a> interface, which is:</p>
<pre><code class="lang-lua">import("xxx.xxx", {inherit = true})
</code></pre>
<p>With the <code>inherit</code> interface, it will be more concise:</p>
<pre><code class="lang-lu">Inherit("xxx.xxx")
</code></pre>
<p>For an example, see the script in the xmake tools directory: <a href="#https://github.com/xmake-io/xmake/blob/master/xmake/tools/clang.lua">clang.lua</a></p>
<p>This is part of the clang tool module that inherits gcc.</p>
<h3 id="trycatchfinally">try-catch-finally</h3>
<h4 id="exceptioncapture">Exception capture</h4>
<p>Lua native does not provide try-catch syntax to catch exception handling, but provides interfaces such as <code>pcall/xpcall</code> to execute lua functions in protected mode.</p>
<p>Therefore, the capture mechanism of the try-catch block can be implemented by encapsulating these two interfaces.</p>
<p>We can look at the packaged try-catch usage first:</p>
<pre><code class="lang-lua">try
{
    -- try code block
    function ()
        error("error message")
    end,

    -- catch code block
    catch
    {
        -- After an exception occurs, it is executed
        function (errors)
            print(errors)
        end
    }
}
</code></pre>
<p>In the above code, an exception is thrown inside the try block, and an error message is thrown, caught in the catch, and the error message is output.</p>
<p>And finally processing, this role is for the <code>try{}</code> code block, regardless of whether the execution is successful, will be executed into the finally block</p>
<p>In other words, in fact, the above implementation, the complete support syntax is: <code>try-catch-finally</code> mode, where catch and finally are optional, according to their actual needs.</p>
<p>E.g:</p>
<pre><code class="lang-lua">try
{
    -- try code block
    function ()
        error("error message")
    end,

    -- catch code block
    catch
    {
        -- After an exception occurs, it is executed
        function (errors)
            print(errors)
        end
    },

    -- finally block
    finally
    {
        -- Finally will be executed here
        function (ok, errors)
            -- If there is an exception in try{}, ok is true, errors is the error message, otherwise it is false, and error is the return value in try
        end
    }
}

</code></pre>
<p>Or only the finally block:</p>
<pre><code class="lang-lua">try
{
    -- try code block
    function ()
        return "info"
    end,

    -- finally block
    finally
    {
        -- Since there is no exception in this try code, ok is true and errors is the return value: "info"
        function (ok, errors)
        end
    }
}
</code></pre>
<p>Processing can get the normal return value in try in finally, in fact, in the case of only try, you can also get the return value:</p>
<pre><code class="lang-lua">-- If no exception occurs, result is the return value: "xxxx", otherwise nil
local result = try
{
    function ()
        return "xxxx"
    end
}
</code></pre>
<p>In xmake&#39;s custom scripting and plugin development, it is also based entirely on this exception catching mechanism.</p>
<p>This makes the development of the extended script very succinct and readable, eliminating the cumbersome <code>if err ~= nil then</code> return value judgment. When an error occurs, xmake will directly throw an exception to interrupt, and then highlight the detailed error. information.</p>
<p>E.g:</p>
<pre><code class="lang-lua">target("test")
    set_kind("binary")
    add_files("src/*.c")

    -- After the ios program is compiled, the target program is ldid signed
    after_build(function (target))
        os.run("ldid -S %s", target:targetfile())
    end
</code></pre>
<p>Only one line <code>os.run</code> is needed, and there is no need to return a value to determine whether it runs successfully. After the operation fails, xmake will automatically throw an exception, interrupt the program and prompt the error.</p>
<p>If you want to run xmake without running interrupts directly after running, you can do it yourself.Add a try and you will be fine:</p>
<pre><code class="lang-lua">target("test")
    set_kind("binary")
    add_files("src/*.c")

    after_build(function (target))
        try
        {
            function ()
                os.run("ldid -S %s", target:targetfile())
            end
        }
    end
</code></pre>
<p>If you want to capture the error message, you can add a catch:</p>
<pre><code class="lang-lua">target("test")
    set_kind("binary")
    add_files("src/*.c")

    after_build(function (target))
        try
        {
            function ()
                os.run("ldid -S %s", target:targetfile())
            end,
            catch
            {
                function (errors)
                    print(errors)
                end
            }
        }
    end
</code></pre>
<p>However, in general, write custom scripts in xmake, do not need to manually add try-catch, directly call a variety of api, after the error, let xmake default handler to take over, directly interrupted. .</p>
<h3 id="pairs">pairs</h3>
<h4 id="usedtotraversethedictionary">Used to traverse the dictionary</h4>
<p>This is lua&#39;s native built-in api. In xmake, it has been extended in its original behavior to simplify some of the daily lua traversal code.</p>
<p>First look at the default native notation:</p>
<pre><code class="lang-lua">local t = {a = "a", b = "b", c = "c", d = "d", e = "e", f = "f"}

for key, val in pairs(t) do
    print("%s: %s", key, val)
end
</code></pre>
<p>This is sufficient for normal traversal operations, but if we get the uppercase for each of the elements it traverses, we can write:</p>
<pre><code class="lang-lua">for key, val in pairs(t, function (v) return v:upper() end) do
     print("%s: %s", key, val)
end
</code></pre>
<p>Even pass in some parameters to the second <code>function</code>, for example:</p>
<pre><code class="lang-lua">for key, val in pairs(t, function (v, a, b) return v:upper() .. a .. b end, "a", "b") do
     print("%s: %s", key, val)
end
</code></pre>
<h3 id="ipairs">ipairs</h3>
<h4 id="fortraversingarrays">for traversing arrays</h4>
<p>This is lua&#39;s native built-in api. In xmake, it has been extended in its original behavior to simplify some of the daily lua traversal code.</p>
<p>First look at the default native notation:</p>
<pre><code class="lang-lua">for idx, val in ipairs({"a", "b", "c", "d", "e", "f"}) do
     print("%d %s", idx, val)
end
</code></pre>
<p>The extension is written like the <a href="#pairs">pairs</a> interface, for example:</p>
<pre><code class="lang-lua">for idx, val in ipairs({"a", "b", "c", "d", "e", "f"}, function (v) return v:upper() end) do
     print("%d %s", idx, val)
end

for idx, val in ipairs({"a", "b", "c", "d", "e", "f"}, function (v, a, b) return v:upper() .. a .. b end, "a", "b") do
     print("%d %s", idx, val)
end
</code></pre>
<p>This simplifies the logic of the <code>for</code> block code. For example, if I want to traverse the specified directory and get the file name, but not including the path, I can simplify the writing by this extension:</p>
<pre><code class="lang-lua">for _, filename in ipairs(os.dirs("*"), path.filename) do
    -- ...
end
</code></pre>
<h3 id="print">print</h3>
<h4 id="wrappingprintterminallog">Wrapping print terminal log</h4>
<p>This interface is also the native interface of lua. xmake is also extended based on the original behavior, and supports: formatted output, multivariable output.</p>
<p>First look at the way native support:</p>
<pre><code class="lang-lua">print("hello xmake!")
print("hello", "xmake!", 123)
</code></pre>
<p>And also supports extended formatting:</p>
<pre><code class="lang-lua">print("hello %s!", "xmake")
print("hello xmake! %d", 123)
</code></pre>
<p>Xmake will support both types of writing at the same time, and the internal will automatically detect and select the output behavior.</p>
<h3 id="printf">printf</h3>
<h4 id="nolineprintingterminallog">No line printing terminal log</h4>
<p>Like the <a href="#print">print</a> interface, the only difference is that it doesn&#39;t wrap.</p>
<h3 id="cprint">cprint</h3>
<h4 id="wrapcolorprintterminallog">Wrap color print terminal log</h4>
<p>The behavior is similar to <a href="#print">print</a>, the difference is that this interface also supports color terminal output, and supports <code>emoji</code> character output.</p>
<p>E.g:</p>
<pre><code class="lang-lua">    cprint(&#39;${bright}hello xmake&#39;)
    cprint(&#39;${red}hello xmake&#39;)
    cprint(&#39;${bright green}hello ${clear}xmake&#39;)
    cprint(&#39;${blue onyellow underline}hello xmake${clear}&#39;)
    cprint(&#39;${red}hello ${magenta}xmake&#39;)
    cprint(&#39;${cyan}hello ${dim yellow}xmake&#39;)
</code></pre>
<p>The results are as follows:</p>
<p><img src="https://tboox.org/static/img/xmake/cprint_colors.png" alt="cprint_colors"></p>
<p>The color-related descriptions are placed in <code>${ }</code>, and you can set several different properties at the same time, for example:</p>
<pre><code>    ${bright red underline onyellow}
</code></pre><p>Indicates: highlighted red, background yellow, and with a down line</p>
<p>All of these descriptions will affect the entire entire line of characters. If you only want to display partial color text, you can insert <code>${clear}</code> at the end position to clear the previous color description.</p>
<p>E.g:</p>
<pre><code>    ${red}hello ${clear}xmake
</code></pre><p>In this case, only hello is displayed in red, and the others are still normal black display.</p>
<p>Other colors belong to, I will not introduce them here, directly paste the list of attributes in the xmake code:</p>
<pre><code class="lang-lua">    colors.keys =
    {
        -- Attributes
        reset = 0 -- reset attribute
    , clear = 0 -- clear attribute
    , default = 0 -- default property
    , bright = 1 -- highlight
    , dim = 2 -- dark
    , underline = 4 -- underline
    , blink = 5 -- flashing
    , reverse = 7 -- reverse color
    , hidden = 8 -- hidden text

        -- Foreground
    , black = 30
    , red = 31
    , green = 32
    , yellow = 33
    , blue = 34
    , magenta = 35
    , cyan = 36
    , white = 37

        -- Background color
    , onblack = 40
    , onred = 41
    , ongreen = 42
    , onyellow = 43
    , onblue = 44
    , onmagenta = 45
    , oncyan = 46
    , onwhite = 47
</code></pre>
<p>In addition to color highlighting, if your terminal is under macosx, lion above the system, xmake can also support the display of emoji expressions, for systems that do not support<br>Ignore the display, for example:</p>
<pre><code class="lang-lua">    cprint("hello xmake${beer}")
    cprint("hello${ok_hand} xmake")
</code></pre>
<p>The above two lines of code, I printed a classic beer symbol in the homebrew, the following line printed an ok gesture symbol, is not very dazzling. .</p>
<p><img src="https://tboox.org/static/img/xmake/cprint_emoji.png" alt="cprint_emoji"></p>
<p>All emoji emoticons, as well as the corresponding keys in xmake, can be found in <a href="http://www.emoji-cheat-sheet.com/">emoji</a>. .</p>
<p>Version 2.1.7 supports 24-bit true color output, if the terminal supports it:</p>
<pre><code class="lang-lua">import("core.base.colors")
if colors.truecolor() then
    cprint("${255;0;0}hello")
    cprint("${on;255;0;0}hello${clear} xmake")
    cprint("${bright 255;0;0 underline}hello")
    cprint("${bright on;255;0;0 0;255;0}hello${clear} xmake")
end
</code></pre>
<p>Xmake&#39;s detection support for truecolor is implemented by the <code>$COLORTERM</code> environment variable. If your terminal supports truecolor, you can manually set this environment variable to tell xmake to enable truecolor support.</p>
<p>It can be enabled and tested with the following command:</p>
<pre><code class="lang-bash">$ export COLORTERM=truecolor
$ xmake --version
</code></pre>
<p>The 2.1.7 version can disable color output with <code>COLORTERM=nocolor</code>.</p>
<h3 id="cprintf">cprintf</h3>
<h4 id="nolinefeedcolorprintterminallog">No line feed color print terminal log</h4>
<p>This interface is similar to <a href="#cprint">cprint</a>, the difference is that it does not wrap the output.</p>
<h3 id="format">format</h3>
<h4 id="formattingastring">Formatting a string</h4>
<p>If you just want to format the string and don&#39;t output it, you can use this interface. This interface is equivalent to the <a href="#stringformat">string.format</a> interface, just a simplified version of the interface name.</p>
<pre><code class="lang-lua">local s = format("hello %s", xmake)
</code></pre>
<h3 id="vformat">vformat</h3>
<h4 id="formattingstringssupportforbuiltinvariableescaping">Formatting strings, support for built-in variable escaping</h4>
<p>This interface is followed by <a href="The #format">format</a> interface is similar, but adds support for the acquisition and escaping of built-in variables.</p>
<pre><code class="lang-lua">local s = vformat("hello %s $(mode) $(arch) $(env PATH)", xmake)
</code></pre>
<h3 id="raise">raise</h3>
<h4 id="throwinganabortprogram">Throwing an abort program</h4>
<p>If you want to interrupt xmake running in custom scripts and plug-in tasks, you can use this interface to throw an exception. If the upper layer does not show the call to <a href="#try-catch-finally">try-catch</a>, xmake will be executed. An error message is displayed.</p>
<pre><code class="lang-lua">if (errors) raise(errors)
</code></pre>
<p>If an exception is thrown in the try block, the error information is captured in catch and finally. See: <a href="#try-catch-finally">try-catch</a></p>
<h3 id="os">os</h3>
<p>The system operation module belongs to the built-in module. It can be called directly by the script scope without using <a href="#import">import</a> import.</p>
<p>This module is also a native module of lua, and xmake has been extended to provide more practical interfaces.</p>
<p>!> Only some readonly interfaces (for example: <code>os.getenv</code>, <code>os.arch</code>) in the os module can be used in the description scope. Other interfaces can only be used in the script domain, for example: <code>os.cp</code>, <code>os .rm</code>etc.</p>
<table>
<thead>
<tr>
<th>Interface</th>
<th>Description</th>
<th>Supported Versions</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#oscp">os.cp</a></td>
<td>Copy files or directories</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osmv">os.mv</a></td>
<td>Move Renamed File or Directory</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osrm">os.rm</a></td>
<td>Delete files or directory tree</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#ostrycp">os.trycp</a></td>
<td>Try copying files or directories</td>
<td>>= 2.1.6</td>
</tr>
<tr>
<td><a href="#ostrymv">os.trymv</a></td>
<td>Try moving the renamed file or directory</td>
<td>>= 2.1.6</td>
</tr>
<tr>
<td><a href="#ostryrm">os.tryrm</a></td>
<td>Try deleting a file or directory tree</td>
<td>>= 2.1.6</td>
</tr>
<tr>
<td><a href="#oscd">os.cd</a></td>
<td>Go to the specified directory</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osrmdir">os.rmdir</a></td>
<td>Delete Directory Tree</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osmkdir">os.mkdir</a></td>
<td>Create the specified directory</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osisdir">os.isdir</a></td>
<td>Determine if the directory exists</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osisfile">os.isfile</a></td>
<td>Determine if the file exists</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osexists">os.exists</a></td>
<td>Determine if a file or directory exists</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osdirs">os.dirs</a></td>
<td>Traversing to get all directories under the specified directory</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osfiles">os.files</a></td>
<td>Traversing to get all the files in the specified directory</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osfiledirs">os.filedirs</a></td>
<td>Traversing to get all files or directories under the specified directory</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osexit">os.exit</a></td>
<td>Exit the program</td>
<td>>= 2.3.1</td>
</tr>
<tr>
<td><a href="#osisexec">os.isexec</a></td>
<td>Test if a file is executable</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osrun">os.run</a></td>
<td>Quiet running program</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osrunv">os.runv</a></td>
<td>Quiet running program with parameter list</td>
<td>>= 2.1.5</td>
</tr>
<tr>
<td><a href="#osexec">os.exec</a></td>
<td>Evoke Run Program</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osexecv">os.execv</a></td>
<td>Echo running program with parameter list</td>
<td>>= 2.1.5</td>
</tr>
<tr>
<td><a href="#osiorun">os.iorun</a></td>
<td>Run and get the program output</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osiorunv">os.iorunv</a></td>
<td>Run and get the program output with parameter list</td>
<td>>= 2.1.5</td>
</tr>
<tr>
<td><a href="#ostmpdir">os.tmpdir</a></td>
<td>Get Temp directory path</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#ostmpfile">os.tmpfile</a></td>
<td>Get Temporary File Path</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#oscurdir">os.curdir</a></td>
<td>Get current directory path</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osfilesize">os.filesize</a></td>
<td>Get File Size</td>
<td>>= 2.1.9</td>
</tr>
<tr>
<td><a href="#osscriptdir">os.scriptdir</a></td>
<td>Get script directory path</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osprogramdir">os.programdir</a></td>
<td>Get xmake install main program script directory</td>
<td>>= 2.1.5</td>
</tr>
<tr>
<td><a href="#osprogramfile">os.programfile</a></td>
<td>Get the path of the xmake executable</td>
<td>>= 2.1.5</td>
</tr>
<tr>
<td><a href="#osprojectdir">os.projectdir</a></td>
<td>Get Project Home</td>
<td>>= 2.1.5</td>
</tr>
<tr>
<td><a href="#osarch">os.arch</a></td>
<td>Get Current System Architecture</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#oshost">os.host</a></td>
<td>Get Current Host System</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#ossubhost">os.subhost</a></td>
<td>Get Subsystem host, e.g. msys, cygwin on windows</td>
<td>>= 2.3.1</td>
</tr>
<tr>
<td><a href="#ossubarch">os.subarch</a></td>
<td>Get Subsystem host architecture</td>
<td>>= 2.3.1</td>
</tr>
<tr>
<td><a href="#osis_host">os.is_host</a></td>
<td>Test if a given host is the current</td>
<td>>= 2.3.1</td>
</tr>
<tr>
<td><a href="#osis_arch">os.is_arch</a></td>
<td>Test if a given arch is the current</td>
<td>>= 2.3.1</td>
</tr>
<tr>
<td><a href="#osis_subhost">os.is_subhost</a></td>
<td>Test if a given sub host is the current</td>
<td>>= 2.3.1</td>
</tr>
<tr>
<td><a href="#osis_subarch">os.is_subarch</a></td>
<td>Test if a given sub arch is the current</td>
<td>>= 2.3.1</td>
</tr>
<tr>
<td><a href="#osln">os.ln</a></td>
<td>Link file or directory to the new symfile</td>
<td>>= 2.2.2</td>
</tr>
<tr>
<td><a href="#osreadlink">os.readlink</a></td>
<td>Read the content of a symlink</td>
<td>>= 2.2.2</td>
</tr>
<tr>
<td><a href="#osraise">os.raise</a></td>
<td>Raise an exception and abort the current script</td>
<td>>= 2.2.8</td>
</tr>
<tr>
<td><a href="#raiselevel">os.raiselevel</a></td>
<td>Raise an exception and abort the current script</td>
<td>>= 2.2.8</td>
</tr>
<tr>
<td><a href="#osfeatures">os.features</a></td>
<td>Get features</td>
<td>>= 2.3.1</td>
</tr>
<tr>
<td><a href="#osgetenvs">os.getenvs</a></td>
<td>Get all current environment variables</td>
<td>>= 2.2.6</td>
</tr>
<tr>
<td><a href="#ossetenvs">os.setenvs</a></td>
<td>Set environment variables</td>
<td>>= 2.2.6</td>
</tr>
<tr>
<td><a href="#osaddenvs">os.addenvs</a></td>
<td>Add environment variables to current envs</td>
<td>>= 2.5.6</td>
</tr>
<tr>
<td><a href="#osjoinenvs">os.joinenvs</a></td>
<td>Join environment variables</td>
<td>>= 2.5.6</td>
</tr>
<tr>
<td><a href="#osgetenv">os.getenv</a></td>
<td>Get Environment Variables</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#ossetenv">os.setenv</a></td>
<td>Setting environment variables</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#osaddenv">os.addenv</a></td>
<td>Add values to one environment variable</td>
<td>>= 2.1.5</td>
</tr>
<tr>
<td><a href="#ossetenvp">os.setenvp</a></td>
<td>Setting environment variables with a given separator</td>
<td>>= 2.1.5</td>
</tr>
<tr>
<td><a href="#osaddenvp">os.addenvp</a></td>
<td>Add values to one environment variable with a given separator</td>
<td>>= 2.1.5</td>
</tr>
<tr>
<td><a href="#osworkingdir">os.workingdir</a></td>
<td>Get the working directory</td>
<td>>= 2.1.9</td>
</tr>
<tr>
<td><a href="#osisroot">os.isroot</a></td>
<td>Test if xmake is running as root</td>
<td>>= 2.1.9</td>
</tr>
<tr>
<td><a href="#osfscase">os.fscase</a></td>
<td>Test if the os has a case sensitive filesystem</td>
<td>>= 2.1.9</td>
</tr>
<tr>
<td><a href="#osterm">os.term</a></td>
<td>Get current terminal</td>
<td>>= 2.7.3</td>
</tr>
<tr>
<td><a href="#osshell">os.shell</a></td>
<td>Get current shell</td>
<td>>= 2.7.3</td>
</tr>
<tr>
<td><a href="#oscpuinfo">os.cpuinfo</a></td>
<td>Get cpu information</td>
<td>>= 2.1.5</td>
</tr>
<tr>
<td><a href="#osmeminfo">os.meminfo</a></td>
<td>Get memory information</td>
<td>>= 2.1.5</td>
</tr>
<tr>
<td><a href="#osdefault_njob">os.default_njob</a></td>
<td>Get default paralled jobs</td>
<td>>= 2.5.8</td>
</tr>
</tbody>
</table>
<h4 id="oscp">os.cp</h4>
<ul>
<li>Copy files or directories</li>
</ul>
<p>The behavior is similar to the <code>cp</code> command in the shell, supporting path wildcard matching (using lua pattern matching), support for multi-file copying, and built-in variable support.</p>
<p>e.g:</p>
<pre><code class="lang-lua">os.cp("$(scriptdir)/*.h", "$(buildir)/inc")
os.cp("$(projectdir)/src/test/**.h", "$(buildir)/inc")
</code></pre>
<p>The above code will copy all the header files in the current <code>xmake.lua</code> directory, the header files in the project source test directory to the <code>$(buildir)</code> output directory.</p>
<p>Among them <code>$(scriptdir)</code>, <code>$(projectdir)</code> These variables are built-in variables of xmake. For details, see the related documentation of <a href="#built-in variables">built-in variables</a>.</p>
<p>The matching patterns in <code>*.h</code> and <code>**.h</code> are similar to those in <a href="#targetadd_files">add_files</a>, the former is a single-level directory matching, and the latter is a recursive multi-level directory matching.</p>
<p>This interface also supports `recursive replication&#39; of directories, for example:</p>
<pre><code class="lang-lua">-- Recursively copy the current directory to a temporary directory
os.cp("$(curdir)/test/", "$(tmpdir)/test")
</code></pre>
<p>The copy at the top will expand and copy all files to the specified directory, and lose the source directory hierarchy. If you want to copy according to the directory structure that maintains it, you can set the rootdir parameter:</p>
<pre><code class="lang-lua">os.cp ("src/**.h", "/tmp/", {rootdir="src"})
</code></pre>
<p>The above script can press the root directory of <code>src</code> to copy all sub-files under src in the same directory structure.</p>
<p>!> Try to use the <code>os.cp</code> interface instead of <code>os.run("cp ..")</code>, which will ensure platform consistency and cross-platform build description.</p>
<p>Under 2.5.7, the parameter <code>{symlink = true}</code> is added to keep the symbolic link when copying files.</p>
<pre><code class="lang-lua">os.cp("/xxx/foo", "/xxx/bar", {symlink = true})
</code></pre>
<h4 id="osmv">os.mv</h4>
<ul>
<li>Move to rename a file or directory</li>
</ul>
<p>Similar to the use of <a href="#oscp">os.cp</a>, it also supports multi-file move operations and pattern matching, for example:</p>
<pre><code class="lang-lua">-- Move multiple files to a temporary directory
os.mv("$(buildir)/test1", "$(tmpdir)")

-- File movement does not support bulk operations, which is file renaming
os.mv("$(buildir)/libtest.a", "$(buildir)/libdemo.a")
</code></pre>
<h4 id="osrm">os.rm</h4>
<ul>
<li>Delete files or directory trees</li>
</ul>
<p>Support for recursive deletion of directories, bulk delete operations, and pattern matching and built-in variables, such as:</p>
<pre><code class="lang-lua">os.rm("$(buildir)/inc/**.h")
os.rm("$(buildir)/lib/")
</code></pre>
<h4 id="ostrycp">os.trycp</h4>
<ul>
<li>Try copying files or directories</li>
</ul>
<p>Similar to <a href="#oscp">os.cp</a>, the only difference is that this interface operation will not throw an exception interrupt xmake, but the return value indicates whether the execution is successful.</p>
<pre><code class="lang-lua">if os.trycp("file", "dest/file") then
end
</code></pre>
<h4 id="ostrymv">os.trymv</h4>
<ul>
<li>Try moving a file or directory</li>
</ul>
<p>Similar to <a href="#osmv">os.mv</a>, the only difference is that this interface operation will not throw an exception interrupt xmake, but the return value indicates whether the execution is successful.</p>
<pre><code class="lang-lua">if os.trymv("file", "dest/file") then
end
</code></pre>
<h4 id="ostryrm">os.tryrm</h4>
<ul>
<li>Try deleting files or directories</li>
</ul>
<p>Similar to <a href="#osrm">os.rm</a>, the only difference is that this interface operation will not throw an exception interrupt xmake, but the return value indicates whether the execution is successful.</p>
<pre><code class="lang-lua">if os.tryrm("file") then
end
</code></pre>
<h4 id="oscd">os.cd</h4>
<ul>
<li>Enter the specified directory</li>
</ul>
<p>This operation is used for directory switching and also supports built-in variables, but does not support pattern matching and multi-directory processing, for example:</p>
<pre><code class="lang-lua">-- Enter the temporary directory
os.cd("$(tmpdir)")
</code></pre>
<p>If you want to leave the previous directory, there are several ways:</p>
<pre><code class="lang-lua">-- Enter the parent directory
os.cd("..")

-- Enter the previous directory, equivalent to: cd -
os.cd("-")

-- Save the previous directory before entering the directory, then use it to cut back directly after the level
local oldir = os.cd("./src")
...
os.cd(oldir)
</code></pre>
<h4 id="osrmdir">os.rmdir</h4>
<ul>
<li>delete only the directory</li>
</ul>
<p>If it is not a directory, it cannot be deleted.</p>
<h4 id="osmkdir">os.mkdir</h4>
<ul>
<li>Create a directory</li>
</ul>
<p>Support for batch creation and built-in variables, such as:</p>
<pre><code class="lang-lua">os.mkdir("$(tmpdir)/test", "$(buildir)/inc")
</code></pre>
<h4 id="osisdir">os.isdir</h4>
<ul>
<li>Determine if it is a directory</li>
</ul>
<p>Return false if the directory does not exist</p>
<pre><code class="lang-lua">if os.isdir("src") then
    -- ...
end
</code></pre>
<h4 id="osisfile">os.isfile</h4>
<ul>
<li>Determine if it is a file</li>
</ul>
<p>Return false if the file does not exist</p>
<pre><code class="lang-lua">if os.isfile("$(buildir)/libxxx.a") then
    -- ...
end
</code></pre>
<h4 id="osexists">os.exists</h4>
<ul>
<li>Determine if a file or directory exists</li>
</ul>
<p>Return false if the file or directory does not exist</p>
<pre><code class="lang-lua">-- Judging the existence of the directory
if os.exists("$(buildir)") then
    -- ...
end

-- Judging the existence of the file
if os.exists("$(buildir)/libxxx.a") then
    -- ...
end
</code></pre>
<h4 id="osdirs">os.dirs</h4>
<ul>
<li>Traverse to get all the directories under the specified directory</li>
</ul>
<p>Supports pattern matching in <a href="#targetadd_files">add_files</a>, supports recursive and non-recursive mode traversal, and returns a table array. If not, returns an empty array, for example:</p>
<pre><code class="lang-lua">-- Recursive traversal to get all subdirectories
for _, dir in ipairs(os.dirs("$(buildir)/inc/**")) do
    print(dir)
end
</code></pre>
<h4 id="osfiles">os.files</h4>
<ul>
<li>Traverse to get all the files in the specified directory</li>
</ul>
<p>Supports pattern matching in <a href="#targetadd_files">add_files</a>, supports recursive and non-recursive mode traversal, and returns a table array. If not, returns an empty array, for example:</p>
<pre><code class="lang-lua">-- Non-recursive traversal to get all child files
for _, filepath in ipairs(os.files("$(buildir)/inc/*.h")) do
    print(filepath)
end
</code></pre>
<h4 id="osfiledirs">os.filedirs</h4>
<ul>
<li>Traverse to get all files and directories under the specified directory</li>
</ul>
<p>Supports pattern matching in <a href="#targetadd_files">add_files</a>, supports recursive and non-recursive mode traversal, and returns a table array. If not, returns an empty array, for example:</p>
<pre><code class="lang-lua">-- Recursive traversal to get all child files and directories
for _, filedir in ipairs(os.filedirs("$(buildir)/**")) do
    print(filedir)
end
</code></pre>
<h4 id="osexit">os.exit</h4>
<ul>
<li>Exit the program</li>
</ul>
<h4 id="osisexec">os.isexec</h4>
<ul>
<li>Test if a file is executable</li>
</ul>
<pre><code class="lang-lua">if os.isexec("path/to/file.exe") then
    os.run("path/to/file.exe")
end
</code></pre>
<h4 id="osrun">os.run</h4>
<ul>
<li>Quietly running native shell commands</li>
</ul>
<p>Used to execute third-party shell commands, but will not echo the output, only after the error, highlight the error message.</p>
<p>This interface supports parameter formatting and built-in variables such as:</p>
<pre><code class="lang-lua">-- Formatted parameters passed in
os.run("echo hello %s!", "xmake")

-- List build directory files
os.run("ls -l $(buildir)")
</code></pre>
<p><p class="warn"><br>Using this interface to execute shell commands can easily reduce the cross-platform build. For <code>os.run("cp ..")</code>, try to use <code>os.cp</code> instead. <br><br>If you must use this interface to run the shell program, please use the <a href="#config-plat">config.plat</a> interface to determine the platform support.<br></p>

</p>
<p>For more advanced process operations and control, see the <a href="#process">process</a> module interface.</p>
<h4 id="osrunv">os.runv</h4>
<ul>
<li>Quietly running native shell commands with parameter list</li>
</ul>
<p>Similar to <a href="#osrun">os.run</a>, just the way to pass parameters is passed through the parameter list, not the string command, for example:</p>
<pre><code class="lang-lua">os.runv("echo", {"hello", "xmake!"})
</code></pre>
<h4 id="osexec">os.exec</h4>
<ul>
<li>Echo running native shell commands</li>
</ul>
<p>Similar to the <a href="#osrun">os.run</a> interface, the only difference is that when this interface executes the shell program, it has the output output, which is used in general debugging.</p>
<h4 id="osexecv">os.execv</h4>
<ul>
<li>Echo running native shell commands with parameter list</li>
</ul>
<p>Similar to <a href="#osexec">os.exec</a>, just the way to pass parameters is passed through the parameter list, not the string command, for example:</p>
<pre><code class="lang-lua">os.execv("echo", {"hello", "xmake!"})
</code></pre>
<p>In addition, this interface also supports an optional parameter for passing settings: redirect output, perform environment variable settings, for example:</p>
<pre><code class="lang-lua">os.execv("echo", {"hello", "xmake!"}, {stdout = outfile, stderr = errfile, envs = {PATH = "xxx;xx", CFLAGS = "xx"}}
</code></pre>
<p>Among them, the stdout and stderr parameters are used to pass redirected output and error output. You can directly pass in the file path or the file object opened by io.open.</p>
<p>After v2.5.1, we also support setting the stdin parameter to support redirecting input files.</p>
<p>!> stdout/stderr/stdin can simultaneously support three types of values: file path, file object, and pipe object.</p>
<p>In addition, if you want to temporarily set and rewrite some environment variables during this execution, you can pass the envs parameter. The environment variable settings inside will replace the existing settings, but will not affect the outer execution environment, only the current command.</p>
<p>We can also get all the current environment variables through the <code>os.getenvs()</code> interface, and then pass in the envs parameter after rewriting some parts.</p>
<h4 id="osiorun">os.iorun</h4>
<ul>
<li>Quietly running native shell commands and getting output</li>
</ul>
<p>Similar to the <a href="#osrun">os.run</a> interface, the only difference is that after executing the shell program, this interface will get the execution result of the shell program, which is equivalent to redirecting the output.</p>
<p>You can get the contents of <code>stdout</code>, <code>stderr</code> at the same time, for example:</p>
<pre><code class="lang-lua">local outdata, errdata = os.iorun("echo hello xmake!")
</code></pre>
<h4 id="osiorunv">os.iorunv</h4>
<ul>
<li>Run the native shell command quietly and get the output with a list of parameters</li>
</ul>
<p>Similar to <a href="#osiorun">os.iorun</a>, just the way to pass arguments is passed through the argument list, not the string command, for example:</p>
<pre><code class="lang-lua">local outdata, errdata = os.iorunv("echo", {"hello", "xmake!"})
local outdata, errdata = os.iorunv("echo", {"hello", "xmake!"}, {envs = {PATH="..."}})
</code></pre>
<h4 id="ostmpdir">os.tmpdir</h4>
<ul>
<li>Get temporary directory</li>
</ul>
<p>Consistent with the result of <a href="#var-tmpdir">$(tmpdir)</a>, it is just a direct return to return a variable that can be maintained with subsequent strings.</p>
<pre><code class="lang-lua">print(path.join(os.tmpdir(), "file.txt"))
</code></pre>
<p>Equivalent to:</p>
<pre><code class="lang-lua">print("$(tmpdir)/file.txt")
</code></pre>
<h4 id="ostmpfile">os.tmpfile</h4>
<ul>
<li>Get temporary file path</li>
</ul>
<p>Used to get a temporary file path, just a path, the file needs to be created by itself.</p>
<h4 id="oscurdir">os.curdir</h4>
<ul>
<li>Get the current directory path</li>
</ul>
<p>Consistent with the result of <a href="#var-curdir">$(curdir)</a>, it is just a direct return to return a variable that can be maintained with subsequent strings.</p>
<p>Usage reference: <a href="#ostmpdir">os.tmpdir</a>.</p>
<h4 id="osfilesize">os.filesize</h4>
<ul>
<li>Get file size</li>
</ul>
<pre><code class="lang-lua">print(os.filesize("/tmp/a"))
</code></pre>
<h4 id="osscriptdir">os.scriptdir</h4>
<ul>
<li>Get the path of the current description script</li>
</ul>
<p>Consistent with the result of <a href="#var-scriptdir">$(scriptdir)</a>, it is just a direct return to return a variable that can be maintained with subsequent strings.</p>
<p>Usage reference: <a href="#ostmpdir">os.tmpdir</a>.</p>
<h4 id="osprogramdir">os.programdir</h4>
<ul>
<li>Get the xmake installation main program script directory</li>
</ul>
<p>Consistent with the result of <a href="#var-programdir">$(programdir)</a>, it is just a direct get returned to a variable, which can be maintained with subsequent strings.</p>
<h4 id="osprogramfile">os.programfile</h4>
<ul>
<li>Get the path of the xmake executable</li>
</ul>
<h4 id="osprojectdir">os.projectdir</h4>
<ul>
<li>Get the project home directory</li>
</ul>
<p>Consistent with the result of <a href="#var-projectdir">$(projectdir)</a>, it is just a direct return to return a variable that can be maintained with subsequent strings.</p>
<h4 id="osarch">os.arch</h4>
<ul>
<li>Get current system architecture</li>
</ul>
<p>That is the default architecture of the current host system, for example, I execute xmake on <code>linux x86_64</code> to build, then the return value is: <code>x86_64</code></p>
<h4 id="oshost">os.host</h4>
<ul>
<li>Get the operating system of the current host</li>
</ul>
<p>Consistent with the result of <a href="#var-host">$(host)</a>, for example, if I execute xmake on <code>linux x86_64</code> to build, the return value is: <code>linux</code></p>
<h4 id="ossubhost">os.subhost</h4>
<ul>
<li>Get Subsystem host, e.g. msys, cygwin on windows</li>
</ul>
<h4 id="ossubarch">os.subarch</h4>
<ul>
<li>Get Subsystem host architecture</li>
</ul>
<h4 id="osis_host">os.is_host</h4>
<ul>
<li>Test if a given host is the current</li>
</ul>
<h4 id="osis_arch">os.is_arch</h4>
<ul>
<li>Test if a given arch is the current</li>
</ul>
<h4 id="osis_subhost">os.is_subhost</h4>
<ul>
<li>Test if a given sub host is the current</li>
</ul>
<h4 id="osis_subarch">os.is_subarch</h4>
<ul>
<li>Test if a given sub arch is the current</li>
</ul>
<h4 id="osln">os.ln</h4>
<ul>
<li>Create a symlink to a file or directory</li>
</ul>
<pre><code class="lang-lua">-- creates a symlink file "xxx.txt.ln" which is pointing to "xxx.txt"
os.ln("xxx.txt", "xxx.txt.ln")
</code></pre>
<h4 id="osreadlink">os.readlink</h4>
<ul>
<li>Read the content of a symlink</li>
</ul>
<h4 id="osraise">os.raise</h4>
<ul>
<li>Raise an exception and abort the current script</li>
</ul>
<pre><code class="lang-lua">-- Raise exception with message "an error occurred"
os.raise("an error occurred")
</code></pre>
<p>!> recommanded to use builtin function <code>raise</code> instead of <code>os.raise</code></p>
<h4 id="osraiselevel">os.raiselevel</h4>
<ul>
<li>Similar to <a href="#osraise">os.raise</a> but you can specify the level of the error</li>
</ul>
<pre><code class="lang-lua">-- Raise exception with message "an error occurred"
os.raiselevel(3,"an error occurred")
</code></pre>
<h4 id="osfeatures">os.features</h4>
<ul>
<li>Get features</li>
</ul>
<h4 id="osgetenvs">os.getenvs</h4>
<ul>
<li>Get all current environment variables</li>
</ul>
<pre><code class="lang-lua">local envs = os.getenvs()
--- home directory (on linux)
print(envs["HOME"])
</code></pre>
<h4 id="ossetenvs">os.setenvs</h4>
<ul>
<li>Set environment variables. Replace the current envs by a new one and return old envs</li>
</ul>
<h4 id="osaddenvs">os.addenvs</h4>
<ul>
<li>Add environment variables to current envs, return the all old envs</li>
</ul>
<pre><code class="lang-lua">os.setenvs({EXAMPLE = "a/path"}) -- add a custom variable to see addenvs impact on it

local oldenvs = os.addenvs({EXAMPLE = "some/path/"})
print(os.getenvs()["EXAMPLE"]) --got some/path/;a/path
print(oldenvs["EXAMPLE"]) -- got a/path
</code></pre>
<h4 id="osjoinenvs">os.joinenvs</h4>
<ul>
<li>Join environment variables. Similar to <a href="#osaddenvs">os.addenvs</a> but with two envs variable</li>
</ul>
<pre><code class="lang-lua">local envs = {CUSTOM = "a/path"}
local envs2 = {CUSTOM = "some/path/"}
print(os.joinenvs(envs, envs2))
</code></pre>
<p>The result is: <code>{ CUSTOM = "a/path;some/path/" }</code></p>
<h4 id="osgetenv">os.getenv</h4>
<ul>
<li>Get system environment variables</li>
</ul>
<pre><code class="lang-lua">print(os.getenv("PATH"))
</code></pre>
<h4 id="ossetenv">os.setenv</h4>
<ul>
<li>Set system environment variables</li>
</ul>
<pre><code class="lang-lua">os.setenv("HOME", "/tmp/")
</code></pre>
<h4 id="osaddenv">os.addenv</h4>
<ul>
<li>Add values to one environment variable</li>
</ul>
<pre><code class="lang-lua">-- Add &#39;bin&#39; to PATH
os.addenv("PATH", "bin")
</code></pre>
<h4 id="ossetenvp">os.setenvp</h4>
<ul>
<li>Setting environment variables with a given separator</li>
</ul>
<h4 id="osaddenvp">os.addenvp</h4>
<ul>
<li>Add values to one environment variable with a given separator</li>
</ul>
<h4 id="osworkingdir">os.workingdir</h4>
<ul>
<li>Get the working directory</li>
</ul>
<h4 id="osisroot">os.isroot</h4>
<ul>
<li>Test if xmake is running as root</li>
</ul>
<h4 id="osfscase">os.fscase</h4>
<ul>
<li>Test if the os has a case sensitive filesystem</li>
</ul>
<h4 id="osterm">os.term</h4>
<ul>
<li>Get current terminal (windows-terminal, vscode, ... )</li>
</ul>
<pre><code class="lang-lua">print(os.term())
-- got vscode
</code></pre>
<h4 id="osshell">os.shell</h4>
<ul>
<li>Get current shell  (pwsh, cmd, ...)</li>
</ul>
<pre><code class="lang-lua">print(os.shell())
-- got pwsh
</code></pre>
<h4 id="oscpuinfo">os.cpuinfo</h4>
<ul>
<li>Get cpu information</li>
</ul>
<pre><code class="lang-lua">print(os.cpuinfo())
-- got { 
--   ncpu = 8,
--   usagerate = 0.0,
--   model_name = "Intel(R) Core(TM) i7-7700 CPU @ 3.60GHz",
--   march = "Kaby Lake",
--   vendor = "GenuineIntel",
--   model = 158,
--   family = 6
-- }
print(os.cpuinfo("march")) -- got "Kaby Lake"
</code></pre>
<h4 id="osmeminfo">os.meminfo</h4>
<ul>
<li>Get memory information</li>
</ul>
<pre><code class="lang-lua">print(os.meminfo())
-- got { 
--   usagerate = 0.53490080822924,
--   totalsize = 16332,
--   availsize = 7596,
--   pagesize = 4096
-- }
</code></pre>
<h4 id="osdefault_njob">os.default_njob</h4>
<ul>
<li>Get default paralled jobs</li>
</ul>
<h3 id="winos">winos</h3>
<p>The windows system operation module is a built-in module, no need to use <a href="#import">import</a> to import, you can directly call its interface in the script domain.</p>
<table>
<thead>
<tr>
<th>Interface</th>
<th>Description</th>
<th>Support version</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#winosversion">winos.version</a></td>
<td>Get windows system version</td>
<td>>= 2.3.1</td>
</tr>
<tr>
<td><a href="#winosregistry_keys">winos.registry_keys</a></td>
<td>Get the list of registry keys</td>
<td>>= 2.5.1</td>
</tr>
<tr>
<td><a href="#winosregistry_values">winos.registry_values</a></td>
<td>Get a list of registry value names</td>
<td>>= 2.5.1</td>
</tr>
<tr>
<td><a href="#winosregistry_query">winos.registry_query</a></td>
<td>Get the registry value</td>
<td>>= 2.3.1</td>
</tr>
</tbody>
</table>
<h4 id="winosversion">winos.version</h4>
<ul>
<li>Get windows system version</li>
</ul>
<p>The version returned is the semver semantic version object</p>
<pre><code class="lang-lua">if winos.version():ge("win7") then
    - ...
end

if winos.version():ge("6.1") then
    - ...
end
</code></pre>
<p>In addition, it can also support the direct judgment of the windows version name. The mapping rules are as follows:</p>
<pre><code>nt4 = "4.0"
win2k = "5.0"
winxp = "5.1"
ws03 = "5.2"
win6 = "6.0"
vista = "6.0"
ws08 = "6.0"
longhorn = "6.0"
win7 = "6.1"
win8 = "6.2"
winblue = "6.3"
win81 = "6.3"
win10 = "10.0"
</code></pre><h4 id="winosregistry_keys">winos.registry_keys</h4>
<ul>
<li>Get the list of registry builds</li>
</ul>
<p>Support through pattern matching, traverse to obtain the registry key path list, <code>*</code> is single-level path matching, <code>**</code> is recursive path matching.</p>
<pre><code class="lang-lua">local keypaths = winos.registry_keys("HKEY_LOCAL_MACHINE\\SOFTWARE\\*\\Windows NT\\*\\CurrentVersion\\AeDebug")
for _, keypath in ipairs(keypaths) do
    print(winos.registry_query(keypath .. ";Debugger"))
end
</code></pre>
<h4 id="winosregistry_values">winos.registry_values</h4>
<ul>
<li>Get a list of registry value names</li>
</ul>
<p>Support to obtain the value name list of the specified key path through pattern matching, and the string after the <code>;</code> is the specified key name pattern matching string.</p>
<pre><code class="lang-lua">local valuepaths = winos.registry_values("HKEY_LOCAL_MACHINE\\SOFTWARE\\xx\\AeDebug;Debug*")
for _, valuepath in ipairs(valuepaths) do
    print(winos.registry_query(valuepath))
end
</code></pre>
<h4 id="winosregistry_query">winos.registry_query</h4>
<ul>
<li>Get the registry value</li>
</ul>
<p>Get the value under the specified registry path, if the value name is not specified, then get the default value of the key path</p>
<pre><code class="lang-lua">local value, errors = winos.registry_query("HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug")
local value, errors = winos.registry_query("HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug;Debugger")
</code></pre>
<h3 id="macos">macos</h3>
<p>The macOS system operation module is a built-in module, no need to use <a href="#import">import</a> to import, you can directly call its interface in the script domain.</p>
<table>
<thead>
<tr>
<th>Interface</th>
<th>Description</th>
<th>Support version</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#macosversion">macos.version</a></td>
<td>Get macOS system version</td>
<td>>= 2.3.1</td>
</tr>
</tbody>
</table>
<h4 id="macosversion">macos.version</h4>
<ul>
<li>Get macOS system version</li>
</ul>
<p>The version returned is the semver semantic version object</p>
<pre><code class="lang-lua">if macos.version():ge("10.0") then
    - ...
end
</code></pre>
<h3 id="linuxos">linuxos</h3>
<p>The linux system operation module is a built-in module, no need to use <a href="#import">import</a> to import, and its interface can be called directly in the script domain.</p>
<table>
<thead>
<tr>
<th>Interface</th>
<th>Description</th>
<th>Support version</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#linuxosname">linuxos.name</a></td>
<td>Get the linux system release name</td>
<td>>= 2.5.2</td>
</tr>
<tr>
<td><a href="#linuxosversion">linuxos.version</a></td>
<td>Get linux system version</td>
<td>>= 2.5.2</td>
</tr>
<tr>
<td><a href="#linuxoskernelver">linuxos.kernelver</a></td>
<td>Get linux system kernel version</td>
<td>>= 2.5.2</td>
</tr>
</tbody>
</table>
<h4 id="linuxosname">linuxos.name</h4>
<ul>
<li>Get linux system name</li>
</ul>
<p>We can also quickly get the view through the following command</p>
<pre><code class="lang-bash">xmake l linuxos.name
</code></pre>
<p>Some names currently supported are:</p>
<ul>
<li>ubuntu</li>
<li>debian</li>
<li>archlinux</li>
<li>manjaro</li>
<li>linuxmint</li>
<li>centos</li>
<li>fedora</li>
<li>opensuse</li>
</ul>
<h4 id="linuxosversion">linuxos.version</h4>
<ul>
<li>Get linux system version</li>
</ul>
<p>The version returned is the semver semantic version object</p>
<pre><code class="lang-lua">if linux.version():ge("10.0") then
    -- ...
end
</code></pre>
<h4 id="linuxoskernelver">linuxos.kernelver</h4>
<ul>
<li>Get linux system kernel version</li>
</ul>
<p>What is returned is also a semantic version object, you can also execute <code>xmake l linuxos.kernelver</code> to quickly view</p>
<h3 id="io">io</h3>
<p>The io operation module extends lua&#39;s built-in io module to provide more easy-to-use interfaces.</p>
<table>
<thead>
<tr>
<th>Interface</th>
<th>Description</th>
<th>Supported Versions</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#ioopen">io.open</a></td>
<td>Open file for reading and writing</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#ioload">io.load</a></td>
<td>De-serialize all table contents from the specified path file</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#iosave">io.save</a></td>
<td>Serialize all table contents to the specified path file</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#ioreadfile">io.readfile</a></td>
<td>Read everything from the specified path file</td>
<td>>= 2.1.3</td>
</tr>
<tr>
<td><a href="#iowritefile">io.writefile</a></td>
<td>Write everything to the specified path file</td>
<td>>= 2.1.3</td>
</tr>
<tr>
<td><a href="#iogsub">io.gsub</a></td>
<td>Full text replaces the contents of the specified path file</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#iotail">io.tail</a></td>
<td>Read and display the tail of the file</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#iocat">io.cat</a></td>
<td>Read and display all contents of a file</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#ioprint">io.print</a></td>
<td>Formatting output with a line feed to a file</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#ioprintf">io.printf</a></td>
<td>No line formatted output to file</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#iolines">io.lines</a></td>
<td>Read all lines from file</td>
<td>>= 2.2.9</td>
</tr>
<tr>
<td><a href="#iostdfile">io.stdfile</a></td>
<td>Get std file</td>
<td>>= 2.2.9</td>
</tr>
<tr>
<td><a href="#ioopenlock">io.openlock</a></td>
<td>Open a lock of a file</td>
<td>>= 2.2.9</td>
</tr>
<tr>
<td><a href="#ioreplace">io.replace</a></td>
<td>Replace text of the given file and return the replaced data</td>
<td>>= 2.3.8</td>
</tr>
</tbody>
</table>
<h4 id="ioopen">io.open</h4>
<ul>
<li>Open file for reading and writing</li>
</ul>
<p>This is a native interface for lua. For detailed usage, see Lua&#39;s official documentation: <a href="https://www.lua.org/pil/21.2.html">The Complete I/O Model</a></p>
<p>If you want to read all the contents of the file, you can write:</p>
<pre><code class="lang-lua">local file = io.open("$(tmpdir)/file.txt", "r")
if file then
    local data = file:read("*all")
    file:close()
end
</code></pre>
<p>Or you can read it more quickly using <a href="#io.readfile">io.readfile</a>.</p>
<p>If you want to write a file, you can do this:</p>
<pre><code class="lang-lua">-- Open file: w is write mode, a is append write mode
local file = io.open("xxx.txt", "w")
if file then

    -- Write data to file with native lua interface, does not support formatting, no line breaks, does not support built-in variables
    file:write("hello xmake\n")

    -- Write data to file with xmake extended interface, support formatting, no line breaks, no built-in variables
    file:writef("hello %s\n", "xmake")

    -- Use xmake extended formatted parameters to write to one line, with line breaks, and support for built-in variables
    file:print("hello %s and $(buildir)", "xmake")

    -- Write a line using the xmake extended formatted arguments, no line breaks, and support for built-in variables
    file:printf("hello %s and $(buildir) \n", "xmake")

    -- Close the file
    file:close()
end
</code></pre>
<h4 id="ioload">io.load</h4>
<ul>
<li>Load all table contents from the specified path file deserialization</li>
</ul>
<p>You can load serialized table contents from a file, generally used with <a href="#iosave">io.save</a>, for example:</p>
<pre><code class="lang-lua">-- Load the contents of the serialized file to the table
local data = io.load("xxx.txt")
if data then

    -- Dump prints the contents of the entire table in the terminal, formatting the output
    utils.dump(data)
end
</code></pre>
<h4 id="iosave">io.save</h4>
<ul>
<li>Serialize all table contents to the specified path file</li>
</ul>
<p>You can serialize the contents of the table to the specified file, generally used in conjunction with <a href="#ioload">io.load</a>, for example:</p>
<pre><code class="lang-lua">io.save("xxx.txt", {a = "a", b = "b", c = "c"})
</code></pre>
<p>The result of the storage is:</p>
<pre><code>{
    ["b"] = "b"
,   ["a"] = "a"
,   ["c"] = "c"
}
</code></pre><h4 id="ioreadfile">io.readfile</h4>
<ul>
<li>Read everything from the specified path file</li>
</ul>
<p>It is more convenient to directly read the contents of the entire file without opening the file, for example:</p>
<pre><code class="lang-lua">local data = io.readfile("xxx.txt")
</code></pre>
<h4 id="iowritefile">io.writefile</h4>
<ul>
<li>Write all content to the specified path file</li>
</ul>
<p>It is more convenient to directly write the contents of the entire file without opening the file, for example:</p>
<pre><code class="lang-lua">io.writefile("xxx.txt", "all data")
</code></pre>
<h4 id="iogsub">io.gsub</h4>
<ul>
<li>Full text replaces the contents of the specified path file</li>
</ul>
<p>Similar to the <a href="#stringgsub">string.gsub</a> interface, the full-text pattern matches the replacement content, but here is the direct operation file, for example:</p>
<pre><code class="lang-lua">-- Remove all whitespace characters from the file
io.gsub("xxx.txt", "%s+", "")
</code></pre>
<h4 id="iotail">io.tail</h4>
<ul>
<li>Read and display the tail content of the file</li>
</ul>
<p>Reads the data of the specified number of lines at the end of the file and displays a command like <code>cat xxx.txt | tail -n 10</code>, for example:</p>
<pre><code class="lang-lua">-- Display the last 10 lines of the file
io.tail("xxx.txt", 10)
</code></pre>
<h4 id="iocat">io.cat</h4>
<ul>
<li>read and display all contents of the file</li>
</ul>
<p>Read all the contents of the file and display it, similar to the <code>cat xxx.txt</code> command, for example:</p>
<pre><code class="lang-lua">io.cat("xxx.txt")
</code></pre>
<h4 id="ioprint">io.print</h4>
<ul>
<li>Formatted output content to file with newline</li>
</ul>
<p>Directly format the passed parameter to output a line of string to the file with a line break, for example:</p>
<pre><code class="lang-lua">io.print("xxx.txt", "hello %s!", "xmake")
</code></pre>
<h4 id="ioprintf">io.printf</h4>
<ul>
<li>Formatted output to file without line breaks</li>
</ul>
<p>Directly format the passed parameter to output a line of string to the file without a line break, for example:</p>
<pre><code class="lang-lua">io.printf("xxx.txt", "hello %s!\n", "xmake")
</code></pre>
<h3 id="iolines">io.lines</h3>
<ul>
<li>Read all lines from file</li>
</ul>
<p>Returns all lines from a given file name</p>
<pre><code class="lang-lua">local lines = io.lines("xxx.txt")
for line in lines do
    print(line)
end
</code></pre>
<h3 id="iostdfile">io.stdfile</h3>
<ul>
<li>Get a std file</li>
</ul>
<p>Returns a file for a given std file name</p>
<pre><code class="lang-lua">-- returns stdin
io.stdin
-- returns stdout
io.stdout
-- returns stderr
io.stderr
</code></pre>
<h3 id="ioopenlock">io.openlock</h3>
<ul>
<li>Open a lock of a file</li>
</ul>
<p>Returns a file lock object when successfully locking the file</p>
<pre><code class="lang-lua">local lock = io.openlock("xxx.txt")
lock:lock()
lock:unlock()
lock:close()
</code></pre>
<h3 id="ioreplace">io.replace</h3>
<ul>
<li>Replace text of the given file and return the replaced data</li>
</ul>
<p>Replaces a given pattern in a file by a replacement string</p>
<pre><code class="lang-lua">-- replace string "Hello" in "xxx.txt" with "World"
io.replace("xxx.txt", "Hello", "World")
-- if you want to replace a string and not a pattern
io.replace("xxx.txt", "1+1=2", "2+2=4", {plain = true})
</code></pre>
<h3 id="path">path</h3>
<p>The path operation module implements cross-platform path operations, which is a custom module of xmake.</p>
<table>
<thead>
<tr>
<th>Interface</th>
<th>Description</th>
<th>Supported Versions</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#pathnew">path.new</a></td>
<td>Create a new path instance</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#pathjoin">path.join</a></td>
<td>Stitching Path</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#pathtranslate">path.translate</a></td>
<td>Convert path to the path style of the current platform</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#pathbasename">path.basename</a></td>
<td>Get the file name with no suffix at the end</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#pathfilename">path.filename</a></td>
<td>Get the file name with the last suffix of the path</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#pathextension">path.extension</a></td>
<td>Get the suffix of the path</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#pathdirectory">path.directory</a></td>
<td>Get the directory name of the path</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#pathrelative">path.relative</a></td>
<td>Convert to relative path</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#pathabsolute">path.absolute</a></td>
<td>Convert to absolute path</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#pathis_absolute">path.is_absolute</a></td>
<td>Determine if it is an absolute path</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#pathsplit">path.split</a></td>
<td>Split by the separator</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#pathsep">path.sep</a></td>
<td>Get the separator character</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#pathislastsep">path.islastsep</a></td>
<td>Get if the last character is a separator</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#pathsplitenv">path.splitenv</a></td>
<td>Split a environment variable value of an array of pathes</td>
<td>>= 2.2.7</td>
</tr>
<tr>
<td><a href="#pathjoinenv">path.joinenv</a></td>
<td>Concat environment variable with environment separator</td>
<td>>= 2.2.7</td>
</tr>
<tr>
<td><a href="#pathenvsep">path.envsep</a></td>
<td>Get the path seperator of environment variable</td>
<td>>= 2.2.7</td>
</tr>
<tr>
<td><a href="#pathcygwin_path">path.cygwin_path</a></td>
<td>Get the converted MSYS2/Cygwin style path</td>
<td>>= 2.2.7</td>
</tr>
<tr>
<td><a href="#pathpattern">path.pattern</a></td>
<td>Convert a path pattern to a lua pattern</td>
<td>>= 2.2.7</td>
</tr>
</tbody>
</table>
<h4 id="pathnew">path.new</h4>
<ul>
<li>Create a new path instance</li>
</ul>
<pre><code class="lang-lua">local p = path.new("/tmp/file.txt")
print(p:filename())
</code></pre>
<p>The result is: <code>file.txt</code></p>
<h4 id="pathjoin">path.join</h4>
<ul>
<li>Stitching path</li>
</ul>
<p>Adding multiple path items by splicing. Due to the path difference of <code>windows/unix</code> style, using api to append paths is more cross-platform, for example:</p>
<pre><code class="lang-lua">print(path.join("$(tmpdir)", "dir1", "dir2", "file.txt"))
</code></pre>
<p>The above splicing on Unix is equivalent to: <code>$(tmpdir)/dir1/dir2/file.txt</code>, and on Windows is equivalent to: <code>$(tmpdir)\\dir1\\dir2\\file.txt</code></p>
<p>If you find this cumbersome and not clear enough, you can use: <a href="#pathtranslate">path.translate</a> to format the conversion path string to the format supported by the current platform.</p>
<h4 id="pathtranslate">path.translate</h4>
<ul>
<li>Convert path to the path style of the current platform</li>
</ul>
<p>Formatting converts the specified path string to the path style supported by the current platform, and supports the path string parameter of the <code>windows/unix</code> format to be passed in, even mixed, such as:</p>
<pre><code class="lang-lua">print(path.translate("$(tmpdir)/dir/file.txt"))
print(path.translate("$(tmpdir)\\dir\\file.txt"))
print(path.translate("$(tmpdir)\\dir/dir2//file.txt"))
</code></pre>
<p>The path strings of the above three different formats, after being standardized by <code>translate</code>, will become the format supported by the current platform, and the redundant path separator will be removed.</p>
<h4 id="pathbasename">path.basename</h4>
<ul>
<li>Get the file name with no suffix at the end of the path</li>
</ul>
<pre><code class="lang-lua">print(path.basename("$(tmpdir)/dir/file.txt"))
</code></pre>
<p>The result is: <code>file</code></p>
<h4 id="pathfilename">path.filename</h4>
<ul>
<li>Get the file name with the last suffix of the path</li>
</ul>
<pre><code class="lang-lua">print(path.filename("$(tmpdir)/dir/file.txt"))
</code></pre>
<p>The result is: <code>file.txt</code></p>
<h4 id="pathextension">path.extension</h4>
<ul>
<li>Get the suffix of the path</li>
</ul>
<pre><code class="lang-lua">print(path.extensione("$(tmpdir)/dir/file.txt"))
</code></pre>
<p>The result is: <code>.txt</code></p>
<h4 id="pathdirectory">path.directory</h4>
<ul>
<li>Get the directory name of the path</li>
</ul>
<pre><code class="lang-lua">Print(path.directory("$(tmpdir)/dir/file.txt"))
</code></pre>
<p>The result is: <code>$(tmpdir)/dir</code></p>
<h4 id="pathrelative">path.relative</h4>
<ul>
<li>Convert to relative path</li>
</ul>
<pre><code class="lang-lua">print(path.relative("$(tmpdir)/dir/file.txt", "$(tmpdir)"))
</code></pre>
<p>The result is: <code>dir/file.txt</code></p>
<p>The second parameter is to specify the relative root directory. If not specified, the default is relative to the current directory:</p>
<pre><code class="lang-lua">os.cd("$(tmpdir)")
print(path.relative("$(tmpdir)/dir/file.txt"))
</code></pre>
<p>The result is the same.</p>
<h4 id="pathabsolute">path.absolute</h4>
<ul>
<li>Convert to absolute path</li>
</ul>
<pre><code class="lang-lua">print(path.absolute("dir/file.txt", "$(tmpdir)"))
</code></pre>
<p>The result is: <code>$(tmpdir)/dir/file.txt</code></p>
<p>The second parameter is to specify the relative root directory. If not specified, the default is relative to the current directory:</p>
<pre><code class="lang-lua">os.cd("$(tmpdir)")
print(path.absolute("dir/file.txt"))
</code></pre>
<p>The result is the same.</p>
<h4 id="pathis_absolute">path.is_absolute</h4>
<ul>
<li>Determine if it is an absolute path</li>
</ul>
<pre><code class="lang-lua">if path.is_absolute("/tmp/file.txt") then
    -- if it is an absolute path
end
</code></pre>
<h4 id="pathsplit">path.split</h4>
<ul>
<li>Split the path by the separator </li>
</ul>
<pre><code class="lang-lua">print(path.split("/tmp/file.txt"))
</code></pre>
<p>The result is: <code>{ "tmp", "file.txt" }</code></p>
<h4 id="pathsep">path.sep</h4>
<ul>
<li>Return the current separator, usually <code>/</code> </li>
</ul>
<pre><code class="lang-lua">print(path.sep("/tmp/file.txt"))
</code></pre>
<p>The result is: <code>/</code></p>
<h4 id="pathislastsep">path.islastsep</h4>
<ul>
<li>Get if the last character is a separator</li>
</ul>
<pre><code class="lang-lua">if (path.islastsep("/tmp/dir/")) then
    -- if the last character is a separator
end
</code></pre>
<h4 id="pathsplitenv">path.splitenv</h4>
<ul>
<li>Split a environment variable value of an array of pathes</li>
</ul>
<pre><code class="lang-lua">local pathes = path.splitenv(vformat("$(env PATH)"))

-- for windows 
local pathes = path.splitenv("C:\\Windows;C:\\Windows\\System32")
-- got { "C:\\Windows", "C:\\Windows\\System32" }

-- for *nix 
local pathes = path.splitenv("/usr/bin:/usr/local/bin")
-- got { "/usr/bin", "/usr/local/bin" }
</code></pre>
<p>The result is an array of strings, each item is a path in the input string.</p>
<h4 id="pathjoinenv">path.joinenv</h4>
<ul>
<li>Concat two environment variable by the environment separator</li>
</ul>
<pre><code class="lang-lua">print(path.joinenv({"/tmp/dir", "/tmp/dir2"}))
</code></pre>
<p>The result is: <code>/tmp/dir;/tmp/dir2</code> (on Windows)</p>
<h4 id="pathenvsep">path.envsep</h4>
<ul>
<li>Get the environment separator</li>
</ul>
<pre><code class="lang-lua">print(path.envsep())
</code></pre>
<p>The result is: <code>;</code></p>
<h4 id="pathcygwin_path">path.cygwin_path</h4>
<ul>
<li>Get the converted MSYS2/Cygwin style path </li>
</ul>
<pre><code class="lang-lua">print(path.cygwin_path("C:\\Windows"))
</code></pre>
<p>The result is: <code>/C/Windows</code></p>
<h4 id="pathpattern">path.pattern</h4>
<ul>
<li>Convert path pattern to lua pattern</li>
</ul>
<pre><code class="lang-lua">print(path.pattern("/tmp/file.txt"))
</code></pre>
<p>The result is: <code>/[tT][mM][pP]/[fF][iI][lL][eE]%.[tT][xX][tT]</code></p>
<h3 id="table">table</h3>
<p>Table belongs to the module provided by Lua native. For the native interface, you can refer to: <a href="https://www.lua.org/manual/5.1/manual.html#5.5">lua official document</a></p>
<p>It has been extended in xmake to add some extension interfaces:</p>
<table>
<thead>
<tr>
<th>Interface</th>
<th>Description</th>
<th>Supported Versions</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#tablejoin">table.join</a></td>
<td>Merge multiple tables and return</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#tablejoin2">table.join2</a></td>
<td>Merge multiple tables into the first table</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#tableunique">table.unique</a></td>
<td>Deduplicate the contents of the table</td>
<td>>= 2.0.1</td>
</tr>
<tr>
<td><a href="#tableslice">table.slice</a></td>
<td>Get the slice of the table</td>
<td>>= 2.0.1</td>
</tr>
</tbody>
</table>
<h4 id="tablejoin">table.join</h4>
<ul>
<li>Merge multiple tables and return</li>
</ul>
<p>You can merge the elements in multiple tables and return to a new table, for example:</p>
<pre><code class="lang-lua">local newtable = table.join({1, 2, 3}, {4, 5, 6}, {7, 8, 9})
</code></pre>
<p>The result is: <code>{1, 2, 3, 4, 5, 6, 7, 8, 9}</code></p>
<p>And it also supports the merging of dictionaries:</p>
<pre><code class="lang-lua">local newtable = table.join({a = "a", b = "b"}, {c = "c"}, {d = "d"})
</code></pre>
<p>The result is: <code>{a = "a", b = "b", c = "c", d = "d"}</code></p>
<h4 id="tablejoin2">table.join2</h4>
<ul>
<li>Combine multiple tables into the first table</li>
</ul>
<p>Similar to <a href="#table.join">table.join</a>, the only difference is that the result of the merge is placed in the first argument, for example:</p>
<pre><code class="lang-lua">local t = {0, 9}
table.join2(t, {1, 2, 3})
</code></pre>
<p>The result is: <code>t = {0, 9, 1, 2, 3}</code></p>
<h4 id="tableunique">table.unique</h4>
<ul>
<li>Deduplicate the contents of the table</li>
</ul>
<p>To de-table elements, generally used in array tables, for example:</p>
<pre><code class="lang-lua">local newtable = table.unique({1, 1, 2, 3, 4, 4, 5})
</code></pre>
<p>The result is: <code>{1, 2, 3, 4, 5}</code></p>
<h4 id="tableslice">table.slice</h4>
<ul>
<li>Get the slice of the table</li>
</ul>
<p>Used to extract some elements of an array table, for example:</p>
<pre><code class="lang-lua">-- Extract all elements after the 4th element, resulting in: {4, 5, 6, 7, 8, 9}
table.slice({1, 2, 3, 4, 5, 6, 7, 8, 9}, 4)

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

-- Extract the 4th-8th element with an interval of 2, resulting in: {4, 6, 8}
table.slice({1, 2, 3, 4, 5, 6, 7, 8, 9}, 4, 8, 2)
</code></pre>
<h4 id="tablecontains">table.contains</h4>
<ul>
<li>Determine that the table contains the specified value</li>
</ul>
<pre><code class="lang-lua">if table.contains(t, 1, 2, 3) then
     - ...
end
</code></pre>
<p>As long as the table contains any value from 1, 2, 3, it returns true</p>
<h4 id="tableorderkeys">table.orderkeys</h4>
<ul>
<li>Get an ordered list of keys</li>
</ul>
<p>The order of the key list returned by <code>table.keys(t)</code> is random. If you want to get an ordered key list, you can use this interface.</p>
<h3 id="string">string</h3>
<p>The string module is a native module of lua. For details, see: <a href="https://www.lua.org/manual/5.1/manual.html#5.4">lua official manual</a></p>
<p>It has been extended in xmake to add some extension interfaces:</p>
<table>
<thead>
<tr>
<th>Interface</th>
<th>Description</th>
<th>Supported Versions</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#stringstartswith">string.startswith</a></td>
<td>Determine if the beginning of the string matches</td>
<td>>= 1.0.1</td>
</tr>
<tr>
<td><a href="#stringendswith">string.endswith</a></td>
<td>Determine if the end of the string matches</td>
<td>>= 1.0.1</td>
</tr>
<tr>
<td><a href="#stringsplit">string.split</a></td>
<td>Split String</td>
<td>>= 1.0.1</td>
</tr>
<tr>
<td><a href="#stringtrim">string.trim</a></td>
<td>Remove the left and right whitespace characters</td>
<td>>= 1.0.1</td>
</tr>
<tr>
<td><a href="#stringltrim">string.ltrim</a></td>
<td>Remove the whitespace character to the left of the string</td>
<td>>= 1.0.1</td>
</tr>
<tr>
<td><a href="#stringrtrim">string.rtrim</a></td>
<td>Remove the whitespace character to the right of the string</td>
<td>>= 1.0.1</td>
</tr>
</tbody>
</table>
<h4 id="stringstartswith">string.startswith</h4>
<ul>
<li>Determine if the beginning of the string matches</li>
</ul>
<pre><code class="lang-lua">local s = "hello xmake"
if s:startswith("hello") then
    print("match")
end
</code></pre>
<h4 id="stringendswith">string.endswith</h4>
<ul>
<li>Determine if the end of the string matches</li>
</ul>
<pre><code class="lang-lua">local s = "hello xmake"
if s:endswith("xmake") then
    print("match")
end
</code></pre>
<h4 id="stringsplit">string.split</h4>
<p>pattern match and ignore empty string</p>
<pre><code class="lang-lua">("1\n\n2\n3"):split(&#39;\n&#39;) => 1, 2, 3
("abc123123xyz123abc"):split(&#39;123&#39;) => abc, xyz, abc
("abc123123xyz123abc"):split(&#39;[123]+&#39;) => abc, xyz, abc
</code></pre>
<p>plain match and ignore empty string</p>
<pre><code class="lang-lua">("1\n\n2\n3"):split(&#39;\n&#39;, {plain = true}) => 1, 2, 3
("abc123123xyz123abc"):split(&#39;123&#39;, {plain = true}) => abc, xyz, abc
</code></pre>
<p>pattern match and contains empty string</p>
<pre><code class="lang-lua">("1\n\n2\n3"):split(&#39;\n&#39;, {strict = true}) => 1, , 2, 3
("abc123123xyz123abc"):split(&#39;123&#39;, {strict = true}) => abc, , xyz, abc
("abc123123xyz123abc"):split(&#39;[123]+&#39;, {strict = true}) => abc, xyz, abc
</code></pre>
<p>plain match and contains empty string</p>
<pre><code class="lang-lua">("1\n\n2\n3"):split(&#39;\n&#39;, {plain = true, strict = true}) => 1, , 2, 3
("abc123123xyz123abc"):split(&#39;123&#39;, {plain = true, strict = true}) => abc, , xyz, abc
</code></pre>
<p>limit split count</p>
<pre><code class="lang-lua">("1\n\n2\n3"):split(&#39;\n&#39;, {limit = 2}) => 1, 2\n3
("1.2.3.4.5"):split(&#39;%.&#39;, {limit = 3}) => 1, 2, 3.4.5
</code></pre>
<h4 id="stringtrim">string.trim</h4>
<ul>
<li>Remove the left and right whitespace characters of the string</li>
</ul>
<pre><code class="lang-lua">string.trim("    hello xmake!    ")
</code></pre>
<p>The result is: "hello xmake!"</p>
<h4 id="stringltrim">string.ltrim</h4>
<ul>
<li>Remove the whitespace character to the left of the string</li>
</ul>
<pre><code class="lang-lua">string.ltrim("    hello xmake!    ")
</code></pre>
<p>The result is: "hello xmake!    "</p>
<h4 id="stringrtrim">string.rtrim</h4>
<ul>
<li>Remove the whitespace character to the right of the string</li>
</ul>
<pre><code class="lang-lua">string.rtrim("    hello xmake!    ")
</code></pre>
<p>The result is: "    hello xmake!"</p>
<h3 id="coroutine">coroutine</h3>
<p>The coroutine module is a native module of lua. For use, see: <a href="https://www.lua.org/manual/5.1/manual.html#5.2">lua official manual</a></p>
<h3 id="signal">signal</h3>
<p>2.9.1 adds a new signal registration interface. We can register signal processing functions such as SIGINT in the Lua layer to customize the response logic.</p>
<h4 id="signalregister">signal.register</h4>
<ul>
<li>Register signal handler</li>
</ul>
<p>Currently, it only supports SIGINT signal processing, and it also supports mainstream platforms such as windows.</p>
<pre><code class="lang-lua">import("core.base.signal")

function main()
     signal.register(signal.SIGINT, function (signo)
         print("signal.SIGINT(%d)", signo)
     end)
     io.read()
end
</code></pre>
<p>This is useful when some sub-processes internally shield SIGINT, causing them to freeze and not exit. Even if the user presses <code>Ctrl+C</code> to exit the xmake process, it does not exit.<br>We can force it out in this way.</p>
<pre><code class="lang-lua">import("core.base.process")
import("core.base.signal")

function main()
     local proc
     signal.register(signal.SIGINT, function (signo)
         print("sigint")
         if proc then
             proc:kill()
         end
     end)
     proc = process.open("./trap.sh")
     if proc then
         proc:wait()
         proc:close()
     end
end
</code></pre>
<p>For the background of this issue, please refer to: <a href="https://github.com/xmake-io/xmake/issues/4889">#4889</a></p>
<h4 id="signalignore">signal.ignore</h4>
<ul>
<li>Ignore a signal</li>
</ul>
<p>We can also ignore the processing of blocking a certain signal through the <code>signal.ignore</code> interface.</p>
<pre><code class="lang-lua">signal.ignore(signal.SIGINT)
</code></pre>
<h4 id="signalreset">signal.reset</h4>
<ul>
<li>Reset a signal</li>
</ul>
<p>We can also clear the processing function of a certain signal and fall back to the default processing logic.</p>
<pre><code class="lang-lua">signal.reset(signal.SIGINT)
</code></pre>
</article>
</body>
</html>