MakeKit provides a few amenities to make your stay in the world of shell script more enjoyable. As you may have noted in the previous chapter, many functions in MakeKit take parameters with explicit names of the form VAR=value. For example:

mk_program \
    PROGRAM="hello" \
    SOURCES="hello.c" \
    INCLUDEDIRS="../include" \
    LIBDEPS="foobar"

These keyword parameters make it clear at a glance what each one means even if you aren't familiar with the function in question. Note that because this is simply a call to a shell function, each line except the last needs a backslash to continue the parameter list on the next line. This is the recommended way to format calls to functions with many parameters.

The keyword parameters in a function call may appear in any order. Many functions have optional parameters that may be omitted entirely.

You can write your own functions that take keyword parameters using mk_parse_params. This will set each keyword parameter passed to your function to the shell variable of the same name. You should consider using mk_push_vars and mk_pop_vars to avoid clobbering their existing values.

Often a function will take a list of items as one of its keyword parameters, such as the SOURCES parameter in the above example. Lists in MakeKit are whitespace-separated. You could add goodbye.c to the above example as follows:

mk_program \
    PROGRAM="hello" \
    SOURCES="hello.c goodbye.c" \
    INCLUDEDIRS="../include" \
    LIBDEPS="foobar"

If you want to use spaces in an item, you will need to add an additional level of quoting around that item. Since the SOURCES parameter is enclosed in double quotes, the easiest option is to use single quotes within it:

mk_program \
    PROGRAM="hello" \
    SOURCES="hello.c goodbye.c 'this name has spaces.c'" \
    INCLUDEDIRS="../include" \
    LIBDEPS="foobar"

If a list is getting a bit long and you want to line wrap it, be sure to use a backslash at the end of each line to indicate that it continues to the next:

mk_program \
    PROGRAM="hello" \
    SOURCES="hello.c \
             goodbye.c \
             'this name has spaces.c'" \
    INCLUDEDIRS="../include" \
    LIBDEPS="foobar"

Any list passed in this manner must be internally shell-quoted to preserve characters that have special meaning to the shell, such as spaces and dollar signs. If the extra quoting is tripping you up, there is an alternative syntax that lets you specify a list as ordinary function parameters, removing one of the layers of quoting:

mk_program \
    PROGRAM="hello" \
    @SOURCES={ hello.c goodbye.c "this name has spaces.c" } \
    INCLUDEDIRS="../include" \
    LIBDEPS="foobar"

If you wish to programmatically quote a string or lists of strings so that they are suitable to pass as one of these parameters, use mk_quote or mk_quote_list. You can expand a quoted list into the position parameters ($1, $2, ...) using mk_unquote_list.

MakeKit allows you to declare variables with special behavior using the mk_declare function. There are 4 types of attributes which may be used in any combination:

Many MakeKit functions conveniently accept file paths relative to the current MakeKitBuild file in the hierarchy (in fact, as you will soon find out, it is a bit more sophisticated than that). However, if you are calling out to a trusty UNIX program such as sed or cp you will need to be a bit more specific about where to look. There are several variables that indicate areas where files of interest can be found:

Rather than forcing you to use the aforementioned variables whenever you want to specify the location of a file, most MakeKit functions accept paths in a standard target notation.

A relative path (one not beginning with a /) indicates a file relative to MK_SOURCE_SUBDIR or MK_OBJECT_SUBDIR. If the file exists in the source directory at the time the target is resolved, then it is taken to be that file. Otherwise, it is assumed to be an intermediate build product in the object directory.

An absolute path (one beginning with /) indicates a file relative to MK_STAGE_DIR. For example, using mk_stage allows you to create a rule that simply copies a file. If you indicate that you want to copy a file to /etc/foo.conf, this will result in a Makefile rule that actually creates $MK_STAGE_DIR/etc/foo.conf.

Finally, there is a fully-qualified form that all targets are resolved to. If a target begins with @, it indicates that the following path should be interpreted verbatim. If the path is relative, it is relative to MK_ROOT_DIR. If it is absolute, then it indicates that precise absolute path on the filesystem. You can use mk_resolve_target to resolve any target to this canonical form.

In general, functions that perform configuration tests, process build files, or create build rules use target notation for any paths they accept. On the other hand, there are many pure utility functions (such as mk_mkdir) that perform useful filesystem operations or paper over incompatibilities between various flavors of UNIX; these accept ordinary paths.