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