From 2502bfd8b0e9a8136aae833dc674a28a884f1de1 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 10 Jul 2017 11:35:11 +0100 Subject: [PATCH] Re-normalise line endings of README.win32 Signed-off-by: Philip Withnall --- README.win32 | 406 +++++++++++++++++++++++++-------------------------- 1 file changed, 203 insertions(+), 203 deletions(-) diff --git a/README.win32 b/README.win32 index 83f0c987a..4fda64ae0 100644 --- a/README.win32 +++ b/README.win32 @@ -1,203 +1,203 @@ -Tor Lillqvist -Hans Breuer - -Note that this document is not really maintained in a serious -fashion. Lots of information here might be misleading or outdated. You -have been warned. - -The general parts, and the section about gcc and autoconfiscated -build, and about a Visual Studio build are by Tor Lillqvist. - -General -======= - -For prebuilt binaries (DLLs and EXEs) and developer packages (headers, -import libraries) of GLib, Pango, GTK+ etc for Windows, go to -http://www.gtk.org/download-windows.html . They are for "native" -Windows meaning they use the Win32 API and Microsoft C runtime library -only. No POSIX (Unix) emulation layer like Cygwin in involved. - -To build GLib on Win32, you can use either gcc ("mingw") or the -Microsoft compiler and tools. For the latter, MSVC6 and later have -been used successfully. Also the Digital Mars C/C++ compiler has -reportedly been used. - -You can also cross-compile GLib for Windows from Linux using the -cross-compiling mingw packages for your distro. - -Note that to just *use* GLib on Windows, there is no need to build it -yourself. - -On Windows setting up a correct build environment can be quite a task, -especially if you are used to just type "./configure; make" on Linux, -and expect things to work as smoothly on Windows. - -The following preprocessor macros are to 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 (msvcr*.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 by a GLib - 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 available in -all source files that include . - -Additionally, there are the compiler-specific macros: -- __GNUC__ is defined when using gcc -- _MSC_VER is defined when using the Microsoft compiler -- __DMC__ is defined when using the Digital Mars C/C++ compiler - -G_OS_WIN32 implies using the Microsoft C runtime, normally -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. If compiled with Microsoft compilers newer -than MSVC6, it also works with their compiler-specific runtimes, like -msvcr70.dll or msvcr80.dll. Please note that it's non totally clear if -you would be allowed by the license to distrubute a GLib linked to -msvcr70.dll or msvcr80.dll, as those are not part of the operating -system, but of the MSVC product. msvcrt.dll is part of Windows. - -For people using Visual Studio 2005 or later: - -If you are building GLib-based libraries or applications, or GLib itself -and you see a C4819 error (or warning, before C4819 is treated as an error -in msvc_recommended_pragmas.h), please be advised that this error/warning should -not be disregarded, as this likely means portions of the build is not being -done correctly, as this is an issue of Visual Studio running on CJK (East Asian) -locales. This is an issue that also affects builds of other projects, such as -QT, Firefox, LibreOffice/OpenOffice, Pango and GTK+, along with many other projects. - -To overcome this problem, please set your system's locale setting for non-Unicode to -English (United States), reboot, and restart the build, and the code should build -normally. See also this GNOME Wiki page [1] that gives a bit further info on this. - -Building software that use GLib or GTK+ -======================================= - -Building software that just *uses* GLib or GTK+ also require to have -the right compiler set up the right way. If you intend to use gcc, -follow the relevant instructions below in that case, too. - -Tor uses gcc with the -mms-bitfields flag which means that in order to -use the prebuilt DLLs (especially of GTK+), if you compile your code -with gcc, 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. Such compatibility is desirable. - -When using the prebuilt GLib DLLs that use msvcrt.dll from code that -uses other C runtimes like for example msvcr70.dll, one should note -that one cannot use such GLib API that take or returns file -descriptors. On Windows, a file descriptor (the small integer as -returned by open() and handled by related functions, and included in -the FILE struct) is an index into a table local to the C runtime -DLL. A file descriptor in one C runtime DLL does not have the same -meaning in another C runtime DLL. - -Building GLib -============= - -Again, first decide whether you really want to do this. - -Before building GLib you must also have a GNU gettext-runtime -developer package. Get prebuilt binaries of gettext-runtime from -http://www.gtk.org/download-windows.html . - -Autoconfiscated build (with gcc) -================================ - -Tor uses gcc 3.4.5 and the rest of the mingw utilities, including MSYS -from www.mingw.org. Somewhat earlier or later versions of gcc -presumably also work fine. - -Using Cygwin's gcc with the -mno-cygwin switch is not recommended. In -theory it should work, but Tor hasn't tested that lately. It can -easily lead to confusing situations where one mixes headers for Cygwin -from /usr/include with the headers for native software one really -should use. Ditto for libraries. - -If you want to use mingw's gcc, install gcc, win32api, binutils and -MSYS from www.mingw.org. - -Tor invokes configure using: - -CC='gcc -mtune=pentium3 -mthreads' CPPFLAGS='-I/opt/gnu/include' \ - LDFLAGS='-L/opt/gnu/lib -Wl,--enable-auto-image-base' CFLAGS=-O2 \ - ./configure --disable-gtk-doc --prefix=$TARGET - -The /opt/gnu mentioned contains the header files for GNU and (import) -libraries for GNU libintl. The build scripts used to produce the -prebuilt binaries are included in the "dev" packages. - -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. 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 shouldn't be any -reason to distribute separate GLib headers and DLLs for gcc and MSVC6 -users, as the compilers generate code that uses the same C runtime -library. - -The DLL generated by either compiler is binary compatible with the -other one. Thus one either has to manually edit glibconfig.h -afterwards, or use the supplied glibconfig.h.win32 which has been -produced by running configure twice, once using gcc and once using -MSVC, and merging the resulting files with diff -D. - -For MSVC7 and later (Visual C++ .NET 2003, Visual C++ 2005, Visual C++ -2008 etc) it is preferred to use specific builds of GLib DLLs that use -the same C runtime as the code that uses GLib. Such DLLs should be -named differently than the ones that use msvcrt.dll. - -For GLib, the DLL that uses msvcrt.dll is called libglib-2.0-0.dll, -and the import libraries libglib-2.0.dll.a and glib-2.0.lib. Note that -the "2.0" is part of the "basename" of the library, it is not -something that libtool has added. The -0 suffix is added by libtool -and is the value of "LT_CURRENT - LT_AGE". The 0 should *not* be -thought to be part of the version number of GLib. The LT_CURRENT - -LT_AGE value will on purpose be kept as zero as long as binary -compatibility is maintained. For the gory details, see configure.ac -and libtool documentation. - -Building with Visual Studio -=========================== - -A more detailed outline of building GLib with its dependencies can -now be found on the GNOME wiki: - -https://wiki.gnome.org/Projects/GTK%2B/Win32/MSVCCompilationOfGTKStack - -Please do not build GLib in paths that contain spaces in them, as -this may cause problems during compilation and during usage of the -library. - -In an unpacked tarball, you will find in build\win32\vs9 (VS 2008) and -build\win32\vs10 (VS 2010) a solution file that can be used to build -the GLib DLLs and some auxiliary programs under VS 2008 and VS 2010 -(Express Edition will suffice with the needed dependencies) respectively. -Read the README.txt file in those folders for more -information. Note that you will need a libintl implementation, zlib, and -libFFI. - -If you are building from a GIT checkout, you will first need to use some -Unix-like environment or run win32/setup.py, -which will expand the VS 2008/2010 project files, the DLL resouce files and -other miscellanious files required for the build. Run win32/setup.py -as follows: - -$python win32/setup.py --perl path_to_your_perl.exe - -for more usage on this script, run -$python win32/setup.py -h/--help - -[1]: https://wiki.gnome.org/Projects/GTK%2B/Win32/MSVCCompilationOfGTKStack under "Preparations" +Tor Lillqvist +Hans Breuer + +Note that this document is not really maintained in a serious +fashion. Lots of information here might be misleading or outdated. You +have been warned. + +The general parts, and the section about gcc and autoconfiscated +build, and about a Visual Studio build are by Tor Lillqvist. + +General +======= + +For prebuilt binaries (DLLs and EXEs) and developer packages (headers, +import libraries) of GLib, Pango, GTK+ etc for Windows, go to +http://www.gtk.org/download-windows.html . They are for "native" +Windows meaning they use the Win32 API and Microsoft C runtime library +only. No POSIX (Unix) emulation layer like Cygwin in involved. + +To build GLib on Win32, you can use either gcc ("mingw") or the +Microsoft compiler and tools. For the latter, MSVC6 and later have +been used successfully. Also the Digital Mars C/C++ compiler has +reportedly been used. + +You can also cross-compile GLib for Windows from Linux using the +cross-compiling mingw packages for your distro. + +Note that to just *use* GLib on Windows, there is no need to build it +yourself. + +On Windows setting up a correct build environment can be quite a task, +especially if you are used to just type "./configure; make" on Linux, +and expect things to work as smoothly on Windows. + +The following preprocessor macros are to 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 (msvcr*.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 by a GLib + 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 available in +all source files that include . + +Additionally, there are the compiler-specific macros: +- __GNUC__ is defined when using gcc +- _MSC_VER is defined when using the Microsoft compiler +- __DMC__ is defined when using the Digital Mars C/C++ compiler + +G_OS_WIN32 implies using the Microsoft C runtime, normally +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. If compiled with Microsoft compilers newer +than MSVC6, it also works with their compiler-specific runtimes, like +msvcr70.dll or msvcr80.dll. Please note that it's non totally clear if +you would be allowed by the license to distrubute a GLib linked to +msvcr70.dll or msvcr80.dll, as those are not part of the operating +system, but of the MSVC product. msvcrt.dll is part of Windows. + +For people using Visual Studio 2005 or later: + +If you are building GLib-based libraries or applications, or GLib itself +and you see a C4819 error (or warning, before C4819 is treated as an error +in msvc_recommended_pragmas.h), please be advised that this error/warning should +not be disregarded, as this likely means portions of the build is not being +done correctly, as this is an issue of Visual Studio running on CJK (East Asian) +locales. This is an issue that also affects builds of other projects, such as +QT, Firefox, LibreOffice/OpenOffice, Pango and GTK+, along with many other projects. + +To overcome this problem, please set your system's locale setting for non-Unicode to +English (United States), reboot, and restart the build, and the code should build +normally. See also this GNOME Wiki page [1] that gives a bit further info on this. + +Building software that use GLib or GTK+ +======================================= + +Building software that just *uses* GLib or GTK+ also require to have +the right compiler set up the right way. If you intend to use gcc, +follow the relevant instructions below in that case, too. + +Tor uses gcc with the -mms-bitfields flag which means that in order to +use the prebuilt DLLs (especially of GTK+), if you compile your code +with gcc, 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. Such compatibility is desirable. + +When using the prebuilt GLib DLLs that use msvcrt.dll from code that +uses other C runtimes like for example msvcr70.dll, one should note +that one cannot use such GLib API that take or returns file +descriptors. On Windows, a file descriptor (the small integer as +returned by open() and handled by related functions, and included in +the FILE struct) is an index into a table local to the C runtime +DLL. A file descriptor in one C runtime DLL does not have the same +meaning in another C runtime DLL. + +Building GLib +============= + +Again, first decide whether you really want to do this. + +Before building GLib you must also have a GNU gettext-runtime +developer package. Get prebuilt binaries of gettext-runtime from +http://www.gtk.org/download-windows.html . + +Autoconfiscated build (with gcc) +================================ + +Tor uses gcc 3.4.5 and the rest of the mingw utilities, including MSYS +from www.mingw.org. Somewhat earlier or later versions of gcc +presumably also work fine. + +Using Cygwin's gcc with the -mno-cygwin switch is not recommended. In +theory it should work, but Tor hasn't tested that lately. It can +easily lead to confusing situations where one mixes headers for Cygwin +from /usr/include with the headers for native software one really +should use. Ditto for libraries. + +If you want to use mingw's gcc, install gcc, win32api, binutils and +MSYS from www.mingw.org. + +Tor invokes configure using: + +CC='gcc -mtune=pentium3 -mthreads' CPPFLAGS='-I/opt/gnu/include' \ + LDFLAGS='-L/opt/gnu/lib -Wl,--enable-auto-image-base' CFLAGS=-O2 \ + ./configure --disable-gtk-doc --prefix=$TARGET + +The /opt/gnu mentioned contains the header files for GNU and (import) +libraries for GNU libintl. The build scripts used to produce the +prebuilt binaries are included in the "dev" packages. + +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. 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 shouldn't be any +reason to distribute separate GLib headers and DLLs for gcc and MSVC6 +users, as the compilers generate code that uses the same C runtime +library. + +The DLL generated by either compiler is binary compatible with the +other one. Thus one either has to manually edit glibconfig.h +afterwards, or use the supplied glibconfig.h.win32 which has been +produced by running configure twice, once using gcc and once using +MSVC, and merging the resulting files with diff -D. + +For MSVC7 and later (Visual C++ .NET 2003, Visual C++ 2005, Visual C++ +2008 etc) it is preferred to use specific builds of GLib DLLs that use +the same C runtime as the code that uses GLib. Such DLLs should be +named differently than the ones that use msvcrt.dll. + +For GLib, the DLL that uses msvcrt.dll is called libglib-2.0-0.dll, +and the import libraries libglib-2.0.dll.a and glib-2.0.lib. Note that +the "2.0" is part of the "basename" of the library, it is not +something that libtool has added. The -0 suffix is added by libtool +and is the value of "LT_CURRENT - LT_AGE". The 0 should *not* be +thought to be part of the version number of GLib. The LT_CURRENT - +LT_AGE value will on purpose be kept as zero as long as binary +compatibility is maintained. For the gory details, see configure.ac +and libtool documentation. + +Building with Visual Studio +=========================== + +A more detailed outline of building GLib with its dependencies can +now be found on the GNOME wiki: + +https://wiki.gnome.org/Projects/GTK%2B/Win32/MSVCCompilationOfGTKStack + +Please do not build GLib in paths that contain spaces in them, as +this may cause problems during compilation and during usage of the +library. + +In an unpacked tarball, you will find in build\win32\vs9 (VS 2008) and +build\win32\vs10 (VS 2010) a solution file that can be used to build +the GLib DLLs and some auxiliary programs under VS 2008 and VS 2010 +(Express Edition will suffice with the needed dependencies) respectively. +Read the README.txt file in those folders for more +information. Note that you will need a libintl implementation, zlib, and +libFFI. + +If you are building from a GIT checkout, you will first need to use some +Unix-like environment or run win32/setup.py, +which will expand the VS 2008/2010 project files, the DLL resouce files and +other miscellanious files required for the build. Run win32/setup.py +as follows: + +$python win32/setup.py --perl path_to_your_perl.exe + +for more usage on this script, run +$python win32/setup.py -h/--help + +[1]: https://wiki.gnome.org/Projects/GTK%2B/Win32/MSVCCompilationOfGTKStack under "Preparations"