+- [1. How to Contribute](#how-to-contribute)
+- [2. Debugging](#debugging)
+- [3. Packaging](#packaging)
+- [4. Coding Style](#coding-style)
+ - [4.1 Linux Kernel Style Basics](#linux-kernel-style-basics)
+ - [4.2 Devault Deviations](#devault-deviations)
+ - [4.3 Labwc Specifics](#labwc-specifics)
+ - [4.3.1 API](#api)
+ - [4.3.2 The Use of glib](#the-use-of-glib)
+ - [4.3.3 The use of GNU extensions](#the-use-of-gnu-extensions)
+ - [4.3.4 Naming Conventions](#naming-conventions)
+- [5. Commit Messages](#commit-messages)
+- [6. Submitting Patches](#submitting-patches)
+- [7. Native Language Support](#native-language-support)
+
# How to Contribute
1. Report bugs as github issues. We don't use a template, but try to provide
# Coding Style
-labwc is written in Drew Devault's preferred [coding style] which is based
-on the [Linux kernel coding style].
+labwc is written in the [Linux kernel coding style] with a small number of
+deviations to align with [Drew Devault's preferred coding style] nameley:
+
+1. [Function Declaration](https://git.sr.ht/~sircmpwn/cstyle#function-declarations)
+2. [Braces for one-line statement](https://git.sr.ht/~sircmpwn/cstyle#brace-placement)
+3. [Organisation of header #include statements](https://git.sr.ht/~sircmpwn/cstyle#header-files)
+4. [Breaking of long lines](https://git.sr.ht/~sircmpwn/cstyle#splitting-long-lines)
The reasons for specifying a style is not that we enjoy creating rules, but
because it makes reading/maintaining the code and spotting problems much easier.
-If you're new to this style and want to get going quickly, either just imitate
+If you are new to this style and want to get going quickly, either just imitate
the style around you, or read the summary below and use [checkpatch.pl] to run
some formatting checks.
-## Style summary
+## Linux Kernel Style Basics
+
+The preferred line length limit is 80 columns, although this is a bit soft.
+
+Tabs are 8 columns wide. Identation with spaces is not used.
+
+Opening braces go on the same line, except for function definitions.
+
+Put `*` with the identifier when defining pointers, for example `char *foo`
+
+Spaces are placed around binary operators but not unary, like this:
+
+```
+int x = y * (2 + z);
+foo(--a, -b);
+```
+
+`sizeof(*foo)` is preferred over `sizeof(struct foo)`
+
+Use `if (!p)` instead of `if (p == 0)` or `if (p == NULL)`
+
+Comments are written as follows:
+
+```
+/* This is a single-line comment */
+
+/*
+ * This is a multi-line comment which is much much much much much much
+ * longer.
+ */
+```
-Functions are defined as:
+When documenting functions in header files we use the [kernel-doc format]:
+
+```
+/**
+ * function_name() - Brief description of function.
+ * @arg1: Describe the first argument.
+ * @arg2: Describe the second argument.
+ * One can provide multiple line descriptions
+ * for arguments.
+ *
+ * A longer description, with more discussion of the function function_name()
+ * that might be useful to those using or modifying it. Begins with an
+ * empty comment line, and may include additional embedded empty
+ * comment lines.
+ *
+ * The longer description may have multiple paragraphs.
+ *
+ * Return: Describe the return value of function_name.
+ *
+ * The return value description can also have multiple paragraphs, and should
+ * be placed at the end of the comment block.
+ */
+```
+
+## Devault Deviations
+
+Functions are defined as below with `name` on a new line:
```
return type
}
```
-Opening braces go on the same line, except for function definitions, and are
-mandatory even for one-line statements.
+Braces are mandatory even for one-line statements.
```
if (cond) {
}
```
-Put * with the identifier when defining pointers: `char *foo`
-
-Spaces are placed around binary operators `int x = y * (2 + z);`, but not unary
-`foo(--a, -b);`
-
-```
- /* This is a single-line comment */
-
- /*
- * This is a multi-line comment which is much much much much much much
- * longer.
- */
-```
-
`#include` statements at the top of the file are organized by locality (`<>`
first, then `""`), then alphabetized.
-The line length limit is 80 columns, although it is a bit soft.
-
-Tabs are 8 columns wide. Identation with spaces is not used.
-
When breaking a statement onto several lines, indent the subsequent lines once.
-If the statement declares a `{}` block, indent twice instead.
-
-## labwc specifics
-
-We prefer `sizeof(*foo)` over `sizeof(struct foo)`
-
-We use `if (!p)` instead of `if (p == 0)` or `if (p == NULL)`
-
-When documenting functions in header files we use the Linux kernel approach.
+If the statement declares a `{}` block, indent twice instead. Also, place
+operators (for example `&&`) on the next line.
```
-/**
- * foo - what foo does
- * @var1: description of variable
- * @var2: ditto
- * Notes and further information
- * Return value unless it is obvious
- */
+ if (seat->pressed.surface && ctx->surface != seat->pressed.surface
+ && !update_pressed_surface(seat, ctx)
+ && !seat->drag_icon) {
+ if (cursor_has_moved) {
+ process_cursor_motion_out_of_surface(server, time_msec);
+ }
+ return;
+ }
```
-# API
+## Labwc Specifics
+
+### API
We have a very small, modest API and encourage you to use it.
-1. [common/mem.h](https://github.com/labwc/labwc/blob/master/include/common/mem.h)
+1. `znew()` - as a shorthand for calloc(1, sizeof()) with type checking
+ [common/mem.h]
-Use `struct wlr_box *box = znew(*box);` instead of
-`struct wlr_box *box = calloc(1, sizeof(struct wlr_box));`
+2. `zfree()` to zero after free - [common/mem.h]
-Use `zfree(foo)` instead of `free(foo)` to set foo=NULL.
+3. `wl_list_append()` to add elements at end of lists - [common/list.h]
-# The use of glib
+### The Use of glib
We try to keep the use of glib pretty minimal for the following reasons:
For example, if we were going to carry out extensive string manipulation,
GString and utf8 helpers would be okay. Some functions such as
`g_utf8_casefold()` would be pretty hard to write from scratch and are fine to
-use. Having said that, labwc does not do much string-work and thus far none of
-these have been needed.
+use. Having said that, labwc does not do much string-mangling.
The following functions are used today and are deemed acceptable by the core
devs:
- `g_shell_parse_argv()`
- `g_strsplit()`
+- `g_pattern_match_simple()`
-# The use of GNU extensions
+When using these types of functions it is often desirable to support with some
+glib code, which is okay provided it is kept local and self-contained. See
+example from `src/theme.c`:
+
+```
+static bool
+match(const gchar *pattern, const gchar *string)
+{
+ GString *p = g_string_new(pattern);
+ g_string_ascii_down(p);
+ bool ret = (bool)g_pattern_match_simple(p->str, string);
+ g_string_free(p, true);
+ return ret;
+}
+```
+
+### The use of GNU extensions
We avoid [GNU C extensions] because we want to fit into the eco-system
(wayland and wlroots) we live in.
want to increase the entry-level for OSs without good reason (and currently
we can't think of one).
+### Naming Conventions
+
+There are three types of coordinate systems: surface, output and layout - for
+which the variables (sx, sy), (ox, oy) and (lx, ly) are used respectively in
+line with wlroots.
+
+With the introduction of the scene-graph API, some wlroots functions also use
+node coordinates (nx, ny) but we prefer (sx, sy) where possible.
+
+We do not worry about namespace issues too much and we try to not make the code
+a pain to use just to uniquify names. If we were writing a library we would
+prefix public functions and structs with `lab_`, but we are not. We do however
+prefix public function names with the filename of the translation unit. For
+example, public functions in `view.c` begin with `view_`.
+
+We do start enums with `LAB_`
+
+We use the prefix `handle_` for signal-handler-functions in order to be
+consistent with sway and rootston. For example
+`view->request_resize.notify = handle_request_resize`
+
# Commit Messages
The log messages that explain changes are just as important as the changes
And please wrap the commit message at max 74 characters, otherwise `git log`
and similar look so weird. URLs and other references are exempt.
-# Naming Convention
-
-There are three types of coordinate systems: surface, output and layout - for
-which the variables (sx, sy), (ox, oy) and (lx, ly) are used respectively in
-line with wlroots.
-
-With the introduction of the scene-graph API, some wlroots functions also use
-node coordinates (nx, ny) but we prefer (sx, sy) where possible.
-
-We use the prefix `handle_` for signal-handler-functions in order to be
-consistent with sway and rootston. For example
-`view->request_resize.notify = handle_request_resize`
-
# Submitting patches
Base both bugfixes and new features on `master`.
[`wlroots/docs/env_vars.md`]: https://gitlab.freedesktop.org/wlroots/wlroots/-/blob/master/docs/env_vars.md
[wlhax]: https://git.sr.ht/~kennylevinsen/wlhax
[drm_info]: https://github.com/ascent12/drm_info
-[coding style]: https://git.sr.ht/~sircmpwn/cstyle
+[Drew Devault's preferred coding style]: https://git.sr.ht/~sircmpwn/cstyle
[Linux kernel coding style]: https://www.kernel.org/doc/html/v4.10/process/coding-style.html
+[kernel-doc format]: https://docs.kernel.org/doc-guide/kernel-doc.html
+[common/mem.h]: https://github.com/labwc/labwc/blob/master/include/common/mem.h
+[common/list.h]: https://github.com/labwc/labwc/blob/master/include/common/list.h
[commit messages]: https://gitlab.freedesktop.org/wlroots/wlroots/-/blob/master/CONTRIBUTING.md#commit-messages
[checkpatch.pl]: https://github.com/johanmalm/checkpatch.pl
[GNU C extensions]: https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html
projects / proto / labwc.git / commitdiff