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:
iqb_compiler_proxy (not called directly, but through symbolic links)
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.
To install IQB®:
- Install Java 6 (or newer), if necessary (refer to your specific Java installation instructions).
- Install PDToolkit 3.17, if necessary:
Shell12345wget http://tau.uoregon.edu/pdt.tgztar -xvzf pdt.tgz cd pdtoolkit-3.17./configure -prefix=<desired-path-to-PDT-installation>/pdtoolkit-3.17makemake install
- Download and expand the IQB tarball:
Shell12wget http://www.paratools.com/downloads/iqb.tgztar -xvzf iqb.tgz
- Configure the installation:
Shell12cd iqb-1.0.1./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
- Set your path so that the IQB compiler comes first in your path:
for sh/bash, or:Shell1source sourceme.csh
for csh/tcsh. If you'd like to do it manually, you can do this (sh/bash):Shell1export PATH=<path-to-IQB-installation>/iqb-1.0.1/bin:$PATH
or this (csh/tcsh):Shell1setenv PATH <path-to-IQB-installation>/iqb-1.0.1/bin:$PATH
- Test the installation:
- 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.
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.
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.
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.
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:Shell123456gcc -c program.c -o program.oprogram.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: /mnt/netapp/home1/khuck/facets/iqb-1.0.1/examples/sample-library/include/sample.h SAMPLE_CONSTANTEnter the symbol file path to use (0 to exit): 1
Missing -I include path:Shell123456gcc -c program.c -o program.oprogram.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.hEnter the header file path to use (0 to exit): 1
- Missing library:
Shell123456789gcc -I../sample-library/include -c program.c -o program.ogcc -o program program.oprogram.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_function2 : /mnt/netapp/home1/khuck/facets/iqb-1.0.1/examples/sample-library/lib/libsample.a sample_functionEnter the symbol file path to use (0 to exit): 2
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.