xmake
/
xmake-docs
огледало од https://github.com/xmake-io/xmake-docs


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282
							<!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/#/guide/faq">https://xmake.io/#/guide/faq</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>
    <h1 id="faqfq">FAQ (F&amp;Q)</h1>
<h2 id="howtogetcommandlineargumentsinformation">How to get command-line arguments information?</h2>
<p>Get the help info of the main command:</p>
<pre><code class="lang-bash">$ xmake [-h|--help]
</code></pre>
<p>Get the help info of the configuration command:</p>
<pre><code class="lang-bash">$ xmake f [-h|--help]
</code></pre>
<p>Get the help info of the given action or plugin command:</p>
<pre><code class="lang-bash">$ xmake [action|plugin] [-h|--help]
</code></pre>
<p>For example:</p>
<pre><code class="lang-bash">$ xmake run --help
</code></pre>
<h2 id="howtosuppressalloutputinfo">How to suppress all output info?</h2>
<pre><code class="lang-bash">$ xmake [-q|--quiet]
</code></pre>
<h2 id="whatdodoifxmakefails">What do do if Xmake fails?</h2>
<p>Please attempt to clean configuration and rebuild it first.</p>
<pre><code class="lang-bash">$ xmake f -c
$ xmake
</code></pre>
<p>If it fails again, please add <code>-v</code> or <code>--verbose</code> options to get more verbose info.</p>
<p>For example:</p>
<pre><code class="lang-bash">$ xmake [-v|--verbose]
</code></pre>
<p>And add <code>-D</code> to get the verbose backtrace and diagnosis info, then you can submit this to <a href="https://github.com/xmake-io/xmake/issues">issues</a>.</p>
<pre><code class="lang-bash">$ xmake -v -D
</code></pre>
<h2 id="howtoseeverbosecompilingwarnings">How to see verbose compiling warnings?</h2>
<pre><code class="lang-bash">$ xmake [-w|--warning]
</code></pre>
<h2 id="howtoscansourcecodeandgeneratexmakeluaautomatically">How to scan source code and generate <code>xmake.lua</code> automatically?</h2>
<p>You only need run the following command:</p>
<pre><code class="lang-bash">$ xmake
</code></pre>
<p>Xmake will scan all source code in current directory and build it automatically.</p>
<p>And we can run it directly.</p>
<pre><code class="lang-bash">$ xmake run
</code></pre>
<p>If we only want to generate <code>xmake.lua</code> file, we can run:</p>
<pre><code class="lang-bash">$ xmake f -y
</code></pre>
<p>If you want to get more information, please see <a href="https://tboox.org/2017/01/07/build-without-makefile/">Scan source codes and build project without makefile</a>.</p>
<h2 id="whyisxmakeluabeingexecutedmultipletimes">Why is xmake.lua being executed multiple times?</h2>
<p>Xmake.lua is divided into description fields and script fields. In the description field, various configuration fields are parsed multiple times in stages, and it is possible to execute multiple times. Therefore, do not write complex scripts in the description field.</p>
<p>If you want to write a variety of complex scripts, please configure them in the script domain. The script domain of <code>target/on_load</code> can also flexibly configure various target related settings and provide more powerful lua script module support.</p>
<p>See: <a href="/mirror/guide/syntax_description.html">Description of Syntax Description</a> for more details.</p>
<h2 id="howtodebugxmakesourcecode">How to debug Xmake source code?</h2>
<h3 id="downloadingsourcecode">Downloading source code</h3>
<p>Since Xmake uses git submodules to maintain submodules, we can pull the full source code in several ways.</p>
<h4 id="cloningwithgit">Cloning with git</h4>
<pre><code class="lang-bash">$ git clone --recursive https://github.com/xmake-io/xmake.git
</code></pre>
<p>or</p>
<pre><code class="lang-bash">$ git clone https://github.com/xmake-io/xmake.git
$ git submodule update --init
</code></pre>
<h4 id="downloadingsourcepackagesfromgithubreleases">Downloading source packages from Github Releases</h4>
<p>Because github&#39;s own downloads attachments do not support archiving submodules, Xmake packages an extra tarball of source code for each release and uploads it to Releases.</p>
<p>Therefore, do not download the wrong link address</p>
<ul>
<li>Incomplete source code: <a href="https://github.com/xmake-io/xmake/archive/refs/tags/v2.7.2.tar.gz">https://github.com/xmake-io/xmake/archive/refs/tags/v2.7.2.tar.gz</a></li>
<li>Full source package: <a href="https://github.com/xmake-io/xmake/releases/download/v2.7.2/xmake-v2.7.2.tar.gz">https://github.com/xmake-io/xmake/releases/download/v2.7.2/xmake-v2.7.2.tar.gz</a></li>
</ul>
<pre><code class="lang-bash">$ wget https://github.com/xmake-io/xmake/releases/download/v2.7.2/xmake-v2.7.2.tar.gz
$ tar -xvf xmake-v2.7.2.tar.gz -C xmake
$ cd xmake
</code></pre>
<p>! > The Xmake tarball does not have a top-level xmake root directory, so it is best to unpack it with <code>-C xmake</code> to specify the output directory.</p>
<h3 id="compilingsourcecode">Compiling source code</h3>
<h4 id="compilingonwindows">Compiling on Windows</h4>
<p>If you are compiling Xmake source code on Windows, you will need to bootstrap it with an existing Xmake pre-build.</p>
<p>Therefore we need to first install Xmake by referring to the <a href="https://xmake.io/#/zh-cn/guide/installation?id=windows">Installing Xmake on Windows</a> documentation.</p>
<p>Then go to the Xmake source directory and compile.</p>
<pre><code class="lang-bash">cd xmake
cd core
xmake
</code></pre>
<p>! > We need to go into the core subdirectory of Xmake and execute the xmake command.</p>
<h4 id="compilingonlinuxmacosfreebsd">Compiling on Linux/macOS/FreeBSD</h4>
<p>To compile Xmake on other unix-like environments, we just need to execute make in the source root.</p>
<pre><code class="lang-bash">$ cd xmake
$ ./configure
$ make
</code></pre>
<p>!> On macOS, you may need to run <code>export SDKROOT=$(xcrun --sdk macosx --show-sdk-path)</code> before configuration so header files can be found at build time.</p>
<h3 id="loadingdebugging">Loading debugging</h3>
<p>If the compilation is complete, we can load the Xmake binary core we just compiled and run the local Lua script.</p>
<h4 id="loadingthelocaldebuggingenvironmentonwindows">Loading the local debugging environment on Windows</h4>
<p>Go to the <code>xmake/scripts</code> directory and double-click on the srcenv.bat script, which will automatically load the local Xmake program and scripts and open a cmd terminal.</p>
<p>From this terminal, we can then enable debugging.</p>
<p>We can also run:</p>
<pre><code class="lang-bash">$ xmake l os.programdir
</code></pre>
<p>...to verify that we have actually loaded the local Lua scripting environment.</p>
<h4 id="loadingalocaldebuggingenvironmentonotherplatforms">Loading a local debugging environment on other platforms</h4>
<p>On Linux/macOS/FreeBSD it&#39;s a bit easier! Just run.</p>
<pre><code class="lang-bash">$ cd xmake
$ source scripts/srcenv.profile
</code></pre>
<p>to get into the local source debugging environment.</p>
<h3 id="debuggingcorebinary">Debugging core binary</h3>
<p>Normally, to debug Xmake&#39;s Lua scripts, you just need to modify the Lua scripts in the current source directory, which takes effect in real time, and we don&#39;t need to recompile the core binary.</p>
<p>However, if there is a problem with Xmake&#39;s C-side core program and you need to debug it or add modules to it, you will need to recompile it.</p>
<p>You can use Xmake&#39;s internal logging functions like so to aide in debugging:</p>
<pre><code class="lang-c">tb_trace_i("hello %s", "xmake");
</code></pre>
<p>If there is a problem with the various submodules that Xmake relies on, such as tbox, and you need to debug it, you can also go directly to the submodule source code, modify it and recompile it for execution.</p>
<p>However, if we need to contribute a patch, we need to commit PR to the submodule&#39;s repository and the patch will be merged and synced to the Xmake source repository by the author at a later date and time.</p>
<h3 id="breakpointdebugging">Breakpoint Debugging</h3>
<p>In version 2.8.3, we added Lua breakpoint debugging support, with <a href="https://github.com/EmmyLua/VSCode-EmmyLua">VSCode-EmmyLua</a> plugin, we can easily debug Xmake source code in VSCode breakpoints.</p>
<p>First of all, we need to install VSCode-EmmyLua plugin in VSCode&#39;s plugin market, and then run the following command to update the xmake-repo repository to keep it up-to-date.</p>
<pre><code class="lang-bash">xrepo update-repo
</code></pre>
<p>!> Xmake also needs to be kept up to date.</p>
<p>Then, execute the following command in your own project directory:</p>
<pre><code class="lang-bash">$ xrepo env -b emmylua_debugger -- xmake build
</code></pre>
<p>The <code>xrepo env -b emmylua_debugger</code> is used to bind the EmmyLua debugger plugin environment, and the arguments after <code>--</code> are the actual xmake commands we need to debug.</p>
<p>Usually we just debug the <code>xmake build</code> build, but if you want to debug other commands, you can tweak it yourself, for example, if you want to debug the <code>xmake install -o /tmp</code> install command, you can change it to:</p>
<pre><code class="lang-bash">$ xrepo env -b emmylua_debugger -- xmake install -o /tmp
</code></pre>
<p>After executing the above command, it will not exit immediately, it will remain in a waiting debugging state, possibly without any output.</p>
<p>At this point, instead of exiting it, let&#39;s go ahead and open VSCode and open Xmake&#39;s Lua script source directory in VSCode.</p>
<p>That is, this directory: <a href="https://github.com/xmake-io/xmake/tree/master/xmake">Xmake Lua Scripts</a>, which we can download locally or directly open the lua script directory in the Xmake installation directory.</p>
<p>Then switch to VSCode&#39;s debugging tab and click <code>RunDebug</code> -> <code>Emmylua New Debug</code> to connect to our <code>xmake build</code> command debugger and start debugging.</p>
<p>As you can see below, the default start breakpoint will automatically break inside <code>debugger:_start_emmylua_debugger</code>, and we can click on the single-step to jump out of the current function, which will take us to the main entry.</p>
<p><img src="/assets/img/manual/xmake-debug.png" alt=""></p>
<p>Then set your own breakpoint and click Continue to Run to break to the code location you want to debug.</p>
<p>We can also set breakpoints in our project&#39;s configuration scripts, which also allows us to quickly debug our own configuration scripts, not just Xmake&#39;s own source code.</p>
<p><img src="/assets/img/manual/xmake-debug2.png" alt=""></p>
<h3 id="remotedebugging">Remote debugging</h3>
<p>Version 2.8.3 now supports remote debugging, but this feature is mainly for the author, because the author&#39;s development computer is a mac, but sometimes he still needs to be able to debug xmake source scripts on windows.</p>
<p>But debugging in a virtual machine is too laggy, not good experience, and the author&#39;s own computer does not have enough disk space, so I usually connect to a separate windows host to debug xmake source code remotely.</p>
<p>Let&#39;s start the remote compilation service on the windows machine:</p>
<pre><code class="lang-bash">$ xmake service
</code></pre>
<p>Then locally, open the project directory where you want to build, make a remote connection, and then run <code>xmake service --sync --xmakesrc=</code> to synchronise the local source:</p>
<pre><code class="lang-bash">$ xmake service --connect
$ xmake service --sync --xmakesrc=~/projects/personal/xmake/xmake/
$ xmake build
$ xmake run
</code></pre>
<p>This way, we can modify the xmake script source locally, sync it to a remote windows machine, and then execute the xmake build command remotely to get the corresponding debug output and analyse the build behaviour.</p>
<p>We can also pull the remote files back to the local machine for analysis with the <code>xmake service --pull=</code> command.</p>
<p>Note: See <a href="http://xmake.io/#/features/remote_build">Remote Build Documentation</a> for a detailed description of remote build features.</p>
<p><img src="/assets/img/manual/xmake-remote.png" alt=""></p>
<h2 id="howtodebugrepositorypackages">How to debug repository packages?</h2>
<p>There are many different ways to debug, here I will focus on the most common debugging method used by the author, which is to pull the xmake-repo repository directly to debug.</p>
<pre><code class="lang-bash">$ git clone https://github.com/xmake-io/xmake-repo.git
$ xmake l scripts/test.lua -vD --shallow zlib
</code></pre>
<p>Using the <code>test.lua</code> script command above to debug packages, we can repeatedly install and test the specified package. <code>--shallow</code> tells Xmake not to repeat the full installation of all its dependencies for each test, but only to test the current package.</p>
<p>We can also test specific platforms, architectures, build modes, vs_runtime and dynamic libraries, static libraries etc.</p>
<pre><code class="lang-bash">$ xmake l scripts/test.lua -vD --shallow -p mingw --mingw=/xxx/sdk zlib
$ xmake l scripts/test.lua -vD --shallow -p iphoneos -a arm64 zlib
$ xmake l scripts/test.lua -vD --shallow -k shared --vs_runtime=MD zlib
$ xmake l scripts/test.lua -vD --shallow -m debug zlib
</code></pre>
<h3 id="debugginglocalpackagesourcecode">Debugging local package source code</h3>
<p>Sometimes, due to problems with the package source and build scripts, we need to modify some code in order to continue testing the installation,<br>and it would be very tedious to go through the debugging changes in on_install by adding_patches/io.replace.</p>
<p>Therefore, we can specify <code>-d package_sourcedir</code> to allow the test script to go directly to<br>our pre-downloaded package source directory and test the build installation without our code changes being reset each time.</p>
<pre><code class="lang-bash">$ xmake l scripts/test.lua -vD --shallow -d /tmp/zlib-1.2.11 zlib
</code></pre>
<p>Once the changes have been debugged, we then generate a patch file based on the changes via <code>git diff > fix.patch</code><br>and configure the patch package to be applied via <code>add_patches</code> to fix the package installation.</p>
<h3 id="remotedebuggingpackagesourcecode">Remote debugging package source code</h3>
<p>We can also debug the package remotely, by first enabling the remote service:</p>
<pre><code class="lang-bash">$ xmake service
</code></pre>
<p>Then pass in the <code>--remote</code> parameter to compile and test the package remotely.</p>
<pre><code class="lang-bash">$ xmake l scripts/test.lua -vD --shallow --remote /tmp/zlib-1.2.11 zlib
</code></pre>
<h2 id="whatshouldidoifthedownloadpackagefailedtogetthelocalissuercertificate">What should I do if the download package failed to get the local issuer certificate?</h2>
<pre><code class="lang-bash">curl: (60) SSL certificate problem: unable to get local issuer certificate
More details here: https://curl.se/docs/sslcerts.html

curl failed to verify the legitimacy of the server and therefore could not
To learn more about this situation and
To learn more about this situation and how to fix it, please visit the web page mentioned above.
</code></pre>
<p>If you encounter the above certificate validation problem when using Xmake to install dependencies, you can try updating the cURL certificate to fix it, or just disable certificate validation in the global configuration to bypass it.</p>
<pre><code class="lang-bash">$ xmake g --insecure-ssl=y
</code></pre>
<p>Of course, disabling certificate validation poses some security risks, but the good news is that packages in the xmake-repo repository have a strict sha256 checksum. Even if the download is hijacked, it will eventually be detected by xmake&#39;s sha256 checksum and treated as an invalid download.</p>
</article>
</body>
</html>