kdb-gen-highlevel(1) -- High-level API code-generator template

kdb gen highlevel <parentKey> <outputName> [parameters...]

• <parentKey>: the parent key to use, MUST be in the spec namespace
• <outputName>: the base name of the output files. .c will be appended for the source file and .h for the header file.
• [parameters...]: see below

This command invokes the code-generator with the template for the high-level API.

The input for this template is a specification. Keys below the parentKey which have a type metakey are considered part of this specification. Every such key must also either have a default metadata or alternatively must be marked with the require metakey. Keys marked with require must be set by the user, otherwise the initialization of the Elektra handle will fail.

The type metakey may only have one of the following values: enum, string, boolean, char, octet, short, unsigned_short, long, unsigned_long, long_long, unsigned_long_long, float, double, long_double, struct, struct_ref and discriminator. Most of these values correspond to the values supported by the high-level API, the remaining values (enum, struct, struct_ref, discriminator) are treated specially and are part of advanced concepts. For more information on these concepts take a look at elektra-highlevel-gen(7). If one of the advanced type values is used, you should also set check/type = any; otherwise the type plugin may produce an error.

The template produces at least three output files: <outputName>.c, <outputName>.h and <outputName>.mount.sh. The .c file only contains implementations, therefore its precise content will not be documented.

The header (.h) file contains the following parts:

1. Generated enums and structs
2. Declarations for generated accessor functions
3. Tags for accessing keys
4. static inline accessor functions for all tags
5. Declarations of initialization functions
6. Convenience accessor macros

Anything else that may be part of the header file is not considered public API and may be subject to change at any point in time. There is also no guarantee of full compatibility between Elektra version for the documented parts of the header, however, we try to have as little breaking changes as possible for the six parts listed above.

The .mount.sh file is a shell script that can be used to mount the specification for the application. You can either use it as a basis for your own script, or wrap it in another script that correctly sets APP_PATH or SPEC_FILE (depending on your configuration). If the generated script happens to use the correct paths already, you can of course use it directly as well.

For detailed information about the contents of the header file see elektra-highlevel-gen(7).

• initFn: Changes the name of the initialization function (default: loadConfiguration)
• helpFn: Changes the name of the function that prints the generated help message (default: printHelpMessage)
• specloadFn: Changes the name of the function that checks for "specload mode" (default: exitForSpecload)
• tagPrefix: Changes the prefix of the generated tags (default: ELEKTRA_TAG_)
• embedHelpFallback: Switches whether a fallback help message should be embedded; allowed values: 1 (default), 0 If enabled (1), a help message will be generated from the specification passed to the code-generator and embedded into the application. This message will be used, if the normal help message could not be generated at runtime.
• enumConv: Switches how enum conversion should be done; allowed values: default (default), switch, strcmp
  • strcmp: uses a simple series of if (strcmp(*, *) == 0) to convert strings into enums
  • switch: constructs a series of switch statements to convert strings into enums
  • auto: uses a switch up to a depth of 2, then switches to strcmp
• headers: Comma-separated (,) list of additional header files to include. For each of the listed headers we will generate an #include "*" statement
• genSetters: Switches whether setters should be generated at all; allowed values: 1 (default), 0
• embeddedSpec: Changes how much of the specification is embedded into the application; allowed values: full (default), defaults, none. see elektra-highlevel-gen(7)
• specValidation: Changes how the specification will be validated on application start-up; allowed values: none (default), minimal. see elektra-highlevel-gen(7)

The simplest invocation is:

kdb gen highlevel /sw/org/app/#0/current config

However, it is not recommended to have the code-generator read from the KDB, so one should instead use:

kdb gen -F ni=spec.ini highlevel /sw/org/app/#0/current config

If you don't want to embed the full specification in your binary, we recommend:

kdb gen -F ni=spec.ini highlevel /sw/org/app/#0/current config embeddedSpec=defaults specValidation=minimal

For the minimal binary size you may use (this comes with its own drawbacks, see elektra-highlevel-gen(7)):

kdb gen -F ni=spec.ini highlevel /sw/org/app/#0/current config embeddedSpec=none specValidation=minimal

• kdb(1) for general information about the kdb tool.
• elektra-spec(7) for an explanation of the spec namespace.