[docs] winelib: Update the spec file section
André Hentschel
nerv at dawncrow.de
Sun Jan 29 13:31:32 CST 2012
---
en/winelib-toolkit.sgml | 281 +++++++++++------------------------------------
1 files changed, 63 insertions(+), 218 deletions(-)
diff --git a/en/winelib-toolkit.sgml b/en/winelib-toolkit.sgml
index 2a262f2..cb1073f 100644
--- a/en/winelib-toolkit.sgml
+++ b/en/winelib-toolkit.sgml
@@ -427,16 +427,7 @@ WRCFLAGS = -r -L
<sect2 id="spec-intro">
<title id="spec-intro.title">Introduction</title>
<para>
- In Windows the program's life starts either when its
- <function>main</function> is called, for console applications, or
- when its <function>WinMain</function> is called, for windows
- applications in the 'windows' subsystem. On Unix it is always
- <function>main</function> that is called. Furthermore in Winelib it
- has some special tasks to accomplish, such as initializing Winelib,
- that a normal <function>main</function> does not have to do.
- </para>
- <para>
- Furthermore windows applications and libraries contain some
+ In Windows applications and libraries contain some
information which are necessary to make APIs such as
<function>GetProcAddress</function> work. So it is necessary to
duplicate these data structures in the Unix world to make these
@@ -444,112 +435,19 @@ WRCFLAGS = -r -L
</para>
<para>
The spec file is there to solve the semantic gap described above.
- It provides the <function>main</function> function that initializes
- Winelib and calls the module's <function>WinMain</function> /
- <function>DllMain</function>, and it contains information about
- each API exported from a Dll so that the appropriate tables can be
- generated.
+ It provides information about each API exported from a Dll so that
+ the appropriate tables can be generated. Further the information is
+ used to for better relay logging.
</para>
<para>
A typical spec file will look something like this:
</para>
<screen>
-init WinMain
-rsrc resource.res
+@ stdcall -private DllCanUnloadNow()
+@ stdcall -private DllGetClassObject(ptr ptr ptr)
+@ stdcall -private DllRegisterServer()
+@ stdcall -private DllUnregisterServer()
</screen>
- <para>
- And here are the entries you will probably want to change:
- </para>
- <variablelist>
- <varlistentry>
- <term>init</term>
- <listitem>
- <para>
- <literal>init</literal> defines what is the entry point of
- that module. For a library this is customarily set to
- <literal>DllMain</literal>, for a console application this
- is <literal>main</literal> and for a graphical application
- this is <literal>WinMain</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>rsrc</term>
- <listitem>
- <para>
- This item specifies the name of the compiled resource file
- to link with your module. If your resource file is called
- <filename>hello.rc</filename> then the wrc compilation step
- (see <xref linkend="wrc" endterm="wrc.title">) will generate
- a file called <filename>hello.res</filename>. This is the
- name you must provide here. Note that because of this you
- cannot compile the spec file before you have compiled the
- resource file. So you should put a rule like the following
- in your makefile:
- </para>
- <programlisting>
-hello.spec.c: hello.res
- </programlisting>
- <para>
- If your project does not have a resource file then you must
- omit this entry altogether.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>@</term>
- <listitem>
- <note><para>
- FIXME: You must now export functions from DLLs.
- </para></note>
- <para>
- This entry is not shown above because it is not always
- necessary. In fact it is only necessary to export functions
- when you plan to dynamically load the library with
- <function>LoadLibrary</function> and then do a
- <function>GetProcAddress</function> on these functions.
- This is not necessary if you just plan on linking with the
- library and calling the functions normally. For more details
- about this see: <xref linkend="spec-reference"
- endterm="spec-reference.title">.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect2>
-
- <sect2 id="spec-compiling">
- <title id="spec-compiling.title">Compiling it</title>
- <note><para>
- FIXME: This section is very outdated and does not correctly
- describe the current use of winebuild and spec files. In
- particular, with recent versions of winebuild most of the
- information that used to be in the spec files is now specified on
- the command line.
- </para></note>
- <para>
- Compiling a spec file is a two step process. It is first
- converted into a C file by winebuild, and then compiled into an
- object file using your regular C compiler. This is all taken
- care of by the winemaker generated makefiles of course. But
- here's what it would like if you had to do it by hand:
- </para>
- <screen>
-WINEBUILD=$(WINE_DIR)/tools/winebuild
-
-.SUFFIXES: .spec .spec.c .spec.o
-
-.spec.spec.c:
- $(WINEBUILD) -fPIC -o $@ -spec $<
-
-.spec.c.spec.o:
- $(CC) -c -o $*.spec.o $<
- </screen>
- <para>
- Nothing really complex there. Just don't forget the
- <literal>.SUFFIXES</literal> statement, and beware of the tab if
- you copy this straight to your Makefile.
- </para>
</sect2>
<sect2 id="spec-reference">
@@ -567,62 +465,10 @@ WINEBUILD=$(WINE_DIR)/tools/winebuild
</para>
<programlisting>
-init FUNCTION
- </programlisting>
- <para>
- This field is optional and specific to Win32 modules. It
- specifies a function which will be called when the DLL is loaded
- or the executable started.
- </para>
-
- <programlisting>
-rsrc RES_FILE
- </programlisting>
- <para>
- This field is optional. If present it specifies the name of the
- .res file containing the compiled resources. See <xref
- linkend="wrc" endterm="wrc.title"> for details on compiling a
- resource file.
- </para>
-
- <programlisting>
-ORDINAL VARTYPE EXPORTNAME (DATA [DATA [DATA [...]]])
-2 byte Variable(-1 0xff 0 0)
- </programlisting>
- <para>
- This field can be present zero or more times.
- Each instance defines data storage at the ordinal specified. You
- may store items as bytes, 16-bit words, or 32-bit words.
- <literal>ORDINAL</literal> is replaced by the ordinal number
- corresponding to the variable. <literal>VARTYPE</literal> should
- be <literal>byte</literal>, <literal>word</literal> or
- <literal>long</literal> for 8, 16, or 32 bits respectively.
- <literal>EXPORTNAME</literal> will be the name available for
- dynamic linking. <literal>DATA</literal> can be a decimal number
- or a hex number preceded by "0x". The example defines the
- variable <literal>Variable</literal> at ordinal 2 and containing
- 4 bytes.
- </para>
-
- <programlisting>
-ORDINAL equate EXPORTNAME DATA
- </programlisting>
- <para>
- This field can be present zero or more times.
- Each instance defines an ordinal as an absolute value.
- <literal>ORDINAL</literal> is replaced by the ordinal number
- corresponding to the variable. <literal>EXPORTNAME</literal> will
- be the name available for dynamic linking.
- <literal>DATA</literal> can be a decimal number or a hex number
- preceded by "0x".
- </para>
-
- <programlisting>
-ORDINAL FUNCTYPE EXPORTNAME([ARGTYPE [ARGTYPE [...]]]) HANDLERNAME
-100 pascal CreateWindow(ptr ptr long s_word s_word s_word s_word
- word word word ptr)
- WIN_CreateWindow
-101 pascal GetFocus() WIN_GetFocus()
+ORDINAL FUNCTYPE OPTIONS EXPORTNAME([ARGTYPE [ARGTYPE [...]]]) HANDLERNAME
+@ stdcall CreateDesktopW(wstr wstr ptr long long ptr)
+@ stdcall CM_Get_Parent(ptr long long) setupapi.CM_Get_Parent
+@ cdecl -arch=x86_64 ceilf(float) MSVCRT_ceilf
</programlisting>
<para>
This field can be present zero or more times.
@@ -638,72 +484,80 @@ ORDINAL FUNCTYPE EXPORTNAME([ARGTYPE [ARGTYPE [...]]]) HANDLERNAME
</para>
<variablelist>
<varlistentry>
- <term>pascal16</term>
+ <term>pascal</term>
<listitem>
<para>
- for a Win16 function returning a 16-bit value
+ for a Win16 function
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>pascal</term>
+ <term>stdcall</term>
<listitem>
<para>
- for a Win16 function returning a 32-bit value
+ for a normal Win32 function
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>register</term>
+ <term>cdecl</term>
<listitem>
<para>
- for a function using CPU register to pass arguments
+ for a Win32 function using the C calling convention
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>interrupt</term>
+ <term>varargs</term>
<listitem>
<para>
- for a Win16 interrupt handler routine
+ for a Win32 function taking a variable number of arguments
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>stdcall</term>
+ <term>thiscall</term>
<listitem>
<para>
- for a normal Win32 function
+ for a Win32 function using the C++ calling convention
</para>
</listitem>
</varlistentry>
+ </variablelist>
+
+ <para>
+ <literal>ARGTYPE</literal> should be one of:
+ </para>
+ <variablelist>
<varlistentry>
- <term>cdecl</term>
+ <term>word</term>
<listitem>
<para>
- for a Win32 function using the C calling convention
+ for a 16-bit word
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>varargs</term>
+ <term>s_word</term>
<listitem>
<para>
- for a Win32 function taking a variable number of arguments
+ for a 16-bit signed word
</para>
</listitem>
</varlistentry>
- </variablelist>
-
- <para>
- <literal>ARGTYPE</literal> should be one of:
- </para>
- <variablelist>
<varlistentry>
- <term>word</term>
+ <term>segptr</term>
+ <listitem>
+ <para>
+ for a segmented pointer
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>segstr</term>
<listitem>
<para>
- for a 16 bit word
+ for a segmented pointer to a null-terminated string
</para>
</listitem>
</varlistentry>
@@ -711,7 +565,7 @@ ORDINAL FUNCTYPE EXPORTNAME([ARGTYPE [ARGTYPE [...]]]) HANDLERNAME
<term>long</term>
<listitem>
<para>
- a 32 bit value
+ a 32-bit value
</para>
</listitem>
</varlistentry>
@@ -732,44 +586,52 @@ ORDINAL FUNCTYPE EXPORTNAME([ARGTYPE [ARGTYPE [...]]]) HANDLERNAME
</listitem>
</varlistentry>
<varlistentry>
- <term>s_word</term>
+ <term>wstr</term>
<listitem>
<para>
- for a 16 bit signed word
+ for a linear pointer to a null-terminated wide
+ (16-bit Unicode) string
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>segptr</term>
+ <term>int64</term>
<listitem>
<para>
- for a segmented pointer
+ a 64-bit value
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>segstr</term>
+ <term>int128</term>
<listitem>
<para>
- for a segmented pointer to a null-terminated string
+ a 128-bit value
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>wstr</term>
+ <term>float</term>
<listitem>
<para>
- for a linear pointer to a null-terminated wide
- (16-bit Unicode) string
+ a 32-bit floating-point value
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>double</term>
+ <listitem>
+ <para>
+ a 64-bit floating-point value
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
- Only <literal>ptr</literal>, <literal>str</literal>,
- <literal>wstr</literal> and
- <literal>long</literal> are valid for Win32 functions.
+ For Win32 functions <literal>word</literal>,
+ <literal>s_word</literal>, <literal>segptr</literal> and
+ <literal>segstr</literal> are not valid.
<literal>HANDLERNAME</literal> is the name of the actual Wine
function that will process the request in 32-bit mode.
</para>
@@ -802,11 +664,6 @@ ORDINAL FUNCTYPE EXPORTNAME([ARGTYPE [ARGTYPE [...]]]) HANDLERNAME
be printed as a string.
</para>
<para>
- The two examples define an entry point for the
- <function>CreateWindow</function> and <function>GetFocus</function>
- calls respectively. The ordinals used are just examples.
- </para>
- <para>
To declare a function using a variable number of arguments in
Win16, specify the function as taking no arguments. The arguments
are then available with CURRENT_STACK16->args. In Win32, specify
@@ -836,18 +693,6 @@ ORDINAL extern EXPORTNAME SYMBOLNAME
to the symbol <literal>SYMBOLNAME</literal> that must be defined
in C code. This type only works with Win32.
</para>
-
- <programlisting>
-ORDINAL forward EXPORTNAME SYMBOLNAME
- </programlisting>
- <para>
- This field can be present zero or more times.
- Each instance defines an entry that is forwarded to another entry
- point (kind of a symbolic link). <literal>EXPORTNAME</literal>
- will forward to the entry point <literal>SYMBOLNAME</literal>
- that must be of the form <literal>DLL.Function</literal>. This
- type only works with Win32.
- </para>
</sect2>
</sect1>
--
Best Regards, André Hentschel
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: Nachrichtenteil als Anhang
URL: <http://www.winehq.org/pipermail/wine-patches/attachments/20120129/d0f77c3a/attachment.ksh>
More information about the wine-patches
mailing list