Bless provides a means to wrap any DDL supported binary file (including .situ files -- see the In-Situ Tool for details) with a common format/header that is well-understood by DDL. The output .ddl file format supports a quick-lookup for internal symbols, perfect for accelerating runtime linking. It also helps with porting your software: no more juggling file types and extensions if they're all .ddl files!
Running the program without any arguments produces the following help screen:
Creates a .ddl file that wraps the provided object file.
The new file name will adopt the name of the provided
object file with a 'ddl' extension by default.
Usage:
bless <object file> { -switch }
-v verbose output
-x (curse) extract object file from .ddl
-n no-create (for test purposes)
-f<file> output to file 'file' (overrides default name)
-a<attr> adds an attribute (name=value) to the ddl
-p<file> uses the property file 'file' for attributes
Tutorials That Use Bless
How to Identify Supported Types
All DDL utilities report what types they support on the help screen. Simply run the program with no arguments, and the last line output will display a series of type strings:
> bless ... Supported Object Types: OMF AR DDL SITU ELF SITUMAP OMFLIB
These are explained in The DDL Reference. Bless must be able to support the type in question in order to wrap it.
General Behavior
Bless will attempt to either wrap a binary file as a .ddl, or extract a binary file from a .ddl. It will not destroy the original file, and it will not append to an existing .ddl file. As .ddl files are in the set of all supported DDL binaries for Bless, it can create a redundant wrapper for a .ddl file.
It can also be instructed to append metadata while wrapping (see below). At this time, Bless cannot append metadata to existing .ddl files - the original file must be passed to Bless for a new wrapping pass instead.
Bless also supports a 'no create' mode (see below) that is useful for testing purposes.
How to Wrap a File
Bless can easily wrap up files as .ddl files simply by passing the utility a supported binary file.
> bless mylib.foo
The filename output is automatically given the '.ddl' extension. You can override the entire output filename via the '-f' option:
> bless mylib.foo -fsomething.bar
How to attach metadata
There are two ways to accomplish this. First, is to use the '-a' option, as many times as needed, to attach each attribute:
> bless mylib.foo -afoo=bar -ahello=world
The second is to use a properties file combined with the '-p' option. The properties file can be any filename, with any extension.
> bless mylib.foo -pproperties.txt
The properties file itself is a UTF-8 formatted document that uses the following syntax:
Properties ::= {Comment | Attribute | Empty} eof;
Comment ::= "#" {any} eol;
Attribute ::= Key ws "=" ws Value eol;
Key ::= {any} /!sp;
Value ::= {any} /!sp;
Empty ::= eol;
An example of a properties file:
#Example properties file foo=bar gorf=goat hello=world
How to Extract a Binary From a .ddl
Extraction is performed by using the -x option. This overrides all the other options, except the no-create option.
> bless -xmylib.ddl
This will output the internal binary as a separate file, and will not destroy the original .ddl.
No Create Mode
Using the '-n' option on the command line keeps Enki from writing any files out. This is really only provided for diagnostic purposes.