The DDL File format solves a number of problems unique to the problem space of DDL. In general it will allow you to use DDL in a manner that is more organized, more efficent and more friendly to other developers as well as users of your software.
For information on how to parse a .ddl file, please see the BNF for the DDL V1.1 file format at the bottom of this document.
Creation of .ddl files is performed exclusively by the Bless utility.
Embedded Binaries
The primary use for a ddl wrapper for your OMF, COFF or ELF library is to give it a name common across all platforms that you may port your application to. When a binary is packaged into a ddl wrapper, it is interrogated for various bits of information which are encoded into the wrapper itself. This way, even if your target platform doesn't have support for that particular binary, it can at least divulge some information about it (as long as it has .ddl support).
The binary type is also encoded in the ddl wrapper. The following values are used to map to the supported DDL types.
- "OMF" - Object Module Format (Intel 32bit) - .obj file
- "OMFLIB" - Object Module Format (Intel 32bit) - .lib file
- "PE/COFF" - Program Executable / Common Object File Format (Microsoft 32bit)
- "ELF" - Executable and Linkable Format
Other types may be added as they become supported by DDL.
Versioning
The ddl file format has a version field as a part of the specification. This is to ensure that a given program has an opportunity to do something intellegent with a .ddl file should it be the wrong version.
Attribute Metadata
Sometimes, you need more information than what is typically available in your binary file. This can involve things such as authoring information, support contacts, and additional resource dependencies. As these things can be so widely varied, the ddl file format supports arbitrary metadata for just this purpose. These are stored in a name = value format, which should support just about any kind of use.
There are some standard keys that are reccomended for common use across all applications, that are free to be used by ddl developers/authors. These are all understood to begin with the prefix "std.".
- "std.version" - the version of this library (used directly by the library loading architecture within DDL)
- "std.author" - the author of the enclosed binary
- "std.author.url" - url for the author's webpage or email address
- "std.filename" - the filename of the enclosed binary (w/o full path)
- "std.copyright" - a copyright notice for the file
- "std.license" - the kind of use license for the binary (eg. "bsd" or "lgpl")
- "std.license.url" - url for the full text of the license
- "std.support" - text about getting support for this library
- "std.support.url" - url for the support email address or webpage
It is strongly reccomended that the ddl developer/author add attributes as needed outside the "std." namespace so that future attribute use reccomendations for the ddl file format can be added to the "std." namespace without collision. Several of the supported file types also use prefixes like "omf.", "coff.", "elf." and "zip." to denote attributes specific to certain file types; these too should be avoided.
Defined Namespaces and Module Dependencies
The ddl file format exposes any D module namespaces and module dependencies that the embeded binary may have. This is a feature that is provided almost explicitly for accelerating runtime linking of D binaries, such that the internal binary does not have to be parsed and loaded before discovering this kind of information.
As DDL supports library files in general, regardless of their original language of origin, these two lookups may be incomplete or even empty, depending on the library in question.
Accelerated Linking
Since the DDL file format is so easy to parse, and it exposes so much information up front, it can be used to accelerate runtime linking operations by delaying the load and parse of the embedded binary file until its actually needed.
DDL File BNF
The BNF for a DDL file is as follows. Note that the version production is actually split as two 16-bit values where the high word is the major version and the lower word is the minor version. In this case, the DDL format is presently version 1.1.
BNF of the .ddl File Format
ddlfile ::= header embeddedFile EOF header ::= magic version binaryStart binaryType processorArch definedNamespaces importedModules attributes magic ::= 'D' 'D' 'L' '!' version ::= 0x00010001 binaryStart ::= uint binaryType ::= string processorArch ::= string definedNamespaces ::= count string(count) importedModules ::= count string(count) attributes ::= count attrib(count) attrib ::= name value name ::= string value ::= string string ::= count char(count) count ::= uint embeddedFile ::= ubyte?