+Tor Lillqvist <tml@iki.fi>
+Hans Breuer <hans@breuer.org>
+
+The general parts, and the stuff about gcc and autoconfiscated build
+are by Tor Lillqvist. The stuff about MSVC build is by Hans Breuer.
+
General
=======
-For more information about the port or GLib, GTk+ and the GIMP to
-native Windows, and pre-built binary packages, see
-http://www.iki.fi/tml/gimp/win32/ . "Native" means that we use the
-Win32 API only, and not any POSIX emulation layer except that provided
-by the Microsoft runtime C library. Additionally, a pthreads emulation
-library is used.
-
-To build GLib on Win32, you can use either the Microsoft compiler and
-tools, or gcc. Both the compiler from MSVC 5.0 and from MSVC 6.0 have
-been used successfully. With gcc I mean egcs-1.1.2 (as distributed by
-Mumit Khan), running under cygwin-b20.1. To successfully use gcc,
-follow the instructions below. We want to use gcc -mno-cygwin,
-i.e. produce executables (.exe and .dll files) that do *not* require
-the cygwin runtime library. This is sometimes called "mingw32".
-
-To test the GLib functions, go to the tests subdirectory and enter
-`nmake -f makefile.msc check` or `make -f makefile.cygwin check`.
-
-If you would want to use the cygwin tools to generate executables that
-*do* use the cygwin runtime, the normal Unix configuration method
-should work as if on Unix. But it won't produce DLLs. At least I
-haven't succeeded in that.
-
-With a little work, it might be possible to use the ./configure
-mechanism also with a "mingw32" configuration.
-
-The following preprocessor macros are defined in glibconfig.h and used
-for conditional compilation related to Win32:
-
-- WIN32 is defined when compiling for the Win32 platform, regardless
- if using the X11 or Win32 windowing API (in the case of GLib, this
- dimension isn't significant), regardless whether using a more or
- less complete POSIX emulation runtime layer (like Cygwin) or not.
-
-- NATIVE_WIN32 is defined when compiling for Win32, *and* without
- any POSIX emulation, other that to the extent provided by the
- bundled Microsoft C library (msvcrt.dll) and the pthreads-win32
- library. For instance, pathnames are in the native Windows syntax.
-
-The Win32 port uses the combination with both of those on. As these
-are in glibconfig.h, they are available to all source files that use
-GLib (or GTk+, which uses GLib).
+For prebuilt binaries (DLLs and EXEs) and developer packages (headers,
+import libraries) of GLib, GTK+, GIMP etc for Windows, surf to
+http://www.gimp.org/win32/ . They are for "native" Windows meaning
+they use the Win32 API and Microsoft C runtime library only, no POSIX
+(Unix) emulation layer (like Cygwin).
+
+To build GLib on Win32, you can use either gcc or the Microsoft
+compiler and tools. Both the compiler from MSVC 5.0 and from MSVC 6.0
+have been used successfully.
+
+But note that to just *use* GLib on Windows, there is no need to build
+it yourself. Prepackaged runtime and developer packages are available
+from the webiste above. On Unix, it is quite normal that system admins
+build and install libraries like GLib themselves. But on Windows
+setting up a correct build environment can be quite a task, especially
+if you are used to on Unix just type ./configure; make, and expect
+things to work as smoothly on Windows.
+
+The following preprocessor macros can be used for conditional
+compilation related to Win32 in GLib-using code:
+
+- G_OS_WIN32 is defined when compiling for native Win32, without
+ any POSIX emulation, other than to the extent provided by the
+ bundled Microsoft C library (msvcrt.dll).
+
+- G_WITH_CYGWIN is defined if compiling for the Cygwin
+ environment. Note that G_OS_WIN32 is *not* defined in that case, as
+ Cygwin is supposed to behave like Unix. G_OS_UNIX *is* defined when
+ compiling for Cygwin.
+
+- G_PLATFORM_WIN32 is defined when either G_OS_WIN32 or G_WITH_CYGWIN
+ is defined.
+
+These macros are defined in glibconfig.h, and are thus (indirectly)
+available in all source files that include <glib.h> or GTK+ headers.
Additionally, there are the compiler-specific macros:
+- __GNUC__ is defined when using gcc
- _MSC_VER is defined when using the Microsoft compiler
-- __GNUC__ is defined when using GCC (i.e. egcs)
-Some of the usage of these macros used to be a bit mixed up, and had
-to be straightened out when adding the gcc support. In particular, I
-used to check for _MSC_VER in some places where I really wanted to
-check for the Microsoft C library, and those checks has now been
-changed to NATIVE_WIN32. NATIVE_WIN32 ought to be renamed to
-USE_MSVCRT.
+G_OS_WIN32 implies using the Microsoft C runtime MSVCRT.DLL. GLib is
+not known to work with the older CRTDLL.DLL runtime, or the static
+Microsoft C runtime libraries LIBC.LIB and LIBCMT.LIB. It apparently
+does work with the debugging version of MSVCRT.DLL, MSVCRTD.DLL.
+
+Building software that use GLib or GTK+
+=======================================
+
+Even building software that just *uses* GLib or GTK+ also require to
+have the right compiler set up the right way, so if you intend to use
+gcc, follow the relevant instructions below in that case, too.
+
+Tor uses gcc with the -fnative-struct flag, which means that in order to
+use the prebuilt DLLs (especially of GTK+), you *must* also use that
+flag. (This flag means that the struct layout rules are identical to
+those used by MSVC. This is essential if the same DLLs are to be
+usable both from gcc- and MSVC-compiled code. This definitely is
+something one wants.)
-Pthreads library
-================
+Building GLib
+=============
-Before building you must get the pthreads library for Win32 from
-http://sourceware.cygnus.com/pthreads-win32/. The pthreads-win32
-snapshot from 1999-05-30 is the one that should be used. Edit the
-location of the pthreads library and include files in makefile.msc or
-makefile.cygwin. The pthreads distribution includes the precompiled dll
-and import libraries both for MSVC and gcc.
+Again, first decide whether you really want to do this.
-The pthreads for Win32 package that the thread support uses supposedly
-isn't quite ready yet, and thus threads stuff should not be relied
-upon for anything serious.
+Before building GLib you must also have the libiconv library, either
+from the same website mentioned above, or from it's homepage at
+http://clisp.cons.org/~haible/packages-libiconv.html. Libiconv has
+makefiles for building with MS Visual C only, but as it is one source
+file only, building it "by hand" with gcc isn't hard.
+
+You must also have the "intl" library from GNU tettext 0.10.40 (or
+later). Get a prebuilt version from the website mentioned above.
+
+Edit the correct paths to those libraries in build/win32/module.defs
+as appropriate.
Where are the makefiles?
========================
If you are building from a CVS snapshot, you will not have any
-makefile.msc or makefile.cygwin file. You should copy the
-corresponding makefile.msc.in or makefile.cygwin.in file to that name,
-and edit the line that sets GLIB_VER to the correct version number.
+makefile.mingw or makefile.msc files. You should copy the
+corresponding makefile.mingw.in or makefile.msc.in file to that name,
+and replace any @...@ strings with the correct value.
+
+This is done automatically when an official GLib source distribution
+package is built, so if you get GLib from a source distribution
+package, there should be makefile.mingw and makefile.msc files ready
+to use (after some editing).
+
+Building GLib with gcc
+======================
+
+Tor uses gcc-2.95.3. Version 2.95.2 will most probably also work.
+
+You can either use gcc running on Cygwin, or the "pure" mingw
+gcc. Using the latter might work better, or at least did at some
+point.
+
+Fetch the latest version of gcc for mingw and the msvcrt runtime, from
+www.mingw.org.
+
+Set up your PATH so that the gcc from the bin directory that got
+created above is the one that gets used. Even if you run the mingw
+gcc, you still want to have Cygwin to run make in.
+
+Then run make -f makefile.mingw. Install the resulting DLLs somewhere
+in your PATH. You can either keep the headers and import libraries
+where they are, or install them somewhere else. There are no rules in
+the makefile.mingws for installing, it is up to you where to put them.
+
+Autoconfiscated build
+=====================
+
+It is also possible to use the auto*, ./configure and libtool
+mechanism when building with gcc. You should be running Cygwin, or
+maybe cross-compiling from real Unix, for the configure script to
+work, obviously. (It might also be possible to use "MSYS", but I
+haven't checked.) You most probably should have very new auto* and
+libtool. Tor invokes configure using:
+
+CC='gcc -mpentium -fnative-struct'
+ CPPFLAGS='-I/src/libiconv-1.7/include -I/target/include'
+ LDFLAGS='-L/src/libiconv-1.7/lib -L/target/lib' ./configure
+ --with-libiconv --disable-static --prefix=/target
+ --host=i386-pc-mingw32 --enable-maintainer-mode
+
+(on a single line)
+
+But please note that the ./configure mechanism should not blindly be
+used to build a GLib to be distributed to other developers because it
+produces a compiler-dependent glibconfig.h (and config.h, but that
+shouldn't matter, as it isn't seen by GLib-using applications). For
+instance, the typedef for gint64 is long long with gcc, but __int64
+with MSVC.
+
+Except for this and a few other minor issues, there really shouldn't
+be any reason to distribute separate GLib headers and DLLs for gcc and
+MSVC users, as both compilers generate code that uses the same C
+runtime library. Thus one either has to manually edit glibconfig.h
+afterwards, or use the supplied config.h.win32 and
+glibconfig.h.win32. These have been produced by running configure
+twice, once using gcc and once using MSVC, and merging the resulting
+files with diff -D.
+
+There might be other hickups when using auto* and configure to build
+with gcc. Lately Tor has used auto*/configure/libtool exclusively when
+building GLib, GTK+, GIMP etc on Win32, and it seems to work well
+(with some patches applied to the current CVS libtool...).
+
+The hand-written makefile.{mingw,msc} files, and the stuff in the
+"build" subdirectory, produce DLLs and import libraries that match
+what Makefile.am and libtool produces. For GLib, the DLL is called
+libglib-1.3-15.dll (at GLib 1.3.15), and the import libraries
+libglib-1.3.dll.a and glib-1.3.lib. Note that the "1.3" is part of the
+"basename" of the library, it is not something that libtool have
+tucked on. The -15 suffix is the value of "LT_CURRENT - LT_AGE". The
+15 is *not* simply the micro version number of GLib, although, for
+GLib 1.3.15, it happens to be the same. For the gory details, see
+configure.in and libtool documentation.
-This is done automatically when an official distribution package is
-built.
+If you want to run the Cygwin-hosted gcc, and still want to produce
+code that does not use Cygwin, but the msvcrt runtime, in theory it
+should work to use the -no-cygwin flag, but Tor hasn't tested that
+lately.
+
+If you would want to use the Cygwin tools to generate a GLib that
+*does* use the Cygwin runtime, the normal Unix configuration method
+should work as if on Unix. Note that successfully producing shared
+libraries (DLLs) for Cygwin most probably requires you to have a very
+new libtool. (And a new libtool probably requires rather new autoconf
+and automake.) Tor hasn't tested this in a while.
Building with MSVC
==================
-If using the Microsoft toolchain, build with `nmake -f
-makefile.msc`. Install with `nmake -f makefile.msc install`.
-
-Building with gcc
-=================
-
-The gcc support was added quite recently, but seems to work. Debugging
-with gdb works. I prefer to use the msvcrt runtime and not the default
-crtdll. Especially, as the pthread library also uses msvcrt, using
-crtdll would probably not be a good idea at all. Using msvcrt can be
-achieved by applying the following diff to the specs file, which
-typically is installed as
-C:\cygnus\cygwin-b20\H-i586-cygwin32\lib\gcc-lib\i586-cygwin32\egcs-2.91.66\specs.
-
-Sorry for the illegibility of this diff, but the specs file is like
-that... This patch replaces -lcrtdll with -lmsvcrt, replaces crt1 with
-crt2, removes -lmoldname (because using functions from it would pull
-in crtdll.dll), and defines __MSVCRT__.
-
---- specs.ORIG Sun Apr 25 00:40:40 1999
-+++ specs Sun Apr 25 00:48:04 1999
-@@ -23 +23 @@
--%{pg:-lgmon} %{!mno-cygwin:-lcygwin} %{mno-cygwin:-lmingw32 -lmoldname -lcrtdll} %{mwindows:-luser32 -lgdi32 -lcomdlg32} -lkernel32 -ladvapi32 -lshell32
-+%{pg:-lgmon} %{!mno-cygwin:-lcygwin} %{mno-cygwin:-lmingw32 -lmsvcrt} %{mwindows:-luser32 -lgdi32 -lcomdlg32} -lkernel32 -ladvapi32 -lshell32
-@@ -29 +29 @@
--%{mdll: %{!mno-cygwin:dllcrt0%O%s} %{mno-cygwin:dllcrt1%O%s}} %{!mdll: %{!mno-cygwin:crt0%O%s} %{mno-cygwin:crt1%O%s} %{pg:gcrt0%O%s}}
-+%{mdll: %{!mno-cygwin:dllcrt0%O%s} %{mno-cygwin:dllcrt2%O%s}} %{!mdll: %{!mno-cygwin:crt0%O%s} %{mno-cygwin:crt2%O%s} %{pg:gcrt0%O%s}}
-@@ -38 +38 @@
---Di386 -D_WIN32 -DWINNT -D_X86_=1 -D__STDC__=1 -D__stdcall=__attribute__((__stdcall__)) -D__cdecl=__attribute__((__cdecl__)) -D__declspec(x)=__attribute__((x)) -Asystem(winnt) -Acpu(i386) -Amachine(i386)
-+-Di386 -D_WIN32 %{mno-cygwin:-D__MSVCRT__ } -DWINNT -D_X86_=1 -D__STDC__=1 -D__stdcall=__attribute__((__stdcall__)) -D__cdecl=__attribute__((__cdecl__)) -D__declspec(x)=__attribute__((x)) -Asystem(winnt) -Acpu(i386) -Amachine(i386)
-
-You should also fix two bugs in the mingw32 headers: The type of
-_dev_t in the header mingw32/sys/types.h should be unsigned int, not
-short. The type for st_uid in sys/stat.h to be short, not int. This is
-what the Microsoft's headers and runtime library use. Otherwise
-accessing the fields in a stat struct as filled in by the stat and
-fstat functions in the MS library will cause various interesting
-failures.
-
-You also will have to get the mingw32 source snapshot from
-http://www.geocities.com/Tokyo/Towers/6162/mingw32_980701_tar.gz (this
-is the source to the "mingw32" part of Mumit Khan's egcs-1.1.2
-distribution.) Unpack it and fix the prototype and call to
-__getmainargs() in init.c to include one more parameter, an int *,
-which should be passed the address of a zero int. Code snippets below:
-
-...
-#ifdef __MSVCRT__
-extern void __getmainargs(int *, char***, char***, int, int *);
-#else
-...
-#ifdef __MSVCRT__
- int newmode = 0;
- (void) __getmainargs(&_argc, &_argv, &dummy_environ, _CRT_glob, &newmode);
-#else
-...
-
-Remake dllcrt2.o (which is the file which gets linked into dlls when
-using msvcrt, as per the specs file above), and move it into place
-(typically C:\cygnus\cygwin-b20\H-i586-cygwin32\i586-cygwin32\lib\dllcrt2.o).
-
-Next, go back to the GLib directory and build using `make -f makefile.cygwin`.
-Building the dlls uses the script build-dll which is an awful hack. But
-I couldn't get things working in a cleaner way.
-
---Tor Lillqvist <tml@iki.fi>
+All the MSVC makefiles are for the command line build with nmake.
+If you want to use the VC-UI you can simply create wrapper .dsp
+makefiles (read the VC docs how to do so).
+
+Some modules may require Perl to auto-generate files. The goal (at
+least Hans's) is to not require any more tools.
+
+Build with:
+
+nmake -f makefile.msc
+ or
+nmake -f makefile.msc DEBUG=1
+
+[
+ The former will create 'release' versions of the DLLs. If you
+ plan to distribute you DLLs please use this command. The latter
+ will create DLLs with debug information _and_ link them with
+ msvcrtd.dll instead of msvcrt.dll.
+ Beware: There are known problems with mixing DLLs in one
+ application, which are build against different runtimes.
+ Especially the index-to-file mapping used by 'unix-style' file
+ operation - _open() _pipe() etc. - breaks sometimes in strange
+ ways (for example the Gimp plug-in communication).
+]
+
+Required libraries (not build from cvs)
+==================
+ libintl (gnu-intl), libiconv
+ libtiff, libpng, zlib, libjpeg
+
+are available pre-built from the website mentioned above.
+
+Versioning
+==========
+Instead of the Unix and auto* way of tracking versions and resolving
+dependencies (configure; make; make install) involving autoconf,
+automake, libtool and friends the MSVC build uses a different
+approach.
+
+The core of it's versioning is the file build/win32/module.defs.
+It contains entries of the form MODULE_VER, e.g.:
+
+ GLIB_VER = 2.0
+ LIBICONV_VER = 1.3
+
+and the placement of these modules defined as MODULE, e.g.:
+
+ GLIB = $(TOP)/glib
+ LIBICONV = $(TOP)/libiconv-$(LIBICONV_VER)
+
+whereas TOP is defined as the relative path from the respective
+module directory to your top build directory. Every makefile.msc
+needs to define TOP before including the common make file part
+make.msc, which than includes module.defs, like:
+
+TOP = ../..
+!INCLUDE $(TOP)/glib/build/win32/make.msc
+
+(Taken from gtk+/gdk/makefile.msc)
+
+With this provision it is possible to create almost placement
+independent makefiles without requiring to 'install' the libraries and
+headers into a common place (as it is done on Unix, and as Tor does
+when producing his zipfiles with prebuilt GLib, GTK+ etc).
+
+Special Files
+=============
+ config.h.win32.in : @XXX_MAJOR_VERSION@ needs to be replaced by
+the current version/build number. The resulting file is to be saved
+as 'config.h.win32'. This should be automatically done if a package
+gets build on the Unix platform.
+
+ makefile.msc.in : @XXX_MAJOR_VERSION@ to be replaced. Save as
+makefile.msc.
+
+ <module>.def : every function which should be used from the outside of
+a dll needs to be marked for 'export'. It is common that one needs to change
+these files after some api changes occured. If there are variables to be
+exported another mechanism is needed, like :
+
+ #ifdef G_OS_WIN32
+ # ifdef GDK_COMPILATION
+ # define GDKVAR __declspec(dllexport)
+ # else
+ # define GDKVAR extern __declspec(dllimport)
+ # endif
+ #else
+ # define GDKVAR extern
+ #endif
+
+
+
+Directory Structure
+===================
+all modules should be build in a common directory tree otherwise you
+need to adapt the file 'module.defs'. They are listed here in increasing
+dependencies order.
+
+<common rootdir without spaces>
+ |
+ +- glib
+ | |
+ | +- build : [this module lives in the cvs root dir]
+ | | +- win32
+ | | .\module.defs : defines (relative) locations of the headers
+ | | and libs and version numbers to be include
+ | | in dll names
+ | | .\make.msc : include by almost every 'makefile.msc'
+ | |
+ | | .\README.WIN32 : more information how to build
+ | | .\glibconfig.h.win32.in : similar to config.h.win32.in
+ | | .\makefile.msc : master makefile, sub dir makefiles should work
+ | |
+ | +- glib
+ | +- gmodule
+ | +- gthread : does _not_ depend on pthread anymore
+ | +- gobject
+ |
+ +- pango
+ | +- pango : 'native' build does not require extra libs and
+ | | includes the minimal required text renderer
+ | | (there is also a currently slightly broken FreeType2
+ | | based implementation for win32)
+ | +- modules (not yet build)
+ |
+ +- atk
+ | +- atk
+ | .\makefile.msc : build here
+ |
+ +- gtk+
+ | | .\config.h.win32 : for all the below
+ | |
+ | +- gdk-pixbuf
+ | | .\gdk_pixbuf.rc.in : version resource for the DLLs. Needs
+ | | to be converted (filled with version info)
+ | | as described above.
+ | |
+ | +- gdk
+ | | | .\makefile.msc : some auto-generation is needed to build in the
+ | | | in the subdirectory
+ | | +- win32
+ | |
+ | +- gtk
+
+ |
+ +- gimp
+ | .\makefile.msc : master makefile to build The Gimp. The makefiles
+ | from the sub dirs should work stand alone, but than
+ | the user needs to know the build order
+
+ |
+ +- dia : additionally depends on libart_lgpl (in cvs)
+ | and libxml2 ( see http://www.xmlsoft.org/ )
+ +- lib
+ +- app
+ +- objects
+ +- plug-ins
+ +- python
+
projects / platform / upstream / glib.git / blobdiff