IQB

IQB®

IQB® is a utility for resolving compiler and linker errors which result from missing symbol declarations or definitions. This can happen in the cases of missing #include statements, missing -I flags, or missing libraries in the link step. IQB automatically parses the error output from the compiler, and searches the pre-built database of symbols or headers which were indexed on the system. If a match is found, you are prompted with a list of solutions which are automatically integrated into the compile or link. For more details, see the Compiling information.

There are four main utilities that come with IQB:

Requirements

IQB® requires the Java 6 runtime (or newer), from Oracle (or equivalent) and PDToolkit 3.17 from the University of Oregon TAU project. For more information on PDT, see the Program Database Toolkit website.

Download

Download IQB!

Install

To install IQB®:

  1. Install Java 6 (or newer), if necessary (refer to your specific Java installation instructions).
  2. Install PDToolkit 3.17, if necessary:
       1 wget http://tau.uoregon.edu/pdt.tgz
       2 tar -xvzf pdt.tgz
       3 cd pdtoolkit-3.17
       4 ./configure -prefix=<desired-path-to-PDT-installation>/pdtoolkit-3.17
       5 make
       6 make install
    
  3. Download and expand the IQB tarball:
       1 wget http://www.paratools.com/downloads/iqb.tgz
       2 tar -xvzf iqb.tgz
    
  4. Configure the installation:
       1 cd iqb-1.0.1
       2 ./configure -optPDT=<path-to-PDT>/pdtoolkit-3.17
    

    The IQB configuration is an interactive process, which should be self-explanatory. For the most common installations, enter the following:

    • select option 1
    • select option 1, confirm database location
    • select option 4 to load the schema
    • select database 1
    • select option 5
    • exit configuration
  5. Set your path so that the IQB compiler comes first in your path:
       1 source sourceme.sh
    
    for sh/bash, or:
       1 source sourceme.csh
    
    for csh/tcsh. If you'd like to do it manually, you can do this (sh/bash):
       1 export PATH=<path-to-IQB-installation>/iqb-1.0.1/bin:$PATH
    
    or this (csh/tcsh):
       1 setenv PATH <path-to-IQB-installation>/iqb-1.0.1/bin:$PATH
    
  6. Test the installation:
       1 cd examples
       2 make
    
    This will:
    • Build a sample library
    • Index the sample header and library
    • Load the mappings into the database
    • Build three projects, each with a different problem. The first project is missing a #include statement. The second project has the #include statement, but is missing the -I flag on the compile line. The third project is missing the library in the link step.

Indexing

To index a directory (of headers, libraries, objects or any combination) run the iqb_processdirectory utility:

iqb_processdirectory -d <directory_name> -o <outfile.xml>

Alternatively, the directory can be processed straight into the database:

iqb_processdirectory -d <directory_name> -s

For more information about the iqb_processdirectory utility, use the -h option. NOTE: If a very large directory is processed, the resulting XML file might be too large to process by iqb_loadmappings. For very large directories, we recommend using the -s/--straight option, or process subdirectories one at a time.

Loading

To load the index into the database, run the iqb_loadmappings utility:

iqb_loadmappings -x <outfile.xml>

For more information about the iqb_loadmappings utility, use the -h option.

Querying

To query the database, use the ilocate utility:

ilocate -s some_symbol
ilocate -d some_header_file 

For more information about the ilocate utility, use the -h option.

Compiling

To compile with IQB, simply prepend the IQB bin directory to your path (alternatively, you can source the sourceme.sh or sourceme.csh file). See above for details.

When IQB is in the user's path, the compiler proxy scripts are executed rather than the actual compiler. The proxy script will run the actual compiler, and capture the result. If the compiler returns an error that can be handled by IQB, the user is prompted by IQB to select a solution, which is usually written to the .iqb-includes.txt file in the current working directory. The compiler proxy script recursively calls itself, resolving errors as it can and adding to the .iqb-includes.txt file upon each successful iteration.

Some example sessions:

  • Missing #include statement:

    gcc  -c program.c -o program.o
    
    program.c: In function "main": program.c:8: error: 'SAMPLE_CONSTANT' undeclared (first use in this function) program.c:8: error: (Each undeclared identifier is reported only once for each function it appears in.) ...
    
    Searching for symbol: SAMPLE_CONSTANT
    1 : /mnt/netapp/home1/khuck/facets/iqb-1.0.1/examples/sample-library/include/sample.h SAMPLE_CONSTANT
    Enter the symbol file path to use (0 to exit): 1
  • Missing -I include path:

    gcc  -c program.c -o program.o
    
    program.c:4:20: error: sample.h: No such file or directory ...
    
    1 : /mnt/netapp/home1/khuck/facets/iqb-1.0.1/examples/sample-library/include/sample.h
    Enter the header file path to use (0 to exit): 1
  • Missing library:
    gcc -I../sample-library/include -c program.c -o program.o
    gcc  -o program program.o
    
    program.o: In function `main': program.c:(.text+0x2e): undefined reference to `sample_function' 
    collect2: ld returned 1 exit status ...
    
    1 : /mnt/netapp/home1/khuck/facets/iqb-1.0.1/examples/sample-library/lib/libsample.so.1 sample_function
    2 : /mnt/netapp/home1/khuck/facets/iqb-1.0.1/examples/sample-library/lib/libsample.a sample_function
    Enter the symbol file path to use (0 to exit): 2

License

Copyright ParaTools, Inc., 2011-2012. IQB® is a registered trademark of ParaTools, Inc. All rights reserved. IQB is a licensed product with a demo evaluation license that expires on Dec. 31, 2012. Please contact ParaTools Information <info AT paratools DOT com> for a permanent license key.