WebAssembly on Jefferson Oliveira

Pleasure to meet you, circ!

Tue, 12 May 2026 08:27:04 -0201

Hey y’all! If you’ve been following the fundamentals of computing series here, you’ve noticed those little widgets. You can click them, toggle the switches, watch the LEDs light up, peek at the circuit topology. Today I want to tell you what’s actually running in them, because I made it.

It’s called circ. It’s a small language for describing digital circuits, and a compiler that turns the description into something your browser can run. First of all I want you to understand this isn’t a serious systems language (yet), and I believe it’s great for this blog but not ready for production. For now it exists for the sole purpose of having the circuits here actually work, instead of being static drawings or handcrafted simulators.

How it reads

I think the best way to introduce a language is to let you look at it. Here’s a half-adder written in .circ:

input a, b

xor s(a=a, b=b)
and c(a=a, b=b)

output sum(in=s.out)
output carry(in=c.out)

That’s the whole file. You declare your inputs, you instantiate gates and give them names, you wire each gate’s ports to the signals that drive them, and you declare which signals leave through the outputs. Doesn’t it read a little like a recipe? Take two inputs. Combine a and b with an XOR, call it s. Combine the same two with an AND, call it c. Send s.out to the sum output, c.out to the carry. That’s it.

The primitives are deliberately tiny: input, output, and, not, wire, led. Six things. Everything else is built from those.

And here’s a detail I’m a little smug about: the built-in gates or, nand, nor, xor, xnor are themselves written in .circ. The compiler’s entire “standard library” is five tiny files that look exactly like the one above. When you write xor s(a=a, b=b), the compiler quietly pulls in a five-line file that defines XOR in terms of AND, OR, and NAND. The language is small enough to be its own standard library, and that makes me unreasonably happy.

Where it came from

circ didn’t start as a language. It started as me wanting to draw circuits.

I’d been writing this series for a while, and every circuit in every post was a static SVG I’d hand-drawn or coaxed out of a TypeScript renderer I kept patching. The drawings worked, but they were just drawings. You couldn’t toggle a switch and watch the LED change. You couldn’t ask “what does this circuit do, exactly?” and get an answer. They were illustrations of computers, not computers.

Around the same time I bought The Elements of Computing Systems, and this book hexed me (pun intended) with the curse of curiosity, which led me right into Nand to Tetris. In it, you build everything from a single NAND gate, in a tiny language called HDL, and every component you write actually runs. The combination of “describe a circuit in a few lines” and “now press play and watch it work” is how circuits should feel when you’re learning about them. So I wanted that, for this blog, for you. The widgets in the posts you’ve already read are the result.

The name is the most boring part of the story: circ is short for circuit (I am not a poet, sorry.)

The two things I love most

Once the compiler started working, two things fell out of it that I didn’t expect to love as much as I do.

The first is that circ can draw itself. Hand it a circuit and it’ll produce an ASCII schematic, complete with rounded corners, fan-out dots, and wires that detour politely around gates that sit in their way. Here’s the half-adder from earlier, rendered by the compiler itself:

╭───╮     ╭───╮         ╭───────╮
│ a ├○─●─▶┤   │ ╭──────▶┤ carry │
╰───╯  │  │AND├○╯       ╰───────╯
      ╭┼─▶┤   │
      ││  ╰───╯
      ││
╭───╮ ││  ╭───────╮     ╭─────╮
│ b ├○●╰─▶┤       │ ╭──▶┤ sum │
╰───╯ │   │[xor:s]├○╯   ╰─────╯
      ╰──▶┤       │
          ╰───────╯

The second is that circ can tabulate itself. Hand it the same file and ask for --truth-table, and you get:

a	b	sum	cout
0	0	0	0
1	0	1	0
0	1	1	0
1	1	0	1

That’s the beauty of it: using only 5 lines you have a circuit description, a picture of itself, and proof that it does what it claims. Every interactive widget in every post of this series has been circ doing this quietly in the background, three times over. Once to render the schematic you see, once to run the simulation when you toggle a switch, once to prove the gates behave the way I said they would.

Until we meet again

That’s just the surface of it. There’s a parser, a resolver, a validator with stable error codes, a tiny WebAssembly runtime that the compiler embeds inside every artifact so the whole thing runs in your browser without needing any toolchain on your machine. But those are stories for other days.

If you want to dig deeper, the language has a home of its own at circ-lang.org, with the full reference and more examples than I could fit here.

For now, the next time you click on a widget in one of these posts, you’ll know what you’re looking at. It’s circ. Pleasure to meet you.

Special thanks

Before we say goodbye, I want to give a special shoutout to @clarete. He is the brain behind langlang, the parser generator that powers this language. He has been hammering my ears about langlang for years and I couldn’t be more proud of what he has done.

References

circ-compiler on GitHub
circ-lang.org, the language reference and examples
Zig
langlang, the PEG parser generator that builds the .circ grammar
From Nand to Tetris

Prazer, circ!

Tue, 12 May 2026 08:27:04 -0200

Olá pessoal, tudo bom? Se vocês têm acompanhado a série de fundamentos da computação aqui, com certeza notaram aqueles circuitinhos. Dá pra clicar neles, mexer nos interruptores, ver os LEDs acendendo, espiar a topologia do circuito. Hoje eu quero contar o que de verdade está rodando neles, porque fui eu que fiz.

Ele se chama circ. É uma linguagem pra descrever circuitos digitais, e um compilador que transforma essa descrição em algo que o seu navegador consegue rodar. Antes de mais nada, quero deixar claro: isso não é uma linguagem séria de sistemas (ainda), e eu acredito que é ótima pra esse blog mas não está pronta pra produção. Por enquanto ela existe pelo único motivo de fazer os circuitos daqui funcionarem de verdade, em vez de serem desenhos estáticos ou simuladores feitos na mão.

Aprendendo a ler

Eu acho que a melhor forma de apresentar uma linguagem é deixar você olhar pra ela. Aqui está um meio-somador (half-adder) escrito em .circ:

input a, b

xor s(a=a, b=b)
and c(a=a, b=b)

output sum(in=s.out)
output carry(in=c.out)

É o arquivo inteiro. Você declara as suas entradas, instancia as portas e dá um nome pra elas, conecta as portas de cada uma aos sinais que as alimentam, e declara quais sinais saem pelas saídas. Não parece um pouco com uma receita? Pegue duas entradas. Combine a e b com um XOR, chame de s. Combine as mesmas duas com um AND, chame de c. Mande s.out pra saída sum, e c.out pra carry. É isso.

As primitivas são propositalmente minúsculas: input, output, and, not, wire, led. Seis coisas. Todo o resto é construído a partir delas.

E aqui vai um detalhe do qual eu me orgulho um pouco: as portas or, nand, nor, xor, xnor também são escritas em .circ. A “biblioteca padrão” inteira do compilador são cinco arquivos que se parecem exatamente com o de cima. Quando você escreve xor s(a=a, b=b), o compilador silenciosamente puxa um arquivo de cinco linhas que define XOR em termos de AND, OR e NAND. A linguagem é pequena o suficiente pra ser a sua própria biblioteca padrão, e isso pra mim é fascinante.

Senta que lá vem história

circ não começou como uma linguagem. Começou como eu querendo desenhar circuitos.

Eu vinha escrevendo essa série há um tempo, e todo circuito de todo post era um SVG estático que eu tinha desenhado na mão ou arrancado de um renderizador em TypeScript que eu não parava de remendar. Os desenhos funcionavam, mas eram só desenhos. Você não podia mexer numa chave e ver o LED mudar. Você não podia perguntar “o que esse circuito faz, exatamente?” e receber uma resposta. Eram ilustrações de computadores, não computadores.

Mais ou menos na mesma época eu comprei o The Elements of Computing Systems, e esse livro explodiu minha cabeça e me levou direto pro Nand to Tetris. Nele, você constrói tudo a partir de uma única porta NAND, numa linguagenzinha chamada HDL, e cada componente que você escreve realmente roda. A combinação de “descreva um circuito em poucas linhas” e “agora aperte play e veja funcionar” é como deveria ser quando você está aprendendo sobre circuitos. Então eu quis isso, pra esse blog, pra você. Os widgets dos posts que você já leu são o resultado.

O nome é a parte mais sem graça da história: circ é abreviação de circuit (não sou poeta, desculpa.)

As cerejas do bolo

Assim que o compilador começou a funcionar, duas coisas saíram dele que eu não esperava amar tanto quanto amo.

A primeira é que o circ consegue se desenhar. Entrega um circuito pra ele e ele produz um esquema em ASCII, completo com cantos arredondados, pontos de fan-out, e fios que desviam educadamente das portas que estão no caminho. Aqui está o meio-somador de antes, renderizado pelo próprio compilador:

╭───╮     ╭───╮         ╭───────╮
│ a ├○─●─▶┤   │ ╭──────▶┤ carry │
╰───╯  │  │AND├○╯       ╰───────╯
      ╭┼─▶┤   │
      ││  ╰───╯
      ││
╭───╮ ││  ╭───────╮     ╭─────╮
│ b ├○●╰─▶┤       │ ╭──▶┤ sum │
╰───╯ │   │[xor:s]├○╯   ╰─────╯
      ╰──▶┤       │
          ╰───────╯

A segunda é que o circ consegue se tabular. Entrega o mesmo arquivo pra ele e peça --truth-table, e você recebe:

a	b	sum	cout
0	0	0	0
1	0	1	0
0	1	1	0
1	1	0	1

Essa é a beleza da coisa: usando só 5 linhas você tem a descrição do circuito, uma imagem dele mesmo, e a prova de que ele faz o que diz que faz. Cada widget interativo de cada post dessa série tem sido o circ fazendo isso silenciosamente no fundo, três vezes seguidas. Uma vez pra renderizar o esquema que você vê, uma vez pra rodar a simulação quando você mexe numa chave, e uma vez pra provar que as portas se comportam do jeito que eu disse que iam se comportar.

Até a próxima

Isso é só a superfície. Tem um parser, um resolvedor, um validador com códigos de erro estáveis, um pequeno runtime em WebAssembly que o compilador injeta dentro de cada artefato pra que tudo rode no seu navegador sem precisar de toolchain nenhum na sua máquina. Mas essas são histórias pra outros dias.

Se quiser se aprofundar, a linguagem tem um site só pra ela em circ-lang.org, com a referência completa e mais exemplos do que coube aqui.

Por enquanto, da próxima vez que você clicar num widget em um desses posts, você vai saber o que está vendo. É o circ. Prazer em te conhecer.

Agradecimentos especiais

Antes de nos despedirmos, eu quero dar um agradecimento especial pro @clarete. Ele é o cérebro por trás do langlang, o gerador de parsers que dá vida pra essa linguagem. Ele vem martelando meus ouvidos sobre o langlang há anos, e eu não poderia estar mais orgulhoso do que ele construiu.

Referências

circ-compiler no GitHub
circ-lang.org, a referência da linguagem e exemplos
Zig
langlang, o gerador de parser PEG que constrói a gramática do .circ
From Nand to Tetris