From 95e5c921201eb0fef365d42afdfc4b1aa37a20a2 Mon Sep 17 00:00:00 2001 From: Francois Gouget Date: Fri, 20 Sep 2002 19:39:42 +0000 Subject: [PATCH] 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. --- documentation/winelib-toolkit.sgml | 173 +++++++++-------------------- 1 file changed, 51 insertions(+), 122 deletions(-) diff --git a/documentation/winelib-toolkit.sgml b/documentation/winelib-toolkit.sgml index a91c4b324ec..3634dcc16ab 100644 --- a/documentation/winelib-toolkit.sgml +++ b/documentation/winelib-toolkit.sgml @@ -252,32 +252,34 @@ VPATH = @srcdir@ SUBDIRS = DLLS = -EXES = hello +EXES = hello.exe This is where the targets for this directory are listed. The names are pretty self-explanatory. SUBDIRS is usually - only present in the top-level makefile. For libraries you should - put the full Unix name, e.g. libfoo.so. + 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. ### Global settings DEFINES = -DSTRICT INCLUDE_PATH = +DLL_PATH = LIBRARY_PATH = LIBRARIES = - This section contains the global compilation settings: they apply - to all the targets in this makefile. The 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 'import' statement of the - spec files. The exception is when you - have not explicitly exported the functions of a Winelib library. One - library you are likely to find here is mfc (note, - the '-l' is omitted). + This section contains the global compilation settings: they apply + to all the targets in this makefile. The 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 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 + mfc (note, the '-l' is omitted). The other variable @@ -287,21 +289,19 @@ LIBRARIES = WRCEXTRA 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 IMPORTS. So you should - put -DSTRICT in DEFINES but - winmm in IMPORTS. + the option's name. Then come one section per target, each describing the various components that target is made of. -### 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 = Each section will start with a comment indicating the name of the @@ -314,32 +314,34 @@ hello_SPEC_SRCS = hello.spec The above variables list the sources that are used togenerate the target. Note that there should only be one resource file in RC_SRCS, and that SPEC_SRCS - will always contain a single spec file. + will usually be empty for executables, and will contain a single + spec file for libraries. -hello_LIBRARY_PATH = -hello_LIBRARIES = -hello_DEPENDS = +hello_exe_DLL_PATH = +hello_exe_DLLS = +hello_exe_LIBRARY_PATH = +hello_exe_LIBRARIES = +hello_exe_DEPENDS = 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. - DEPENDS, when present, specifies a list of other - targets that this target depends on. Winemaker will automatically - fill this field, and the LIBRARIES field, when an - executable and a library are built in the same directory. + The 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. - 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 LIBRARIES field. + 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. -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) @@ -350,19 +352,22 @@ hello_OBJS = $(hello_C_SRCS:.c=.o) \ ### 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) This section builds 'summary' lists of source files. These lists are used by the Make.rules file. + + FIXME:The following is not up-to-date. + ### Generic autoconf targets -all: $(DLLS) $(EXES:%=%.so) +all: $(DLLS:%=%.so) $(EXES:%=%.so) @MAKE_RULES@ @@ -550,37 +555,17 @@ WRCFLAGS = -r -L A typical spec file will look something like this: -name hello -type win32 -mode guiexe init WinMain rsrc resource.res - -import winmm.dll And here are the entries you will probably want to change: - name - - - 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'). - - - - - mode init - mode defines whether what you are - building is a library, dll, a console - application, cuiexe or a regular - graphical application guiexe. Then init defines what is the entry point of that module. For a library this is customarily set to DllMain, for a console application this @@ -589,17 +574,6 @@ import winmm.dll - - import - - - 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). - - - rsrc @@ -626,6 +600,9 @@ hello.spec.c: hello.res @ + + FIXME: You must now export functions from dlls. + 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 @@ WINEBUILD=$(WINE_DIR)/tools/winebuild More details - - (Extracted from tools/winebuild/README) - Here is a more detailed description of the spec file's format. @@ -693,44 +667,6 @@ WINEBUILD=$(WINE_DIR)/tools/winebuild Anything after a '#' will be ignored as comments. - -name NAME -type win16|win32 <--- the |'s mean it's one or the other - - - These two fields are mandatory. name - defines the name of your module and type - whether it is a Win16 or Win32 module. Note that for Winelib - you should only be using Win32 modules. - - - -file WINFILENAME - - - This field is optional. It gives the name of the Windows file that - is replaced by the builtin. <name>.DLL - is assumed if none is given. This is important for kernel, which - lives in the Windows file KRNL386.EXE. - - - -heap SIZE - - - This field is optional and specific to Win16 modules. It defines - the size of the module local heap. The default is no local heap. - - - -mode dll|cuiexe|guiexe - - - 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. - - init FUNCTION @@ -740,15 +676,6 @@ init FUNCTION or the executable started. - -import DLL - - - 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). - - rsrc RES_FILE @@ -912,7 +839,7 @@ ORDINAL FUNCTYPE EXPORTNAME([ARGTYPE [ARGTYPE [...]]]) HANDLERNAME 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. @@ -967,7 +894,9 @@ ORDINAL forward EXPORTNAME SYMBOLNAME Linking it all together - + + FIXME:The following is not up-to-date. + To link an executable you need to link together: your object files, the spec file, any Windows libraries that your application depends