<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Tomas Carnecky on Medium]]></title>
        <description><![CDATA[Stories by Tomas Carnecky on Medium]]></description>
        <link>https://medium.com/@werehamster?source=rss-568a84b64c61------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*h72aVdlDFcGkULhRqX5XSQ.jpeg</url>
            <title>Stories by Tomas Carnecky on Medium</title>
            <link>https://medium.com/@werehamster?source=rss-568a84b64c61------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sat, 21 Nov 2026 23:22:59 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@werehamster/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Why I document my React components]]></title>
            <link>https://werehamster.medium.com/why-i-document-my-react-components-3578d47ccef?source=rss-568a84b64c61------2</link>
            <guid isPermaLink="false">https://medium.com/p/3578d47ccef</guid>
            <dc:creator><![CDATA[Tomas Carnecky]]></dc:creator>
            <pubDate>Thu, 25 Mar 2021 10:05:42 GMT</pubDate>
            <atom:updated>2021-03-25T10:05:42.004Z</atom:updated>
            <content:encoded><![CDATA[<p>This article explains why I personally place so much importance on documenting the React components which I write as part of projects, and why try I do it in similar way as the third-party components which the projects rely on.</p><p>While this article describes my approach specific to React component, its ideas do not apply only to React projects. They can just as well be used in projects which use Vue, Angular and any other frontend/UI/web framework.</p><h3>Introduction</h3><p>In any non-trival project I’ll inevitably be using a component library, such as Theme UI, Chakra UI, Material-UI or some other.</p><p>These component libraries usually come with pretty good documentation. In that documentation I see how the components look and how they behave. The better libraries even provide source code which I can copy&amp;paste straight out of the documentation into my own project. The documentation is an invaluable source for both developers and designers.</p><p>Over the years I noticed that when we create our own, custom components which build on top of this solid foundation, we often don’t give their documentation the same attention. Let me show you why it is worth your while to spend a bit more time documenting your project.</p><h3>Tale of a &lt;LoaderButton&gt;</h3><p>Let’s say the component library provides a &lt;Button&gt; component. Pretty basic, right? And in my project the design asks for a particular kind of button which shows an optional loading indicator over the label, and that special button is used in many places. So it only makes sense that I create my own component which builds on top of &lt;Button&gt;. Let’s call that new component &lt;LoaderButton&gt;.</p><p>I strongly believe that a developer working with me on that project should have the same experience whether they are using &lt;Button&gt; or &lt;LoaderButton&gt;. Just looking a bit of source code that’s using either, they should not be able to tell whether the component is coming from the third-party library or not. The components should be largely interchangeable (to the extent possible), and when the developer learns how to use one, they should instantly be able to effectively use the other.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*w17pDegLRuyQQe7b0uIAIA.png" /><figcaption>Changing the &lt;Button&gt; to &lt;LoaderButton&gt; should be straight-forward and require only minimal changes.</figcaption></figure><h3>Artificial Divide</h3><p>The fact that one component was written by the component library developers and the other one by me doesn’t make them inherently any different. If we think of them as different, we’re building an artificial divide that serves no purpose.</p><p>Any divide between first- and third-party components increases friction. I can learn how to efficiently use Material-UI components, but that skill has little value of I can’t apply it consistently throughout the whole project. If I have to keep track in my head which kind each component I’m looking at, and how to use them, it decreases the amount of bandwidth I have for more important things.</p><p>When creating my own first-party component I try very hard to follow the same patterns as the third-party component library. For example, all Theme UI components support a sx prop to easily override the style. If I base my components on Theme UI, I’ll make sure that — if possible — the components that I write also support that prop.</p><p>Part of me is always thinking: how would I design this component if I wanted to submit it for inclusion in the upstream component library, or at the very least pull it out of the project into my own component library. This drives a lot of my decisions about how to design the APIs, make them simpler, easier to understand, and more consistent overall.</p><p>In the documentation for my components I try to provide examples that highlight the capabilities and also limitations of the implementation. This gives designers — some of who surprisingly often visit the documentation pages — more context about where, how, and why the components diverge from the design. And also which kind of changes might be easier to implement than others. Because let’s be honest, the design is never set in stone in any project, and will change. And if the designer has to decide between two (functionally equivalent) options, I want them to pick the one that is easier for me to implement.</p><h3>Who’s paying for all this?</h3><p>This consistency and documentation comes at a cost. It takes a bit longer to create each new component, to think of sensible examples, to describe how the components work etc. Don’t worry though, the more you practice the easier it gets. Still, it takes more effort than not doing all of that additional work.</p><p>In the end, it’s a personal decision that every developer has to make for themselves. How much do you value consistency? How important is a clean, well-documented code base to you? How much are you willing to invest in order to give your coworkers—not only developers but also designers—a good foundation for understanding the overall state of UI components in the project?</p><p>I know my answer. What’s yours?</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3578d47ccef" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Writing reusable React components]]></title>
            <link>https://werehamster.medium.com/writing-reusable-react-components-6af5c041b827?source=rss-568a84b64c61------2</link>
            <guid isPermaLink="false">https://medium.com/p/6af5c041b827</guid>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[components]]></category>
            <category><![CDATA[react]]></category>
            <dc:creator><![CDATA[Tomas Carnecky]]></dc:creator>
            <pubDate>Sun, 01 Sep 2019 11:25:12 GMT</pubDate>
            <atom:updated>2019-09-02T04:33:28.524Z</atom:updated>
            <content:encoded><![CDATA[<blockquote>In the past we used to write our React components in a particular way which did not encourage component reuse. In this article I’ll show our past approach, explain how and why it makes reuse difficult, and outline my new way of writing React components that I’ll try in my upcoming projects.</blockquote><p>I’ll use a pretty simple Button component for illustration. In the past we’d design the component along these lines:</p><pre>interface ButtonProps {<br> inverted?: boolean<br> disabled?: boolean;<br> onClick: () =&gt; void;<br>}</pre><pre>export function Button(props: ButtonProps) {<br> return &lt;button … /&gt;<br>}</pre><p>Note that the interface lists only very few properties. They an can be categorised into:</p><ul><li>Properties which are used for internal purposes, to describe custom behaviour or styling (`inverted`)</li><li>Properties which are forwarded to the underlying HTML element (`disabled`, `onClick`)</li></ul><p>The underlying HTML element (`&lt;button&gt;`) supports many more properties which we didn’t include. Also, while our definition of the `onClick` prop is technically compatible with the `onClick` prop of a `&lt;button&gt;`, it doesn’t include the event argument, making the function less useful in some situations.</p><p>We excluded the underlying `&lt;button&gt;` props for two reasons:</p><ol><li>We didn’t need them in the particular project. HTML elements have a lot of props, including all of them in the interface would be wasted work.</li><li>We explicitly didn’t want to include certain properties (eg. `style`) to encourage best practices (eg. use CSS instead of inline styles).</li></ol><p>The first point is due to laziness, and can be solved with better tools. Or rather, with better understanding of our existing tools! The React type definitions come with types which describe the props of all HTML elements, and we should make use of it:</p><pre>interface ButtonProps extends React.ComponentProps&lt;”button”&gt; {<br>  inverted?: boolean;<br>}</pre><p>With this definition, the component accepts all the same props that `&lt;button&gt;` does, plus our own. We just need to make sure to forward all the extra props to the underlying HTML element.</p><pre>export function Button({ inverted, …props }: ButtonProps) {<br>  return &lt;button {…props} /&gt;<br>}</pre><p>For the majority of the components we write, we can identify what the underlying HTML element will be. Very often it’s a `&lt;div&gt;`, but it might also be a `&lt;button&gt;`, or `&lt;input&gt;` etc. Our components should be explicit about what the root element is and accept all their properties.</p><p>The second reason to exclude properties is I believe misguided. The type system is not the right place to enforce best practices. Best practices often stand in the way of experiments and hinder playful exploration.</p><p>For the same reason that I sometimes create Git commits with messages such as “…” or “WIP” , I want to be able to write all the dirty ugly code that I need in order to explore ideas. Yes, I know it’s bad code, but trust me, I’ll clean it up before pushing it to GitHub.</p><p>Furthermore, excluding specific props makes it seem that code which uses these is bad and everything else is good. But the situation is not black and white like a strict type system makes it appear. Just because you’re /not/ using inline styles doesn’t mean you’re doing it right, there are still plenty of ways to write bad code without inline styles.</p><p>Lastly, if it works it ain’t stupid.</p><p>Linters (~automated tools) and code reviews (~humans) are much better places to enforce best practices. If only for the simple reason that you can disable them, or discuss the code with your peers if you really feel the rules shouldn’t apply in your particular situation.</p><p>I haven’t talked about refs yet, but it’s important that any component which renders a specific HTML element should also accept ref and forward it to the element.</p><p>How does this look in practice? When creating a new component go through these steps:</p><ol><li>Decide what the underlying HTML element is.</li><li>Write down the interface, extending `React.ComponentPropsWithRef&lt;…&gt;`.</li><li>Define the component with `React.forwardRef()`, and forward the ref as well as any extra props to the underlying HTML element.</li></ol><pre>interface ButtonProps extends React.ComponentPropsWithRef&lt;”button”&gt; {<br>  inverted?: boolean;<br>}</pre><pre>export const Button = React.forwardRef&lt;HTMLButtonElement, ButtonProps&gt;(function Button({ inverted, …props }, ref) {<br>  return &lt;button ref={ref} {…props} /&gt;<br>});</pre><p>Sometimes you may want to change the underlying HTML element. This is often done for semantic reasons. A good example here is if you want to have a link (`&lt;a&gt;`), that looks like a button. <a href="https://material-ui.com/">Material-UI</a> does it rather well, all of their components have a uniform API to do that:</p><pre>import { Button } from “<a href="http://twitter.com/material">@material</a>-ui/core”</pre><pre>&lt;Button component=”a” href=”/home”&gt;Click Me!&lt;/Button&gt;</pre><p>Supporting this is not straightforward in the type system. The type of underlying HTML element changes the types of props that the component accepts. When you use `&lt;Button&gt;` it should accept all `&lt;button&gt;` props but when you use `&lt;Button component=“a”`&gt; it should accept all `&lt;a&gt;` props (eg. `href`).</p><p>How to express that nicely in the type system is material for another article though. Until then, happy coding.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6af5c041b827" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[My policy for publishing to NPM]]></title>
            <link>https://werehamster.medium.com/my-policy-for-publishing-to-npm-2845b2d4238f?source=rss-568a84b64c61------2</link>
            <guid isPermaLink="false">https://medium.com/p/2845b2d4238f</guid>
            <category><![CDATA[npm]]></category>
            <category><![CDATA[javascript]]></category>
            <dc:creator><![CDATA[Tomas Carnecky]]></dc:creator>
            <pubDate>Mon, 28 Jan 2019 06:34:49 GMT</pubDate>
            <atom:updated>2019-01-28T06:34:49.413Z</atom:updated>
            <content:encoded><![CDATA[<p>JavaScript packages published to NPM are used by different consumers. It has become impossible to generate a truly universal package, because the consumers have fundamentally different needs. This document describes the policy that I follow when publishing my JavaScript packages to NPM.</p><p>First we need to identify the consumers. A JavaScript package can be</p><ul><li>required by a node.js application.</li><li>used by a bundler tool (webpack, rollup, parcel).</li><li>served directly to web pages through <a href="https://unpkg.com/">unpkg.com</a>.</li></ul><p>Depending on the consumer, the JavaScript source code must be prepared differently. For example source code that is loaded by a node.js application can use most of the the latest ES2018 features (classes, arrow functions, iterators, generators etc., depending on the version of node.js you are targeting), but must use require() when referencing other files. Files which are consumed through a bundler tool should use the latest ES2018 syntax, and be written as ES6 modules (use import / export statements). Files served to web pages should be transpiled to be compatible with whatever browser versions you are targeting, minified, but still provide source maps.</p><p>I have another constraint–a personal choice–to provide TypeScript type declarations for my packages.</p><p>Thankfully it’s possible to create a single package that can cater to all of these, by defining different “entry file” to each. In package.json, you can specify which file should be used when the package is consumed by node.js, a bundler, or unpkg.com:</p><pre>{<br>    &quot;main&quot;: &quot;dist/index.node.js&quot;, /* node.js */<br>    &quot;module&quot;: &quot;dist/index.js&quot;,    /* bundler */<br>    &quot;unpkg&quot;: &quot;dist/index.min.js&quot;, /* unpkg.com */<br>    &quot;types&quot;: &quot;dist/index.d.ts&quot;    /* TypeScript */<br>}</pre><p>What this means for the organization of the source code in the repository, and the build / publish process:</p><ul><li>I start with a folder (src/) which contains the TypeScript source code.</li><li>I use the TypeScript compiler with the target=es2018 option, to compile the sources into another folder (dist/). This will generate ES2018-compatible code that uses ES6 module syntax. This is exactly what the bundler tools need. The TypeScript compiler also generates separate type declaration files.</li><li>Then I use <a href="https://rollupjs.org/">rollup</a> with the format=cjs option and a babel configuration that targets a specific node.js version (currently 10) to generate a separate file suitable for node.js.</li><li>If required–not all my package provide this–I’ll use another rollup configuration (target=amd, babel env config which targets specific browser versions, and a minfier) to generate a file that can be loaded by web browsers, for use through unpkg.com.</li><li>All generated files go into the dist/ folder. This folder along with the package.json file is what I put into the tarball that is uploaded to NPM.</li></ul><p>Some repositories which are set up like this are: <a href="https://github.com/wereHamster/computation">computation</a>, <a href="https://github.com/wereHamster/avers/tree/master/pkg/js/avers">avers</a>, <a href="https://github.com/wereHamster/valde">valde</a>.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2845b2d4238f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Simple Square Packing Algorithm]]></title>
            <link>https://medium.com/interactive-things/simple-square-packing-algorithm-ddd3c2793711?source=rss-568a84b64c61------2</link>
            <guid isPermaLink="false">https://medium.com/p/ddd3c2793711</guid>
            <dc:creator><![CDATA[Tomas Carnecky]]></dc:creator>
            <pubDate>Fri, 17 Mar 2017 14:02:00 GMT</pubDate>
            <atom:updated>2017-03-17T14:02:00.982Z</atom:updated>
            <content:encoded><![CDATA[<p>In a recent project the design asked for a component which shows a small number of values in squares. It was important to represent the relation between the values, so they should be mapped to the area and not the size of the squares.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/550/1*jAdw4vW-yTkVuJlyFAZjgw.png" /></figure><p>My initial read of the design was: largest value in the center, then increasingly smaller values packed around it. I knew that there would be fewer than about 7 distinct values. And the domain wouldn’t be too wide (all values between zero and one, roughly). Furthermore, these charts are rendered once each can be reviewed for correctness before the whole website is published. There was no need to have a fancy algorithm which would work for arbitrary input.</p><p>Given these constraints, my approach was to write a simple algorithm to pack these squares: place the largest value in the center, and pack the rest (in decreasing value) such that each new square shares at least one edge with an existing square.</p><h3>Use D3 Force Layout?</h3><p>I was briefly considering using <a href="https://github.com/d3/d3-force">D3 force</a> layout. But it seemed overkill, because of the static nature of the underlying data: the number of values doesn’t change and the values themselves don’t change. There was no need to make the behavior dynamic at runtime. Once the squares are placed their position and size won’t change. D3 force layout uses an iterative approach and is more expensive than a simple algorithm which iterates over the data once.</p><h3>The Algorithm</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/600/1*r_qLCnZJs9WBxcUQW09kZQ.gif" /></figure><p>Placing the first square is simple: straight in the middle of the canvas. The algorithm for all remaining squares is the same:</p><ul><li>Find the vertex that is closest to the centroid of the figure.</li><li>The second vertex needs to be along one of the edges which is going out of this first vertex. Pick one direction, it doesn’t matter. Given that we pack the values in decreasing order, we have a guarantee that the edge of the new square will be shorter than the existing edge.</li><li>The third vertex is on the edge which goes into the other direction. Here we have the first complications: First the case where the two edges are parallel, and second when we know that the resulting square would overlap its neighbor. But these problem are easy to solve with a bit of math.</li><li>The fourth vertex is given by the other three.</li></ul><p>The most difficult part is the first step. For that we need a list of all existing vertices — the outline of the whole figure. I could compute the outline at the beginning of each step. That would be most robust, but I opted for a solution which is a bit simpler: keep a list of vertices which make up the outline and manually update it at the end of each step.</p><p>The complexity of the algorithm is O(n). And given that the number of input values is expected to be in the single-digit range, it is very cheap.</p><h3>The Edge Cases</h3><p>That algorithm is pretty much guaranteed to work for up to five values. Unfortunately there are edge cases where it stops working properly, the symptoms are that it places squares on top of each other. There are two causes:</p><ul><li>Once the algorithm picks the first vertex, it’s committed to placing the square at that location. But there are cases where there isn’t enough space around. The algorithm doesn’t backtrack and pick the second closest vertex (or even one farther away from the centroid).</li><li>There are cases where manually updating the outline doesn’t work correctly. Remember when I said that we <em>have a guarantee that the edge of the new square will be shorter than the existing edge</em>? Yeah, that’s not always true. The algorithm would be more robust if I calculated the outline at the beginning of each step from the list of squares that have already been placed on the canvas, but it would increase the code size.</li></ul><h3>The Code</h3><p>The original source code is available in my <a href="https://github.com/wereHamster/simple-square-packing">simple-square-packing</a> repository on GitHub. It is written in <a href="https://www.typescriptlang.org/">TypeScript</a>. When compressed with the <a href="https://developers.google.com/closure/compiler/">Google Closure Compiler</a>, it’s only 3.1KB in size.</p><p>The repository contains some example code which uses the algorithm to calculate the placement and <a href="https://d3js.org/">D3</a> to render the result (while rotating the whole group by 90 degrees, as required by the design). You can play with the example in the <a href="https://werehamster.github.io/simple-square-packing/#16,9,5,1">playground</a> or on <a href="https://bl.ocks.org/wereHamster/13f3e76d621e9cbaafff3398c0e8a2c7">bl.ocks.org</a>. In this playground you can supply your own list of values and the SVG shows the squares as well as some additional information which is useful: the extent of the whole figure, the exact outline, and the centroid of the whole figure.</p><h3>Playground</h3><p>Below are a few screenshots from the <a href="https://werehamster.github.io/simple-square-packing/#16,9,5,1">playground</a> which I used to test whether the algorithm works correctly when given a particular list of values. The rendering also shows additional useful information about the chart: centroid (blue dot), outline (red line), and extent (green line).</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/981/1*B2AKlWNb3Z6qwQoYEDPntA.png" /><figcaption>Example playground</figcaption></figure><p>In the next screenshot you see 11 distinct values being shown in the chart. Adding one more value will cause two squares to overlap. <a href="https://werehamster.github.io/simple-square-packing/#6,3,7,9,3,67,5,51,24,37,28,">See for yourself!</a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*F84ZOhWJ3QM2dM_TOlGcnw.png" /><figcaption>Playground showing 11 distinct values</figcaption></figure><p>Next up is an <a href="https://werehamster.github.io/simple-square-packing/#7,7,3,1,8,2,15,4,7,10">example</a> of what happens when the algorithm first breaks down. Two squares are placed on top of each other.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hPIsW78X_6rKUrhrOCi9oA.png" /><figcaption>Two squares are overlapping</figcaption></figure><p>Attempting to render many values (&gt;30) exhibits interesting behaviour patterns. Each value you add or remove in this <a href="https://werehamster.github.io/simple-square-packing/#1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,2,2,2,2,2,2,2,2,2,2,2,2,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,">example</a> causes seemingly unpredictable changes in the chart. Delete the last value and observe what happens! It also show that the code which updates the outline (the red line) is not robust enough to handle all edge-cases.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4ZXYz2TSCtj3rdoGJhWj0w.png" /><figcaption>Interesting patterns emerge when showing a large number of values</figcaption></figure><h3>Code and Examples</h3><ul><li><a href="https://github.com/wereHamster/simple-square-packing">The algorithm on GitHub</a></li><li><a href="https://werehamster.github.io/simple-square-packing/#16,9,5,1">Playground</a></li><li><a href="https://bl.ocks.org/wereHamster/13f3e76d621e9cbaafff3398c0e8a2c7">bl.ocks.org</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ddd3c2793711" width="1" height="1" alt=""><hr><p><a href="https://medium.com/interactive-things/simple-square-packing-algorithm-ddd3c2793711">Simple Square Packing Algorithm</a> was originally published in <a href="https://medium.com/interactive-things">Interactive Things</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Evilness of Global State]]></title>
            <link>https://medium.com/interactive-things/the-evilness-of-global-state-fe3375be35ad?source=rss-568a84b64c61------2</link>
            <guid isPermaLink="false">https://medium.com/p/fe3375be35ad</guid>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[react]]></category>
            <dc:creator><![CDATA[Tomas Carnecky]]></dc:creator>
            <pubDate>Fri, 20 Jan 2017 09:29:06 GMT</pubDate>
            <atom:updated>2017-01-30T09:05:58.023Z</atom:updated>
            <content:encoded><![CDATA[<p>Over the past two years I’ve worked on numerous projects. In pretty much all of them, I’ve run into issues which were caused by the same fundamental cause: use of global state.</p><p>In this article I explain why global state is bad, and how to avoid it. First illustrated with a simple, plain JavaScript example, and later in the context of React inline CSS libraries which use global state and have caused me a lot of headaches in the past (and still do).</p><p>We start with a simple example: Let’s write a function which returns the result of the integer division of two numbers.</p><blockquote>The JavaScript code in this article is written using ES2015 syntax. If you are not familiar with it yet, take a few minutes to go through the <a href="https://babeljs.io/docs/learn-es2015/">Babel documentation</a> on that topic. In particular, the sections about arrow functions and destructuring are required for understanding the code examples in this article.</blockquote><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/6399d18ad821e156ba55a285ff3d4cbf/href">https://medium.com/media/6399d18ad821e156ba55a285ff3d4cbf/href</a></iframe><p>Ok, that wasn’t rocket science. Wouldn’t it be nice if the function also returned the remainder? But wait, a function can only return a single value. Bummer. Maybe if we store the remainder in a global variable, so that the caller can read the remainder out of it after calling the function? Let’s try that.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/10ddc73f74e72b7c58979bd5e8c4f344/href">https://medium.com/media/10ddc73f74e72b7c58979bd5e8c4f344/href</a></iframe><p>Nice. Works in this simple example. Shipit. And now let’s try it on a more complex example:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/a2d99f0d69540523b0a2187e7fc534e3/href">https://medium.com/media/a2d99f0d69540523b0a2187e7fc534e3/href</a></iframe><p>Uh oh. The second call to <em>divRem</em> overwrote the remainder which was computed by the first call. So, how do we avoid this problem?</p><p>Even though a function can only return one value, that value can be an object. Or array. Or an instance of a class. Any of these can be used to wrap<br>multiple values. We <em>can</em> write functions which return multiple values, we just have to wrap them in some kind of container.</p><p>Here I’m going to use a plain JavaScript object with two keys:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/4f36f65ba2b57c29147380d3754f7ff4/href">https://medium.com/media/4f36f65ba2b57c29147380d3754f7ff4/href</a></iframe><p>Now we can call that function as many times as we want, without having to worry about somebody overwriting results from previous calls!</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/63877369584fa8bbcd3f830f13554f61/href">https://medium.com/media/63877369584fa8bbcd3f830f13554f61/href</a></iframe><blockquote>Summary: Don’t use global variables if you want to return more than one value from a function call. Wrap them in a container instead.</blockquote><h3>Global state in React inline CSS libraries</h3><blockquote>This section discusses issues caused by the use of global state in the context of React libraries which allow developers to write component styling in JavaScript. The concept is often referred to as CSS-in-JS. To understand this section, you therefore need knowledge of React.</blockquote><p>React render functions are defined to return a React Virtual DOM Element. Such an Element represents a DOM element with all its properties (style, class, href, …), event handlers (onClick, onMouseEnter, …) and any children it may have. This presents a problem for React CSS libraries which attempt to support media queries, custom font faces and other CSS features which can not be expressed in inline styles attached to DOM elements.</p><p>Libraries such as <a href="https://github.com/Khan/aphrodite">Aphrodite</a> or <a href="https://github.com/threepointone/glamor">Glamor</a> work around it by writing these rules into a global object, much like the example at the beginning of this article did with the remainder. Some of the issues you may run into are:</p><ul><li>If you are not careful how you structure your code, the global object may not include all the styles which were generated during rendering of a particular React Element.</li><li>Crashes because the global object is not properly initialised. Example: <a href="http://facebook.github.io/jest/">jest</a> tests need to be marked asynchronous otherwise Aphrodite will crash with an runtime exception.</li><li>Rendering two elements concurrently will merge the two sets of styles. This is a problem if you want to use server-side rendering.</li><li>Certain types of optimisations become unsafe. Compression tools like <a href="http://lisperator.net/uglifyjs/">UglifyJS</a> or the <a href="https://developers.google.com/closure/compiler/">Google Closure Compiler</a> need to be pessimistic and can not apply useful optimisations.</li></ul><p>Now that we know what one of the possible solutions looks like, how do we apply it in the context of React inline CSS?</p><h4>Understanding the React Virtual DOM Element type</h4><p>First we need to understand what a React Virtual DOM Element actually is. At runtime these are are represented as plain JavaScript objects, and don’t forget that JSX is only syntactic sugar for <a href="https://facebook.github.io/react/docs/react-api.html#createelement">React.createElement</a>!</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/b65726b4010cd2b50a4f2cc4f452b63d/href">https://medium.com/media/b65726b4010cd2b50a4f2cc4f452b63d/href</a></iframe><p>If you inspect those objects you’ll see that they are plain JavaScript objects with a few properties. We are only interested in two: <em>type</em> and <em>props</em>.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/4410fc067b20ca8b3feeccfe0caabbf6/href">https://medium.com/media/4410fc067b20ca8b3feeccfe0caabbf6/href</a></iframe><p>Given such an object, we can write a function which extracts the style property out of it:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/1b64f2241ed3545adcc752f1a5cb2831/href">https://medium.com/media/1b64f2241ed3545adcc752f1a5cb2831/href</a></iframe><blockquote>You should use the official React API to create and clone elements. But the basic idea remains the same, since we’re dealing with plain objects.</blockquote><p>With this function in place, we have no reason anymore to write the CSS rules into a global object, since we can attach it to the virtual DOM elements and extract them later. In the trivial example of a single React element:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/0157bb823f82e18d3352ac63e610fb7c/href">https://medium.com/media/0157bb823f82e18d3352ac63e610fb7c/href</a></iframe><p>One challenge remains: Generalise the <em>extractStyle</em> function to work on a whole virtual DOM tree instead just a single element.</p><h3>Conclusion</h3><ul><li>Global state is bad.</li><li>We have ways to avoid it. If you use global state to return multiple values from a function, wrap them all in a container instead.</li><li>We can write React components in a way such that they don’t need to use global variables.</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=fe3375be35ad" width="1" height="1" alt=""><hr><p><a href="https://medium.com/interactive-things/the-evilness-of-global-state-fe3375be35ad">The Evilness of Global State</a> was originally published in <a href="https://medium.com/interactive-things">Interactive Things</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[TemplateHaskell and GHCJS]]></title>
            <link>https://werehamster.medium.com/templatehaskell-and-ghcjs-aed5ce0c9522?source=rss-568a84b64c61------2</link>
            <guid isPermaLink="false">https://medium.com/p/aed5ce0c9522</guid>
            <category><![CDATA[react]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[haskell]]></category>
            <category><![CDATA[nauva]]></category>
            <category><![CDATA[ghcjs]]></category>
            <dc:creator><![CDATA[Tomas Carnecky]]></dc:creator>
            <pubDate>Thu, 05 Jan 2017 11:00:06 GMT</pubDate>
            <atom:updated>2017-01-05T11:00:06.222Z</atom:updated>
            <content:encoded><![CDATA[<blockquote>This is another post outlining some of my struggles when writing <a href="https://github.com/wereHamster/nauva">Nauva</a>. This time it’s about getting <a href="https://wiki.haskell.org/Template_Haskell">TemplateHaskell</a> to work in <a href="https://github.com/ghcjs/ghcjs">GHCJS</a>.</blockquote><blockquote>TLDR: In your JS FFI files, make sure all top-level expressions only depend on symbols defined in the JavaScript language (ES5, ES2015 etc), avoid use of symbols which are specific to a platform (W3C DOM APIs, nodejs APIs etc).</blockquote><p>I use TemplateHaskell to convert strings (inline in the source code, through the use of <a href="https://wiki.haskell.org/Quasiquotation">quasiquotation</a> or loaded from external files) into Catalog pages at compile time. There isn’t any need to do this at runtime since it’s a pure transformation and by doing that at compile time I can avoid having to include the whole markdown parser in the executable.</p><p>GHCJS implements TH by compiling the Haskell code into a JavaScript string, passing that string into a forked nodejs process which eval()&#39;s it and sends the result back.</p><p>The nauva-client package includes a JS FFI file which implements bindings to React and other supporting code which requires the presence of W3C DOM APIs. Even though that FFI code is not actually needed by the TH splices, GHCJS still includes it in the JavaScript code which is sent to nodejs for execution. That means all top-level expressions in the FFI file are evaluated, and if they reference anything that is not available in the nodejs runtime, compiling the TH splice will fail! I had a few of such expressions:</p><pre>class ControlledInput extends React.Component { ... }</pre><pre>const style = document.createElement(&quot;style&quot;);<br>document.head.appendChild(style);</pre><p>I tried to wrap the relevant code in typeof checks (eg. if (typeof React !== &#39;undefined&#39;) { ... }, but that didn’t work, the TH code was still failing.</p><p>The solution was to wrap all code which depends on React, document and other global symbols in a function. A thunk, essentially. If the function is never executed — is is not by the TH code — then it will not crash.</p><pre>function ControlledInput = (() =&gt; {<br>    let v = undefined;</pre><pre>    return () =&gt; {<br>        if (v === undefined) {<br>            v = class extends React.Component { ... };<br>        }<br>        return v;<br>    };<br>});</pre><p>Remember, GHCJS smashes all the compiled code and your JS FFI files into a single, big blob of JavaScript code. Everything is global, you can access any function from anywhere. There is no concept of namespaces or modules.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=aed5ce0c9522" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Process-wide unique identifiers in Haskell]]></title>
            <link>https://werehamster.medium.com/process-wide-unique-identifiers-in-haskell-cce57c3f997b?source=rss-568a84b64c61------2</link>
            <guid isPermaLink="false">https://medium.com/p/cce57c3f997b</guid>
            <category><![CDATA[functional-programming]]></category>
            <category><![CDATA[haskell]]></category>
            <dc:creator><![CDATA[Tomas Carnecky]]></dc:creator>
            <pubDate>Tue, 03 Jan 2017 20:49:55 GMT</pubDate>
            <atom:updated>2017-01-03T20:49:55.982Z</atom:updated>
            <content:encoded><![CDATA[<p>In <a href="https://github.com/wereHamster/nauva">Nauva</a> I need to generate process-wide unique identifiers in pure code.</p><h3>From pure code? Why?</h3><p>There are two contributing factors:</p><p>First, I need a way to compare two Component or Thunk values for equality. But they are records which contain functions. So I can not make use of Eq because Haskell doesn’t provide an instance for (a -&gt; b). My approach is to allocate a unique identifier for each Component or Thunk whenever one such value is created. The usual approach in a pure language is to create a source of uniqueness during start of the application (eg. at the beginning of the main function) and pass it along to anyone who needs it.</p><p>However, that is impractical in my case. Even in a small Nauva codebase, I expect there to be dozens if not hundreds of components and thunks. Developers will hate me if I force them to create the components and thunks in the main function during process initialisation, register them somewhere, and pass them down the call stack (explicitly, through a Reader monad or some such nonsense). I really want to allow them to define components and thunks as top-level expressions. Thunk, semantically, shouldn’t be much different from a plain function, so developers should be able to define it in the same fashion.</p><h3>GHC StaticPtr</h3><p>GHC provides an <a href="https://ghc.haskell.org/trac/ghc/wiki/StaticPointers">extension</a> where it generates unique identifiers (StaticPtr or StaticKey) for you. However I am not able to use that extension because it only works on top-level expressions. And I want to allow users of my library to dynamically create components.</p><h3>The unsafePerformIO hack</h3><p>The source of my unique identifiers is a counter in a global IORef. It is created with the well-known unsafePerformIO hack. That is easy:</p><pre>componentIdCounter :: IORef Int<br>componentIdCounter = unsafePerformIO $ newIORef 1<br>{-# NOINLINE componentIdCounter #-}</pre><p>The whole expression is marked as NOINLINE to prevent GHC from inlining, and thus duplicating, the IORef.</p><p>But now how can I generate new identifiers? My first attempt was to create another expression which would return one such identifier. My assumption was that each time GHC encounters such expression in the code, it would evaluate the IO and thus generate a new identifier.</p><pre>newtype ComponentId = ComponentId Int</pre><pre>mkComponentId :: ComponentId<br>mkComponentId = ComponentId $ unsafePerformIO $<br>    atomicModifyIORef&#39; componentIdCounter $ \i -&gt; (i + 1, i)</pre><pre>-- ... later</pre><pre>myComponent :: Component<br>myComponent = Component<br>    { componentId = mkComponentId<br>    , ....<br>    }</pre><p>However, I discovered that all my identifiers are the same! Thinking about this, it makes sense. The module exports a constant expression, the compiler has no way knowing that there is an IO block inside of it.</p><p>My next attempt was to add a dummy argument to the mkComponentId function, to force the compiler to create a new ComponentId every time I use the function. Even though the argument is always the same, the compiler shouldn’t be allowed to optimise two call sites and merge them.</p><pre>mkComponentId :: () -&gt; ComponentId<br>mkComponentId () = ComponentId $ unsafePerformIO $<br>    atomicModifyIORef&#39; componentIdCounter $ \i -&gt; (i + 1, i)</pre><pre>-- ... later</pre><pre>myComponent :: Component<br>myComponent = Component<br>    { componentId = mkComponentId ()<br>    , ....<br>    }</pre><p>Think of mkComponentId as a monster, a cookie eating monster. You give it a cookie (there is only one cookie, the monster can’t be picky). And it gives you a present, a different present each time, surprise 🎉. Would be fun to rewrite the code as (people would hate me for using unicode though):</p><pre>data 🍪 = 🍪</pre><pre>surpriseMe :: 🍪 -&gt; ComponentId<br>surpriseMe 🍪 = ...</pre><p>Voila! That worked.</p><p>But… only when the code was compiled with GHC. When I tried to run the same code in the browser, compiled with GHCJS, to code was still generating the same identifier multiple times.</p><p>My intuition lead me to believe that passing the same argument to the function somehow confuses the compiler and it still tries to merge multiple call sites. So how do I ensure that the compiler doesn’t see two calls to mkComponentId as equal and tries to do CSE (Common Subexpression Elimination) on them?</p><p>Well, instead of a unit (or a cookie), give it a function! A function which takes a ComponentId and returns a Component. GHC now really shouldn’t be able to see if two calls to createComponent are equal, it would have to compare two functions and it can’t do that. It is ugly but works.</p><pre>createComponent :: (ComponentId -&gt; Component) -&gt; Component<br>createComponent f = unsafePerformIO $ do<br>    cId &lt;- atomicModifyIORef&#39; componentIdCounter $ \i -&gt; (i + 1, i)<br>    pure $ f $ ComponentId cId</pre><pre>-- ... later</pre><pre>myComponent :: Component<br>myComponent = createComponent $ \componentId -&gt; Component<br>    { componentId = componentId<br>    , ....<br>    }</pre><p>And this is how I generate process-wide unique identifiers in Haskell.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=cce57c3f997b" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[BitTorrent Sync device in the Google Cloud]]></title>
            <link>https://werehamster.medium.com/bittorrent-sync-device-in-the-google-cloud-d761be219c3f?source=rss-568a84b64c61------2</link>
            <guid isPermaLink="false">https://medium.com/p/d761be219c3f</guid>
            <category><![CDATA[google]]></category>
            <category><![CDATA[bittorrent-sync]]></category>
            <category><![CDATA[cloud-computing]]></category>
            <dc:creator><![CDATA[Tomas Carnecky]]></dc:creator>
            <pubDate>Tue, 01 Mar 2016 19:31:34 GMT</pubDate>
            <atom:updated>2016-03-01T19:31:34.157Z</atom:updated>
            <content:encoded><![CDATA[<p>I use <a href="https://www.getsync.com/">BitTorrent Sync</a> to distribute copies of my personal files (documents, pictures, GoPro videos and so on) and to share files with my friends. For the later to work reliably, the data needs to be stored in a device which is always turned on. I have a Mac Mini at home and a personal laptop, both of which are asleep during much of the day. I run a few instances in the Google Cloud, so I was looking into putting a BitTorrent Sync device there so it can serve as a central hub.</p><h4>Google Cloud Storage</h4><p>At first I looked into storing the files in Google Cloud Storage (a bucket similar to S3, if you’re familiar with Amazon AWS). This is by far the cheapest option, when using the <a href="https://cloud.google.com/storage/docs/durable-reduced-availability">Durable Reduced Availability (DRA)</a> storage class, it costs 20$ / TB / month. Also, there is no need to provision space, and you pay for what you use. However the BitTorrent Sync client needs to have the files on a filesystem. I found <a href="https://cloud.google.com/storage/docs/gcs-fuse">gcs-fuse</a>, an implementation of <a href="https://en.wikipedia.org/wiki/Filesystem_in_Userspace">FUSE</a> which stores files in Google Cloud Storage. But the btsync client refused to work with it. I suspect the high latency and the fact that the gcs-fuse implementation is not particularly efficient when applications continuously write small blocks into large files (as is the case with any BitTorrent client). I could not get BitTorrent Sync to run reliably, I had to give up.</p><h4>Google Compute — Persistent Disks</h4><p><a href="https://cloud.google.com/compute/docs/disks/">Persistent Disks</a> is a type of block storage which you attach to instances. You need to provision a fixed size and you pay for that, not just for what you use. Persistent Disks are twice as expensive as Google Cloud Storage DRA (40$ / TB / month). I did not want to overprovision the space, and still have the option to grow in the future as needed. My idea was to provision space in small blocks (~ 100GB) and add more disks as needed.</p><p>I briefly considered using <a href="https://en.wikipedia.org/wiki/ZFS">ZFS</a> to manage the disk pool. I’ve had good experience with ZFS, but setting it up on my instances would be difficult: I run <a href="https://coreos.com/">CoreOS</a> on my instances and everything is packaged up in <a href="https://www.docker.com/">Docker</a> containers. CoreOS supports <a href="https://en.wikipedia.org/wiki/Btrfs">btrfs</a> out of the box, and it is trivial to mount a btrfs pool and expose it as volume to a Docker container.</p><h4>Initial BitTorrent Sync Device setup</h4><p>Once I had the disk pool mounted and a Docker container with BitTorrent Sync up and running, I needed configure the new device. The whole setup is done through a web UI, which is nice.</p><p>The easiest way to share folders with the new device would be to link it with my existing identity. But instead of that, I created a completely new identity. The reasons are so that I can treat it as a untrusted device, individually select which folders I want to share with it, and most importantly, so that I can use the <em>Encrypted Folder</em> feature to encrypt my sensitive files. I can even offer my friends a backup service if they give me the <em>Encrypted</em> key of their folders.</p><p>I named the new identity <em>Tomas Carnecky (Google Cloud)</em>:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/774/1*ibxMAQPBQTKz7mVxJAmq4w.png" /></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d761be219c3f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Beware: React setState is asynchronous!]]></title>
            <link>https://werehamster.medium.com/beware-react-setstate-is-asynchronous-ce87ef1a9cf3?source=rss-568a84b64c61------2</link>
            <guid isPermaLink="false">https://medium.com/p/ce87ef1a9cf3</guid>
            <category><![CDATA[react]]></category>
            <category><![CDATA[javascript]]></category>
            <category><![CDATA[api-design]]></category>
            <dc:creator><![CDATA[Tomas Carnecky]]></dc:creator>
            <pubDate>Sun, 07 Feb 2016 20:00:49 GMT</pubDate>
            <atom:updated>2016-02-07T20:00:49.319Z</atom:updated>
            <content:encoded><![CDATA[<p>I recently fixed a bug in one of my applications whose root cause was that I was calling <strong>setState</strong> multiple times during a single update cycle. Because <strong>setState</strong> is asynchronous, subsequent calls in the same update cycle will overwrite previous updates, and the previous changes will be lost.</p><p>Consider the following line of code. When you read it, the intentions are clear: set <em>foo</em> to 42 and keep the other properties untouched. But the change may never take effect if somebody else calls <strong>setState</strong> during the same update cycle and sets a different property!</p><pre>this.setState({ ...this.state, foo: 42 });</pre><p>It’s uncommon to call <strong>setState</strong> multiple times from the same block of code (e.g. an event callback), though even there I can imagine situations where that would not look completely out of place:</p><pre>this.setState({ ...this.state, foo: 42 });<br>if (condition) {<br>    this.setState({ ...this.state, isBar: true });<br>}</pre><p>But there are far less obvious situations which lead to multiple calls to <strong>setState</strong>. For example: combination of <strong>componentWillReceiveProps</strong> and an input <strong>onChange</strong> event handler, like I had in my application.</p><p>Invalidating state changes is one issue here. Another is that you may be acting on an outdated view of the current state. Any time you access <strong>this.state</strong> you can not be sure that it’s the most recent version. This is especially important if you do state changes such as incrementing or appending:</p><pre>// Increment foo<br>this.setState({ ...this.state, foo: this.state.foo + 1 });</pre><pre>// Append an item to an array<br>this.setState({ ...this.state, foo: [].concat(this.state.foo, 1) });</pre><p>These state changes <em>must</em> be done atomically and you must be sure that you are basing your decisions and actions on the current view of the state.</p><blockquote>Considering the implications — innocently looking code which doesn’t behave as expected — I firmly believe that using this particular setState API should be avoided.</blockquote><h3>Alternative setState calling convention</h3><p>It’s relatively easy to avoid these problems: <strong>setState</strong> supports an alternative calling convention where instead of giving it the new state directly, you give it a function which atomically transforms the current state and props into a new state.</p><pre>this.setState((previousState, currentProps) =&gt; {<br>    return { ...previousState, foo: currentProps.bar };<br>});</pre><p>Writing the callback inline like that is convenient, but it doesn’t completely prevent the problem from happening. It is still possible to write the callback such that it returns the new state based on a potentially outdated view of the current state, namely when you capture values from the state outside of the callback:</p><pre>// Capturing values from the state outside of the setState callback.<br>let previousFoo = this.state.foo;</pre><pre>this.setState(function incrementFoo(previousState) {<br>    // BAD! Setting `foo` based on a potentially outdated<br>    // view of its current value: `foo` may have been updated<br>    // in the meantime by another call to `setState`.</pre><pre>    return { ...previousState, foo: previousFoo + 10 };<br>});</pre><p>For best results move the callback to a place where it doesn’t have access to the component instance (<strong>this.state</strong>). The following code makes it unambiguous which external values the transformation depends on (in this case the <strong>delta</strong>), and leaves very little opportunity to act on an outdated view of the state.</p><pre>function incrementFooBy(delta) {<br>    return (previousState, currentProps) =&gt; {<br>        return { ...previousState, foo: previousState.foo + delta };<br>    };<br>}</pre><pre>class MyComponent extends React.Component {<br>    onClick = () =&gt; {<br>        this.setState(incrementFooBy(42));<br>    }</pre><pre>    render() {<br>        return &lt;button onClick={onClick}&gt;click me&lt;/button&gt;;<br>    }<br>}</pre><p>If you squint your eyes, that pattern looks strikingly close to how <a href="https://github.com/rackt/react-redux">Redux</a> works: <strong>setState</strong> is the Redux <strong>dispatch</strong> function to which you pass descriptions how you would like the state to be transformed. In React the transformation function itself, in Redux an abstract description of the transformation (in the form of a plain JavaScript object) which is interpreted by the reducer.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ce87ef1a9cf3" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Cross-compiling for the Onion Omega]]></title>
            <link>https://werehamster.medium.com/cross-compiling-for-the-onion-omega-1cf8ee80df02?source=rss-568a84b64c61------2</link>
            <guid isPermaLink="false">https://medium.com/p/1cf8ee80df02</guid>
            <category><![CDATA[omega]]></category>
            <category><![CDATA[compilers]]></category>
            <category><![CDATA[haskell]]></category>
            <dc:creator><![CDATA[Tomas Carnecky]]></dc:creator>
            <pubDate>Sun, 07 Feb 2016 16:45:10 GMT</pubDate>
            <atom:updated>2016-02-07T16:45:10.255Z</atom:updated>
            <content:encoded><![CDATA[<p>TLDR: I figured out how to build a C and Haskell cross-compiler for the <a href="https://onion.io/omega">Onion Omega</a>, instructions are in my <a href="https://github.com/wereHamster/onion-omega">GitHub repository</a>.</p><p>I ordered four <a href="https://onion.io/omega">Onion Omega</a> devices late last year and they arrived mid January 2016. They are tiny, nicely built, and the HTML GUI is gorgeous. Sadly there are not that many apps available yet. I was hoping that there would be at least <a href="https://nodejs.org/">node</a> available for it so I could run small JavaScript apps on it.</p><p>Anyway, first thing I did was give them names (mauve, scarlet, sienna, umber) and do the basic setup (Wi-Fi name, password etc). Then I stared looking how to build software for it.</p><p>First challenge: the device has only 16MB flash, half of which is used up by the OS (<a href="https://openwrt.org/">OpenWrt</a>). There is about 7MB usable persistent storage, a bit more if you place the files into tmpfs, but then the files are not persisted across reboots. Any reasonably sized application will push that limit. The node binary on my Mac alone is 23MB!</p><pre># df -h<br>Filesystem           Size    Used  Available  Use%  Mounted on<br>rootfs               7.5M  480.0K       7.0M    6%  /<br>/dev/root            7.3M    7.3M          0  100%  /rom<br>tmpfs               29.9M   15.9M      14.0M   53%  /tmp<br>/dev/mtdblock3       7.5M  480.0K       7.0M    6%  /overlay<br>overlayfs:/overlay   7.5M  480.0K       7.0M    6%  /<br>tmpfs              512.0K       0     512.0K    0%  /dev</pre><h3>Building the C toolchain</h3><p>The next step was to build the C toolchain. For that I needed to know the exact target configuration: What kind of CPU it is, which <a href="https://en.wikipedia.org/wiki/Instruction_set">ISA</a> it supports, what <a href="https://en.wikipedia.org/wiki/C_standard_library">libc</a> the system uses, the <a href="https://en.wikipedia.org/wiki/Application_binary_interface">ABI</a> etc. If you compile an application for the wrong target it may behave unexpectedly at runtime (if you use the wrong <a href="https://en.wikipedia.org/wiki/Application_binary_interface">ABI</a>) or fail hard with an <em>Illegal instruction </em>exception<em> (</em>if the binary was compiled for a different <a href="https://en.wikipedia.org/wiki/Instruction_set">ISA</a>).</p><p>Unfortunately there isn’t much information yet on the internet about the exact capabilities of the device, and <em>/proc/cpuinfo</em> isn’t of much help.</p><pre>system type:             Atheros AR9330 rev 1<br>machine:                 Onion Omega<br>processor:               0<br>cpu model:               MIPS 24Kc V7.4<br>BogoMIPS:                265.42<br>wait instruction:        yes<br>microsecond timers:      yes<br>tlb_entries:             16<br>extra interrupt vector:  yes<br>hardware watchpoint:     yes, count: 4, address/irw mask: [0x0ffc, 0x0ffc, 0x0ffb, 0x0ffb]<br>isa:                     mips1 mips2 mips32r1 mips32r2<br>ASEs implemented:        mips16<br>shadow register sets:    1<br>kscratch registers:      0<br>package:                 0<br>core:                    0<br>VCED exceptions:         not available<br>VCEI exceptions:         not available</pre><p>It’s a MIPS 24Kc CPU and supports up to the <em>mips32r2</em> ISA, so far good. But what you don’t see is that the chip doesn’t have a <a href="https://en.wikipedia.org/wiki/Floating-point_unit">FPU</a>. So while a primitive Hello World C application runs just fine, once you start using Floating Point (FP) instructions it’ll crash with the aforementioned exception.</p><p>The OS uses an archaic libc (uClibc 0.9.33.2) which isn’t maintained anymore, not standards conform and thus incompatible with more recent userland tools. In particular, <a href="https://www.haskell.org/ghc/">GHC</a>, the <a href="https://www.haskell.org/">Haskell</a> compiler, can’t be built against it. I settled on <a href="http://www.musl-libc.org/">musl libc</a> which is a tiny libc optimised for static linking.</p><p>I built the toolchain using <a href="http://crosstool-ng.org/">crosstools-ng</a>, and the following defconfig. Since I’m using the compiler only for that specific target I set both <em>march</em> and <em>mtune</em> to the exact CPU model.</p><pre>CT_ARCH_ARCH=&quot;24kc&quot;<br>CT_ARCH_TUNE=&quot;24kc&quot;<br>CT_ARCH_FLOAT_SW=y<br>CT_ARCH_mips=y<br>CT_KERNEL_linux=y<br>CT_LIBC_musl=y</pre><p>That gave me a working C compiler which I was able to use to generate static binaries, copy them over to the device and run.</p><h3>Haskell / GHC</h3><p>Next up was GHC. It is a huge, complicated beast, and it takes forever to build. Google Cloud provided most of the hardware during this time. With jut a few clicks I could spin up a 32-core machine and repeatedly compile GHC. It saved me a lot of time.</p><p>MIPS is not a Tier 1 platform, which means that the GHC maintainers don’t guarantee that it works. GHC does know that the MIPS architecture exists, but can’t actually emit working bytecode for it. It looked like I was in for a lot of work (actually, I’d have given up if I had to write a complete MIPS assembler codegen). In the end though it wasn’t much that was needed to get it working.</p><p>GHC has a mode where it generates LLVM IR code, the rest is taken care of by the LLVM compiler. And fortunately the LLVM complier knows how to build MIPS binaries. In all, I had to make four changes:</p><ul><li>GHC needs to write a short prelude into each LLVM IR file. It describes the architecture (how many registers it has of each type, how wide pointers are etc) and is used by the LLVM optimiser to optimise the code for that particular target. It consists of two lines which I copied from the Clang repository. Easy.</li><li>There is a <a href="https://ghc.haskell.org/trac/ghc/ticket/11538">bug</a> in GHC where it generates wrong LLVM IR when the host and target have different <a href="https://en.wikipedia.org/wiki/Endianness">endianness</a>. I adapted the code specifically for my situation, where the host is little endian (x86) and target big endian (MIPS).</li><li>Since the chip on the Onion Omega has no FPU, I needed to pass an option to the LLVM compiler to not generate FP instructions. The GHC source code doesn’t distinguish between soft-float and hard-float for architectures other than ARM. So I hardcoded it in the source code.</li><li>libffi fails to build for a soft-float target. Known issue, patches are available but have not been integrated into the official repository (libffi seems not maintained anymore, the repository on GitHub has tons of open issues and pull requests).</li></ul><p>One other thing which took me a while to figure out is to disable stripping in <em>mk/build.mk</em>. There’s either a bug in binutils or the linker which prevents the final binary from being assembled, or <em>strip</em> needs to be given additional options (to not strip too much out of the object files).</p><p>After figuring out all these necessary changes, it took just a few hours to actually build GHC. And then, finally, I had a shiny new GHC cross-compiler: <em>mips-unknown-linux-musl-ghc.</em> With it, I was able to build a Haskell Hello World app, copy it over to the Omega and run. Yay.</p><p>I should note though that the Hello World binary, even stripped, is 8.6MB, and as such doesn’t fit into the free space available on the Onion Omega flash. So I had to run it from tmpfs.</p><h3>Building the toolchains on Mac OS X</h3><p>The instructions in my GitHub repository are for Linux (docker containers based on Ubuntu 16.04 to be exact). I tried to replicate the instructions on my Mac OS X laptop, but that worked only for the C toolchain.</p><p>You can install crosstools-ng from homebrew and use pretty much the same defconfig. That gives you a working C toolchain. But I had to give up at compiling GHC. There are too many subtle differences between Linux and Mac OS X. Part of the problem is also GHC’s build system which seems to mix up build/host/target flags (CPP/C/LD) in various makefile rules, leading to failures in the middle of the build process.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1cf8ee80df02" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>