Note: The libtodb tool is obsolete. Please refer to the LSB Library Import Tools for more information about importing libraries information to the LSB database.
The libtodb tool is developed to speed up the addition of new library into LSB Database. This tool uses `readelf` to get the DWARF info from a library, It parses the output of `readelf` and then puts it in a format which can be compared or inserted into the LSB Database.
Before using this tool I strongly recommend setting up a local copy of the LSB specification database. If you remotely run libtodb against a central LSB mysql server, it will execute painfully slow (it makes many, many database queries) and may make harm to the db if something goes wrong.
You need to know following information about library before you insert into LSB Database. This information would be required by tool.
|Information||Used by option||Description||Required/Optional|
|Library run time name||-S||grep SONAME||R|
|Header Name||-H||Header file used by library and path should be relative to /usr/include||R|
|Standard||-s||Standard (either an FSG approved spec, an ISO spec, an IETF RFC on the standards track or from an organization in liaison with ISO) defines the Interface or Interfaces entered using this tool. DB index (DBi) is a index value of standard entry, can be found from specdb/Standard.init file, if standard DOESN'T EXIST THEN CREATE ONE. If NO standard defined for an interface then use LSB STANDARD, index value of LSB is 10||R|
|Module||-M||Module this library belongs. DB index (DBi) is a index value of Module entry in specdb/Module.init file. if entry DOESN'T EXIST THEN CREATE ONE||R|
|Host Architecture||-A||Architecture of machine where debugged version of library was compiled (refer Architecture.init to find appropriate string e.g. IA32) This architecture info is used to enter size and offset data of different datatype appropriately||R|
|Architecture||-a||By Default interfaces is added for all architecture, you can override by specifying the architecture||O|
|Library Group||-L||This option is used to specify the LibGroup Name. This is optional when inserting interfaces into DB. Default will take if not specified.||O|
|Exclude/Include interface||-l/-x||By default this tool insert all the exported interfaces in given library, you can control that by creating a include or exclude list, file has to have one symbol per line||O|
|Exclude/Include type||-X/-T||Tool enters all the datatype associated with public interfaces, but in certain cases that may not be the complete list of datatypes, so you can use this option to force to add missing types. You can specifiy the list in the form of exclude or include. List one interface per line in a file. Specify path of that file (File name is optional for -X, switch required to enable this feature).||O|
|Opaque datatypes||-o||List of data type, which appears as opaque reference in header file. List one interface per line in a file. Specify path of that file.||O|
|Regular expression||-e||Exclude interfaces matches the regex||O|
|Constants||-c||List all the #define in a file in a given specific format, format should be <type>#define identifier token-sequence or <type>#define identifier (identifier-list) token-seq. Here <type> is as defined in the database Constants.Ctype field. Default value of type is int if type is not defined in angle bracket. e.g. <>#define MAX 256||O|
User need to build a debug version of the library, most cases you can do this by specifying --enable-debug switch during configuration, otherwise either look for an option or modify makefile.
To run libtodb, you'll need to pass the parameters it needs for connecting to the mysql server along with other option. You can feed it command-line options, as detailed in the output of './libtodb -h' or, you can set the environment variables as suggested in LSB SpecDB setup wiki page for DB connection.
`./libtodb [options] <library filename>`
e.g. for glib `./libtodb -q -H glib-2.0/glib.h -i -M 4 -s 96 -S libglib-2.0.so.0 -A IA32 -X ./extype.list -x ./ex.list -c ./const.def ~user/glib-2.0/libglib-2.0.so.0.600.4`
NOTE: I strongly encourage you to read the tool help before using it.
This section list the instructions to run other tools which consumes data insert by libtodb tool. This section just capture what I learned during validation of libtodb tool, so may not be complete. Ideally this page just cross reference the respective tool wiki pages.
DevChk test suite should be generated and executed to check the collected data against the system headers.
Building stub library
Now run DevChk test suite against the generated headers.
The tool itself is organized into several smaller units.
In the beginning, the script handles command-line options, sets up sql queries, and does some housekeeping necessary to parse the DWARF info.
Next, the script reads the DWARF information from the library whose name it is given. (This is the loop containing get_level1_record().) get_level1_record() calls a whole bunch of functions, which also call each other. This whole system is composed of the functions beginning with "parse", and is in the section labeled "DWARF parsing subroutines". It puts all of this information into a few internal hashes.
The section titled "DB reading functions" contains subroutines that build a tree of hashes, rooted at an interface. The script currently builds one such tree for every interface that it sees in the public section of the DWARF information that it already parsed.
The section titled "Print naked reports" contains subroutines that take one of the trees constructed above and output them in a tree-like format; this makes their structure visible. It's mostly there for debugging, but might also be useful to be a way to simplify hand-editing in exceptional cases that this script might not handle. It's also a good example of how to traverse the interface trees.
The section titled "Database Editing" adds parsed DWARF interfaces to the database. Approach here is top down, It starts adding the interface and adds all the relevant data type and so on.
The section titled "#define handling" handles the addition of #defines.