lcgdict Command

LCG Project | LCG Applications Area

SEAL Project | Project Portal

 

$Date: 2004/06/28 11:16:36 $

Functionality

The lcgdict command is used to generate the C++ code from header files that will be used to populate the LCG C++ Reflection information  when it will be loaded into an application. It is based on the GCC_XML open-source C++ parser, the C++ front-end to GCC, which is currently able to deal with the language in its entirety.

The lcgdict command  is directly available from the SEAL installation <prefix>/SEAL_X_Y_Z/<arch>/bin. It requires to have access to an installation of GCC_XML (from the PATH environment variable or explicitly specified using a command option).

Command syntax
lcgdict headerfile1.h [headerfile2.h] [options] [pre-processor options]
Available Options
-s <file>, --selection_file=<file>
-o <file>, --output <file>
-c, --capabilities=<file>
--pool
--deep
--split
--gccxmlpath=<path>
-h, --help

The lcgdict command produces a C++ file per input header file with the name by default <header>_dict.cpp containing the definition of the dictionary for one or more classes available from the header files. The resulting file will need to be compiled and linked to produce a dictionary library (dynamically loadable library)  that will be later loaded by the application requiring the dictionary.

Command Options

-s, --selection_file=<selectionFile.xml>

The XML selection file is optional. It is used by the  lcgdict command to select from the classes accessible from the input header file, which ones are going to produce dictionary information.  In addition, extra information attached to the dictionary can be added. What information will be attached to dictionaries and can be extended later. Here is an example of selection file:

<lcgdict>
  [<selection>]
    <class [name="classname"] [pattern="wildname"] [id="xxxx"] [type="vector"]/>
    <class name="classname" >
      <field name="m_transient" transient="true"/>
      <field name="m_anothertransient" transient="true"/>
    </class>
  [</selection>]
  <exclusion>
  <class [name="classname"] [pattern="wildname"] />
    <method name="unwanted" />
  </class>
  ...
</lcgdict>

If no selection file is specified, by default, the lcgdict command will generate the dictionary for the classes directly defined at input header file and will ignore any class defined in any included file. In may occur  that the compiler generates "hiddden" implementation specific classes and therefore these classes will appear unfortunately in the list of classes for which to generate the dictionary. To avoid compiler depend behavior it is recommend to use a selection file to explicitly select the classes.

Classes matching the specific class name  (when using attribute "name") or a pattern name with wildcards (when using attribute "pattern") in the <selection> block will be selected. The wildcard characters are: "*" for any undetermined number of characters and "?" for a single one. Notice that the character "*" is interpreted as a wildcard character in patterns instead of the C/C++ pointer. Classes matching the specific class name or a pattern name in the <exclusion> block will be excluded if selected in the selection block.

Extra reflection information can be added for classes, methods and fields:

-o, --output=<file>|<dir>

The -o option specifies the output directory if the name specified is a directory name, otherwise it is interpreted as a file name. The default output is the current directory with the name <header_file>_dict.cpp.

-c, --capabilities=<file>

The -c option tells the lcgdict command to collect all the names of the classes for which the dictionary is generated and produce a function used by the SEAL Plugin Manager to obtain this list. The output capabilities file will located in the same directory as the <header>_dict.cpp file and will need to be compiled and linked with the rest of the other generated files to produce the dictionary library.

--pool

This option tells the lcgdict command to generate the reflection information only for the class data members and their constructors and destructors. This option is useful for obtaining more compact dictionary libraries for projects interested in using only the POOL persistency system.

--deep

This option tells the lcgdict command to generate the dictionary for all the classes in the current header files and an all reachable classes (as members and bases classes)

--split

This option is only needed for Windows platforms. In this platform the method mangled name depends in the visibility attribute of the method (i.e. public, protected, private) and therefore the trick of defining "private" as "public" may result in undefined symbols. The way to solve the problem is to split the resulted output file in two files: a file with the class dictionary definitions file and a file with the "stub" function implementations.

--gccxmlpath=<path>

Option to set the path where to find the the gccxml command. The default is to look in the current PATH.

C-preprocessor options: -D -I -U -P

Any C-preprocessor is accepted as lcgdict command option. These options are passed directly to the gcc_xml command (gcc compiler). 

 

Usage

Example

>lcgdict foo.h
Parsing file foo.h with GCC_XML OK
Generating LCG Dictionary
class Bar
class Foo

Error Messages


Contact: Pere Mato