Skip to content

Contribution

Jump to bottom
Travis edited this page Nov 15, 2023 · 6 revisions

Description

There are generally two ways to contribute to the project: improve the compiler itself or improve the standard library. The compiler is written in C11 language (there are no plans for the self-hosted version so far). The standard library is written in BL and might be easier to start with since the compiler itself can be a bit complicated for newcomers.

Find First Issue

The best way to start is to pick your first issue from the list and start experimenting; issues with good first issue tag are supposed to be the best for newcomers. You can also create your own issue in case you want to fix a bug or improve something not listed there. Note that in case you have plans to do bigger things, it's a good idea to discuss them first on discord.

Building & Testing

Please follow the instructions here.

Project Structure

The following table contains a list of top-level directories in the project root:

Directory Description
bin Compiler executable and other utils.
deps Source code for project dependencies.
docs Project documentation.
etc Compiler local configuration.
how-to Bunch of example projects.
lib BL Standard Library source.
src Compiler C source code.
syntax Some plugins for vim, emacs, and sublime (might be outdated).
tests Compiler unit tests.

Code Formatting

  • Please use clang-format before every commit. The configuration is included in the .clang-format file at the repo root.
  • Use tabs for indentation in all source files (including standard library).
  • There is no column limit specified; keep it reasonable.

Code Guidelines

C

While most of the common patterns might be obvious just by looking at the code, I want to highlight some of them:

  • Use good old snake-case (even for types).
  • For types as int, unsigned int, ... use typedefs in src/basic_types.h so s32, u32, .... The only exception is char* for C strings.
  • We use old-fashioned C namespaces for structs and enums; typedefs are used only in some cases for commonly used basic structures like str_t. See the following example:
struct my_structure {
    ...
};

// Later used with `struct` prefix

void do_something(struct my_structure *my_structure) {}
  • Types (defined using typedef are supposed to use _t suffix in the name (e.g. str_buf_t).
  • Use forward declarations if possible.
  • Each report printed by the compiler should start with a capital letter.
  • Write meaningful error messages giving some hit on what is wrong. Cannot create file 'XY'. vs Cannot initialize a new project, file 'XY' already exists.

Hints

  • Before you start implementing a new utility function, please look into src/common.h; there might already be one implemented for you.
  • Most code editors have plugins for the clang-format (e.g. to invoke it on each save).
  • stb_ds is used for dynamic containers.

BL

No strict rules are defined; follow the style of already existing code. Note that this section might be updated in the future.

Commits

Each commit message should contain an introduction line with [compiler] or [API] tag followed by a short description. In case there are more things to be mentioned in the message, leave an empty line after the introduction and list all other notes below.

[compiler] Fix failing Linux build.

Fix CMakeSetup for Linux.
Fix missing includes.

Testing

  • Each created merge request is supposed to pass all tests on (Windows, Linux, and Mac).

Clone this wiki locally