cve-check-tool/HACKING

Hacking cve-check-tool
----------------------

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 g_free() calls.

Acceptable:
        char *something = NULL;
        doFunc(&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.

Memory management:
------------------
cve-check-tool 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(GError) *error = NULL;

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

        gchar *somestr = NULL;
        {
                autofree(gchar) *str = g_strdup_printf("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
---------------
cve-check-tool 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)

Unless absolutely required, prefer non GIO/GLib methods, as they are
known to cause leaks, and introduce non-portable changes for a high
cost. An example of this is gio leaking both memory and file descriptors
on exit.

Currently there is an ongoing effort to strip all of GIO/GLib usage from
cve-check-tool, so when writing new code please avoid using these libraries.

String Handling
---------------
Internally some code paths may still make use of g_strdup, strdup, asprintf,
etc. Note that the use of the 'strlen' function is not permitted within
cve-check-tool. If you require access to a string length, then please use
the safe cve_string functions:

        /* duplicate a string and compare it*/
        cve_string *str = cve_string_dup("some text");
        if (cve_string_const_equal(str, "some text")) {
                printf("Equal\n");
        }
        cve_string_free(str);

        /* printf style dup */
        cve_string *str = cve_string_dup_printf("X is: %d", x);

        /* Access internal string and length */
        printf("String (len: %d): %s\n", str->len, str->str);

Also note scope based autofree helpers exist for cve_string, so you should
only rarely need to manually free a cve_string:

        {
                autofree(cve_string) *str = NULL;
                str = cve_string_dup("some text");
        } /* Out of scope, now freed */

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.