mirror of
https://github.com/javalsai/lidm.git
synced 2025-07-03 14:25:03 +02:00
90 lines
3.3 KiB
Markdown
90 lines
3.3 KiB
Markdown
# Introduction
|
|
|
|
This file aims to explain the basic project structure and some code conventions
|
|
and patterns used for contributors. If you plan on contributing a considerable
|
|
amount of code, please read this thoroughly to keep the project behavior
|
|
consistent.
|
|
|
|
Even if your changes are not very related to the code, this guide can help to
|
|
understand how they can be related to the rest of the project and what side
|
|
changes it can require.
|
|
|
|
# Structure
|
|
|
|
The file structure is very simple, you have `.c` files in `src/` with their
|
|
header `.h` counterpart in `include/`, they are listed in the `Makefile` and
|
|
built all together on the same layer.
|
|
|
|
Each file contains functions aimed to provide some specialized behavior, they
|
|
tend to follow a common prefix (like `vec_` for vector functions) to avoid name
|
|
collisions with themselves.
|
|
|
|
## Important Files
|
|
|
|
The `main.c` of course provides the entry point of the program, then each file
|
|
has special functionality, but a special one is `util.h`, is linked with almost
|
|
every file and provides some shared utilities to dealing with UTF-8, dynamic
|
|
Vectors and other stuff.
|
|
|
|
`log.c` is also an important file as it provides logging utilities for
|
|
debugging, there's no need to deal with it's initialization, it behaves just
|
|
like standard printing utilities but integrated into the configured logfile.
|
|
|
|
# Debugging
|
|
|
|
The log module can be easily used by just setting up the `LIDM_LOG`
|
|
environmental variable to the logs output path.
|
|
|
|
# Header Files
|
|
|
|
But what if you create a new file? It's important that the definitions are only
|
|
evaluated once by the compiler, even if they are included by several files. For
|
|
this, you can use this simple trick (assume this is for a file named
|
|
`mylib.h`):
|
|
|
|
```h
|
|
#ifndef MYLIBH_
|
|
#define MYLIBH_
|
|
|
|
// library contents
|
|
// ...
|
|
|
|
#endif
|
|
```
|
|
|
|
It's also a good idea to include brief comments above functions if it's not
|
|
evident what they do and name all parameters.
|
|
|
|
# Nullability Checks
|
|
|
|
Nullability checks are not really enforced in the code but it's never a bad
|
|
idea to include them, however, `gcc` doesn't support them under certain
|
|
conditions.
|
|
|
|
For this you can use `NULLABLE`, `NNULLABLE` and `UNULLABLE` macros from
|
|
`"macros.h"` to conditionally include `_Nullable`, `_Nonnull` and
|
|
`_Null-unspecified` respectively.
|
|
|
|
# Handling & Support
|
|
|
|
Every function should properly handle allocation failures (avoid them with
|
|
stack arrays where possible), support UTF-8 strings, use the `log` module
|
|
instead of printing to stdout (messing with the state of the ui) and free all
|
|
lost memory (if it can be lost before reaching the final stage where it execs
|
|
another program, I'm fine with not freeing memory still reachable at the end).
|
|
|
|
# Code format, style and linting
|
|
|
|
Be reasonable and follow `clang-format` and `clang-tidy` rules. `clang-tidy`
|
|
can be quite pedantic with the current primitive rules, so feel free to use
|
|
`LINTIGNORE` or discuss if said rule should be enforced in first place.
|
|
|
|
Also avoid grammar typos and for shell scripts use `shellcheck`, you can run
|
|
this checks with `make pre-commit` if you have the required tools.
|
|
|
|
# Documentation
|
|
|
|
Please, also check if there's documentation related to the feature/changes you
|
|
are implementing, could be on markdown or manpages, if there is and you have
|
|
some spare time, it's really helpful to update it; although not enforced.
|