This repository has been archived on 2022-07-17. You can view files and clone it, but cannot push or open issues or pull requests.
arsenm-dev-site/public/docs/advmake/build-files/index.html

73 lines
21 KiB
HTML
Raw Normal View History

2021-02-01 00:06:57 +00:00
<!doctype html><html lang=en-us><head><meta charset=utf-8><meta http-equiv=x-ua-compatible content="ie=edge"><meta name=viewport content="width=device-width,initial-scale=1,shrink-to-fit=no"><script src=https://code.iconify.design/1/1.0.7/iconify.min.js></script><link rel=preload as=font href=/fonts/vendor/jost/jost-v4-latin-regular.woff2 type=font/woff2 crossorigin><link rel=preload as=font href=/fonts/vendor/jost/jost-v4-latin-700.woff2 type=font/woff2 crossorigin><link rel=stylesheet href=/main.7eddbef50c63a34a7ce8d3d4323fd9d90d4a1ed40f1dac16e7f06f603627c8fcb7a465d753bb51709c98661474547c7972beae0a5876e777466d416c709dea36.css integrity="sha512-ft2+9Qxjo0p86NPUMj/Z2Q1KHtQPHawW5/BvYDYnyPy3pGXXU7tRcJyYZhR0VHx5cr6uClh253dGbUFscJ3qNg==" crossorigin=anonymous><noscript><style>img.lazyload{display:none}</style></noscript><meta name=robots content="index, follow"><meta name=googlebot content="index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1"><meta name=bingbot content="index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1"><title>Build Files | Arsen Dev</title><meta name=description content="Understanding AdvMake Build Files"><link rel=canonical href=/docs/advmake/build-files/><meta name=twitter:card content="summary"><meta name=twitter:title content="Build Files"><meta name=twitter:description content="Understanding AdvMake Build Files"><meta name=twitter:site content="@"><meta name=twitter:creator content="@"><meta property="og:title" content="Build Files"><meta property="og:description" content="Understanding AdvMake Build Files"><meta property="og:type" content="article"><meta property="og:url" content="/docs/advmake/build-files/"><meta property="og:site_name" content="Arsen Dev"><meta property="article:publisher" content="https://www.facebook.com/"><meta property="article:author" content="https://www.facebook.com/"><meta property="og:locale" content><script type=application/ld+json>{"@context":"http://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"\/"},{"@type":"ListItem","position":2,"name":"Docsadvmakebuild Files","item":"\/docsadvmakebuild-files\/"}]}</script><meta name=theme-color content="#fff"><link rel=apple-touch-icon sizes=180x180 href=/apple-touch-icon.png><link rel=icon type=image/png sizes=32x32 href=/favicon-32x32.png><link rel=icon type=image/png sizes=16x16 href=/favicon-16x16.png><link rel=manifest href=/site.webmanifest></head><body class="docs single"><div class="header-bar fixed-top"></div><header class="navbar fixed-top navbar-expand-md navbar-light"><div class=container><input class="menu-btn order-0" type=checkbox id=menu-btn>
<label class="menu-icon d-md-none" for=menu-btn><span class=navicon></span></label><a class="navbar-brand order-1 order-md-0 mr-auto" href=/>Arsen Dev</a>
<button id=mode class="btn btn-link order-2 order-md-4" type=button aria-label="Toggle mode">
<span class=toggle-dark><svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentcolor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-moon"><path d="M21 12.79A9 9 0 1111.21 3 7 7 0 0021 12.79z"/></svg></span><span class=toggle-light><svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentcolor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-sun"><circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3"/><line x1="12" y1="21" x2="12" y2="23"/><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/><line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/><line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/><line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/><line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/></svg></span></button><ul class="navbar-nav social-nav order-3 order-md-5"><li class=nav-item><a class=nav-link href=https://gitea.arsenm.dev/Arsen6331><span class=iconify data-icon=cib:gitea data-inline=false></span><span class="ml-2 sr-only">Gitea</span></a></li><li class=nav-item><a class=nav-link href=https://gitlab.com/moussaelianarsen><span class=iconify data-icon=fa-brands:gitlab data-inline=false></span><span class="ml-2 sr-only">GitLab</span></a></li></ul><div class="collapse navbar-collapse order-4 order-md-1"><ul class="navbar-nav main-nav mr-auto order-5 order-md-2"><li class=nav-item><a class=nav-link href=/>Home</a></li><li class="nav-item active"><a class=nav-link href=/docs/>Docs</a></li></ul><div class="break order-6 d-md-none"></div><form class="navbar-form flex-grow-1 order-7 order-md-3"><input id=userinput class="form-control is-search" type=search placeholder="Search docs..." aria-label="Search docs..." autocomplete=off><div id=suggestions class="shadow bg-white rounded"></div></form></div></div></header><div class="wrap container" role=document><div class=content><div class="row flex-xl-nowrap"><div class="col-lg-5 col-xl-4 docs-sidebar"><nav class=docs-links aria-label="Main navigation"><h3>Docs</h3><ul class=list-unstyled><li><a class=docs-link href=/docs/advmake/>AdvMake Docs</a></li><li><a class=docs-link href=/docs/opensend/>OpenSend Docs</a></li><li><a class=docs-link href=/docs/pak/>Pak Docs</a></li></ul></nav></div><nav class="docs-toc d-none d-xl-block col-xl-3" aria-label="Secondary navigation"><div class=page-links><h3>On this page</h3><nav id=TableOfContents><ul><li><ul><li><a href=#format>Format</a></li><li><a href=#configuration>Configuration</a></li><li><a href=#builtins>Builtins</a></li></ul></li></ul></nav></div></nav><main class="docs-content col-lg-11 col-xl-9 mx-xl-auto"><a href=..>&lArr; AdvMake Docs</a><h1 style=margin-top:.2rem>Build Files</h1><p class=lead></p><p><a class=btn style=color:#fff;background-color:green href=https://gitea.arsenm.dev/Arsen6331/advmake><span class=iconify data-icon=cib:gitea></span>&nbsp;AdvMake</a>
<a class=btn style=color:#fff;background-color:OrangeRed href=https://www.gitlab.com/moussaelianarsen/advmake><span class=iconify data-icon=fa-brands:gitlab></span>&nbsp;AdvMake</a></p><h3 id=format>Format<a href=#format class=anchor aria-hidden=true>#</a></h3><p>AdvMake uses <a href=https://github.com/bazelbuild/starlark>Starlark</a> as the format for its build files.
Extra builtins are also defined for both convenience and extra functionality.</p><p>Starlark is a Python-like language meant for configuration files.</p><h3 id=configuration>Configuration<a href=#configuration class=anchor aria-hidden=true>#</a></h3><p>Build files are by default called <code>AdvMakefile</code>, but that can be set via <code>-f</code></p><p>An AdvMakefile example can be found at AdvMake&rsquo;s repo as it uses AdvMake itself.</p><p>AdvMake runs functions exposed by starlark in the format <code>&lt;name>_&lt;target></code>.
To set the default name and target, the global variables <code>defaultName</code>, and <code>defaultTarget</code> must be set.
Here is an example from AdvMake&rsquo;s AdvMakefile:</p><div class=highlight><pre class=chroma><code class=language-python data-lang=python><span class=n>defaultName</span> <span class=o>=</span> <span class=s2>&#34;advmake&#34;</span>
<span class=n>defaultTarget</span> <span class=o>=</span> <span class=s2>&#34;build&#34;</span>
</code></pre></div><p>This will tell AdvMake to run the function <code>advmake_build()</code> when run with no arguments.</p><p>If AdvMake is run with one argument (such as <code>advmake install</code>), it will use the default name with the specified target,
so in that case, it would run <code>advmake_install()</code>.</p><p>If run with two arguments, AdvMake will use the first argument as the name and the second as the target.
So, running <code>advmake hello world</code> would run the function <code>hello_world()</code>.</p><h3 id=builtins>Builtins<a href=#builtins class=anchor aria-hidden=true>#</a></h3><p>As previously mentioned, AdvMake comes with extra builtins. Those are as follows:</p><h4 id=log><code>log()</code><a href=#log class=anchor aria-hidden=true>#</a></h4><p>The log function uses zerolog in go to log a message to STDOUT. It has two arguments.
The first is a string with the message to log, and the second is <code>level</code> which is optional</p><p>Examples:</p><div class=highlight><pre class=chroma><code class=language-python data-lang=python><span class=n>log</span><span class=p>(</span><span class=s2>&#34;Info log&#34;</span><span class=p>)</span> <span class=c1># Default level is info</span>
<span class=n>log</span><span class=p>(</span><span class=s2>&#34;Warn log&#34;</span><span class=p>,</span> <span class=n>level</span><span class=o>=</span><span class=s2>&#34;warn&#34;</span><span class=p>)</span> <span class=c1># Warn level log</span>
<span class=n>log</span><span class=p>(</span><span class=s2>&#34;Debug log&#34;</span><span class=p>,</span> <span class=n>level</span><span class=o>=</span><span class=s2>&#34;debug&#34;</span><span class=p>)</span> <span class=c1># Debug level log</span>
<span class=n>log</span><span class=p>(</span><span class=s2>&#34;Fatal log&#34;</span><span class=p>,</span> <span class=n>level</span><span class=o>=</span><span class=s2>&#34;fatal&#34;</span><span class=p>)</span> <span class=c1># Fatal level log. This will exit the program when executed</span>
</code></pre></div><hr><h4 id=execute><code>execute()</code><a href=#execute class=anchor aria-hidden=true>#</a></h4><p>The execute function runs a script using <code>sh -c</code>. This function has three arguments.
The first is required and is a string with the script to run, the second is <code>output</code>
which is optional. It can be set to <code>return</code>, <code>stdout</code>, or <code>both</code>, and the default is <code>both</code>.</p><p>The <code>output</code> argument controls where the script&rsquo;s output will be directed:</p><ul><li><code>return</code>: Returns script output as string</li><li><code>stdout</code>: Prints script output to STDOUT, returning nothing</li><li><code>both</code>: Prints to STDOUT and returns as string</li></ul><p>The third argument is <code>concurrent</code> which can be either <code>True</code> or <code>False</code>, default <code>False</code>.
If <code>concurrent</code> is set to <code>True</code>, all the lines in the script will be split and run concurrently
via goroutines. The maximum threads for goroutines can be controlled using the <code>GOMAXPROCS</code> environment
variable and is by default the amount of CPU cores present.</p><p>Examples:</p><div class=highlight><pre class=chroma><code class=language-python data-lang=python><span class=n>user</span> <span class=o>=</span> <span class=n>execute</span><span class=p>(</span><span class=s2>&#34;whoami&#34;</span><span class=p>)</span> <span class=c1># This will print the username to STDOUT and set the user variable to it</span>
<span class=n>user</span> <span class=o>=</span> <span class=n>execute</span><span class=p>(</span><span class=s2>&#34;whoami&#34;</span><span class=p>,</span> <span class=n>output</span><span class=o>=</span><span class=s2>&#34;return&#34;</span><span class=p>)</span> <span class=c1># This will set the user variable to the username but not print it</span>
<span class=n>execute</span><span class=p>(</span><span class=s2>&#34;&#34;&#34;
</span><span class=s2>cp file destination
</span><span class=s2>mv destination destination-1
</span><span class=s2>echo &#39;hello world&#39;
</span><span class=s2>&#34;&#34;&#34;</span><span class=p>)</span> <span class=c1># Example of a multiline script</span>
<span class=n>execute</span><span class=p>(</span><span class=s2>&#34;&#34;&#34;
</span><span class=s2>install -Dm755 program /usr/bin
</span><span class=s2>install -Dm755 program.cfg /etc
</span><span class=s2>&#34;&#34;&#34;</span><span class=p>,</span> <span class=n>concurrent</span><span class=o>=</span><span class=bp>True</span><span class=p>)</span> <span class=c1># Example of a concurrent multiline script</span>
</code></pre></div><hr><h4 id=getenv><code>getEnv()</code><a href=#getenv class=anchor aria-hidden=true>#</a></h4><p>The getEnv function simply returns the value of the environment variable specified in its first argument.</p><p>Example:</p><div class=highlight><pre class=chroma><code class=language-python data-lang=python><span class=n>term</span> <span class=o>=</span> <span class=n>getEnv</span><span class=p>(</span><span class=s2>&#34;TERM&#34;</span><span class=p>)</span> <span class=c1># Sets variable term to value of $TERM</span>
<span class=k>print</span><span class=p>(</span><span class=s2>&#34;Nice &#34;</span> <span class=o>+</span> <span class=n>term</span><span class=p>)</span> <span class=c1># Prints &#34;Nice $TERM&#34;</span>
</code></pre></div><hr><h4 id=setenv><code>setEnv()</code><a href=#setenv class=anchor aria-hidden=true>#</a></h4><p>The setEnv function sets an environment variable. It has three arguments.
The first is the key, it is the name of the environment variable.
The second is the new value, what the key should be set to.
The third is optional, it is <code>onlyIfUnset</code> and it can be set to <code>True</code> or <code>False</code>, default <code>False</code></p><p><code>onlyIfUnset</code> checks that the variable is not already set before setting it, this can be useful for
setting defaults.</p><p>Examples:</p><div class=highlight><pre class=chroma><code class=language-python data-lang=python><span class=n>setEnv</span><span class=p>(</span><span class=s2>&#34;MY_ENV_VAR&#34;</span><span class=p>,</span> <span class=s2>&#34;Hello, World&#34;</span><span class=p>)</span> <span class=c1># Sets $MY_ENV_VAR to &#34;Hello, World&#34;</span>
<span class=n>setEnv</span><span class=p>(</span><span class=s2>&#34;CC&#34;</span><span class=p>,</span> <span class=s2>&#34;gcc&#34;</span><span class=p>,</span> <span class=n>onlyIfUnset</span><span class=o>=</span><span class=bp>True</span><span class=p>)</span> <span class=c1># Sets $CC to &#34;gcc&#34;, but only if $CC is not already set</span>
</code></pre></div><hr><h4 id=expandfile><code>expandFile()</code><a href=#expandfile class=anchor aria-hidden=true>#</a></h4><p>The expandFile function replaces all instances of $VAR with the value specified.</p><p>expandFile has two arguments. The first accepts a filename to modify.
The second accepts a dictionary to act as mappings for value replacements.</p><p>Example:</p><div class=highlight><pre class=chroma><code class=language-python data-lang=python><span class=n>expandFile</span><span class=p>(</span><span class=s2>&#34;a.txt&#34;</span><span class=p>,</span> <span class=p>{</span><span class=s2>&#34;A&#34;</span><span class=p>:</span> <span class=s2>&#34;Hello&#34;</span><span class=p>,</span> <span class=s2>&#34;B&#34;</span><span class=p>:</span> <span class=s2>&#34;World&#34;</span><span class=p>})</span> <span class=c1># Replace $A with Hello and $B with world in file a.txt</span>
</code></pre></div><hr><h4 id=download><code>download()</code><a href=#download class=anchor aria-hidden=true>#</a></h4><p>The download function downloads a file at a URL.</p><p>download has two arguments. The first is a URL, and the second is an optional
argument called <code>filename</code>. If <code>filename</code> is not provided, the filename will
be taken from the URL.</p><p>Examples:</p><div class=highlight><pre class=chroma><code class=language-python data-lang=python><span class=n>download</span><span class=p>(</span><span class=s2>&#34;https://www.arsenm.dev/logo-white.png&#34;</span><span class=p>)</span> <span class=c1># Downloads logo-white.png</span>
<span class=n>download</span><span class=p>(</span><span class=s2>&#34;https://www.arsenm.dev/logo-white.png&#34;</span><span class=p>,</span> <span class=n>filename</span><span class=o>=</span><span class=s2>&#34;logo.png&#34;</span><span class=p>)</span> <span class=c1># Downloads logo-white.png as logo.png</span>
</code></pre></div><hr><h4 id=lookpath><code>lookPath()</code><a href=#lookpath class=anchor aria-hidden=true>#</a></h4><p>The lookPath function uses go&rsquo;s <code>exec.LookPath()</code> to find the absolute path of a command.
It has a single argument which is the command to look for. If a command is not found, lookPath
returns <code>-1</code>.</p><p>Examples:</p><div class=highlight><pre class=chroma><code class=language-python data-lang=python><span class=n>lookPath</span><span class=p>(</span><span class=s2>&#34;sh&#34;</span><span class=p>)</span> <span class=c1># /bin/sh</span>
<span class=n>lookPath</span><span class=p>(</span><span class=s2>&#34;nonExistentCommand&#34;</span><span class=p>)</span> <span class=c1># -1</span>
</code></pre></div><hr><h4 id=userchoice><code>userChoice()</code><a href=#userchoice class=anchor aria-hidden=true>#</a></h4><p>The userChoice function presents the user with a choice. It has two arguments. The first
is a prompt to be displayed to the user, and the second is a list of choices.</p><p>Example:</p><div class=highlight><pre class=chroma><code class=language-python data-lang=python><span class=n>userChoice</span><span class=p>(</span><span class=s2>&#34;Choose command&#34;</span><span class=p>,</span> <span class=p>[</span><span class=s2>&#34;find&#34;</span><span class=p>,</span> <span class=s2>&#34;ls&#34;</span><span class=p>])</span>
<span class=c1># This returns:</span>
<span class=c1># [1] &#34;find&#34;</span>
<span class=c1># [2] &#34;ls&#34;</span>
<span class=c1># Choose command:</span>
</code></pre></div><p>The function will return the chosen object (if input to above is <code>1</code>, function returns <code>"find"</code>)</p><hr><h4 id=input><code>input()</code><a href=#input class=anchor aria-hidden=true>#</a></h4><p>The input function is a simple function that uses go&rsquo;s <code>fmt.Print()</code> and <code>fmt.Scanln()</code> to replicate
the functionality of python&rsquo;s <code>input()</code> function. It has a single argument, which is the prompt and returns
the inputted text.</p><p>Example:</p><div class=highlight><pre class=chroma><code class=language-python data-lang=python><span class=n>x</span> <span class=o>=</span> <span class=nb>input</span><span class=p>(</span><span class=s2>&#34;Name: &#34;</span><span class=p>)</span> <span class=c1># This will print &#34;Name: &#34; and then wait for input.</span>
</code></pre></div><hr><h4 id=fileexists><code>fileExists()</code><a href=#fileexists class=anchor aria-hidden=true>#</a></h4><p>The fileExists function checks if a specified file exists and is accessible in the filesystem. It has a single
argument which is the path to the file being checked, and returns a boolean reflecting the state of the file.</p><p>Examples:</p><div class=highlight><pre class=chroma><code class=language-python data-lang=python><span class=k>if</span> <span class=n>fileExists</span><span class=p>(</span><span class=s2>&#34;/etc/passwd&#34;</span><span class=p>):</span>
<span class=k>print</span><span class=p>(</span><span class=s2>&#34;/etc/passwd exists!&#34;</span><span class=p>)</span> <span class=c1># /etc/passwd exists!</span>
<span class=k>if</span> <span class=n>fileExists</span><span class=p>(</span><span class=s2>&#34;/abcdef&#34;</span><span class=p>):</span>
<span class=k>print</span><span class=p>(</span><span class=s2>&#34;/abcdef exists!&#34;</span><span class=p>)</span> <span class=c1># No output because /abcdef most likely does not exist</span>
</code></pre></div><hr><h4 id=getos><code>getOS()</code><a href=#getos class=anchor aria-hidden=true>#</a></h4><p>The getOS function returns the value of <code>runtime.GOOS</code>. It has no arguments.</p><p>Example:</p><div class=highlight><pre class=chroma><code class=language-python data-lang=python><span class=k>if</span> <span class=n>getOS</span><span class=p>()</span> <span class=o>==</span> <span class=s2>&#34;linux&#34;</span><span class=p>:</span>
<span class=k>print</span><span class=p>(</span><span class=s2>&#34;This is Linux!&#34;</span><span class=p>)</span>
</code></pre></div><hr><h4 id=getarch><code>getArch()</code><a href=#getarch class=anchor aria-hidden=true>#</a></h4><p>The getArch function returns the value of <code>runtime.GOARCH</code>. It has no arguments.</p><p>Example:</p><div class=highlight><pre class=chroma><code class=language-python data-lang=python><span class=k>if</span> <span class=n>getArch</span><span class=p>()</span> <span class=o>==</span> <span class=s2>&#34;386&#34;</span><span class=p>:</span>
<span class=k>print</span><span class=p>(</span><span class=s2>&#34;x86 32-bit&#34;</span><span class=p>)</span>
</code></pre></div><hr><h4 id=getcpunum><code>getCPUNum()</code><a href=#getcpunum class=anchor aria-hidden=true>#</a></h4><p>The getCPUNum function returns the amount of CPUs available to AdvMake. It has no arguments.</p><p>Example:</p><div class=highlight><pre class=chroma><code class=language-python data-lang=python><span class=k>print</span><span class=p>(</span><span class=n>getCPUNum</span><span class=p>()</span> <span class=o>+</span> <span class=s2>&#34; CPUs available!&#34;</span><span class=p>)</span>
</code></pre></div><hr></main></div></div></div><script src=/main.f6b484f556ad1f3bcf6061082139a2f21fa759f13930c39a25fe4a9f78f35e64122c2d86dffd56e67b292dabbda4095d8077194f196e0e348441c106a9f3d40e.js integrity="sha512-9rSE9VatHzvPYGEIITmi8h+nWfE5MMOaJf5Kn3jzXmQSLC2G3/1W5nspLau9pAldgHcZTxluDjSEQcEGqfPUDg==" crossorigin=anonymous defer></script><script src=/index.min.9cdd9b109f38962a87d37988a029187e94afa0a8cfd065a128ca9a3d3fff9550b5d90c1ff03fc65f1fa346b6c43c29c1ccbb7e4bb0a2f4be5619da0b1085c564.js integrity="sha512-nN2bEJ84liqH03mIoCkYfpSvoKjP0GWhKMqaPT//lVC12Qwf8D/GXx+jRrbEPCnBzLt+S7Ci9L5WGdoLEIXFZA==" crossorigin=anonymous defer></script></body></html>