rafaellcoellho.com

Usando argparse, tox e setuptools para fazer aplicativo de cli em python

2022-10-16T14:45:00+00:00

Vou escrever um aplicativo “hello world” para aprender como escrever, testar e deployar um aplicativo de linha de comando.

Criando aplicação

O python já vem com uma biblioteca para facilitar a criação de aplicações de linha de comando chamada argparse. Vou começar criando o modulo principal:

└── cli
    ├── main.py
    └── __init__.py

O arquivo main.py vai conter todo o código:

import argparse


def main(argv=None):
    parser = argparse.ArgumentParser(prog="greet")
    parser.add_argument("name")
    args = parser.parse_args(argv)

    print(f"hello {args.name}")

    return 0


if __name__ == "__main__":
    exit(main())

Vou testar se o módulo está funcionando usando a linha de comando:

$ python -m cli.main rafael
hello rafael

Sucesso! Mas caso a minha aplicação comece a ficar mais complexa não vou querer testar manualmente todas as possibilidades. Vou criar um teste para garantir que essa lógica esteja sempre correta.

Escrevendo testes

Criando o mudulo de testes:

├── cli
│   ├── __init__.py
│   ├── main.py
└── tests
    ├── __init__.py
    └── test_cli.py

Utilizei a própria função main para passar os argumentos e o pytest também ajuda a checar o stdout utilizando o argumento capsys:

from cli.main import main


def test_hello_world_cli(capsys):
    main(["test"])
    result = capsys.readouterr()
    assert result.out == "hello test\n"

Usando pytest:

$ pytest
============================= test session starts ==============================
platform linux -- Python 3.10.4, pytest-7.1.3, pluggy-1.0.0
[...]
collected 1 item                                                               

tests/test_cli.py .                                                      [100%]

============================== 1 passed in 0.01s ===============================

Mas ter que rodar o pytest instalado globalmente não é tão bom assim. Prefiro utilizar a ferramenta tox, que vai automatizar esses testes serem executados em vários ambientes diferentes. Mas antes disso é preciso empacotar a nossa aplicação utilizando o setuptoopls.

Empacotando usando setuptools

O setuptools precisa de alguns arquivos de configuração para empacotar o aplicativo, são eles: setup.py, setup.cfg e pyproject.toml. Após criar eles na raiz do projeto, é preciso preencher o setup.py e pyproject.toml com valores padrão:

from setuptools import setup

setup()

[build-system]
build-backend = "setuptools.build_meta"
requires = ["setuptools", "wheel"]

Agora vou criar o arquivo principal, setup.cfg:

[metadata]
name = greet
version = 0.0.1

[options]
packages = cli

[options.entry_points]
console_scripts =
    greet = cli.main:main

Agora basta usar o comando build:

$ python -m build
* Creating virtualenv isolated environment...
* Installing packages in isolated environment... (setuptools, wheel)
* Getting dependencies for sdist...
[...]
Successfully built greet-0.0.1.tar.gz and greet-0.0.1-py3-none-any.whl

Temos o nosso pacote na pasta dist/. Para instalar basta usar pip:

$ pip install dist/greet-0.0.1-py3-none-any.whl 
Processing ./dist/greet-0.0.1-py3-none-any.whl
Installing collected packages: greet
Successfully installed greet-0.0.1

Agora a aplicação foi instalada, basta usar:

$ greet rafael
hello rafael

Finalmente posso usar o tox para rodar os testes.

Rodando testes com tox

Adicionando o arquivo tox.ini na raiz do projeto com uma configuração bem básica:

[tox]
envlist = py310

[testenv]
deps = pytest
commands =
    pytest {posargs:tests}

Para rodar os testes em todos os ambientes disponíveis na sua máquina:

$ tox --skip-missing-interpreters

Caso eu queira rodar um teste especifico em um ambiente específico:

$ tox -e py310 -- tests/test_cli.py::test_hello_world_cli

Black, mypy e pre-commit

Também vou adicionar algumas ferramentas para ajudar no desenvolvimento. Mais um arquivo de configuração na raiz do projeto chamado .pre-commit-config.yaml:

repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v3.2.0
    hooks:
    -   id: trailing-whitespace
    -   id: end-of-file-fixer
    -   id: check-yaml
-   repo: https://github.com/psf/black
    rev: 22.10.0
    hooks:
    -   id: black
-   repo: https://github.com/pre-commit/mirrors-mypy
    rev: v0.982
    hooks:
    -   id: mypy
        additional_dependencies: [types-all]
        exclude: tests

A ideia é usar o pre-commit para sempre utilizar o mypy e black antes de cada commit. Para iniciar no projeto basta:

$ pre-commit install
pre-commit installed at .git/hooks/pre-commit

Caso queira executar sem fazer commit basta usar:

$ pre-commit run --all-files

Conclusão

Esse foi o esqueleto básico de uma aplicação de linha de comando usando python. O código-fonte mostrado nesse post se encontra no meu github.

Referências

Using argparse, tox and setuptools to build a Python CLI app

2022-10-16T14:45:00+00:00

I’ll write a “hello world” application to learn how to write, test and deploy a command-line application.

Creating the application

Python ships with a library to make building command-line applications easier called argparse. I’ll start by creating the main module:

└── cli
    ├── main.py
    └── __init__.py

The main.py file will contain all the code:

import argparse


def main(argv=None):
    parser = argparse.ArgumentParser(prog="greet")
    parser.add_argument("name")
    args = parser.parse_args(argv)

    print(f"hello {args.name}")

    return 0


if __name__ == "__main__":
    exit(main())

I’ll test if the module is working using the command line:

$ python -m cli.main rafael
hello rafael

Success! But if my application starts getting more complex I won’t want to test all possibilities manually. I’ll create a test to ensure this logic is always correct.

Writing tests

Creating the test module:

├── cli
│   ├── __init__.py
│   ├── main.py
└── tests
    ├── __init__.py
    └── test_cli.py

I used the main function itself to pass arguments, and pytest also helps check stdout using the capsys argument:

from cli.main import main


def test_hello_world_cli(capsys):
    main(["test"])
    result = capsys.readouterr()
    assert result.out == "hello test\n"

Using pytest:

$ pytest
============================= test session starts ==============================
platform linux -- Python 3.10.4, pytest-7.1.3, pluggy-1.0.0
[...]
collected 1 item                                                               

tests/test_cli.py .                                                      [100%]

============================== 1 passed in 0.01s ===============================

But having to run a globally installed pytest isn’t ideal. I prefer using the tox tool, which will automate running these tests in multiple different environments. But first we need to package our application using setuptools.

Packaging with setuptools

setuptools needs some configuration files to package the application: setup.py, setup.cfg and pyproject.toml. After creating them at the root of the project, fill in setup.py and pyproject.toml with default values:

from setuptools import setup

setup()

[build-system]
build-backend = "setuptools.build_meta"
requires = ["setuptools", "wheel"]

Now I’ll create the main file, setup.cfg:

[metadata]
name = greet
version = 0.0.1

[options]
packages = cli

[options.entry_points]
console_scripts =
    greet = cli.main:main

Now just use the build command:

$ python -m build
* Creating virtualenv isolated environment...
* Installing packages in isolated environment... (setuptools, wheel)
* Getting dependencies for sdist...
[...]
Successfully built greet-0.0.1.tar.gz and greet-0.0.1-py3-none-any.whl

We have our package in the dist/ folder. To install it just use pip:

$ pip install dist/greet-0.0.1-py3-none-any.whl 
Processing ./dist/greet-0.0.1-py3-none-any.whl
Installing collected packages: greet
Successfully installed greet-0.0.1

Now the application is installed, just use it:

$ greet rafael
hello rafael

Now I can finally use tox to run the tests.

Running tests with tox

Adding the tox.ini file at the root of the project with a very basic configuration:

[tox]
envlist = py310

[testenv]
deps = pytest
commands =
    pytest {posargs:tests}

To run tests in all available environments on your machine:

$ tox --skip-missing-interpreters

If I want to run a specific test in a specific environment:

$ tox -e py310 -- tests/test_cli.py::test_hello_world_cli

Black, mypy and pre-commit

I’ll also add some tools to help with development. One more configuration file at the root of the project called .pre-commit-config.yaml:

repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v3.2.0
    hooks:
    -   id: trailing-whitespace
    -   id: end-of-file-fixer
    -   id: check-yaml
-   repo: https://github.com/psf/black
    rev: 22.10.0
    hooks:
    -   id: black
-   repo: https://github.com/pre-commit/mirrors-mypy
    rev: v0.982
    hooks:
    -   id: mypy
        additional_dependencies: [types-all]
        exclude: tests

The idea is to use pre-commit to always run mypy and black before each commit. To set it up in the project:

$ pre-commit install
pre-commit installed at .git/hooks/pre-commit

To run it without making a commit:

$ pre-commit run --all-files

Conclusion

This was the basic skeleton of a command-line application using Python. The source code shown in this post can be found on my github.

References

Makefile as a Command Runner

2022-02-26T23:34:29+00:00

Make is a “build automation tool” according to wikipedia. But it can be useful even when there’s nothing to compile.

It’s possible to use make as a command runner. The advantage of using make for this is that it’s commonly found in Linux distributions. It’s also easy to read, write and maintain a makefile for this purpose.

An example of this can be found in the pydantic project. I’ll use the makefile from version 1.9.0 of the lib as an example:

.DEFAULT_GOAL := all
isort = isort pydantic tests
black = black -S -l 120 --target-version py38 pydantic tests

[...]

.PHONY: lint
lint:
	flake8 pydantic/ tests/
	$(isort) --check-only --df
	$(black) --check --diff

[...]

.PHONY: mypy
mypy:
	mypy pydantic

[...]

.PHONY: test
test:
	pytest --cov=pydantic

.PHONY: testcov
testcov: test
	@echo "building coverage html"
	@coverage html

[...]

.PHONY: all
all: lint mypy testcov

[...]

How make executes a rule

Assuming I’m in the root folder of the pydantic project and I run:

$ make

Make looks for the first rule in the file to start executing. This is called the default goal.

In pydantic’s makefile, it uses the special variable .DEFAULT_GOAL to point to which rule make should execute first. Even though the lint, mypy and testcov rules are written before the all rule, they will be executed afterwards.

How to run a specific rule

If I only want to run the testcov rule:

$ make testcov

In this case make will only run the testcov rule and its dependency target test.

.PHONY targets

The .PHONY syntax is used to signal that the target is not a filename. This avoids a possible conflict with the name of a real file and optimizes performance. The syntax:

.PHONY action_name
action_name: dependencies
  commands
  ...

Print command output

The default behavior of make is that every command executed is sent to standard output. One way to prevent this is to use the -s or --silent flag:

$ make --silent

If you want it to only print without executing the commands, there is the -n or --just-print flag:

$ make --just-print

Help command

Moving away from the pydantic makefile example and into other tips.

Browsing the web there are several examples of ways to automatically add a help command to a makefile. One of the most interesting I found was this one:

.PHONY: help
help:
	@echo "$$(tput bold)Commands:$$(tput sgr0)"
	@echo
	@sed -n -e "/^## / { \
		h; \
		s/.*//; \
		:doc" \
		-e "H; \
		n; \
		s/^## //; \
		t doc" \
		-e "s/:.*//; \
		G; \
		s/\\n## /---/; \
		s/\\n/ /g; \
		p; \
	}" ${MAKEFILE_LIST} \
	| LC_ALL='C' sort --ignore-case \
	| awk -F '---' \
		-v ncol=$$(tput cols) \
		-v indent=19 \
		-v col_on="$$(tput setaf 6)" \
		-v col_off="$$(tput sgr0)" \
	'{ \
		printf "%s%*s%s ", col_on, -indent, $$1, col_off; \
		n = split($$2, words, " "); \
		line_length = ncol - indent; \
		for (i = 1; i <= n; i++) { \
			line_length -= length(words[i]) + 1; \
			if (line_length <= 0) { \
				line_length = ncol - indent - length(words[i]) - 1; \
				printf "\n%*s ", -indent, " "; \
			} \
			printf "%s ", words[i]; \
		} \
		printf "\n"; \
	}' \
	| more $(shell test $(shell uname) == Darwin && echo '--no-init --raw-control-chars')

We can then populate the help command like this:

.PHONY: hello-world
## Prints hello world message to the terminal
hello-world:
	@echo "hello world"


.PHONY: wont-appear-in-help
# This one won't appear in help
wont-appear-in-help:
	@echo "Not shown in help"

The result:

$ make help
Commands:

hello-world         Prints hello world message to the terminal

Splitting commands into different files

Make has an option to specify which file the command will read:

$ make -f FileName.mk

By convention I used the .mk extension for other makefile files in the same project.

In this example project I decided to separate the command runner from the makefile that compiles source files. Considering the folder structure:

├── src
│   └── main.c
├── Makefile
└── MakeGb.mk

In the main makefile, I created the command:

gb:
	@ make -f MakeGb.mk all

So by running make gb, make only compiles the source files.

References

Makefile como executor de comandos

2022-02-26T23:34:29+00:00

O make é uma “ferramenta de automação de compilação” segundo a wikipedia. Mas ela pode ser útil mesmo quando não é preciso compilar nada.

É possível usar o make como um executor de comandos. A vantagem de usar o make para fazer isso é por ser comumente encontrada em distribuições Linux. Além de fácil de ler, escrever e manter um makefile para esse objetivo.

Um exemplo de utilização pode ser encontrado no projeto pydantic. Vou usar como exemplo o makefile na versão 1.9.0 da lib:

.DEFAULT_GOAL := all
isort = isort pydantic tests
black = black -S -l 120 --target-version py38 pydantic tests

[...]

.PHONY: lint
lint:
	flake8 pydantic/ tests/
	$(isort) --check-only --df
	$(black) --check --diff

[...]

.PHONY: mypy
mypy:
	mypy pydantic

[...]

.PHONY: test
test:
	pytest --cov=pydantic

.PHONY: testcov
testcov: test
	@echo "building coverage html"
	@coverage html

[...]

.PHONY: all
all: lint mypy testcov

[...]

Como o make executa uma regra

Considerando que estou na pasta raiz do projeto do pydantic e executo o comando:

$ make

O make procura a primeira regra no arquivo para começar a executar. Isso é chamado default goal.

No makefile do pydantic, ele usa a variável especial chamada .DEFAULT_GOAL para apontar para qual regra o make deve executar primeiro. Apesar das regras de lint, mypy e testcov estarem escritas antes da regra all elas serão executadas depois.

Como executar uma regra específica

Caso eu queira executar só a regra de testcov:

$ make testcov

Nesse caso o make vai executar apenas a regra testcov e seu target com dependência test.

Targets .PHONY

A sintaxe .PHONY é utilizada para sinalizar que o target não é um nome de arquivo. Isso evita um possível conflito com o nome de um arquivo real e otimiza desempenho. A sintaxe:

.PHONY nome_da_acao
nome_da_acao: dependecias
  comandos
  ...

Imprimir comando da saída

O comportamento comum do make é que todo comando executado é enviado para saída padrão. Uma maneira de evitar isso é usar a flag -s ou --silent:

$ make --silent

Caso queira que apenas exiba e não execute os comandos, existem a flag -n ou --just-print:

$ make --just-print

Comando help

Já saindo do exemplo do makefile do pydantic e entrando em outras dicas.

Fuçando na web existem vários exemplos de maneiras de adicionar um comando de help automaticamente num makefile. Um dos mais interessantes que encontrei foi esse:

.PHONY: help
help:
	@echo "$$(tput bold)Comandos:$$(tput sgr0)"
	@echo
	@sed -n -e "/^## / { \
		h; \
		s/.*//; \
		:doc" \
		-e "H; \
		n; \
		s/^## //; \
		t doc" \
		-e "s/:.*//; \
		G; \
		s/\\n## /---/; \
		s/\\n/ /g; \
		p; \
	}" ${MAKEFILE_LIST} \
	| LC_ALL='C' sort --ignore-case \
	| awk -F '---' \
		-v ncol=$$(tput cols) \
		-v indent=19 \
		-v col_on="$$(tput setaf 6)" \
		-v col_off="$$(tput sgr0)" \
	'{ \
		printf "%s%*s%s ", col_on, -indent, $$1, col_off; \
		n = split($$2, words, " "); \
		line_length = ncol - indent; \
		for (i = 1; i <= n; i++) { \
			line_length -= length(words[i]) + 1; \
			if (line_length <= 0) { \
				line_length = ncol - indent - length(words[i]) - 1; \
				printf "\n%*s ", -indent, " "; \
			} \
			printf "%s ", words[i]; \
		} \
		printf "\n"; \
	}' \
	| more $(shell test $(shell uname) == Darwin && echo '--no-init --raw-control-chars')

Assim podemos popular o comando de help da seguinte maneira:

.PHONY: oi-mundo
## Mostra mensagem de oi mundo no terminal
oi-mundo:
	@echo "oi mundo"


.PHONY: nao-aparecer-no-help
# Essa não vai aparecer no help
nao-aparecer-no-help:
	@echo "Não mostra no help"

Temos então o resultado:

$ make help
Comandos:

oi-mundo            Mostra mensagem de oi mundo no terminal

Dividindo comandos em arquivos diferentes

O make tem uma opção onde é possível passar qual arquivo vai ser lido pelo comando:

$ make -f NomeDoArquivo.mk

Por convenção usei a extensão .mk para outros arquivos de makefile no mesmo projeto.

Nesse projeto de exemplo resolvi separar o executor de comandos do makefile que compila os arquivos de código-fonte. Considerando a estrutura de pastas:

├── src
│   └── main.c
├── Makefile
└── MakeGb.mk

No makefile principal, criei o comando:

gb:
	@ make -f MakeGb.mk all

Então ao dar um make gb, o make apenas compila os arquivos código-fonte.

Referências

Aprendendo o básico de makefile

2022-02-24T22:05:44+00:00

Ao decorrer dos anos eu já precisei usar/escrever makefiles várias vezes. Mas eu nunca entendi bem a sintaxe e nunca parei para estudar. Decidi escrever esse post para aprender melhor.

Nada melhor para aprender do que encontrar uma motivação em um projeto pessoal. Inspirado pelo Modern Vintage Gamer nesse vídeo resolvi escrever um makefile simples para compilar jogos de GameBoy escritos em C usando o GBDK-2020.

Criei um repositório com um projeto exemplo para usar como modelo para outros projetos.

Variáveis

Nas primeiras linhas do makefile é definido as variáveis necessárias para configurar as regras de compilação e evitar reescrever a mesma coisa várias vezes.

A sintaxe de uma variável é a seguinte:

NOME_DA_VARIAVEL = valor

O nome das variáveis é case sensitive, mas por convenção são sempre nomeadas em caixa alta. O valor é uma string. Para utilizar o valor das variáveis é só usar $(NOME_DA_VARIAVEL).

Comecei criando algumas variáveis de configuração. Os nomes são auto-explicativos:

NOME_DO_JOGO=foo
ARQUIVO_GB=build/$(NOME_DO_JOGO).gb

DIRETORIO_SOURCES=src
DIRETORIO_OBJ=build
[...]
COMPILADOR=gbdk/bin/lcc

FLAGS_DO_COMPILADOR=-Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG

Funções builtin

Em seguida é preciso definir variáveis que leiam quais arquivos existe no projeto. Para isso utilizarei funções builtin dos makefiles. A primeira é o wildcard:

ARQUIVOS_C=$(wildcard $(DIRETORIO_SOURCES)/*.c)

Como demonstrado na documentação a sintaxe é $(wildcard pattern…). Essa função vai expandir para um valor com nomes dos arquivos que coincidem com o pattern, separado por espaço.

Considerando que a estrutura de pastas seja:

├── build
├── src
│   ├── main.c
│   ├── oi_mundo.c
│   └── oi_mundo.h
└── Makefile

A variável vai conter o valor:

ARQUIVOS_C = src/main.c src/oi_mundo.c

A segunda função buildin que utilizei foi a patsubst. A sintaxe é:

$(patsubst pattern,replacement,text)

Essa função encontra palavras separadas por espaço em text que coincidem com o pattern e substitui pelo formato do replacement. Meio confuso mas é possível entender melhor com o exemplo a seguir:

ARQUIVOS_OBJ=$(patsubst $(DIRETORIO_SOURCES)/%.c, $(DIRETORIO_OBJ)/%.o, $(ARQUIVOS_C))

O objetivo é transformar todos os arquivos de código-fonte (.c) em arquivos objeto (.o). Então no pattern passamos $(DIRETORIO_SOURCES)/%.c para coincidir com todos os arquivos no text, o conteúdo da variável ARQUIVOS_C que criei anteriormente. O replacemnt é o formato que os arquivos .o devem ter na pasta build. O resultado seria:

ARQUIVOS_OBJ = build/main.o build/oi_mundo.o

Regras

Agora vou começar a escrever as regras de compilação. Como indicado no manual cada regra segue a sintaxe:

targets : prerequisites
  recipe
  …

targets: normalmente é o nome do arquivo resultado dessa regra. Mas também pode ser uma ação;
prerequisites: arquivos de entrada ou outro target;
recipe: comando para ser interpretados pelo shell. Por padrão o make usa o /bin/sh ao executar.

A primeira regra que escrevi é essa:

all: criar_diretorio_build $(ARQUIVO_GB)

O primeiro pré-requisito é criar_diretorio_build e logo em seguida temos o arquivo do jogo. O foco aqui é entender que o all é a regra principal do makefile e ela comunica que primeiro é preciso criar a pasta para armazenar os artefatos para em seguida criar o arquivo do jogo.

Para criar o ARQUIVO_GB, o makefile precisa saber como gerar esse arquivo. Então escrevi a segunda regra:

$(ARQUIVO_GB): $(ARQUIVOS_OBJ)
	$(COMPILADOR) $(FLAGS_DO_COMPILADOR) -o $(ARQUIVO_GB) $(ARQUIVOS_OBJ)

Essa regra pode ser lida assim: para gerar o ARQUIVO_GB, passo como entrada ARQUIVOS_OBJ e executa o comando $(COMPILADOR) $(FLAGS_DO_COMPILADOR) -o $(ARQUIVO_GB) $(ARQUIVOS_OBJ).

Para facilitar o entendimento, a regra anterior seria o equivalente a escrever isso:

foo.gb: build/main.o build/oi_mundo.o
  gbdk/bin/lcc -Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG -o build/foo.gb  build/main.o  build/oi_mundo.o

Variáveis automáticas em regras

Antes de continuar para a escrever a próxima regra, preciso primeiro apresentar duas variáveis automáticas: $@ e $<.

No exemplo a seguir

objeto.o: requisito.c
  $(COMPILADOR) $(FLAGS_DO_COMPILADOR) -o $@ $<

$@: O valor do target (objeto.o);
$<: O valor do pré-requisito (requisito.c).

Regras Implícitas

Partindo da ideia de que eu fosse executar os comandos de compilação manualmente, ficaria assim:

$ gbdk/bin/lcc -Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG -c -o build/main.o src/main.c
$ gbdk/bin/lcc -Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG -c -o build/oi_mundo.o src/oi_mundo.c

Então o objetivo aqui é criar uma regra para gerar um comando para cada arquivo objeto sendo construído.

Para ser mais didático, vou partir dessas regras mais simples:

build/main.o: src/main.c
  gbdk/bin/lcc -Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG -c -o $@ $<

build/oi_mundo.o: src/oi_mundo.c
  gbdk/bin/lcc -Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG -c -o $@ $<

O problema dessa abordagem é que ao adicionar um novo arquivo terei que escrever mais uma regra. Para evitar isso posso usar a sintaxe do makefile para compilar qualquer quantidade arbitrária de arquivos. Com a vantagem do make não executar regras novamente se os pré-requisitos não mudaram desde a última vez, deixando esse processo muito mais eficiente.

Mas como fazer isso? Através do conceito de regras implícitas. Um bom tutorial de como isso funciona está aqui.

Basicamente posso substituir pelos patterns e variáveis automáticas:

build/%.o: src/%.c
  gbdk/bin/lcc -Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG -c -o  $@ $<

Essa regra esta definindo que para cada arquivo na pasta build que coincide com o pattern de %.o, vamos ter como pré-requisito outro arquivo na pasta src que coincide com o pattern %.c e vamos executar o comando gbdk/bin/lcc -Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG -c -o $@ $< substituindo o target ($@) e pré-requisito ($<).

Por fim substituindo pelas variáveis já criadas no início:

$(DIRETORIO_OBJ)/%.o: $(DIRETORIO_SOURCES)/%.c
	$(COMPILADOR) $(FLAGS_DO_COMPILADOR) -c -o $@ $<

Regra como executor de comandos

Mas ainda faltam algumas regras extras:

criar_diretorio_build:
	@ mkdir -p build

clean:
	@ rm -rf $(DIRETORIO_OBJ)/*

Por padrão o makefile imprime na saída todo comando executado em uma regra, mas usei o @ no começo do comando para evitar isso.

A regra criar_diretorio_build é auto-explicativa. Já a regra clean é uma regra bastante comum em makefiles, que por convenção apaga e limpa o ambiente. Nessa situação isso significa apagar todos os arquivos na pasta de build.

Makefile completo

NOME_DO_JOGO=foo
ARQUIVO_GB=build/$(NOME_DO_JOGO).gb

DIRETORIO_SOURCES=src
DIRETORIO_OBJ=build

ARQUIVOS_C=$(wildcard $(DIRETORIO_SOURCES)/*.c)
ARQUIVOS_OBJ=$(patsubst $(DIRETORIO_SOURCES)/%.c, $(DIRETORIO_OBJ)/%.o, $(ARQUIVOS_C))

COMPILADOR=gbdk/bin/lcc

FLAGS_DO_COMPILADOR=-Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG

all: criar_diretorio_build $(ARQUIVO_GB)

$(ARQUIVO_GB): $(ARQUIVOS_OBJ)
	$(COMPILADOR) $(FLAGS_DO_COMPILADOR) -o $(ARQUIVO_GB) $(ARQUIVOS_OBJ)

$(DIRETORIO_OBJ)/%.o: $(DIRETORIO_SOURCES)/%.c
	$(COMPILADOR) $(FLAGS_DO_COMPILADOR) -c -o $@ $<

criar_diretorio_build:
	@ mkdir -p build

clean:
	@ rm -rf $(DIRETORIO_OBJ)/*

Referências

Learning Makefile Basics

2022-02-24T22:05:44+00:00

Over the years I’ve had to use/write makefiles many times. But I never really understood the syntax and never stopped to study it. I decided to write this post to learn it better.

Nothing beats learning when you find motivation in a personal project. Inspired by Modern Vintage Gamer in this video I decided to write a simple makefile to compile GameBoy games written in C using GBDK-2020.

I created a repository with an example project to use as a template for other projects.

Variables

The first lines of the makefile define the variables needed to configure the compilation rules and avoid rewriting the same thing multiple times.

The syntax of a variable is as follows:

VARIABLE_NAME = value

Variable names are case sensitive, but by convention they are always named in uppercase. The value is a string. To use the value of variables just use $(VARIABLE_NAME).

I started by creating some configuration variables. The names are self-explanatory:

GAME_NAME=foo
GB_FILE=build/$(GAME_NAME).gb

SOURCES_DIR=src
OBJ_DIR=build
[...]
COMPILER=gbdk/bin/lcc

COMPILER_FLAGS=-Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG

Builtin functions

Next we need to define variables that read which files exist in the project. For that I’ll use make’s builtin functions. The first is wildcard:

C_FILES=$(wildcard $(SOURCES_DIR)/*.c)

As shown in the documentation the syntax is $(wildcard pattern…). This function will expand to a value with the names of files matching the pattern, separated by spaces.

Assuming the folder structure is:

├── build
├── src
│   ├── main.c
│   ├── hello_world.c
│   └── hello_world.h
└── Makefile

The variable will contain:

C_FILES = src/main.c src/hello_world.c

The second builtin function I used was patsubst. The syntax is:

$(patsubst pattern,replacement,text)

This function finds space-separated words in text that match the pattern and replaces them with the replacement format. A bit confusing but it’s easier to understand with the following example:

OBJ_FILES=$(patsubst $(SOURCES_DIR)/%.c, $(OBJ_DIR)/%.o, $(C_FILES))

The goal is to transform all source files (.c) into object files (.o). So in pattern we pass $(SOURCES_DIR)/%.c to match all files in text, the content of the C_FILES variable I created earlier. The replacement is the format the .o files should have in the build folder. The result would be:

OBJ_FILES = build/main.o build/hello_world.o

Rules

Now I’ll start writing the compilation rules. As indicated in the manual each rule follows the syntax:

targets : prerequisites
  recipe
  …

targets: usually the name of the file produced by this rule. But it can also be an action;
prerequisites: input files or another target;
recipe: commands to be interpreted by the shell. By default make uses /bin/sh when executing.

The first rule I wrote is this:

all: create_build_dir $(GB_FILE)

The first prerequisite is create_build_dir followed by the game file. The key point here is that all is the main rule of the makefile and it communicates that we first need to create the folder to store the build artifacts and then create the game file.

To create the GB_FILE, the makefile needs to know how to generate that file. So I wrote the second rule:

$(GB_FILE): $(OBJ_FILES)
	$(COMPILER) $(COMPILER_FLAGS) -o $(GB_FILE) $(OBJ_FILES)

This rule can be read as: to generate the GB_FILE, pass OBJ_FILES as input and run the command $(COMPILER) $(COMPILER_FLAGS) -o $(GB_FILE) $(OBJ_FILES).

To make it easier to understand, the above rule would be equivalent to writing:

foo.gb: build/main.o build/hello_world.o
  gbdk/bin/lcc -Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG -o build/foo.gb  build/main.o  build/hello_world.o

Automatic variables in rules

Before moving on to write the next rule, I first need to introduce two automatic variables: $@ and $<.

In the following example:

object.o: prerequisite.c
  $(COMPILER) $(COMPILER_FLAGS) -o $@ $<

$@: The value of the target (object.o);
$<: The value of the prerequisite (prerequisite.c).

Implicit rules

Starting from the idea that I would run the compilation commands manually, it would look like this:

$ gbdk/bin/lcc -Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG -c -o build/main.o src/main.c
$ gbdk/bin/lcc -Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG -c -o build/hello_world.o src/hello_world.c

So the goal here is to create a rule that generates a command for each object file being built.

To be more didactic, let me start from these simpler rules:

build/main.o: src/main.c
  gbdk/bin/lcc -Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG -c -o $@ $<

build/hello_world.o: src/hello_world.c
  gbdk/bin/lcc -Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG -c -o $@ $<

The problem with this approach is that when adding a new file I’ll have to write another rule. To avoid this I can use makefile syntax to compile any arbitrary number of files — with the bonus that make won’t re-run rules if the prerequisites haven’t changed since the last time, making the process much more efficient.

But how? Through the concept of implicit rules. A good tutorial on how this works is here.

I can basically substitute with patterns and automatic variables:

build/%.o: src/%.c
  gbdk/bin/lcc -Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG -c -o  $@ $<

This rule defines that for each file in the build folder matching the pattern %.o, we’ll have another file in the src folder matching the pattern %.c as a prerequisite, and we’ll run gbdk/bin/lcc -Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG -c -o $@ $< substituting the target ($@) and prerequisite ($<).

Finally, substituting with the variables already created at the beginning:

$(OBJ_DIR)/%.o: $(SOURCES_DIR)/%.c
	$(COMPILER) $(COMPILER_FLAGS) -c -o $@ $<

Rule as a command executor

There are still a few extra rules missing:

create_build_dir:
	@ mkdir -p build

clean:
	@ rm -rf $(OBJ_DIR)/*

By default makefile prints to output every command executed in a rule, but I used @ at the beginning of the command to prevent that.

The create_build_dir rule is self-explanatory. The clean rule is a very common one in makefiles — by convention it deletes and cleans the environment. In this case that means deleting all files in the build folder.

Complete makefile

GAME_NAME=foo
GB_FILE=build/$(GAME_NAME).gb

SOURCES_DIR=src
OBJ_DIR=build

C_FILES=$(wildcard $(SOURCES_DIR)/*.c)
OBJ_FILES=$(patsubst $(SOURCES_DIR)/%.c, $(OBJ_DIR)/%.o, $(C_FILES))

COMPILER=gbdk/bin/lcc

COMPILER_FLAGS=-Wa-l -Wl-m -Wf--debug -Wl-y -Wl-w -DUSE_SFR_FOR_REG

all: create_build_dir $(GB_FILE)

$(GB_FILE): $(OBJ_FILES)
	$(COMPILER) $(COMPILER_FLAGS) -o $(GB_FILE) $(OBJ_FILES)

$(OBJ_DIR)/%.o: $(SOURCES_DIR)/%.c
	$(COMPILER) $(COMPILER_FLAGS) -c -o $@ $<

create_build_dir:
	@ mkdir -p build

clean:
	@ rm -rf $(OBJ_DIR)/*

References

Basic OpenGL Setup with C++ on Linux

2020-10-28T01:59:00+00:00

Before we start we need to check if we have the OpenGL drivers installed on our machine.

$ glxinfo | grep OpenGL
OpenGL vendor string: Intel Open Source Technology Center
OpenGL renderer string: Mesa DRI Intel(R) HD Graphics (Whiskey Lake 3x8 GT2) 
OpenGL core profile version string: 4.5 (Core Profile) Mesa 19.1.8
OpenGL core profile shading language version string: 4.50
OpenGL core profile context flags: (none)
OpenGL core profile profile mask: core profile
OpenGL core profile extensions:
OpenGL version string: 3.0 Mesa 19.1.8
OpenGL shading language version string: 1.30
OpenGL context flags: (none)
OpenGL extensions:
OpenGL ES profile version string: OpenGL ES 3.2 Mesa 19.1.8
OpenGL ES profile shading language version string: OpenGL ES GLSL ES 3.20

If the command output is empty, you’ll need to look up how to install Mesa 3D on your Linux system. But if everything is fine with the drivers, we can move on to the essential libraries:

GLFW
GLEW

To install them on Fedora:

$ sudo dnf install glfw-devel glew-devel

Now let’s start putting it all together and write some code. Let’s create a folder for our first project and create the first source file:

$ mkdir hello-world-opengl && cd hello-world-opengl && touch main.cpp

Using the example of how to create a window provided by the GLFW documentation:

#include <iostream>

#include <GL/glew.h>
#include <GLFW/glfw3.h>

int main() {
    GLFWwindow* window;

    if (!glfwInit())
        return -1;

    window = glfwCreateWindow(640, 480, "Hello World", NULL, NULL);
    if (!window) {
        glfwTerminate();
        return -1;
    }

    glfwMakeContextCurrent(window);

    if (glewInit() != GLEW_OK)
        std::cout << "Error!" << std::endl;

    std::cout << glGetString(GL_VERSION) << std::endl;

    while (!glfwWindowShouldClose(window)) {
        glClear(GL_COLOR_BUFFER_BIT);

        glBegin(GL_TRIANGLES);
        glVertex2f(-0.5f, -0.5f);
        glVertex2f(0.0f, 0.5f);
        glVertex2f(0.5f, -0.5f);
        glEnd();

        glfwSwapBuffers(window);
        glfwPollEvents();
    }

    glfwTerminate();
    return 0;
}

Now what? What do we do with this? We need to compile our code together with the libraries to generate the binary and run it. Let’s use CMake to make the process easier. We need to write the CMakeLists.txt:

cmake_minimum_required(VERSION 3.15)
project(hello_world_opengl)

set(CMAKE_CXX_STANDARD 14)

add_executable(hello_world_opengl main.cpp)
target_link_libraries(hello_world_opengl -lGL -lGLEW -lglfw)

Now just generate the makefile, compile and run the program:

$ mkdir build && cd build
$ cmake ..
-- The C compiler identification is GNU 9.2.1
-- The CXX compiler identification is GNU 9.2.1
-- Check for working C compiler: /usr/lib64/ccache/cc
[...]
$ make
Scanning dependencies of target hello_world_opengl
[ 50%] Building CXX object CMakeFiles/hello_world_opengl.dir/main.cpp.o
[100%] Linking CXX executable hello_world_opengl
[100%] Built target hello_world_opengl
$ ./hello_world_opengl
3.0 Mesa 19.1.8

Result:

If you don’t change anything in CMakeLists.txt, just run make -C ./build && ./build/hello_world_opengl.

Now it’s time to start playing with OpenGL :D.

References:

Setup básico para OpenGL com C++ no Linux

2020-10-28T01:59:00+00:00

Antes de começar precisamos descobrir se temos os drivers para OpenGL instalados na nossa máquina.

$ glxinfo | grep OpenGL
OpenGL vendor string: Intel Open Source Technology Center
OpenGL renderer string: Mesa DRI Intel(R) HD Graphics (Whiskey Lake 3x8 GT2) 
OpenGL core profile version string: 4.5 (Core Profile) Mesa 19.1.8
OpenGL core profile shading language version string: 4.50
OpenGL core profile context flags: (none)
OpenGL core profile profile mask: core profile
OpenGL core profile extensions:
OpenGL version string: 3.0 Mesa 19.1.8
OpenGL shading language version string: 1.30
OpenGL context flags: (none)
OpenGL extensions:
OpenGL ES profile version string: OpenGL ES 3.2 Mesa 19.1.8
OpenGL ES profile shading language version string: OpenGL ES GLSL ES 3.20

Caso a saída do comando esteja vazia é preciso procurar como instalar o Mesa 3D no seu sistema linux. Mas se tudo estiver nos conformes com os drivers, podemos partir para as bibliotecas essenciais:

GLFW
GLEW

Para instalar os pacotes dela no fedora seria algo como:

$ sudo dnf install glfw-devel glew-devel

Agora vamos começar a juntar tudo isso e escrever algum código. Vamos criar a pasta para nosso primeiro projeto e criar o primeiro arquivo de código fonte:

$ mkdir hello-world-opengl && cd hello-world-opengl && touch main.cpp

Usando o exemplo de como criar uma janela fornecido pela documentação do GLFW temos:

#include <iostream>

#include <GL/glew.h>
#include <GLFW/glfw3.h>

int main() {
    GLFWwindow* window;

    if (!glfwInit())
        return -1;

    window = glfwCreateWindow(640, 480, "Hello World", NULL, NULL);
    if (!window) {
        glfwTerminate();
        return -1;
    }

    glfwMakeContextCurrent(window);

    if (glewInit() != GLEW_OK)
        std::cout << "Erro!" << std::endl;

    std::cout << glGetString(GL_VERSION) << std::endl;

    while (!glfwWindowShouldClose(window)) {
        glClear(GL_COLOR_BUFFER_BIT);

        glBegin(GL_TRIANGLES);
        glVertex2f(-0.5f, -0.5f);
        glVertex2f(0.0f, 0.5f);
        glVertex2f(0.5f, -0.5f);
        glEnd();

        glfwSwapBuffers(window);
        glfwPollEvents();
    }

    glfwTerminate();
    return 0;
}

E agora? Fazemos o que com isso? Temos que compilar o nosso código junto com as bibliotecas para gerar o binário e executar o código. Vamos usar o CMake para facilitar o processo. Temos que escrever o CMakeLists.txt:

cmake_minimum_required(VERSION 3.15)
project(hello_world_opengl)

set(CMAKE_CXX_STANDARD 14)

add_executable(hello_world_opengl main.cpp)
target_link_libraries(hello_world_opengl -lGL -lGLEW -lglfw)

Agora só gerar o makefile, compilar e rodar o programa:

$ mkdir build && cd build
$ cmake ..
-- The C compiler identification is GNU 9.2.1
-- The CXX compiler identification is GNU 9.2.1
-- Check for working C compiler: /usr/lib64/ccache/cc
[...]
$ make
Scanning dependencies of target hello_world_opengl
[ 50%] Building CXX object CMakeFiles/hello_world_opengl.dir/main.cpp.o
[100%] Linking CXX executable hello_world_opengl
[100%] Built target hello_world_opengl
$ ./hello_world_opengl
3.0 Mesa 19.1.8

Resultado:

Se não mudar nada no CMakeLists.txt é só dar make -C ./build && ./build/hello_world_opengl.

Agora é só começar a brincar com OpenGL :D.

Referências:

Grafo em C usando lista de adjacências

2019-03-02T22:19:30+00:00

Como falei no post anterior, meu objetivo ao implementar uma lista ligada era para na sequência implementar algoritmos relacionados a grafos. Mas antes disso eu preciso implementar o grafo em si.

A implementação não é indicada para ser utilizada em coisas sérias, é apenas uma prova de conceito. Eu não me importei em verificar se ponteiros são nulos ou se tentaram inserir uma aresta num vértice inexistente.

Uma boa fonte para entender grafos está aqui.

No post anterior eu acabei por esquecer de implementar uma operação de lista ligada que seria útil na implementação do grafo, então vou começar por ela.

Como saber que itens uma lista ligada tem?

Acontece que eu preciso percorrer os itens da linked list para o algoritmo que eu quero implementar. A maneira mais simples de fazer isso (não a mais eficiente e elegante) é percorrer toda a lista e retornar um array com os itens.

uint32_t *LinkedList_Array(llist *self)
{
    uint32_t *array = malloc(sizeof(uint32_t) * self->size);
    link p_aux = self->head;

    for(uint32_t i = 0; i < self->size; i++) {
        array[i] = p_aux->item;
        p_aux = p_aux->next;
    }
    
    return array;
}

Estruturas

Um grafo é um conjunto de vértices conectados por arestas. Existem várias maneiras de representar isso numa estrutura de dados, é possível mencionar Lista de Adjacências, Lista de incidência, Matriz de Adjacências e Matriz de Incidência. A primeira é muito interessante pois é possível fazer várias operações comuns (obter grau de um vértice etc) em grafos de maneira satisfatória, sendo a mais adequada das quatro para ser uma implementação generalista de um grafo.

Uma lista de adjacências é um array de vértices, e cada posição do array contém um ponteiro para uma lista ligada contendo as adjacências do vértice em si. É mais fácil trabalhar com exemplos:

A lista de adjacência seria a seguinte:

V[1]    2->4->              // O vertice 1 se liga ao vertice 2 e 4
V[2]    1->3->4->5->        // O vertice 2 se liga ao 1, 3, 4 e 5
V[3]    2->5->              // etc...
V[4]    1->2->5->
V[5]    2->3->4->

Essa seria a estrutura em C:

struct graph {
    uint32_t n_edges;
    uint32_t n_vertices;
    llist **array_vertices;
};

E como alocar dinamicamente um array de ponteiros?

Nessa hora que o bicho pega. A lógica é simples mas pode ser difícil de lembrar se você não programa em C frequentemente. Quem já teve que alocar dinamicamente uma matriz sabe como fazer.

A implementação nada mais é que um ponteiro para um ponteiro. Primeiro você aloca como um array normal, usando um:

llist **matrix;
matrix = malloc(sizeof(llist *) * n_vertices);

A matriz tem que acomodar um ponteiro para uma lista ligada, e tem que ter o tamanho do número de vértices do grafo.

Depois disso você precisa percorrer cada posição do array e colocar uma lista ligada vazia em cada posição. O detalhe é que caso uma dessas alocações falhe, você tem que ir “voltando” dando free no que você já alocou. Como eu já implementei a alocação da lista ligada, ficou assim:

for(uint32_t i = 0; i < n_vertices; i++) {
    matrix[i] = LinkedList_Create();
    if (matrix[i] == NULL) {
        for(uint32_t j= 0; j<i; j++) 
            LinkedList_Destroy(matrix[j]);
        free(matrix);
        return NULL;
    }
}

No fim, adicionando umas verificação de NULL e retornando a “matriz”:

llist **allocate_matrix(uint32_t n_vertices) 
{
    llist **matrix;

    matrix = malloc(sizeof(llist *) * n_vertices);
    if (matrix == NULL) 
        return NULL;
     
    for(uint32_t i = 0; i < n_vertices; i++) {
        matrix[i] = LinkedList_Create();
        if (matrix[i] == NULL) {
            for(uint32_t j= 0; j<i; j++) 
                LinkedList_Destroy(matrix[j]);
            free(matrix);
            return NULL;
        }
    }
    
    return matrix;
}

Criando e destruindo

Depois que nos livramos desse fardo que é a alocação da matriz de vértices, criar e destruir um grafo é mais do mesmo:

graph *Graph_Create(uint32_t n_vertices) 
{
    graph *self = malloc(sizeof(graph));
    self->n_edges = 0;
    self->n_vertices = n_vertices;
    self->array_vertices = allocate_matrix(n_vertices);

    if(self->array_vertices == NULL) {
        free(self);
        return NULL;
    } else {
        return self;
    }
}

void Graph_Destroy(graph *self) 
{
    for(uint32_t i = 0; i < self->n_vertices; i++) 
        LinkedList_Destroy(self->array_vertices[i]);
    free(self->array_vertices);
    free(self);
}

Agora é possível instanciar um grafo e utilizar como um “objeto”.

Inserindo arestas

Uma operação tão boba. Escolhendo os dois vértices para ligar, u e v por exemplo. Vou na lista ligada de u adicionando v, e vice-versa.

void Graph_InsertEdge(graph *self, uint32_t source, uint32_t destiny) 
{   
    llist *s = self->array_vertices[source];
    llist *d = self->array_vertices[destiny];

    LinkedList_Prepend(s, destiny);
    LinkedList_Prepend(d, source);
}

Note que se eu chamar a função passando source e destiny inexistentes, o programa dá um segmentation fault violento. Mas só quem vai usar sou eu, então tá tudo de boas.

Considerações finais

O próximo passo é implementar algum algoritmo. Vou usar esse repositório para deixar o código disponível, e ir adicionando algoritmos conforme for postando.

No post passado eu falei que estava usando o Ceedling. Acontece que build systems são um inferno. O ceedling funcionou bem para aquele projeto e é um ótimo software, mas como é do nicho do firmware e não muito popular acaba tendo carência de quantidade de informação na internet.

Resolvi fazer minha ultima tentativa: meson. É relativamente popular, tem uma documentação orientada a exemplos e casos comuns, alguns tutoriais no medium…

Para testar migrei o projeto anterior para ele. Esse projeto também faz uso do mesmo. Quem sabe eu faço um post no futuro sobre casos de uso.

Referências

tutorialspoint.com/graph_theory/

Graph in C Using Adjacency Lists

2019-03-02T22:19:30+00:00

As I mentioned in the previous post, my goal when implementing a linked list was to then implement graph-related algorithms. But before that I need to implement the graph itself.

This implementation is not meant to be used in serious projects — it’s just a proof of concept. I didn’t bother checking for null pointers or whether someone tried to insert an edge on a non-existent vertex.

A good resource for understanding graphs is here.

In the previous post I forgot to implement a linked list operation that would be useful in the graph implementation, so I’ll start with that.

How do you know what items a linked list has?

It turns out I need to iterate over the items of the linked list for the algorithm I want to implement. The simplest way to do this (not the most efficient or elegant) is to traverse the entire list and return an array with the items.

uint32_t *LinkedList_Array(llist *self)
{
    uint32_t *array = malloc(sizeof(uint32_t) * self->size);
    link p_aux = self->head;

    for(uint32_t i = 0; i < self->size; i++) {
        array[i] = p_aux->item;
        p_aux = p_aux->next;
    }
    
    return array;
}

Structures

A graph is a set of vertices connected by edges. There are several ways to represent this in a data structure — Adjacency List, Incidence List, Adjacency Matrix and Incidence Matrix are some worth mentioning. The first is very interesting because it allows many common graph operations (getting the degree of a vertex, etc.) to be performed satisfactorily, making it the most suitable of the four for a general-purpose graph implementation.

An adjacency list is an array of vertices, and each position in the array contains a pointer to a linked list holding that vertex’s adjacencies. It’s easier to understand with an example:

The adjacency list would be as follows:

V[1]    2->4->              // Vertex 1 connects to vertices 2 and 4
V[2]    1->3->4->5->        // Vertex 2 connects to 1, 3, 4 and 5
V[3]    2->5->              // etc...
V[4]    1->2->5->
V[5]    2->3->4->

This would be the structure in C:

struct graph {
    uint32_t n_edges;
    uint32_t n_vertices;
    llist **array_vertices;
};

How do you dynamically allocate an array of pointers?

This is where things get tricky. The logic is simple but can be hard to remember if you don’t program in C frequently. Anyone who has had to dynamically allocate a matrix knows how to do it.

The implementation is nothing more than a pointer to a pointer. First you allocate it like a regular array:

llist **matrix;
matrix = malloc(sizeof(llist *) * n_vertices);

The matrix has to accommodate a pointer to a linked list, and it has to be the size of the number of vertices in the graph.

After that you need to go through each position of the array and place an empty linked list at each position. The detail is that if any of these allocations fails, you have to “roll back” by freeing what you already allocated. Since I already implemented the linked list allocation, it looked like this:

for(uint32_t i = 0; i < n_vertices; i++) {
    matrix[i] = LinkedList_Create();
    if (matrix[i] == NULL) {
        for(uint32_t j= 0; j<i; j++) 
            LinkedList_Destroy(matrix[j]);
        free(matrix);
        return NULL;
    }
}

Adding a NULL check and returning the “matrix”:

llist **allocate_matrix(uint32_t n_vertices) 
{
    llist **matrix;

    matrix = malloc(sizeof(llist *) * n_vertices);
    if (matrix == NULL) 
        return NULL;
     
    for(uint32_t i = 0; i < n_vertices; i++) {
        matrix[i] = LinkedList_Create();
        if (matrix[i] == NULL) {
            for(uint32_t j= 0; j<i; j++) 
                LinkedList_Destroy(matrix[j]);
            free(matrix);
            return NULL;
        }
    }
    
    return matrix;
}

Creating and destroying

Once we’ve dealt with the burden of allocating the vertex matrix, creating and destroying a graph is more of the same:

graph *Graph_Create(uint32_t n_vertices) 
{
    graph *self = malloc(sizeof(graph));
    self->n_edges = 0;
    self->n_vertices = n_vertices;
    self->array_vertices = allocate_matrix(n_vertices);

    if(self->array_vertices == NULL) {
        free(self);
        return NULL;
    } else {
        return self;
    }
}

void Graph_Destroy(graph *self) 
{
    for(uint32_t i = 0; i < self->n_vertices; i++) 
        LinkedList_Destroy(self->array_vertices[i]);
    free(self->array_vertices);
    free(self);
}

It’s now possible to instantiate a graph and use it like an “object”.

Inserting edges

Such a trivial operation. Pick the two vertices to connect, u and v for example. Go to u’s linked list and add v, then do the same for v.

void Graph_InsertEdge(graph *self, uint32_t source, uint32_t destiny) 
{   
    llist *s = self->array_vertices[source];
    llist *d = self->array_vertices[destiny];

    LinkedList_Prepend(s, destiny);
    LinkedList_Prepend(d, source);
}

Note that if I call the function passing non-existent source and destiny, the program throws a violent segmentation fault. But I’m the only one using it, so it’s all good.

Final thoughts

The next step is to implement some algorithm. I’ll use this repository to keep the code available and add algorithms as I post about them.

In the previous post I mentioned I was using Ceedling. It turns out that build systems are a nightmare. Ceedling worked well for that project and is great software, but since it’s a firmware niche tool and not very popular, it lacks information on the internet.

I decided to make one last attempt: meson. It’s relatively popular, has example- and use-case-driven documentation, and a few tutorials on Medium…

To test it I migrated the previous project to it. This project uses it as well. Maybe I’ll write a post about use cases in the future.

References

tutorialspoint.com/graph_theory/