# idl-c

The idl-c script is the primary parser for TDL files, producing essential C++ headers and auto-generating interface definitions based on class and module specs.  It also generates XML documentation by way of the idl-doc extension.

The idl-c script is located in Kōtuku's `scripts/dev/` folder.  The following command-line parameters are accepted:

|Arg|Description|
|:-|:-|
|src|The source TDL file (required).|
|output|Output path for the C++ header.  Not required if the TDL defines a named module.|
|feedback|Feedback level, can be set to `verbose` for extra log messages.|
|output-defs|C++ interface definitions (e.g. the module function table) will be output to this file if specified.|
|output-proto|Function prototypes will be output to this file if specified.|
|prototypes|Can be set to `static` to output static prototype functions in conjunction with `output-proto`.|
|sdk|Refers to the path of the Kōtuku SDK.  Not normally required as it can be inferred.|
|files|A list of source files that need to be processed in conjunction with the TDL file.|

This example from the Core API parses `errors.tdl` as a straight header file with no interface definitions:

```
origo scripts/dev/idl-c src=defs/errors.tdl output=sdk:include/system/errors.h
```

This example parses every function interface for the Core API, and auto-generates C prototypes according to their definitions:

```
origo scripts/dev/idl-c src=defs/core.tdl
  output-proto=prototypes.h
  output-defs=data_functions.c
  files={ "core.cpp" "lib_objects.cpp" "lib_base64.cpp" "lib_events.cpp" "lib_fields_read.cpp"
   "lib_fields_write.cpp" "lib_filesystem.cpp" "lib_functions.cpp" "lib_locking.cpp"
   "lib_log.cpp" "lib_messages.cpp" "lib_memory.cpp" "lib_strings.cpp" "lib_unicode.cpp"
   "fs_folders.cpp" "fs_identify.cpp" "fs_resolution.cpp" "fs_volumes.cpp"
  }
```

---

# idl-doc

The idl-doc script is an extension of idl-c and cannot be run independently.  XML documentation is automatically generated as part of idl-c's process, and document files are saved to the `sdk:docs/xml/` path.

We use XML style-sheets to process the XML documents into HTML.  An automated script that will process every manual is located at `sdk:docs/generate.tiri` and requires `xsltproc` to be installed.

---

# idl-compile

idl-compile will parse an TDL file and produce compiled IDL data that is in a universal format.  The IDL describes all classes, structs and constants defined in the TDL source.

The compiled IDL is expected to be compiled into the module binary and referenced from its `KOTUKU_MOD()` definition, which will make it available in the module header.  Run-time languages like Tiri will be able to read the IDL at run-time and bind to it, guaranteeing that the language header and the compiled binary are correctly matched.

The idl-compile script is located in Kōtuku's `scripts/dev/` folder.  The following command-line parameters are accepted:

|Arg|Description|
|:-|:-|
|src|The source TDL file (required).|
|output|Output path for the C++ header.  Not required if the TDL defines a named module.|
|feedback|Feedback level, can be set to `verbose` for extra log messages.|
|sdk|Refers to the path of the Kōtuku SDK.  Not normally required as it can be inferred.|
|format|Set to 'c' if the IDL should be output as a C char string named `glIDL`.  It is otherwise generated as a constant for a `.h` C header, and named `MOD_IDL`.|
|append|If true, the generated output will be appended to the target output file.|

Example:

```
origo scripts/dev/idl-compile src=defs/core.tdl output=idl.h format=c
```

# CMake Support

The IDL scripts are not intended for direct use from the command-line, and should instead be integrated as part of a module's build process.  Kōtuku's `CMakeLists.txt` file has a number of pre-defined functions to help with integrating TDL processing into your build.

They are as follows:

### idl_gen()

`idl_gen("{TDL_PATH}" NAME "{NAME}" OUTPUT "{OUTPUT}" ...)`

`idl_gen()` is used to generate C/C++ headers from TDL files, and produces XML document files as a by-product.  It can also produce IDL output in C-format if `APPEND_IDL` is specified.

The following options are available:

|Option|Description|
|:-|:-|
|NAME|Required.  Defines the CMake target name for add_custom_target().|
|OUTPUT|Required.  Defines the `output` parameter for idl-c and also acts as a CMake dependency.  _Must be a full path_.|
|FILES|A list of C/C++ source files to be passed to the idl-c `files` parameter.|
|ARGS|Additional arguments to be passed directly to the idl-c script.|
|APPEND_IDL|Run the idl-compile script and _append_ the output to the given path.|

```
idl_gen ("${MOD}.tdl" NAME ${MOD}_defs
   OUTPUT "${INCLUDE_OUTPUT}/modules/${MOD}.h"
   FILES "class_rsvg.cpp" "class_svg.cpp")
```

### idl_compile()

`idl_compile("{TDL_PATH}") NAME "{NAME}" OUTPUT "{OUTPUT_PATH}")`

Calls the idl-compile script with `TDL_PATH` as the source and `OUTPUT_PATH` as the target C file, which will be _overwritten_.  The `NAME` must be a unique target name for CMake.

Example of typical usage:

```
idl_compile ("svg.tdl" NAME svg_idl OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/svg_def.c")
```