aboutsummaryrefslogtreecommitdiff
path: root/CONTRIBUTING.md
blob: aab5a9b175affa53b4755339b690b7663df86c03 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
# Contributing to libcarrot
## Introduction
First of all, thanks for reading this! It probably means you think libcarrot
is worth the effort you are going to put in it, and that rocks! :D

As I want to keep things clean and organized for anyone using this library,
I'm defining this set of rules (from my own coding style, as it is how I
started this project). Don't think it's against you or anything: I just don't
want this project to be a coding style mess, where you have to learn a new
coding style before contributing to any new header/source file.

Any disrespect to those rules in your contribution will make your contribution
not merged upstream until you respect them (this doesn't mean it will always
be accepted if you respect them, don't get me wrong). If you think one of the
rules should really be abolished/is not productive at all, you should discuss
with the current maintainer(s) about it: they have the authority here.

If you have any questions about some obscure point of this contribution guide,
or you have deduced something from the existing codebase and noticed it was
not described here (it should, but writing a contribution guide is far from
being easy), please suggest the changes (by proposing commits or tipping off
the maintainer(s))!

## File organization
Modules are in `./arch`. They are grouped by platform, which, if you haven't
understood that yet, is the kernel/OS for which it is meant. The `all`
platform is special, because all of the modules that don't have a single
platform in mind should go in there -- that's the case for the core modules
containing platform-independant headers, or for modules having specific
architectures (not platforms) in mind.

Each platform or module have an information file, `info.yml`, encoded in
YAML 1.2 (usually with the '%YAML 1.2' magic), which contain
machine-readable information about it. What they should contain is described
in the `FORMATS.md` file. From there, I will suppose you have read the
file and created your information files successfully.

Each module will have a few files and folders ("opt." stands for "optional",
"man." stands for "mandatory") that will be read by the build tools:

- `include/`      (opt.): the C/C++ source headers folder;
- `bits/`         (opt.): the C/C++ header bits folder;
- `src/`          (opt.): the C/C++/ASM source files;
- `info.yml`      (man.): machine-readable information file discussed above;
- `copyright.yml` (rec.): machine-readable copyright information file;
- `roles.yml`     (rec.): machine-readable roles for your source files.

Other files (usually documentation) can of course be put there.

In order not to make a coding style patchwork out of this project, you really
should follow the project's coding style, defined in `CODING.md`. If you don't
and make an upstream merge request with an incorrectly presented code, your
request will systematically be denied. If you think the coding style can be
improved for everyone's comfort, please contact the current maintainer(s),
as they have authority. And please, if it is denied, don't make a scene out
of it: fork this project, and do a better job at maintaining it.

## Roles file (top comments)
**The top comment of each source/include file is NOT hand-written**,
it is generated by a script, `tools/updatesource.py`, which reads the
copyright lines and the licences from the machine-readable copyright
information files `copyright.yml`, and the short description of each file
from the roles files `roles.yml` present in each module root.

See the section about roles files in `FORMATS.md`.

## C/C++ headers and header bits
libcarrot uses a C superpreprocessor, which role is to:

- find the header files in all of the selected modules (usually ending by
  `.h`, `.hpp`, or not having any extension (C++ standard headers));
- regroup those headers into one folder, the header output folder
  (usually `./include` from the project root);
- make the top comment including the authors and licensing information;
- add the appropriate include guards;
- include the appropriate bits at the appropriate places;
- profile and optimize the headers.

The idea behind header bits comes from the glibc `bits/` subfolder, where
machine or platform specific code is located; for example, `bits/endian.h`
defines `__BYTE_ORDER` to `__LITTLE_ENDIAN` when the glibc is compiled for
the x86 or x86_64 architecture.

That's what I did first, but then thought it could be quite heavy and
not optimized enough to include other headers when their content could just
be in the final header. Furthermore, I also wanted to be able to include
zero, one or more headers at one place, using a path; that's how the bits
header came to what it is today.

To include all of the bits with a certain name, you just have to use
`#include_bits <the/bit.h>`, which will include all of the bits having a
relative path `the/bit.h` to the bits directories in the bits path (all of
the found `bits/` directories in the selected modules).

To know which bits are expected, in what sort of modules they should be
defined and what they are expected to define, the modules using this
instruction should have a `BITS.md` documentation at their root (e.g.
in `arch/all/core/`).

## C/C++/ASM source files
Sources are found automatically in the `src` folder, using their extensions
(`c` for C source files, `cpp`, `cc`, `cxx` and others for C++ source files,
and assembler/dialect-specific extensions for assembly source files).
If you don't want a source file to be found, append `.draft`, `.disabled` or
any unrecognized extension to its name.