README.w32

   1 README for compiling and installing gAlan on Win32 (Win9X and WinNT systems)
   2 ============================================================================
   3 Tony Garnock-Jones, 3 September 1999
   4
   5 IMPORTANT NOTE: The Win32 port is based on the development versions of
   6 glib, gdk and gtk+. This means that it must be considered
   7 UNSTABLE. Any stability you observe is sure to be an exception rather
   8 than the rule :-) If this bothers you, I'm sure anything you can
   9 contribute to the job of porting GTK+ to Win32 will be appreciated -
  10 the mailing-list details are on Tor Lillqvist's GTK+/Win32 page, URLs
  11 given below.
  12
  13 The file TODO.w32 contains some notes on current problems with the Win32
  14 build.
  15
  16 Section 1. Ingredients
  17 Section 2. Method
  18 Section 3. What needs changing in libaudiofile
  19
  20 ============================================================================
  21 SECTION 1. INGREDIENTS
  22
  23 You will need:
  24 * a recent egcs/gcc for mingw32 - no earlier than egcs 1.1.2
  25 * the port of GNU make to Win32 - 3.77 works nicely
  26 * recent glib-dev and gtk+-dev packages - no earlier than 19990726
  27 * a recent extralibs-dev package - no earlier than 19990726, I assume
  28 * Michael Pruett's audiofile - version 0.1.7 works fine
  29
  30 I have had success with gcc 2.95 (mingw32) from Mumit Khan (thanks for
  31 a wonderful tool, Mumit!), GNU make 3.77 ported to Win32 by JanJaap
  32 van der Heijden, and Tor Lillqvist's pioneering effort to port GTK+ to
  33 Win32.
  34
  35 The files I downloaded from Tor's page were:
  36 - glib-dev-19990726.zip
  37 - gtk+-dev-19990726.zip
  38 - extralibs-dev-19990828.zip, although I daresay 19990726 would have worked,
  39   too.
  40
  41 Mumit Khan's gcc is available by following links from his gcc/egcs webpage at
  42
  43         http://www.xraylith.wisc.edu/~khan/software/gnu-win32/index.html
  44
  45 I believe there is also a link from there to a copy of GNU make for
  46 Win32. I got mine elsewhere, and can't remember where that elsewhere
  47 was :-(
  48
  49 Tor Lillqvist's port of GTK+ to Win32 is available from these URLs
  50 (the bottom two are mirrors of the top one):
  51
  52         http://www.iki.fi/tml/gimp/win32/       (Finland)
  53         http://user.sgic.fi/~tml/gimp/win32/    (Finland)
  54         http://www.gimp.org/~tml/gimp/win32/    (USA)
  55
  56 You can find Michael Pruett's audiofile library from this site:
  57
  58         http://www.68k.org/~michael/audiofile
  59
  60 Note that I used version 0.1.7 - newer versions may well work, but
  61 you might find yourself needing to edit the files Makefile.libaudiofile
  62 and config.h.libaudiofile in this distribution to match any changes
  63 made in newer versions of audiofile.
  64
  65 ============================================================================
  66 SECTION 2. METHOD
  67
  68 0. I'm going to use the following directories (and the Makefile.w32 as
  69 shipped is set to use them too):
  70
  71 c:\gcc                          for mingw32 gcc
  72 c:\devel\galan-X.Y.Z            for the gAlan distribution
  73 c:\devel\gtk                    to unpack glib/gtk+ into
  74 c:\devel\gtk\src\...            where glib/gtk+ end up
  75 c:\devel\audiofile-0.1.7        for the audiofile distribution
  76
  77 Once you've got a binary, you'll need some of the .DLLs from glib/gtk+
  78 and the .DLL for libaudiofile to actually run gAlan, and you will need
  79 to copy them into the install directory by hand. (Note that the
  80 Makefile tries to do the right thing, but if it doesn't match your
  81 setup, it will break and you will have to copy the DLLs by hand.) The
  82 DLLs you will need:
  83
  84         gdk-1.3.dll             gmodule-1.3.dll
  85         glib-1.3.dll            gthread-1.3.dll
  86         gtk-1.3.dll             gnu-intl.dll
  87         libaudiofile.dll
  88
  89 If you have already installed an earlier version of gAlan, I recommend
  90 deleting it (and probably its preferences file) before installing the
  91 newer version.
  92
  93 1. Install gcc as per INSTALL.TXT. The steps I took were:
  94         a. > mkdir c:\gcc
  95         b. > cd c:\gcc
  96         c. > unzip gcc-2.95-mingw32.zip
  97         d. Added the following two lines to my autoexec.bat:
  98
  99                 SET GCC_EXEC_PREFIX=c:\gcc\lib\gcc-lib\
 100                 PATH=C:\GCC\BIN;%PATH%
 101
 102            Note the lowercase for GCC_EXEC_PREFIX! It seems to be important.
 103         e. Rebooted (sigh)
 104
 105 2. You might like to test gcc with a small C program, such as 'hello
 106 world'.  Once you're satisfied that gcc works ok, you need to install
 107 glib/gtk+ and audiofile.  I chose to install to my development
 108 directory, c:\devel, but you could choose anywhere else.
 109
 110         > cd c:\devel
 111         > mkdir gtk
 112         > cd gtk
 113         > unzip glib-dev-19990726.zip
 114         > unzip gtk+-dev-19990726.zip
 115         > unzip extralibs-dev-19990828.zip
 116
 117 Note that these zip files put all their contents in a directory called
 118 'src'.
 119
 120 For libaudiofile, I chose to untar the distribution into c:\devel as
 121 well - this created a directory c:\devel\audiofile-0.1.7 for me, with
 122 the subdirectory 'libaudiofile' containing the sources to the library
 123 itself.
 124
 125 3. Now we get to the interesting bit. Unpack the contents of your
 126 gAlan source-code tarball into c:\devel. You will get a directory
 127 called galan-X.Y.Z (with the version number filled in
 128 appropriately). Once this is done, we configure gAlan.
 129
 130 (NOTE: if you're using WinZip to decompress the tar/gz file, make sure
 131 that "TAR File Smart CR/LF Conversion" is switched *OFF* in the
 132 Options/Configuration dialog box. Otherwise, the example files
 133 included will not decompress properly.)
 134
 135         > make -f makefile.w32 setup
 136         Edit config.h appropriately
 137         Edit Makefile.w32 appropriately
 138
 139 There is probably very little that needs to be done to
 140 config.h. Makefile.w32, on the other hand, may require extensive
 141 alteration:
 142
 143 * set DEST_DIR to the directory you want the binary and support files
 144 to be installed into. You'll have to backslashify the directory
 145 separators, as in
 146
 147         DEST_DIR = C:\\PROGRA~1\\gAlan
 148
 149 Don't use forward-slashes to separate directory components here - this
 150 variable is used by the install target to copy files, and the plain
 151 old DOS 'copy' command doesn't understand forward-slash as a directory
 152 separator.
 153
 154 (Note that as distributed, gAlan does not put any files in C:\WINDOWS
 155 or C:\WINDOWS\SYSTEM - it tries to keep itself to itself by only
 156 installing into DEST_DIR.)
 157
 158 * set DEST_DIR_C to an extra-escaped version of DEST_DIR. You can
 159 either quadruple-escape backslashes, like this
 160
 161         DEST_DIR_C = \"C:\\\\PROGRA~1\\\\gAlan\"
 162
 163 or use forward-slashes here, since the only place this variable is
 164 used is as a #define for the C code:
 165
 166         DEST_DIR_C = \"C:/PROGRA~1/gAlan\"
 167
 168 You need to put \"...\" around the contents of DEST_DIR_C, though -
 169 this is to make it appear as a string to the C code.
 170
 171 * set GTK_BASE_DIR to the directory you unpacked the
 172 "*-dev-1999????.zip" files into. If you didn't follow the instructions
 173 above (fair enough), you will need to alter the definitions of
 174 INCLUDES and LIBDIRS too.
 175
 176 * set LIBAUDIOFILE_DIR to the directory containing the *source files*
 177 for the audiofile library. On my system, that's
 178 c:\devel\audiofile-0.1.7\libaudiofile.
 179
 180 * check to make sure that the versions of glib, gmodule, gdk and gtk+
 181 are correctly accounted for in the LIBS definition.
 182
 183 4. Configuration done - try a compile!
 184
 185         > cd c:\devel\galan-X.Y.Z
 186         > make -f makefile.w32
 187
 188 If compiling libaudiofile fails, you'll probably have to edit the
 189 files Makefile.libaudiofile and config.h.libaudiofile included in the
 190 gAlan distribution to kludge it together.
 191
 192 Note that as of version 0.1.7, libaudiofile has a slight limitation
 193 that stops it working for writing audio files on Win32 (although
 194 reading works fine). You'll have to edit one of the files from
 195 audiofile-0.1.7 - see section 3 at the bottom of this file for
 196 details.
 197
 198 You might get an error about "Out of environment space". In this case,
 199 try changing the allocated environment space to something like
 200 4096. You can find the environment setting in the properties tab of
 201 the command prompt, under 'Memory'.
 202
 203 You might also get cpp.exe complaining that it has too many
 204 command-line options. This is (probably?) caused by too long a
 205 command-line... you might have to put some of the EXTRA_DEFS into
 206 config.h, and maybe consolidate some of the include directories
 207 etc. in order to shorten it.
 208
 209 You can ignore warnings from dllwrap saying:
 210         Warning: no export definition file provided
 211         dllwrap will create one, but may not be what you want
 212
 213 - in this case, it *is* what we want.
 214
 215 Other than that, if it doesn't work, fix it :-) and try again. It's
 216 changing too rapidly for me to even attempt working through 'common'
 217 problems here yet.
 218
 219 5. Once it compiles, you can install it.
 220
 221         > make -f makefile.w32 install
 222
 223 or, if you don't want debug information (more than quadruples the
 224 .exe/.dll file size, usually),
 225
 226         > make -f makefile.w32 install-strip
 227
 228 You will now need to hunt through your unpacked glib/gtk+ directories
 229 for the .DLL files mentioned above, in step 0. (Note that
 230 libaudiofile.dll should be sitting in the directory named in the
 231 makefile as $(LIBAUDIOFILE_DIR).) Copy them into the same directory
 232 that galan.exe ends up in after the install. If you unpacked all the
 233 glib/gtk+ archives into a single directory, and that directory is
 234 named by GTK_BASE_DIR, then you can use
 235
 236         > make -f makefile.w32 install-dll
 237
 238 or
 239
 240         > make -f makefile.w32 install-dll-strip
 241
 242 to install the program and DLLs together. (This does the right thing
 243 with regard to both glib/gtk+ and libaudiofile.) Otherwise use the
 244 'install' target as above, and copy the DLLs by hand.
 245
 246 ============================================================================
 247 SECTION 3. WHAT NEEDS CHANGING IN LIBAUDIOFILE
 248
 249 Libaudiofile 0.1.7, as shipped, needs changing to work with
 250 Win32. Newer versions may have addressed the problem.
 251
 252 libaudiofile/audiofile.c, function afOpenFile: there is a piece of
 253 code that looks like this:
 254
 255         if (!strcmp(mode, "w"))
 256                 return _afOpenFileWrite(filename, mode, setup);
 257
 258 It needs changing to read
 259
 260         if (strchr(mode, 'w'))
 261                 return _afOpenFileWrite(filename, mode, setup);
 262
 263 This is because clients on Win32 need to specify "wb" as the write
 264 mode (and "rb" as the read mode), because Microsoft in their infinite
 265 wisdom continue to leave the default fopen() mode set to *TEXT* unless
 266 you specify binary with the extra "b" flag. This is braindead
 267 behaviour, which makes life difficult when moving code back and forth
 268 between Win32 and other, less idiosyncratic systems.
 269
 270 I've emailed Michael Pruett with details of this - with any luck,
 271 libaudiofile will fix this problem in a later release.