Small Winelib documentation update

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 




This is a small Winelib documentation update to at least make it less 
misleading.

Changelog:

    Francois Gouget <fgouget@codeweavers.com>

  * documentation/winelib-toolkit.sgml

    Small updates to better match the format of current Makefiles
    Remove the documentation of no longer supported spec file options
    Add notes to point out the sections that are particularly out of date

-- 
Francois Gouget
fgouget@codeweavers.com

Index: documentation/winelib-toolkit.sgml
===================================================================
RCS file: /home/wine/wine/documentation/winelib-toolkit.sgml,v
retrieving revision 1.4
diff -u -r1.4 winelib-toolkit.sgml
--- documentation/winelib-toolkit.sgml	17 Sep 2002 00:06:30 -0000	1.4
+++ documentation/winelib-toolkit.sgml	19 Sep 2002 19:59:25 -0000
@@ -252,32 +252,34 @@
         <programlisting>
 SUBDIRS               =
 DLLS                  =
-EXES                  = hello
+EXES                  = hello.exe
         </programlisting>
         <para>
           This is where the targets for this directory are listed. The names 
           are pretty self-explanatory. <varname>SUBDIRS</varname> is usually 
-          only present in the top-level makefile. For libraries you should 
-          put the full Unix name, e.g. <literal>libfoo.so</literal>.
+          only present in the top-level makefile. For libraries and
+          executables, specify the full name, including the '.dll' or '.exe'
+          extension. Note that these names must be in all lowercase.
         </para>
         <programlisting>
 ### Global settings
 
 DEFINES               = -DSTRICT
 INCLUDE_PATH          =
+DLL_PATH              =
 LIBRARY_PATH          =
 LIBRARIES             =
         </programlisting>
         <para>
-          This section contains the global compilation settings: they apply 
-          to all the targets in this makefile. The <varname>LIBRARIES</varname> 
-          variable allows you to specify additional Unix libraries to link with. 
-          Note that you would normally not specify Winelib libraries there. To 
-          link with a Winelib library, one uses the 'import' statement of the 
-          <link linkend="spec-file">spec files</link>. The exception is when you 
-          have not explicitly exported the functions of a Winelib library. One 
-          library you are likely to find here is <literal>mfc</literal> (note, 
-          the '-l' is omitted).
+          This section contains the global compilation settings: they apply
+          to all the targets in this makefile. The <varname>LIBRARIES</>
+          variable allows you to specify additional Unix libraries to link
+          with. Note that you would normally not specify Winelib libraries
+          there. To link with a Winelib library, one uses the <varname>DLLS</>
+          variables of the Makefile. The exception is for C++ libraries where
+          you currently don't have  a choice but to link with them in the
+          Unix sense. One library you are likely to find here is 
+          <literal>mfc</> (note, the '-l' is omitted).
         </para>
         <para>
           The other variable 
@@ -287,21 +289,19 @@
           <varname>WRCEXTRA</varname> which allow you to specify additional 
           flags for, respectively, the C compiler, the C++ compiler and the 
           resource compiler. Finally note that all these variable contain 
-          the option's name except <varname>IMPORTS</varname>. So you should 
-          put <literal>-DSTRICT</literal> in <varname>DEFINES</varname> but 
-          <literal>winmm</literal> in <varname>IMPORTS</varname>.
+          the option's name.
         </para>
         <para>
           Then come one section per target, each describing the various 
           components that target is made of.
         </para>
         <programlisting>
-### hello sources and settings
+### hello.exe sources and settings
 
-hello_C_SRCS          = hello.c
-hello_CXX_SRCS        =
-hello_RC_SRCS         =
-hello_SPEC_SRCS       = hello.spec
+hello_exe_C_SRCS          = hello.c
+hello_exe_CXX_SRCS        =
+hello_exe_RC_SRCS         =
+hello_exe_SPEC_SRCS       =
         </programlisting>
         <para>
           Each section will start with a comment indicating the name of the 
@@ -314,32 +314,34 @@
           The above variables list the sources that are used togenerate the 
           target. Note that there should only be one resource file in 
           <varname>RC_SRCS</varname>, and that <varname>SPEC_SRCS</varname> 
-          will always contain a single spec file.
+          will usually be empty for executables, and will contain a single
+          spec file for libraries.
         </para>
         <programlisting>
-hello_LIBRARY_PATH    =
-hello_LIBRARIES       =
-hello_DEPENDS         =
+hello_exe_DLL_PATH        =
+hello_exe_DLLS            =
+hello_exe_LIBRARY_PATH    =
+hello_exe_LIBRARIES       =
+hello_exe_DEPENDS         =
         </programlisting>
         <para>
           The above variables specify how to link the target. Note that they 
           add to the global settings we saw at the beginning of this file.
         </para>
         <para>
-          <varname>DEPENDS</varname>, when present, specifies a list of other 
-          targets that this target depends on. Winemaker will automatically 
-          fill this field, and the <varname>LIBRARIES</varname> field, when an 
-          executable and a library are built in the same directory.
+          The <varname>DLLS</> field is where you would enumerate the list of
+          dlls that executable imports. It should contain the full dll name
+          including the '.dll' extension, but not the '-l' option.
         </para>
         <para>
-          The reason why winemaker also links with libraries in the Unix sense 
-          in the case above is because functions will not be properly exported. 
-          Once you have exported all the functions in the library's spec file 
-          you should remove them from the <varname>LIBRARIES</varname> field.
+          <varname>DEPENDS</>, when present, specifies a list of other 
+          targets that this target depends on. Winemaker will automatically 
+          fill this field when an executable and a library are built in the
+          same directory.
         </para>
         <programlisting>
-hello_OBJS            = $(hello_C_SRCS:.c=.o) \
-                        $(hello_CXX_SRCS:.cpp=.o) \
+hello_exe_OBJS        = $(hello_exe_C_SRCS:.c=.o) \
+                        $(hello_exe_CXX_SRCS:.cpp=.o) \
                         $(EXTRA_OBJS)
         </programlisting>
         <para>
@@ -350,19 +352,22 @@
         <programlisting>
 ### Global source lists
 
-C_SRCS                = $(hello_C_SRCS)
-CXX_SRCS              = $(hello_CXX_SRCS)
-RC_SRCS               = $(hello_RC_SRCS)
-SPEC_SRCS             = $(hello_SPEC_SRCS)
+C_SRCS                = $(hello_exe_C_SRCS)
+CXX_SRCS              = $(hello_exe_CXX_SRCS)
+RC_SRCS               = $(hello_exe_RC_SRCS)
+SPEC_SRCS             = $(hello_exe_SPEC_SRCS)
         </programlisting>
         <para>
           This section builds 'summary' lists of source files. These lists are 
           used by the <filename>Make.rules</filename> file.
         </para>
+        <note><para>
+          FIXME:The following is not up-to-date.
+        </para></note>
         <programlisting>
 ### Generic autoconf targets
 
-all: $(DLLS) $(EXES:%=%.so)
+all: $(DLLS:%=%.so) $(EXES:%=%.so)
 
 @MAKE_RULES@
 
@@ -550,37 +555,17 @@
           A typical spec file will look something like this:
         </para>
         <screen>
-name    hello
-type    win32
-mode    guiexe
 init    WinMain
 rsrc    resource.res
-
-import  winmm.dll
         </screen>
         <para>
           And here are the entries you will probably want to change: 
         </para>
         <variablelist>
           <varlistentry>
-            <term>name</term>
-            <listitem>
-              <para>
-                This is the name of the Win32 module. Usually this is the 
-                same as that of the application or library (but without the 
-                'lib' and the '.so').
-              </para>
-            </listitem>
-          </varlistentry>
-          <varlistentry>
-            <term>mode</term>
             <term>init</term>
             <listitem>
               <para>
-                <literal>mode</literal> defines whether what you are 
-                building is a library, <literal>dll</literal>, a console 
-                application, <literal>cuiexe</literal> or a regular 
-                graphical application <literal>guiexe</literal>. Then 
                 <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 
@@ -590,17 +575,6 @@
             </listitem>
           </varlistentry>
           <varlistentry>
-            <term>import</term>
-            <listitem>
-              <para>
-                Add an 'import' statement for each library that this 
-                executable depends on. If you don't, these libraries will 
-                not get initialized in which case they may very well not 
-                work (e.g. winmm).
-              </para>
-            </listitem>
-          </varlistentry>
-          <varlistentry>
             <term>rsrc</term>
             <listitem>
               <para>
@@ -626,6 +600,9 @@
           <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 
@@ -678,9 +655,6 @@
 
       <sect2 id="spec-reference">
         <title id="spec-reference.title">More details</title>
-        <para>
-          (Extracted from tools/winebuild/README)
-        </para>
 
         <para>
           Here is a more detailed description of the spec file's format.
@@ -694,44 +668,6 @@
         </para>
 
         <programlisting>
-name    NAME
-type    win16|win32 &lt;--- the |'s mean it's one or the other
-        </programlisting>
-        <para>
-            These two fields are mandatory. <literal>name</literal> 
-            defines the name of your module and <literal>type</literal> 
-            whether it is a Win16 or Win32 module. Note that for Winelib 
-            you should only be using Win32 modules.
-        </para>
-
-        <programlisting>
-file    WINFILENAME
-        </programlisting>
-        <para>
-          This field is optional. It gives the name of the Windows file that 
-          is replaced by the builtin. <literal>&lt;name&gt;.DLL</literal> 
-          is assumed if none is given. This is important for kernel, which 
-          lives in the Windows file <filename>KRNL386.EXE</filename>.
-        </para>
-
-        <programlisting>
-heap    SIZE
-        </programlisting>
-        <para>
-          This field is optional and specific to Win16 modules. It defines 
-          the size of the module local heap. The default is no local heap.
-        </para>
-
-        <programlisting>
-mode    dll|cuiexe|guiexe
-        </programlisting>
-        <para>
-          This field is optional. It specifies specifies whether it is the 
-          spec file for a dll or the main exe. This is only valid for Win32 
-          spec files.
-        </para>
-
-        <programlisting>
 init    FUNCTION
         </programlisting>
         <para>
@@ -741,15 +677,6 @@
         </para>
 
         <programlisting>
-import  DLL
-        </programlisting>
-        <para>
-          This field can be present zero or more times.
-          Each instance names a dll that this module depends on (only for 
-          Win32 modules at the present).
-        </para>
-
-        <programlisting>
 rsrc    RES_FILE
         </programlisting>
         <para>
@@ -912,7 +839,7 @@
         </itemizedlist>
         <para>
           It is for debug messages. If the parameter is OUT
-          it might not be initialized as thus it should not
+          it might not be initialized and thus it should not
           be printed as a string.
         </para>
         <para>
@@ -967,7 +894,9 @@
 
     <sect1 id="linking">
       <title id="linking.title">Linking it all together</title>
-      <!-- FIXME: This is outdated -->
+      <note><para>
+        FIXME:The following is not up-to-date.
+      </para></note>
       <para>
         To link an executable you need to link together: your object files, 
         the spec file, any Windows libraries that your application depends

[Index of Archives]     [Gimp for Windows]     [Red Hat]     [Samba]     [Yosemite Camping]     [Graphics Cards]     [Wine Home]

  Powered by Linux