PR binutils/249
* doc/binutils.texi (def file format): New node. (dlltool): Use the tool name as the @chapter name, like all the other binutils. Use @file{.def} throughout for consistency.
This commit is contained in:
parent
c7de92161e
commit
2aa9814eac
|
@ -1,3 +1,10 @@
|
||||||
|
2004-12-07 Ben Elliston <bje@au.ibm.com>
|
||||||
|
|
||||||
|
PR binutils/249
|
||||||
|
* doc/binutils.texi (def file format): New node.
|
||||||
|
(dlltool): Use the tool name as the @chapter name, like all the
|
||||||
|
other binutils. Use @file{.def} throughout for consistency.
|
||||||
|
|
||||||
2004-12-06 Ben Elliston <bje@au.ibm.com>
|
2004-12-06 Ben Elliston <bje@au.ibm.com>
|
||||||
|
|
||||||
* dlltool.c: Comment fix.
|
* dlltool.c: Comment fix.
|
||||||
|
|
|
@ -2854,16 +2854,25 @@ the Info entries for @file{binutils}.
|
||||||
@end ignore
|
@end ignore
|
||||||
|
|
||||||
@node dlltool
|
@node dlltool
|
||||||
@chapter Create files needed to build and use DLLs
|
@chapter dlltool
|
||||||
@cindex DLL
|
@cindex DLL
|
||||||
@kindex dlltool
|
@kindex dlltool
|
||||||
|
|
||||||
@command{dlltool} may be used to create the files needed to build and use
|
@command{dlltool} is used to create the files needed to create dynamic
|
||||||
dynamic link libraries (DLLs).
|
link libraries (DLLs) on systems which understand PE format image
|
||||||
|
files such as Windows. A DLL contains an export table which contains
|
||||||
|
information that the runtime loader needs to resolve references from a
|
||||||
|
referencing program.
|
||||||
|
|
||||||
|
The export table is generated by this program by reading in a
|
||||||
|
@file{.def} file or scanning the @file{.a} and @file{.o} files which
|
||||||
|
will be in the DLL. A @file{.o} file can contain information in
|
||||||
|
special @samp{.drectve} sections with export information.
|
||||||
|
|
||||||
@quotation
|
@quotation
|
||||||
@emph{Warning:} @command{dlltool} is not always built as part of the binary
|
@emph{Note:} @command{dlltool} is not always built as part of the
|
||||||
utilities, since it is only useful for those targets which support DLLs.
|
binary utilities, since it is only useful for those targets which
|
||||||
|
support DLLs.
|
||||||
@end quotation
|
@end quotation
|
||||||
|
|
||||||
@c man title dlltool Create files needed to build and use DLLs.
|
@c man title dlltool Create files needed to build and use DLLs.
|
||||||
|
@ -2906,13 +2915,13 @@ When creating a DLL, along with the source for the DLL, it is necessary
|
||||||
to have three other files. @command{dlltool} can help with the creation of
|
to have three other files. @command{dlltool} can help with the creation of
|
||||||
these files.
|
these files.
|
||||||
|
|
||||||
The first file is a @samp{.def} file which specifies which functions are
|
The first file is a @file{.def} file which specifies which functions are
|
||||||
exported from the DLL, which functions the DLL imports, and so on. This
|
exported from the DLL, which functions the DLL imports, and so on. This
|
||||||
is a text file and can be created by hand, or @command{dlltool} can be used
|
is a text file and can be created by hand, or @command{dlltool} can be used
|
||||||
to create it using the @option{-z} option. In this case @command{dlltool}
|
to create it using the @option{-z} option. In this case @command{dlltool}
|
||||||
will scan the object files specified on its command line looking for
|
will scan the object files specified on its command line looking for
|
||||||
those functions which have been specially marked as being exported and
|
those functions which have been specially marked as being exported and
|
||||||
put entries for them in the .def file it creates.
|
put entries for them in the @file{.def} file it creates.
|
||||||
|
|
||||||
In order to mark a function as being exported from a DLL, it needs to
|
In order to mark a function as being exported from a DLL, it needs to
|
||||||
have an @option{-export:<name_of_function>} entry in the @samp{.drectve}
|
have an @option{-export:<name_of_function>} entry in the @samp{.drectve}
|
||||||
|
@ -2930,12 +2939,12 @@ The second file needed for DLL creation is an exports file. This file
|
||||||
is linked with the object files that make up the body of the DLL and it
|
is linked with the object files that make up the body of the DLL and it
|
||||||
handles the interface between the DLL and the outside world. This is a
|
handles the interface between the DLL and the outside world. This is a
|
||||||
binary file and it can be created by giving the @option{-e} option to
|
binary file and it can be created by giving the @option{-e} option to
|
||||||
@command{dlltool} when it is creating or reading in a .def file.
|
@command{dlltool} when it is creating or reading in a @file{.def} file.
|
||||||
|
|
||||||
The third file needed for DLL creation is the library file that programs
|
The third file needed for DLL creation is the library file that programs
|
||||||
will link with in order to access the functions in the DLL. This file
|
will link with in order to access the functions in the DLL. This file
|
||||||
can be created by giving the @option{-l} option to dlltool when it
|
can be created by giving the @option{-l} option to dlltool when it
|
||||||
is creating or reading in a .def file.
|
is creating or reading in a @file{.def} file.
|
||||||
|
|
||||||
@command{dlltool} builds the library file by hand, but it builds the
|
@command{dlltool} builds the library file by hand, but it builds the
|
||||||
exports file by creating temporary files containing assembler statements
|
exports file by creating temporary files containing assembler statements
|
||||||
|
@ -2969,7 +2978,7 @@ The command line options have the following meanings:
|
||||||
@item -d @var{filename}
|
@item -d @var{filename}
|
||||||
@itemx --input-def @var{filename}
|
@itemx --input-def @var{filename}
|
||||||
@cindex input .def file
|
@cindex input .def file
|
||||||
Specifies the name of a .def file to be read in and processed.
|
Specifies the name of a @file{.def} file to be read in and processed.
|
||||||
|
|
||||||
@item -b @var{filename}
|
@item -b @var{filename}
|
||||||
@itemx --base-file @var{filename}
|
@itemx --base-file @var{filename}
|
||||||
|
@ -2984,7 +2993,7 @@ Specifies the name of the export file to be created by dlltool.
|
||||||
|
|
||||||
@item -z @var{filename}
|
@item -z @var{filename}
|
||||||
@itemx --output-def @var{filename}
|
@itemx --output-def @var{filename}
|
||||||
Specifies the name of the .def file to be created by dlltool.
|
Specifies the name of the @file{.def} file to be created by dlltool.
|
||||||
|
|
||||||
@item -l @var{filename}
|
@item -l @var{filename}
|
||||||
@itemx --output-lib @var{filename}
|
@itemx --output-lib @var{filename}
|
||||||
|
@ -2998,7 +3007,7 @@ option. You may add to the list of symbols to not export by using the
|
||||||
@option{--exclude-symbols} option.
|
@option{--exclude-symbols} option.
|
||||||
|
|
||||||
@item --no-export-all-symbols
|
@item --no-export-all-symbols
|
||||||
Only export symbols explicitly listed in an input .def file or in
|
Only export symbols explicitly listed in an input @file{.def} file or in
|
||||||
@samp{.drectve} sections in the input object files. This is the default
|
@samp{.drectve} sections in the input object files. This is the default
|
||||||
behaviour. The @samp{.drectve} sections are created by @samp{dllexport}
|
behaviour. The @samp{.drectve} sections are created by @samp{dllexport}
|
||||||
attributes in the source code.
|
attributes in the source code.
|
||||||
|
@ -3034,10 +3043,10 @@ double quotes.
|
||||||
|
|
||||||
@item -D @var{name}
|
@item -D @var{name}
|
||||||
@itemx --dll-name @var{name}
|
@itemx --dll-name @var{name}
|
||||||
Specifies the name to be stored in the .def file as the name of the DLL
|
Specifies the name to be stored in the @file{.def} file as the name of
|
||||||
when the @option{-e} option is used. If this option is not present, then
|
the DLL when the @option{-e} option is used. If this option is not
|
||||||
the filename given to the @option{-e} option will be used as the name of
|
present, then the filename given to the @option{-e} option will be
|
||||||
the DLL.
|
used as the name of the DLL.
|
||||||
|
|
||||||
@item -m @var{machine}
|
@item -m @var{machine}
|
||||||
@itemx -machine @var{machine}
|
@itemx -machine @var{machine}
|
||||||
|
@ -3125,9 +3134,60 @@ Displays dlltool's version number and then exits.
|
||||||
|
|
||||||
@c man end
|
@c man end
|
||||||
|
|
||||||
|
@menu
|
||||||
|
* def file format:: The format of the dlltool @file{.def} file
|
||||||
|
@end menu
|
||||||
|
|
||||||
|
@node def file format
|
||||||
|
@section The format of the @command{dlltool} @file{.def} file
|
||||||
|
|
||||||
|
A @file{.def} file contains any number of the following commands:
|
||||||
|
|
||||||
|
@table @asis
|
||||||
|
|
||||||
|
@item @code{NAME} @var{name} @code{[ ,} @var{base} @code{]}
|
||||||
|
The result is going to be named @var{name}@code{.exe}.
|
||||||
|
|
||||||
|
@item @code{LIBRARY} @var{name} @code{[ ,} @var{base} @code{]}
|
||||||
|
The result is going to be named @var{name}@code{.dll}.
|
||||||
|
|
||||||
|
@item @code{EXPORTS ( ( (} @var{name1} @code{[ = } @var{name2} @code{] ) | ( } @var{name1} @code{=} @var{module-name} @code{.} @var{external-name} @code{) )}
|
||||||
|
@item @code{[} @var{integer} @code{] [ NONAME ] [ CONSTANT ] [ DATA ] [ PRIVATE ] ) *}
|
||||||
|
Declares @var{name1} as an exported symbol from the DLL, with optional
|
||||||
|
ordinal number @var{integer}, or declares @var{name1} as an alias
|
||||||
|
(forward) of the function @var{external-name} in the DLL
|
||||||
|
@var{module-name}.
|
||||||
|
|
||||||
|
@item @code{IMPORTS ( (} @var{internal-name} @code{=} @var{module-name} @code{.} @var{integer} @code{) | [} @var{internal-name} @code{= ]} @var{module-name} @code{.} @var{external-name} @code{) ) *}
|
||||||
|
Declares that @var{external-name} or the exported function whose
|
||||||
|
ordinal number is @var{integer} is to be imported from the file
|
||||||
|
@var{module-name}. If @var{internal-name} is specified then this is
|
||||||
|
the name that the imported function will be referred to in the body of
|
||||||
|
the DLL.
|
||||||
|
|
||||||
|
@item @code{DESCRIPTION} @var{string}
|
||||||
|
Puts @var{string} into the output @file{.exp} file in the
|
||||||
|
@code{.rdata} section.
|
||||||
|
|
||||||
|
@item @code{STACKSIZE} @var{number-reserve} @code{[, } @var{number-commit} @code{]}
|
||||||
|
@item @code{HEAPSIZE} @var{number-reserve} @code{[, } @var{number-commit} @code{]}
|
||||||
|
Generates @code{--stack} or @code{--heap}
|
||||||
|
@var{number-reserve},@var{number-commit} in the output @code{.drectve}
|
||||||
|
section. The linker will see this and act upon it.
|
||||||
|
|
||||||
|
@item @code{CODE} @var{attr} @code{+}
|
||||||
|
@item @code{DATA} @var{attr} @code{+}
|
||||||
|
@item @code{SECTIONS (} @var{section-name} @var{attr}@code{ + ) *}
|
||||||
|
Generates @code{--attr} @var{section-name} @var{attr} in the output
|
||||||
|
@code{.drectve} section, where @var{attr} is one of @code{READ},
|
||||||
|
@code{WRITE}, @code{EXECUTE} or @code{SHARED}. The linker will see
|
||||||
|
this and act upon it.
|
||||||
|
|
||||||
|
@end table
|
||||||
|
|
||||||
@ignore
|
@ignore
|
||||||
@c man begin SEEALSO dlltool
|
@c man begin SEEALSO dlltool
|
||||||
the Info entries for @file{binutils}.
|
The Info pages for @file{binutils}.
|
||||||
@c man end
|
@c man end
|
||||||
@end ignore
|
@end ignore
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue