mirror of
git://source.winehq.org/git/wine.git
synced 2024-10-31 11:26:10 +00:00
Documentation update.
This commit is contained in:
parent
69d7cb5681
commit
d756a0ac93
1 changed files with 116 additions and 75 deletions
|
@ -45,7 +45,8 @@ tracing of calls to the DLL, and (in some cases) automatically determining
|
||||||
the parameters, calling conventions, and return values of the DLLs functions.
|
the parameters, calling conventions, and return values of the DLLs functions.
|
||||||
|
|
||||||
You can think of winedump as somewhat similar to the IMPLIB tool when
|
You can think of winedump as somewhat similar to the IMPLIB tool when
|
||||||
only its basic functionality is used.
|
only its basic functionality is used. In addition, winedump can be used to
|
||||||
|
dump other information from PE files; See the section 'Dumping' below.
|
||||||
|
|
||||||
|
|
||||||
Usage
|
Usage
|
||||||
|
@ -54,18 +55,26 @@ Usage
|
||||||
Winedump is a command line tool. Running it with no arguments or passing
|
Winedump is a command line tool. Running it with no arguments or passing
|
||||||
it '-h' on the command line lists the available options:
|
it '-h' on the command line lists the available options:
|
||||||
|
|
||||||
Winedump can be used for different usages:
|
|
||||||
- generating default source files (.spec, .c...) for using a native DLL in Wine
|
|
||||||
- demangling MSVC C++ symbol names
|
|
||||||
- dumping the 'PE' files contents
|
|
||||||
|
|
||||||
Usage: winedump [-h | sym <sym> | spec <dll> | dump <dll>] [mode options]
|
Usage: winedump [-h | sym <sym> | spec <dll> | dump <dll>] [mode options]
|
||||||
When used in -h mode
|
|
||||||
-h Display this help message
|
Winedump can be used in several different modes. The first argument to the
|
||||||
When used in sym mode
|
program determines the mode winedump will run in.
|
||||||
sym <sym> Demangle C++ symbol <sym>' and exit
|
|
||||||
When used in spec mode
|
-h Help mode. Basic usage help is printed.
|
||||||
spec <dll> Use dll for input file and generate implementation code
|
sym Symbol mode. Used to demangle C++ symbols
|
||||||
|
spec For generating .spec files and stub DLL's
|
||||||
|
dump To dump the contents of a PE file.
|
||||||
|
|
||||||
|
[mode options] depend on the mode given as the first argument.
|
||||||
|
|
||||||
|
Help mode:
|
||||||
|
No options are used. The program prints help and then exits
|
||||||
|
|
||||||
|
Sym mode:
|
||||||
|
<sym> Demangles C++ symbol <sym>' and then exits.
|
||||||
|
|
||||||
|
Spec mode:
|
||||||
|
<dll> Use dll for input file and generate implementation code
|
||||||
-I dir Look for prototypes in 'dir' (implies -c)
|
-I dir Look for prototypes in 'dir' (implies -c)
|
||||||
-c Generate skeleton code (requires -I)
|
-c Generate skeleton code (requires -I)
|
||||||
-t TRACE arguments (implies -c)
|
-t TRACE arguments (implies -c)
|
||||||
|
@ -75,17 +84,21 @@ When used in spec mode
|
||||||
-C Assume __cdecl calls (default: __stdcall)
|
-C Assume __cdecl calls (default: __stdcall)
|
||||||
-s num Start prototype search after symbol 'num'
|
-s num Start prototype search after symbol 'num'
|
||||||
-e num End prototype search after symbol 'num'
|
-e num End prototype search after symbol 'num'
|
||||||
|
-S symfile Search only prototype names found in 'symfile'
|
||||||
-q Don't show progress (quiet).
|
-q Don't show progress (quiet).
|
||||||
-v Show lots of detail while working (verbose).
|
-v Show lots of detail while working (verbose).
|
||||||
When used in dump mode
|
|
||||||
dump <dll> Dumps the content of the dll named <dll>
|
Dump mode:
|
||||||
|
<dll> Dumps the content of the dll named <dll>
|
||||||
-C Turns on symbol demangling
|
-C Turns on symbol demangling
|
||||||
-f Dumps file header information
|
-f Dumps file header information
|
||||||
-j sect_name Dumps only the content of section sect_name (import, export, debug)
|
-j sect_name Dumps only the content of section sect_name (import, export, debug)
|
||||||
-x Dumps everything
|
-x Dumps everything
|
||||||
|
|
||||||
Basic options
|
Each modes options are explained below.
|
||||||
-------------
|
|
||||||
|
Spec mode: Basic options
|
||||||
|
------------------------
|
||||||
|
|
||||||
OPTION: -o name Set the output dll name (default: dll)
|
OPTION: -o name Set the output dll name (default: dll)
|
||||||
|
|
||||||
|
@ -120,8 +133,8 @@ winedump determines the calling convention for and which does not match
|
||||||
the assumed calling convention.
|
the assumed calling convention.
|
||||||
|
|
||||||
|
|
||||||
Generating stub DLLS
|
Spec mode: Generating stub DLLS
|
||||||
--------------------
|
-------------------------------
|
||||||
|
|
||||||
If all you want to do is generate a stub DLL to allow you to link your
|
If all you want to do is generate a stub DLL to allow you to link your
|
||||||
Winelib application to an x86 DLL, the above options are all you need.
|
Winelib application to an x86 DLL, the above options are all you need.
|
||||||
|
@ -153,14 +166,14 @@ This is the .spec file. Each exported function is listed as a stub:
|
||||||
...
|
...
|
||||||
|
|
||||||
This means that winebuild will generate dummy code for this function. That
|
This means that winebuild will generate dummy code for this function. That
|
||||||
doesn't concern us, because all we want is for winebuild to allow the
|
doesn't concern us, because all we want is for winebuild to allow the symbols
|
||||||
symbols to be resolved. At run-time, the functions in the native DLL will
|
to be resolved when linking. At run-time, the functions in the native DLL will
|
||||||
be called; this just allows us to link.
|
be called; this just allows us to link.
|
||||||
|
|
||||||
zipextra_dll.h zipextra_main.c
|
zipextra_dll.h zipextra_main.c
|
||||||
These are source code files containing the minimum set of code to build
|
These are source code files containing the minimum set of code to build
|
||||||
a stub DLL. The C file contains one function, ZIPEXTRA_Init, which does
|
a stub DLL. The C file contains one function, ZIPEXTRA_Init, which does
|
||||||
nothing.
|
nothing (but must be present).
|
||||||
|
|
||||||
Makefile.in
|
Makefile.in
|
||||||
This is a template for 'configure' to produce a makefile. It is designed
|
This is a template for 'configure' to produce a makefile. It is designed
|
||||||
|
@ -175,8 +188,8 @@ zipextra_install
|
||||||
A shell script for adding zipextra to the Wine source tree (see below).
|
A shell script for adding zipextra to the Wine source tree (see below).
|
||||||
|
|
||||||
|
|
||||||
Inserting a stub DLL into the Wine tree
|
Spec mode: Inserting a stub DLL into the Wine tree
|
||||||
---------------------------------------
|
--------------------------------------------------
|
||||||
|
|
||||||
To build your stub DLL as part of Wine, do the following:
|
To build your stub DLL as part of Wine, do the following:
|
||||||
|
|
||||||
|
@ -190,6 +203,17 @@ To build your stub DLL as part of Wine, do the following:
|
||||||
|
|
||||||
Your application can now link with the DLL.
|
Your application can now link with the DLL.
|
||||||
|
|
||||||
|
If you recieve the following error when running autoconf:
|
||||||
|
|
||||||
|
autoconf: configure.in: No such file or directory
|
||||||
|
|
||||||
|
Then you need to install a newer version of autoconf. At the time of writing
|
||||||
|
version 2.53 or later is required to re-generate configure.
|
||||||
|
|
||||||
|
If you have problems with this step, you can post to the wine-devel mailing
|
||||||
|
list for help. The build process can change regularly and winebuild may lag
|
||||||
|
behind in support.
|
||||||
|
|
||||||
NOTE: **DO NOT** submit patches to Wine for 3rd party DLLs! Building DLLs
|
NOTE: **DO NOT** submit patches to Wine for 3rd party DLLs! Building DLLs
|
||||||
into your copy of the tree is just a simple way for you to link. When
|
into your copy of the tree is just a simple way for you to link. When
|
||||||
you release your application you won't be distributing the Unix .so
|
you release your application you won't be distributing the Unix .so
|
||||||
|
@ -198,8 +222,8 @@ NOTE: **DO NOT** submit patches to Wine for 3rd party DLLs! Building DLLs
|
||||||
involved, it should be pretty resiliant to changes).
|
involved, it should be pretty resiliant to changes).
|
||||||
|
|
||||||
|
|
||||||
Advanced Options
|
Spec mode: Advanced Options
|
||||||
----------------
|
---------------------------
|
||||||
|
|
||||||
This section discusses features of winedump that are useful to Wine Hackers
|
This section discusses features of winedump that are useful to Wine Hackers
|
||||||
or developers looking to reimplement a Win32 DLL for Unix. Using these
|
or developers looking to reimplement a Win32 DLL for Unix. Using these
|
||||||
|
@ -209,7 +233,7 @@ have a general understanding of Wine programming.
|
||||||
|
|
||||||
OPTION: -I dir Look for prototypes in 'dir' (implies -c)
|
OPTION: -I dir Look for prototypes in 'dir' (implies -c)
|
||||||
|
|
||||||
For all advanced functionality, you must give winedump a directoryor file that
|
For all advanced functionality, you must give winedump a directory or file that
|
||||||
contains prototypes for the DLL. In the case of Windows DLLs, this could be
|
contains prototypes for the DLL. In the case of Windows DLLs, this could be
|
||||||
either the standard include directory from your compiler, or an SDK include
|
either the standard include directory from your compiler, or an SDK include
|
||||||
directory. If you have a text document with prototypes (such as documentation)
|
directory. If you have a text document with prototypes (such as documentation)
|
||||||
|
@ -249,6 +273,12 @@ function, for example, if you wanted to add functionality to an existing DLL.
|
||||||
|
|
||||||
They is also useful for debugging problems, in conjunction with -v.
|
They is also useful for debugging problems, in conjunction with -v.
|
||||||
|
|
||||||
|
OPTION: -S symfile Search only prototype names found in 'symfile'
|
||||||
|
|
||||||
|
If you want to only generate code for a subset of exported functions from
|
||||||
|
your source DLL, you can use this option to provide a text file containing
|
||||||
|
the names of the symbols to extract, one per line. Only the symbols present
|
||||||
|
in this file will be used in your output DLL.
|
||||||
|
|
||||||
OPTION: -D Generate documentation
|
OPTION: -D Generate documentation
|
||||||
|
|
||||||
|
@ -420,8 +450,8 @@ code automatically for common Win32 types.
|
||||||
See below for more information on setting up a forwarding DLL.
|
See below for more information on setting up a forwarding DLL.
|
||||||
|
|
||||||
|
|
||||||
Problems compiling a DLL containing generated code
|
Spec mode: Problems compiling a DLL containing generated code
|
||||||
--------------------------------------------------
|
-------------------------------------------------------------
|
||||||
|
|
||||||
Unless you are very lucky, you will need to do a small amount of work to
|
Unless you are very lucky, you will need to do a small amount of work to
|
||||||
get a DLL generated with -c, -t or -f to compile. The reason for this is
|
get a DLL generated with -c, -t or -f to compile. The reason for this is
|
||||||
|
@ -487,8 +517,8 @@ the .spec entry in order to forward correctly. Otherwise, include the typedef
|
||||||
in your fixup header to avoid compile errors.
|
in your fixup header to avoid compile errors.
|
||||||
|
|
||||||
|
|
||||||
Using a forwarding DLL
|
Spec mode: Using a forwarding DLL
|
||||||
----------------------
|
---------------------------------
|
||||||
|
|
||||||
To create and use a forwarding DLL to trace DLL calls, you need to first
|
To create and use a forwarding DLL to trace DLL calls, you need to first
|
||||||
create a DLL using the -f option as outlined above, and get it to compile.
|
create a DLL using the -f option as outlined above, and get it to compile.
|
||||||
|
@ -534,6 +564,62 @@ arguments on the way.
|
||||||
At this point you are ready to start reimplementing the calls.
|
At this point you are ready to start reimplementing the calls.
|
||||||
|
|
||||||
|
|
||||||
|
Sym mode: Demangling
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
If you need to demangle a single C++ symbol, you can use the demangling mode
|
||||||
|
of winedump. This is useful for testing the demangler or implementing
|
||||||
|
C++ functions in partially implemented wine DLLS. As an example:
|
||||||
|
|
||||||
|
winedump sym "??3@YAXPAX@Z"
|
||||||
|
|
||||||
|
Gives:
|
||||||
|
|
||||||
|
void __cdecl _global_operator_delete_1(void * arg0)
|
||||||
|
|
||||||
|
Which is enough information to begin implementing the function.
|
||||||
|
|
||||||
|
|
||||||
|
Dump Mode: Dumping a PE file
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
Another use for this tool is to diplay information about a 32bit DLL or PE
|
||||||
|
format image file. When used in this way winedump functions similarly to tools
|
||||||
|
such as pedump provided by many Win32 compiler vendors.
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
winedump dump <dllname.dll> [switches]
|
||||||
|
|
||||||
|
dump mode switches:
|
||||||
|
-h Display this help message
|
||||||
|
-C Turns on symbol demangling
|
||||||
|
-f Dump file header information
|
||||||
|
-j dir_name Dump only the contents of directory dir_name (import, export, debug)
|
||||||
|
-x Dump everything
|
||||||
|
|
||||||
|
|
||||||
|
Dump Mode: Options
|
||||||
|
------------------
|
||||||
|
|
||||||
|
OPTION: -x Dump everything
|
||||||
|
|
||||||
|
This command prints all available information about the file. You may wish to
|
||||||
|
pipe the output through more/less or into a file, since a lot of output will
|
||||||
|
be produced.
|
||||||
|
|
||||||
|
If you are only interested in a subset of the available information, you can
|
||||||
|
use one of the following switches:
|
||||||
|
|
||||||
|
OPTION: -f Dump file header information-x Dump everything
|
||||||
|
|
||||||
|
This option dumps only the standard PE header structures, along with the COFF
|
||||||
|
sections available in the file.
|
||||||
|
|
||||||
|
OPTION: -j dir_name Dump directory dir_name (import, export, debug)
|
||||||
|
|
||||||
|
To dump only a given directory, specify them using this option. Currently only
|
||||||
|
the import, export and debug directories are implemented.
|
||||||
|
|
||||||
Final comments
|
Final comments
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
|
@ -561,48 +647,3 @@ References
|
||||||
|
|
||||||
[1] See the Wine and Wine.conf man pages for details on how to tell Wine
|
[1] See the Wine and Wine.conf man pages for details on how to tell Wine
|
||||||
whether to use native (Win32) or internal DLLs.
|
whether to use native (Win32) or internal DLLs.
|
||||||
|
|
||||||
|
|
||||||
Demangling
|
|
||||||
----------
|
|
||||||
|
|
||||||
If you need to demangle a single C++ symbol, you can use the demangling mode
|
|
||||||
of winedump. This is useful for testing the demangler or implementing
|
|
||||||
C++ functions in partially implemented wine DLLS. As an example:
|
|
||||||
|
|
||||||
winedump sym "??3@YAXPAX@Z"
|
|
||||||
|
|
||||||
Gives:
|
|
||||||
|
|
||||||
void __cdecl _global_operator_delete_1(void * arg0)
|
|
||||||
|
|
||||||
Which is enough information to begin implementing the function.
|
|
||||||
|
|
||||||
|
|
||||||
Dumping
|
|
||||||
-------
|
|
||||||
|
|
||||||
Another tool might be helpful for digging into a 32bit DLL (and any PE image file):
|
|
||||||
pedump.
|
|
||||||
|
|
||||||
Usage:
|
|
||||||
winedump [-h | sym <sym> | spec <dll> | dump <dll> ] [switches]
|
|
||||||
|
|
||||||
winedump switches:
|
|
||||||
-h Display this help message
|
|
||||||
-d <dll> Use dll for input file and generate implementation code
|
|
||||||
-C Turns on symbol demangling
|
|
||||||
-f Dumps file header information
|
|
||||||
-j dir_name Dumps only the content of directory dir_name (import, export, debug)
|
|
||||||
-x Dumps everything
|
|
||||||
|
|
||||||
The basic usage, to look at everything in a file is:
|
|
||||||
winedump dump mydll.dll -x
|
|
||||||
|
|
||||||
It'll print any available information on the file. This information can be splitted
|
|
||||||
into sub-categories:
|
|
||||||
- file headers (request by -f or -x) are made of the standard PE header structures,
|
|
||||||
plus the COFF sections
|
|
||||||
- directories: you can print them one after the other using the -j switch.
|
|
||||||
Currently, only the import, export and debug directories are implemented.
|
|
||||||
- -x displays the file headers and any available directory.
|
|
||||||
|
|
Loading…
Reference in a new issue