Devlog #01: Emulador NES, Github e build simples com Github Actions

Com este workflow simples em mãos, vamos começar a botar a mão na massa e escrever um pouco de C. Deixe o Pull Request aberto, a gente ainda vai precisar dele!

Olá mundo: compilando um programa simples em C

Na linguagem C, todo programa precisa ter uma função de entrada. Normalmente esta função se chama main(). Vamos escrever um arquivo chamado src/main.c com o seguinte conteúdo:

#include <stdio.h>

int main(void)
{
  printf("Olá mundo");
  return 0;
}

O programa acima deverá escrever o texto “Olá mundo” na tela quando executado, e o seu código de saída (exit code) deverá ser 0 (zero). Nós podemos verificar o código de saída do último comando executado através da variável $?.

Para compilar o programa acima, utilize o seguinte comando:

$ clang src/main.c -o build/main.o -std=c99 -Wall

E o conjunto da obra deverá ficar mais ou menos assim:

O comando acima não apenas compilou o nosso arquivo main.c mas também executou um processo chamado Linkedição. Para facilitar a nossa vida no futuro, eu quero quebrar a compilação do nosso programa em duas partes: compilação e linkedição de objetos.

Para isto, nós primeiro precisamos compilar os arquivos .c utilizando a flag -c. Depois coletamos todos os arquivos .o e entregamos ao compilador para gerar um único executável, que aqui chamamos de “qmario”. Fica assim:

$ clang -c src/main.c -o build/main.o -std=c99 -Wall
$ clang build/main.o -o build/qmario

Criar um Makefile para o projeto

Vamos criar e editar alguns arquivos antes de mais nada. Como eu sei que no próximo post eu vou trabalhar a emulação da CPU, vamos já criar os arquivos da CPU: cpu.h (cabeçalho, onde ficam as assinaturas de função), cpu.c (implementações concretas) e cpu.test.c (testes automatizados para as funções de CPU).

Dê os seguintes conteúdos para estes arquivos:

// no arquivo cpu.h escreva o seguinte

#ifndef _cpu_h_
#define _cpu_h_

void cpu_reset(void);

#endif

// no arquivo cpu.c escreva o seguinte
#include "cpu.h"

void cpu_reset(void)
{
}

// no arquivo cpu.test.c escreva o seguinte
#include "cpu.h"

int main(void)
{
    cpu_reset();
}

// no arquivo main.c escreva o seguinte
#include "cpu.h"

int main(void)
{
    cpu_reset();

    return 0;
}

• build/ é a pasta que recebe todos os arquivos compilados e intermediários. Quando o projeto é clonado, esta pasta não deverá existir

• src/ todo nosso código C ficará nesta pasta, incluindo os testes!

• src/*.test.c alguns arquivos poderão receber o sufixo .test.c, que indica que são arquivos de teste. Desta forma conseguimos escrever testes e garantir maior qualidade no projeto

Portanto vamos criar o arquivo Makefile com o seguinte conteúdo:

CC=clang
CFLAGS=-std=c99 -Wall
LFLAGS=

SRCDIR=src
BUILDDIR=build
OUT=qmario

OBJS=$(BUILDDIR)/cpu.o
MAINOBJ=$(BUILDDIR)/main.o
TOBJS=$(BUILDDIR)/cpu.test.o

run: $(BUILDDIR)/$(OUT)
    $(BUILDDIR)/$(OUT)

test: $(BUILDDIR) $(OBJS) $(TOBJS)
    $(CC) $(OBJS) $(TOBJS) -o $(BUILDDIR)/tests $(LFLAGS)
    $(BUILDDIR)/tests

# Constrói o executável principal
$(BUILDDIR)/$(OUT): $(BUILDDIR) $(OBJS) $(MAINOBJ)
    $(CC) $(OBJS) $(MAINOBJ) -o $(BUILDDIR)/$(OUT) $(LFLAGS)

$(BUILDDIR):
    mkdir -p $(BUILDDIR)

$(BUILDDIR)/%.o: $(SRCDIR)/%.c
    $(CC) -c $< -o $@ $(CFLAGS)

.PHONY: clean
clean:
    $(RM) -r $(BUILDDIR)

Agora que o arquivo Makefile existe, podemos executar o comando make clean run para compilar e executar o programa que definimos em main.c.

$ make clean run

E para rodar nossos testes, definidos no arquivo cpu.test.c, podemos rodar o comando make clean test. Como a seguir:

$ make clean test

A estrutura de pastas deverá ficar mais ou menos assim:

├── LICENSE
├── Makefile
├── build
│   ├── cpu.o
│   ├── cpu.test.o
│   ├── main.o
│   ├── qmario
│   └── tests
└── src
    ├── cpu.c
    ├── cpu.h
    ├── cpu.test.c
    └── main.c

Vamos rodar os testes como parte da integração contínua

Agora que a nosso Makefile está configurado e funcionando bonitinho, podemos alterar o arquivo .github/workflows/ci.yaml para fazermos a compilação e rodar os testes sempre que abrirmos um Pull Request no repositório que criamos.

Dê o seguinte conteúdo para o arquivo .github/workflows/ci.yaml:

name: CI
on:
    push:
        branches: [ "main" ]
    pull_request:
        branches: [ "main" ]
jobs:
    build:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v3
            - name: Fazer build e rodar
              run: make clean test

Pode enviar o código para o Github e note que o CI agora está verde, indicando que todos os passos foram executados e tudo correu bem:

Próximos passos

Já temos uma integração contínua configurada e pronta para receber nosso código. O próximo passo é começar a escrever o emulador!

O primeiro componente a ser escrito é justamente a CPU, que deverá ser escrita em conjunto com o barramento (memory BUS). No próximo artigo nós vamos começar a entender o chip 6502 utilizado pelo NES, e vamos emular algumas operações.

Não se esqueça de que o próximo artigo só sai se um número suficiente de pessoas ajudar a divulgar a série! 👇