(C) Copyright Microsoft Corporation, 1987 Microsoft (R) QuickC (TM) Compiler, Version 1.0 QLIB.DOC This document describes the new QLIB utility, which builds Quick libraries from existing C source files, existing object files, or standard-library routines. This utility provides a method for building Quick libraries that is simpler than the methods described in Sections 10.1.1 and 10.1.3 of the Microsoft QuickC Compiler Programmer's Guide. Installing QLIB --------------- The files required to run QLIB are on Disk 3 of the package. If you want to be able to run QLIB from any directory, install the QLIB files as shown below: 1. Copy the QLIB.EXE and QLIB.INI files to any directory or directories given in the PATH environment variable. 2. Copy the QUICKLIB.OBJ file to the directory given in the LIB environment variable. Building Quick Libraries from Existing Files -------------------------------------------- To build a Quick library containing existing C source or object files, simply specify these files on the QLIB command line. Note that any object files must have been compiled with the medium memory model (either created in the QuickC environment or compiled with the /AM option on the QCL command line). Example: QLIB HELPER1.C HELPER2.OBJ The example above compiles the HELPER1.C file and, if no errors occur, links it with the HELPER2.OBJ file to produce a Quick library named HELPER1.QLB. You can give wild-card characters on the QLIB command line. Example: QLIB *.C The example above compiles and links all C source files in the current directory to produce a Quick library. Searching for Standard-Library Routines: The /S Option ------------------------------------------------------- QLIB can search any text file, including a C source file, for the names of standard-library functions and build a Quick library containing these functions. Simply give the /S option, followed by any files to be searched, on the QLIB command line. QLIB finds any function names that do not appear in C comment blocks and combines these functions in a Quick library. As QLIB searches each file, it lists on the standard-output device any routines that are not in the core library. Example: QLIB /S MOD1.C MOD2.C MOD3.C If you enter the command line above, QLIB searches the C source files MOD1.C, MOD2.C, and MOD3.C for any standard-library functions and creates a Quick library named MOD1.QLB containing these functions. QLIB can search files other than C source files, and it can find function names even if the name does not appear as a function call. Example: If you have a file named ADDLIB.TXT with the contents asin(); cabs [_dos_write] _arc() /* ceil(); floor(); */ and you enter the command line QLIB /S ADDLIB.TXT QLIB builds a Quick library containing the asin, cabs, _dos_write, and _arc functions. It does not include the ceil and floor functions because these functions appear in a comment block. You can build Quick libraries containing both your own modules and standard- library functions using the same QLIB command line. Example: QLIB HELPER1.C MOD?.OBJ HELPER2.C /S *.C The command line above tells QLIB to compile HELPER1.C and HELPER2.C and combine the resulting object files, the object files specified by MOD?.OBJ, and any standard-library routines found in any C source file in the current directory. The resulting Quick library is named HELPER1.QLB. Renaming the Quick Library: The /N Option ------------------------------------------ Ordinarily, the Quick library produced by QLIB has the same base name as the first file on the command line, plus the extension .QLB. To rename the Quick library, give the /N option, followed by the new file name, on the QLIB command line. To use the default extension .QLB, simply give the base name after the /N option. Example: QLIB /N MODULES MOD1.OBJ MOD2.OBJ MOD3.OBJ The command line above combines the given object files into a Quick library named MODULES.OBJ. Using Additional Libraries: The /L Option ------------------------------------------ When QLIB finds the name of a standard-library function in a file, it pulls that function into the Quick library from the standard C library MLIBCE.LIB. To pull functions from libraries other than MLIBCE.LIB, give the /L option, followed by the name of the other library or libraries, on the command line. Example: QLIB DRAWING.C /L GRAPHICS.LIB MYMATH.LIB The example above compiles DRAWING.C and places the resulting object file, along with any of the routines required by DRAWING.C from the GRAPHICS.LIB and MYLIB.LIB libraries, in a Quick library named DRAWING.QLB. Turning Off Memory-Model Checking: The /O Option ------------------------------------------------- Ordinarily, if any object file used for a Quick library is not a medium-model file, QLIB cannot build the Quick library. However, in some cases (for example, object files produced by the Microsoft Macro Assembler (MASM)), QLIB cannot determine whether or not an object-file was created with the medium model. If you want to include object files without memory-model information in a Quick library, or if you know that all of the object files you want to include were compiled with medium model, give the /O option on the QLIB command line. This option also speeds the library-building process. However, if you give this option and include non-medium-model object files in a Quick library, the results will be unpredictable. Example: QLIB /O /N TOTAL.QLB *.OBJ The example above combines all object files in the current directory into a Quick library named TOTAL.QLB. QLIB does not check the memory model of any of the object files. Identifying Standard-Library Functions: The QLIB.INI File --------------------------------------------------------- When QLIB finds a function name in a file, it checks the QLIB.INI file to determine whether or not the function is a standard-library function. The QLIB.INI file lists all standard-library functions, as well as the names of the libraries containing those functions. The QLIB.INI file supplied in the package contains references only to the standard C library, the standard C math functions, and the QuickC graphics functions. You can add the names of routines or libraries to QLIB.INI to tell QLIB to recognize them as "standard." You can also remove the names of routines (for example, routines in the core library) or libraries from QLIB.INI to reduce the number of routines that QLIB builds into a Quick library. To add a new library to QLIB.INI, type a dollar sign ($) followed by the library name and the names of any functions in the library. The function names may be separated by any character that is not part of a valid C identifier (typically, a space or a tab). QLIB can recognize up to 700 functions in QLIB.INI. It can recognize up to 20 libraries between the command line and in the QLIB.INI file. Example: $MYMATH.LIB quadratic cubic biquadratic If you add the example above to QLIB.INI, QLIB recognizes the quadratic, cubic, and biquadratic functions. If it finds any of these names in the files it searches, QLIB takes these files from the MYMATH.LIB library and places them in the Quick library it builds. QLIB Limits ----------- The QLIB program has the following limits: o QLIB spawns LINK to create the Quick library. Since this requires extra memory, there may be times when the linker does not have enough memory to create the Quick library. Usually, however, this is not a problem, since the linker writes its temporary file to disk when it has insufficient memory. o You may get linker error L1049, "too many segments," when you run QLIB. QLIB allows a Quick library to have a maximum of either 10 times the number of modules specified or 3072 segments, whichever is smaller. If you get this error, create the Quick library with the LINK utility, as described in Section 10.1.1, and give a larger value using the /SE linker option. o QLIB does not expand macros or search include files. As a consequence, if a module includes code from an include file, QLIB does not put this code in the Quick library. Another consequence is that QLIB includes code "removed" by #if directives. If an open comment appears in this code, QLIB may generate unpredictable results. o QLIB checks all strings that may be valid function names. This means that QLIB may place unneeded functions in the Quick library it creates. For example, if a program has an "#include " directive, QLIB will place the stat function in the Quick library even if stat is never called in the program. QLIB Error Messages ------------------- 1 : Cannot open build file QLIB could not open the default build file, QLIBBLD.OBJ. Check to see if QLIBBLD.OBJ is read only or if the disk is full. 2 : Cannot open QLIB.INI QLIB.INI was not found in the current directory or path. 3 : Not enough memory to process files QLIB did not have enough memory to read in a file such as QLIB.INI. To solve this problem, try removing memory-resident programs or removing functions from QLIB.INI. 4 : Problem reading from initialization file QLIB found the QLIB.INI file but could not read it. 5 : QLIB.INI contains too many key words Too many function names are listed in QLIB.INI. Comment out some of the function names. 6 : QLIB.INI contains too many libraries More than 20 library names appear in QLIB.INI and on the QLIB command line. 7 : Unclosed comment in file An unclosed comment appear in QLIB.INI or in a file that was being searched. QLIB ignores text in C comments, but it does not recognize other preprocessor directives. In particular QLIB has problems if sections of code with unclosed comments are removed by #if directives, or if the comment symbol has been redefined. 8 : Problems opening file to search QLIB could not find a file given with the /S option in the current directory or the specified directory. 9 : Problems reading file to search QLIB found a file given with the /S option but could not read the file. 10 : The object file was not compiled medium model An object file given on the command line was not compiled with the medium memory model. This may be because o The default memory model for QCL (small) or another memory model other than medium model was used during compilation. o The object file was created using MASM or a non-Microsoft compiler. o The object file had an invalid format. Specifying the source file on the QLIB command line may solve the problem. To force QLIB to build the library anyway, use the /O option. 11 : Unable to locate QUICKLIB.OBJ The QUICKLIB.OBJ file was neither in the current directory nor in the directory specified by the LIB environment variable. 12 : Problem compiling source file The compile phase of a source file failed because of errors in the source file or because not enough memory was available for the compilation. Try compiling the file with the QCL command and the /c option, then running QLIB on the resulting object file to create the Quick library. 13 : Linking phase failed The linker could not produce the Quick library. Unresolved functions and missing libraries are common reasons for link failures. 14 : Unable to open link response file "QLIBBLD.LNK" QLIB tried to create the file QLIBBLD.LNK, but could not open the file. This error occurs if the QLIBBLD.LNK file is read-only or the disk is full. 15 : Problem writing to link response file "QLIBBLD.LNK" QLIB opened the response file but could not write to it. This error occurs if the disk is full.