Jekyll2022-09-16T19:43:08+02:00https://tpiekarski.github.io/feed.xmldlqx/development/labA laboratory and a sandbox for tips, prototyping and learning of ideas, concepts and technologies in software development.Thomas PiekarskiFunctions in Makefiles2020-04-09T00:00:00+02:002020-04-09T00:00:00+02:00https://tpiekarski.github.io/blog/tips/2020/04/09/makefile-functions<p><em>When you wrote for the second time almost the same code and for the next time you started to copy & paste those code.
That sounds like you should introduce a function. Functions in Makefile can shorten and clean things up and will be
shown in the following…</em></p>
<h2 id="basic-syntax">Basic syntax</h2>
<pre><code class="language-Makefile">define print_anything
@echo "\nMakefile: $(1)\n"
endef
</code></pre>
<p>That is a simple print function taking one argument to echo with a prefix and two line breaks. Functions in a Makefile
are enclosed with the two keywords <code class="language-plaintext highlighter-rouge">define</code> and <code class="language-plaintext highlighter-rouge">endef</code> (yes, that extra d is omitted and reads rather unusual). There
is no need to define arguments of those functions, it is possible to access them directly by <code class="language-plaintext highlighter-rouge">$(1)</code> and subsequently
with <code class="language-plaintext highlighter-rouge">$(n)</code> where <code class="language-plaintext highlighter-rouge">n > 0</code>. The indention is optional what is noteworthy due to Makefile targets forcing indention.
In this particular case it can increase readability like it is always with indention.</p>
<pre><code class="language-Makefile">test:
$(call print_anything, "Testing a first function in a Makefile.")
</code></pre>
<p>The custom function <code class="language-plaintext highlighter-rouge">print</code> is called with the keyword <code class="language-plaintext highlighter-rouge">call</code> inside <code class="language-plaintext highlighter-rouge">$()</code>. The parameters are passed to the function
by specifying them inside those parenthesis separated by a comma. Makefile targets won’t complain when this comma has
been forgotten. The parameter will be silently ignored and won’t be available inside the function. Thats one drawback
of calling those functions and can lead to some time spend debugging weird issues.</p>
<h2 id="example-to-color-output-with-functions">Example to color output with functions</h2>
<p>After writing about the basic syntax of how to define and call a function it is time for a more practical example. In
the following there’re be a few functions defined to color the output of Makefiles. Three levels of messages will be
used, they read - <em>info</em>, <em>warning</em> and <em>error</em>. This time it’ll be shown the other way round.</p>
<p>That’s the target to test all three print functions:</p>
<pre><code class="language-Makefile">test_colors:
$(call print_info, "That\'s an information only.")
$(call print_warning, "That\'s a warning. Maybe you should do something.")
$(call print_error, "That\'s an error. Do something! Now!")
</code></pre>
<p>Three distinct functions are coloring the output based upon the urgency of the message.</p>
<pre><code class="language-Makefile">define print_info
$(call print, $(1), "gray")
endef
define print_warning
$(call print, $(1), "yellow")
endef
define print_error
$(call print, $(1), "red")
endef
</code></pre>
<p>All those function call another function <code class="language-plaintext highlighter-rouge">print</code> and passing next to the message itself another parameter naming the
color.</p>
<pre><code class="language-Makefile">define print
@case ${2} in \
gray) echo "\e[90m${1}\e[0m" ;; \
red) echo "\e[91m${1}\e[0m" ;; \
yellow) echo "\e[93m${1}\e[0m" ;; \
*) echo "\e[97m${1}\e[0m" ;; \
esac
endef
</code></pre>
<p>This named color is processed by a switch-case-block which matches the human-readable name to the corresponding
terminal control sequence. A fallback will color everything white, should the function called directly.</p>
<p>That’s it, a short and direct primer to functions inside Makefiles without too many words describing probably obvious
things. Like always there is much more to write about functions, but to be frank I even did not check upon further
things which I could maybe add to that blog post here. Used to discover things in passing when I need them, instead
of studying manuals in advance. But people deal in different ways with learning new things and thats another story
for another blog post.</p>
<h2 id="downloads">Downloads</h2>
<ul>
<li><a href="https://tpiekarski.github.io/downloads/Makefile-functions.mk">Makefile-functions.mk</a> contains both examples</li>
</ul>
<p>To check both examples, run…</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>make <span class="nt">-f</span> Makefile-functions.mk <span class="nb">test
</span>make <span class="nt">-f</span> Makefile-functions.mk test_colors
</code></pre></div></div>
<h2 id="links">Links</h2>
<ul>
<li>FLOZz’ MISC, <a href="https://misc.flogisoft.com/bash/tip_colors_and_formatting">Bash tips: Colors and formatting</a>
by Fabien Loison</li>
<li>GNU Makefile, <a href="https://www.gnu.org/software/make/manual/html_node/Functions.html">Functions</a></li>
<li>Linuxize, <a href="https://linuxize.com/post/bash-case-statement/">Bash Case Statement</a></li>
</ul>Thomas PiekarskiWhen you wrote for the second time almost the same code and for the next time you started to copy & paste those code. That sounds like you should introduce a function. Functions in Makefile can shorten and clean things up and will be shown in the following…Snippets for Visual Studio Code2020-04-03T00:00:00+02:002020-04-03T00:00:00+02:00https://tpiekarski.github.io/blog/tips/2020/04/03/vsc-snippets<p><em>Typing ‘for’, ‘if’, ‘main’… and hitting tab to expand a snippet can save some time.</em></p>
<p><em>Snippets in any editor or environment saves time typing, as well as sometimes the devs sanity - preventing dull
repetitive tasks. In Visual Studio Code it is straight forward to write snippets for different files and subsequently
the basic syntax gets shown. Sometimes I wish I had a snippet for those little articles, but there’s none, so have to
keep writing ;)</em></p>
<h2 id="a-first-simple-snippet">A first simple snippet</h2>
<p>Snippets are stored in JSON files and can be created within Visual Studio Code by Menu <em>File » Preferences » User
snippets</em>. The dialog will offer either to edit present snippets or to create new global or workspace ones with
predefined scopes. Scopes are definitions for which files snippets should be available. In this first simple snippet
common keys are presented and it looks like that here…</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nl">"First snippet"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="nl">"scope"</span><span class="p">:</span><span class="w"> </span><span class="s2">"markdown"</span><span class="p">,</span><span class="w">
</span><span class="nl">"prefix"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="s2">"snip"</span><span class="w">
</span><span class="p">],</span><span class="w">
</span><span class="nl">"body"</span><span class="p">:</span><span class="w"> </span><span class="s2">"That's a snippet to get that post going..."</span><span class="p">,</span><span class="w">
</span><span class="nl">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"First example snippet"</span><span class="w">
</span><span class="p">},</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<p>Snippets consists of an JSON object with key-value pairs and the common four keys are…</p>
<ol>
<li>scope [optional] - defines the files/filetypes for which a snippet should be available</li>
<li>prefix - defines the keyword to trigger snippet selection</li>
<li>body - contains what should be inserted for that snippet</li>
<li>description [optional] - a description about what a snippet is or could be good for</li>
</ol>
<h2 id="jumping-through-snippets">Jumping through snippets</h2>
<p>When such a snippet is expanded - the prefix turn to the body it is possible to control the location of subsequent tab
key strokes. In doing so it will be like fast forwarding through the body of the snippet and entering the important
and custom pieces.</p>
<div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w">
</span><span class="nl">"Second snippet"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
</span><span class="nl">"scope"</span><span class="p">:</span><span class="w"> </span><span class="s2">"markdown"</span><span class="p">,</span><span class="w">
</span><span class="nl">"prefix"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="s2">"snap"</span><span class="w">
</span><span class="p">],</span><span class="w">
</span><span class="nl">"body"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="w">
</span><span class="s2">"That's a snippet to show how to control tab..."</span><span class="p">,</span><span class="w">
</span><span class="s2">"1. ${1}"</span><span class="p">,</span><span class="w">
</span><span class="s2">"2. ${2:Second point}"</span><span class="p">,</span><span class="w">
</span><span class="s2">"3. ${3|Third point,3rd point,another point|}"</span><span class="p">,</span><span class="w">
</span><span class="s2">"${0}"</span><span class="w">
</span><span class="p">],</span><span class="w">
</span><span class="nl">"description"</span><span class="p">:</span><span class="w"> </span><span class="s2">"Second example snippet"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></code></pre></div></div>
<p>When this snippet gets expanded the second tab key stroke will get you to <code class="language-plaintext highlighter-rouge">${1}</code> and all subsequent tabs to subsequent
<code class="language-plaintext highlighter-rouge">${n}</code>. It will end at <code class="language-plaintext highlighter-rouge">{0}</code> which marks the exit point of the snippet, so to say. The second <code class="language-plaintext highlighter-rouge">${2}</code> provides a default
value when there could be something used over and over again. And the last and third one <code class="language-plaintext highlighter-rouge">${3}</code> offers two options to
choose from.</p>
<p>That is a starter about creating snippets to ease writing code and can be used also
to scaffold files in a much faster way than copy/pasting things around. Sure there is
more about snippets, but for writing more about them I’d really need a snippet to
expand :P</p>
<h2 id="downloads">Downloads</h2>
<ul>
<li><a href="https://tpiekarski.github.io/downloads/examples.code-snippets">examples.code-snippets</a> containing
both example snippets</li>
</ul>
<h2 id="links">Links</h2>
<ul>
<li><a href="https://code.visualstudio.com/docs/editor/userdefinedsnippets">Snippets in Visual Studio Code</a></li>
</ul>Thomas PiekarskiTyping ‘for’, ‘if’, ‘main’… and hitting tab to expand a snippet can save some time.Testing at CLI level2020-03-26T00:00:00+01:002020-03-26T00:00:00+01:00https://tpiekarski.github.io/blog/tips/2020/03/26/testing-at-cli<p><em>Testing can be tedious, testing can be tricky and testing can drive whole development… insane ;)
But it is an important part of professional software development, but sometimes usually late at night only one line can make the trick.
And staying with a shell - the environment devops used to use a lot it gets even more easier to write little one-line tests</em></p>
<p>This little blog post is about that. Writing little one-line tests for comparing two values. And either proceeding happily or aborting
sullenly after some change which you hoped to work out.</p>
<h2 id="the-command-test">The command test</h2>
<p>Part of the package coreutils is the executable test which can be used to test simple expressions. It is used quite often inside shell scripts to
check if some file is around or a directory is accessible. This command can be used for the described purpose and thats what will be looked at.
The basic syntax is unambiguous and rather easy to grasp. It consists most of the time of two values which should be compared and an operator.
In the first one of the following examples something stored in VALUE should be equal to 10. The next one tests if the file foo exists and the last
one checks if the contents of this file foo is equal to something (with the help of cat).</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">test</span> <span class="nv">$VALUE</span> <span class="nt">-eq</span> 10
<span class="nb">test</span> <span class="nt">-f</span> foo
<span class="nb">test</span> <span class="si">$(</span><span class="nb">cat </span>foo<span class="si">)</span> <span class="o">=</span> <span class="s2">"something"</span>
</code></pre></div></div>
<p>The result of such tests can be concatenate with further actions. And if such a test fails a script or Makefile can abort or if succeeds it can
echo some relief.</p>
<h2 id="further-actions-by-concatenation">Further actions by concatenation</h2>
<p>Within shell scripting such further actions like mentioned before would expect an if; then; (else)…fi. But all of this can be also written
in only one line.</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">test</span> <span class="nv">$VALUE</span> <span class="nt">-eq</span> 10 <span class="o">&&</span> <span class="nb">echo</span> <span class="s2">"Value is indeed 10."</span> <span class="o">||</span> <span class="nb">echo</span> <span class="s2">"Something broke!"</span>
</code></pre></div></div>
<p>The command test returns a value after the expression was processed. This return value can be passed along and based upon that value
it is possible to take further action. The line above shows how to accomplish such further actions. When the contents of $VALUE is 10
the first one and when it is not the second message is echoed.</p>
<h2 id="application-inside-makefiles">Application inside Makefiles</h2>
<p>This simple and easy one-liner can be used inside Makefiles to test if something worked out in our favor.</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>@test <span class="nt">-f</span> /proc/some_new_proc_file <span class="se">\</span>
<span class="o">||</span> <span class="o">(</span><span class="nb">echo</span> <span class="s2">"New proc file could not be found, aborting."</span><span class="p">;</span> <span class="nb">exit </span>1<span class="o">)</span>
</code></pre></div></div>
<p>The above example present a possible usage of these one-line tests. Imagine running a test target and after loading a kernel module which
registers a proc entry. The Makefile should make sure if there is this new proc file before attempting to read out some value in the
successive step. This can be established with test and concatenate a group of commands. Here a message is echoed and then the current
target is exited with a non-zero return value.</p>
<p>For concluding this blog post there are many different solutions how to test. There are huge ones, hard to configure and fuzzy to use.
There are modern ones, easy to use but still with some effort and time to spent on. Sometimes the closest solution at hand can come in
convenient when you want to make sure nothing broke after changing things.</p>Thomas PiekarskiTesting can be tedious, testing can be tricky and testing can drive whole development… insane ;) But it is an important part of professional software development, but sometimes usually late at night only one line can make the trick. And staying with a shell - the environment devops used to use a lot it gets even more easier to write little one-line testsVariables and Makefiles2020-03-25T00:00:00+01:002020-03-25T00:00:00+01:00https://tpiekarski.github.io/blog/tips/2020/03/25/variables-and-makefiles<p><em>Makefiles are long, they tend to be complex and we used to have a configure script which built them for us. Did you
ever looked into such generated Makefile, maybe a file of one of a bigger project?
For me they seem sometimes like one long regexp ;)</em></p>
<p>Of course they come in handy and in small projects they seem to stay readable and manageable. At least for some time.</p>
<p>While discovering a little the odds and ends of module development for the Linux Kernel I stumbled upon the need to use
a Makefile in a more advanced way than just to call a compiler. That Makefile grew with every little module I came up
with and suddenly I faced myself with the urge to introduce variables.</p>
<h2 id="variables-for-multiple-targets">Variables for multiple targets</h2>
<p>The first kind of variables are the one most straightforward and obvious to use. They are usually defined at the top
of the Makefile and can be used in every target. Thats how for example additional things for the include path or some
arguments to the compiler are passed. See the following example of how such variables for multiple targets are used.
The variable <em>var</em> with the value <em>something</em> will be available in both targets.</p>
<pre><code class="language-Makefile">var = something
example-1:
@echo $(var)
example-2:
@echo $(var)
</code></pre>
<h2 id="variables-for-single-targets">Variables for single targets</h2>
<p>When variables should be used only inside one target, they are going to be defined in another way. For that madder
<em>eval</em> can be used to define a variable local inside the current target. In the following little example the variable
<em>var</em> with the value anything will be only available inside the target <em>example-3</em> and not in the following <em>example-4</em>.</p>
<pre><code class="language-Makefile">example-3:
$(eval var = nothing)
@echo $(var)
example-4:
@echo $(var)
</code></pre>
<p>In that example target it will be still the value <em>something</em> which was defined earlier. If all those example targets
are written down in one Makefile. That is also one convenient way to overwrite a value defined for multiple targets.</p>
<h2 id="variables-within-variables">Variables within variables</h2>
<p>In the next example variables will be based upon other variables and mixed within scope of targets.</p>
<pre><code class="language-Makefile">example-5:
$(eval message = $(var) could be made with that Makefile)
@echo $(message)
</code></pre>
<p>So is this Makefile going to do something or nothing? Reviewing once more the above two use cases for variables this
target should output <em>something could be made with that Makefile</em>. And it is going to output that. In such a way it
is possible to use variables within variables.</p>
<h2 id="variables-coming-from-outside">Variables coming from outside</h2>
<p>The last thing which comes up to my mind what could be helpful when it comes down to variables is to use values from
outside. When make is executed at CLI it is possible to pass not only the targets name but parameters as well.
Imagine calling make in the following way:</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>make example-5 <span class="nv">var</span><span class="o">=</span>anything
</code></pre></div></div>
<p>Can be anything done with Makefiles? Yes, it seems so. The output will be <em>anything could be made with that Makefile</em>
and illustrates how to overwrite defined variables from outside the Makefile. This procedure is I think is common when
for example the include path should be changed based upon a different environment. Or something optional should be
compiled into a project, like debug output. At least I used to use it in such a way. In the last example something
from outside will be referenced inside another variable.</p>
<pre><code class="language-Makefile">example-6:
$(eval bottom-line=$(outside) $(message))
@echo $(bottom-line)
</code></pre>
<p>When calling this target in the following way the bottom line of the Makefile which was written example-by-example and
the bottom line of this little post will be reached. The output will be build by two variables and will read <em>with
variables can be done in different ways.</em></p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>make example-6 outside-value<span class="o">=</span><span class="s2">"with variables can be done in different ways."</span>
</code></pre></div></div>
<p>Sure I am there is much more about Makefiles and variables and there are more different ways to use variables.
But for a first variable to be defined it will work :)</p>
<h2 id="downloads">Downloads</h2>
<ul>
<li><a href="https://tpiekarski.github.io/downloads/Makefile-variables.mk">Makefile-variables.mk</a> containing all six examples</li>
</ul>
<p>To check examples, run <code class="language-plaintext highlighter-rouge">make -f Makefile-variables.mk example-n</code>, where n is the number of one of the six examples.</p>
<h2 id="links">Links</h2>
<ul>
<li>GNU make, <a href="https://www.gnu.org/software/make/manual/html_node/Using-Variables.html">Using Variables</a></li>
</ul>Thomas PiekarskiMakefiles are long, they tend to be complex and we used to have a configure script which built them for us. Did you ever looked into such generated Makefile, maybe a file of one of a bigger project? For me they seem sometimes like one long regexp ;)Dealing with typos with typo-aliasing2019-02-24T00:00:00+01:002019-02-24T00:00:00+01:00https://tpiekarski.github.io/blog/tips/2019/02/24/dealing-with-typos<p><em>Did you ever thought of alias typos in your shell alias file?</em></p>
<p>Something like this. Well you could say: go and learn to type, but hey… :)</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">alias </span><span class="nv">ks</span><span class="o">=</span><span class="s2">"ls"</span>
<span class="nb">alias </span>ös<span class="o">=</span><span class="s2">"ls"</span>
<span class="nb">alias </span>öls<span class="o">=</span><span class="s2">"ls"</span>
<span class="nb">alias </span>lös<span class="o">=</span><span class="s2">"ls"</span>
<span class="nb">alias </span><span class="nv">lks</span><span class="o">=</span><span class="s2">"ls"</span>
<span class="nb">alias </span><span class="nv">mroe</span><span class="o">=</span><span class="s2">"more"</span>
<span class="nb">alias </span><span class="nv">les</span><span class="o">=</span><span class="s2">"less"</span>
<span class="nb">alias </span><span class="nv">hit</span><span class="o">=</span><span class="s2">"git"</span>
<span class="nb">alias </span><span class="nv">exitz</span><span class="o">=</span><span class="s2">"exit"</span>
</code></pre></div></div>
<p>After I encountered sometimes mistyping a handful of commands in the same way more often I decided to alias them.
Just in case for the next typo. But I tend not to typo-alias anything critical like rm, that could end fatal ;)</p>
<p>With allowing duplicates in a big sized shell history file you can take a look how often such typo-alias have been
used and decide if they’re useful or you should book a course in typewriting. This way identifying what to alias in
general is helpful as well. Of course you’ve got to live with those duplicate entries when going up the history. I
tend to always use reverse search and can live with those duplicates (at least for some time).</p>
<p>But some other way of statistics about how often you use which command could be a nice new side project.</p>Thomas PiekarskiDid you ever thought of alias typos in your shell alias file?Nudging build pipelines2019-02-24T00:00:00+01:002019-02-24T00:00:00+01:00https://tpiekarski.github.io/blog/tips/2019/02/24/nudging-build-pipeline<p><em>When setting up a build pipeline with for example TravisCI or AppVeyor did the first build worked out?</em></p>
<p>For me it fails most of time and I’ve got to tweak the configuration and test again. Usually you’d rerun the task, but
sometimes you have to commit anything to go through the whole cycle including git and probably some hooks for Jenkins,
Gerrit, Crucible, Sonar, Coverall, etc. as well.</p>
<p>When you finished configuration and want to retry (perhaps for a second time - only to be sure) try not change anything
somewhere and commit, instead allow an empty commit like this:</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git commit <span class="nt">-m</span> <span class="s2">"Want to be sure for n-th time that pipeline works"</span> <span class="nt">--allow-empty</span>
</code></pre></div></div>
<p>Nevertheless I’ll try to avoid that and commit empty things only when finishing and testing pipelines
(or nudging impatiently jekyll to update that pages here ;)).</p>Thomas PiekarskiWhen setting up a build pipeline with for example TravisCI or AppVeyor did the first build worked out?When to prefer output over breakpoints2019-02-24T00:00:00+01:002019-02-24T00:00:00+01:00https://tpiekarski.github.io/blog/office/2019/02/24/when-to-prefer-output-over-breakpoint<p><em>When do you prefer raw console output over using a debugger and setting breakpoints?</em></p>
<p>At work in the office I recently been a part of a mob debugging session where a few developers came together to analyze
and hopefully solve a bug in Frontend validation. We ventured a few times through the code, talked about this and about
that. Dived into the callstack and wondered where this false validation is coming from.</p>
<p>Very keen to solve this puzzle we used the debugger and started to set up breakpoints, soon that points have been all
over the place. But the bug managed to avoid us, our breakpoints and all of our countermeasures and hid very well.</p>
<p>Only one little detail we missed. With all those breakpoints in place we did not see that the validation ran twice.</p>
<p>The first validation succeeded, but the second validation, triggered by something failed. Between this two validations
the field was modified in a way that first of all triggered the second validation and then altered the field value in
such a way that this second validation failed.</p>
<p>By coincidence another developer dropped by and saw that second validation.
So now another puzzle occurred how we did not see this two rounds of validation right from the start.</p>
<p><strong>The learning I took from this experience is to be not too keen about debuggers and breakpoints.
Sometimes a simple log of values to the console can make the trick.</strong><br />
(or just another dev dropping by :))</p>Thomas PiekarskiWhen do you prefer raw console output over using a debugger and setting breakpoints?