HACKING

Hacking clr-boot-manager
----------------------

clr-boot-manager makes use of clang-format and a .clang-format configuration
file found in the source root in order to validate changes conform to most of
the style rules around spacing and indentation.

Indentation is strictly 8 spaces (set tab stops to 8 spaces) - No tabs
No spaces between function name and parentheses. Only use space after
"if (", etc.

Curly braces must be on the same line (i.e. expressions) unless it
is the function declaration:

Acceptable:
        int main(int argc, char **argv)
        {
                if (someThingOrOther) {
                        // Do something
                }
                return 0;
        }

Unacceptable:
        int main(int argc, char **argv) {

                if(someThingOrOther)
                {
                        // Do something
                }
                return 0;
        }

When appropriate remember to declare your function first! It helps when
looking back through the file.

Use consistent pointers! "*" should prefix your variable name. Also ensure
your pointers (where appropriate) are not left uninitialized, resulting
in broken free() calls.

Variable and function names are lower case and functions should be fully
spelled out words. Use '_' to split words in variables and functions.

Acceptable:
        char *something = NULL;
        do_function(&something);

Unacceptable:
        char* something;
        doFunc(&someThing);

Minimise your use of "goto"'s, and test every code path is reached. Also
ensure *every* if/else, etc, even if single line, is wrapped in curly braces.

All conditional statements (if, if-else, while, do-while) should always use
brackets regardless of the number of lines in the consequent blocks.

Memory management:
------------------
clr-boot-manager prefers a scope-based approach to memory management,
employing a RAII-like system for allocations. Where possible, avoid
explicit free's and reuse of unrelated variables.

util.h defines a number of autofree()-ready types. These are implemented
using __attribute__ ((cleanup(x))), available in GCC and Clang. Thus,
MSVC (and potentially other compilers) are not supported.

An autofree variable is declared using the autofree() macro, which is
primarily provided for syntatical sugar. Here is an example of a
variable that is automatically reaped/freed when it goes out of scope:

        autofree(char) *error = NULL;

Remember that these *are* scope sensitive, so the following would result
in undefined behaviour:

        char *somestr = NULL;
        {
                autofree(char) *str = strdup("Scoped string\n");
                somestr = str;
        }
        printf("%s: %d\n", somestr, strlen(somestr));

At this point, 'str' has been freed, and somestr still points to the
memory that has now been freed.

As a rule of thumb, if you find yourself in an instance where you have
used an explicit free/unref in a fashion that could be automated, you
should define the cleanup function in util.h (see DEF_AUTOFREE)

C99 vs GLibisms
---------------
clr-boot-manager is implemented using C99 (not GNU C99) and as such must
build with either GCC or Clang using C99 mode (-std=c99). We use the
stdbool type "bool", and public methods should use these in place of
GLib's "gboolean" (which is an integer)

GLib usage is not permitted in clr-boot-manager

Pull Requests/commiting:
------------------------
Commits should clearly define the purpose in less than 80 columns in
the first line. Futher expansion, if needed, should be provided in a
following paragraph, separated by one blank line.