FDL Tools

idl-c

The idl-c script is the primary parser for FDL 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 Parasol's scripts/dev/ folder. The following command-line parameters are accepted:

Arg	Description
src	The source FDL file (required).
output	Output path for the C++ header. Not required if the FDL 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 parasol SDK. Not normally required as it can be inferred.
files	A list of source files that need to be processed in conjunction with the FDL file.

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

parasol scripts/dev/idl-c src=defs/errors.fdl 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:

parasol scripts/dev/idl-c src=defs/core.fdl 
  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.fluid and requires xsltproc to be installed.

---

idl-compile

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

The compiled IDL is expected to be compiled into the module binary and referenced from its PARASOL_MOD() definition, which will make it available in the module header. Run-time languages like Fluid 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 Parasol's scripts/dev/ folder. The following command-line parameters are accepted:

Arg	Description
src	The source FDL file (required).
output	Output path for the C++ header. Not required if the FDL defines a named module.
feedback	Feedback level, can be set to verbose for extra log messages.
sdk	Refers to the path of the parasol 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:

parasol scripts/dev/idl-compile src=defs/core.fdl 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. Parasol's CMakeLists.txt file has a number of pre-defined functions to help with integrating FDL processing into your build.

They are as follows:

idl_gen()

idl_gen("{FDL_PATH}" NAME "{NAME}" OUTPUT "{OUTPUT}" ...)

idl_gen() is used to generate C/C++ headers from FDL 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}.fdl" NAME ${MOD}_defs
   OUTPUT "${INCLUDE_OUTPUT}/modules/${MOD}.h"
   FILES "class_rsvg.cpp" "class_svg.cpp")

idl_compile()

idl_compile("{FDL_PATH}") NAME "{NAME}" OUTPUT "{OUTPUT_PATH}")

Calls the idl-compile script with FDL_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.fdl" NAME svg_idl OUTPUT "${CMAKE_CURRENT_SOURCE_DIR}/svg_def.c")