lib2exp.txt
documentation for LIB2EXP 0.4 (BETA 2)
by Daniel Guerrero Miralles (daguer@geocities.com)
April 17, 1999.


-------------------------------------------------------------------------------
WARNING!!:

The program is not fully functional and may contain bugs. USE AT YOUR OWN
RISK.

Please, report any bugs by Internet e-mail to daguer@geocities.com. If
possible, and the file is smaller than 64 KB, send a (compressed) copy of the
library that caused the error, along with a detailed description of the bug
and information about your system configuration (processor model, RAM size,
free HD space, OS version, etc).

DO NOT SEND FILES LARGER THAN 64 KB WITHOUT ASKING FIRST.
-------------------------------------------------------------------------------


DESCRIPTION
-----------

Almost all SDKs available for Windows include libraries for Microsoft
compilers. Static libraries made with Microsoft tools are compatible with
the LCC-Win32 linker, but import libraries (those used to link applications
with DLLs) are not.

I wrote this little utility to help in creation of import libraries suitable
for LCC-Win32 from those included in the SDKs.


USAGE
-----

A this moment (Beta 2), LIB2EXP does not generate libraries. Instead, it
can look into libraries in Microsoft format (those used to link with
Microsoft compilers) and make a list of imported functions. Then it dumps
this list to a file with the same name of the input file, but with EXP
extension. This file can be used to feed LCC-Win32's "buildlib.exe" utility,
that will (hopefully) generate the import library.

LIB2EXP should be called from the command line (a DOS window in Windows 9x),
passing as parameters the list of libraries that should be converted to EXP
files.

This is an example of how to invoke the program:
-------------------------------------------------------------------------------
lib2exp c:\dxsdk\lib\ddraw.lib
-------------------------------------------------------------------------------

This will generate an output file named "ddraw.exp" in the current directory.
You can pass any number of files to LIB2EXP. Also, you can use wildcards,
for example:
-------------------------------------------------------------------------------
lib2exp c:\dxsdk\lib\*.lib
-------------------------------------------------------------------------------

In this case you will get an EXP file for each LIB file found in the
"c:\dxsdk\lib" directory that contains imports (libraries with no imports
are not processed, they can be used with LCC-Win32 as they are).

When you have the EXP files, you should edit each one to ensure that the
conversion was right. A correct dump should look like this:
-------------------------------------------------------------------------------
DDRAW.dll
_D3DParseUnknownCommand@8 D3DParseUnknownCommand
_DDHAL32_VidMemAlloc@16 DDHAL32_VidMemAlloc
_DDHAL32_VidMemFree@12 DDHAL32_VidMemFree
_DDInternalLock@8 DDInternalLock
_DDInternalUnlock@4 DDInternalUnlock
_DSoundHelp@12 DSoundHelp
_DirectDrawCreate@12 DirectDrawCreate
_DirectDrawCreateClipper@12 DirectDrawCreateClipper
_DirectDrawEnumerateA@8 DirectDrawEnumerateA
_DirectDrawEnumerateExA@12 DirectDrawEnumerateExA
_DirectDrawEnumerateExW@12 DirectDrawEnumerateExW
_DirectDrawEnumerateW@8 DirectDrawEnumerateW
_GetAliasedVidMem GetAliasedVidMem
_GetNextMipMap GetNextMipMap
_GetSurfaceFromDC@12 GetSurfaceFromDC
_HeapVidMemAllocAligned@20 HeapVidMemAllocAligned
_InternalLock InternalLock
_InternalUnlock InternalUnlock
_LateAllocateSurfaceMem@16 LateAllocateSurfaceMem
_VidMemAlloc@12 VidMemAlloc
_VidMemAmountFree@4 VidMemAmountFree
_VidMemFini@4 VidMemFini
_VidMemFree@8 VidMemFree
_VidMemInit@20 VidMemInit
_VidMemLargestFree@4 VidMemLargestFree
-------------------------------------------------------------------------------

Note that the dump begins with the name of a DLL file, followed by a table
with 2 columns separated by a white space. There is an optional third column,
which if present, can only be the string "data" (without quotes), also
separated by a white space. This means that the import described by the row
is a variable in the DLL, rather than a function.

After the conversion process, you may notice that some particular function
or variable is missing from the EXP file, for example, trying to convert the
DirectX 6.1 SDK import library named "dsound.lib" generates an empty EXP
file. This may happen if the name of the function was not stored in the
source library.

For such cases, LIB2EXP has the hability to search missing names in the
related DLL. This behavior is inactive by default; to activate it use the
"-dll" command in the LIB2EXP command line, and ensure that the DLL file
is available. The program will try to locate the DLL by searching the
current directory and then the Windows and System directories (in this
order).

Now that you have the EXP, you should invoke buildlib to generate the
import library. This is an example of how to do this:
-------------------------------------------------------------------------------
c:\lcc\bin\buildlib ddraw.exp ddraw.lib
-------------------------------------------------------------------------------

This will generate a file named "ddraw.lib", the import library. Copy the
library to LCC-Win32 libraries directory (usually "c:\lcc\lib") and from
now you can use the lib just like any other.

Other commands LIB2EXP accepts are:

-v:<number>
Adjust the verbose level. By default, the verbose level is set to 1
(minimum). You can increase the number of progress messages that the
program generates by providing a higher number. The maximum level is 4.
You can also set this value to 0 to avoid all except error messages.

-ord
Allow ordinals in the generated EXP file. This option is only useful for
debugging, because this will make the generated file to be unusable for
BUILDLIB.


POSSIBLE ERRORS IN THE EXP FILES
--------------------------------

You should ALWAYS check the output of LIB2EXP before building the import
library. These are possible errors that will make the EXP file unusable:

+ Empty dump.
+ Missing or corrupt DLL name.
+ Missing import table.
+ "Garbage" in the table, that is, symbols other than "@" or "_" (or "#"
if you set the "-ord" switch), for example "?", "*", "&", "%", etc.

No output file (and an error message saying "no library information to dump")
should mean that the library passed to LIB2EXP is not an import library, that
is, it contains no import information. If you are sure that it is an import
library, then you have found a bug, so please report it!.


BETA VERSION NOTES
------------------

1) Some Microsoft import libraries also include static code. LIB2EXP will 
warn you if it founds static data or code in an library (if the verbose 
level is not set to 0). This will make the LCC-Win32 library incomplete, 
and thus, if may not work. You can, however, extract this data from 
the source library and add it to the target library with the compiler 
tool caller "lcclib.exe". Follow this process to do it:

- Extract all members in the source (Microsoft) library with the 
  LCCLIB command "-extract". All members will be extracted from the 
  library.
-------------------------------------------------------------------------------
c:\lcc\bin\lcclib <source library.lib> -extract
-------------------------------------------------------------------------------

- add all files with OBJ extension to the target library. 
-------------------------------------------------------------------------------
c:\lcc\bin\lcclib <target library.lib> *.obj
-------------------------------------------------------------------------------

  You can ignore all files without OBJ extension, specially those 
  with DLL extension (they are missinterpreted imports).


2) You must also be warned that this BETA verion only dumps C imports from the
library. That means that no C++ symbols should appear in the EXP files.
C++ symbols can be noticed because they include question mark characters (?)
in their names. So, the dump of an import library with only C++ symbols should
be empty. If you find question marks in the program output, please report it.
A swich may be added in a future verion to allow dumping of C++ symbols.


3) It may be interesting to save progress and error messages, specially when
converting a large number of them. To do this, you simply need to redirect
the standard output to a file. This is an example:
-------------------------------------------------------------------------------
lib2exp *.lib > output.txt
-------------------------------------------------------------------------------
