tools/windows_packaging/README

   1 Building Ardour for Windows
   2
   3 The windows build is compiled and tested with the MinGW compiler that is
   4 packaged in Fedora, Currently using Fedora 19. There are many cross compiled
   5 "mingw" libraries that Ardour requires that are available on Fedora but
   6 not all are yet.
   7
   8
   9 Prerequisites
  10
  11 For setting up the required packages to build Ardour refer to the README
  12 file located at https://github.com/mojofunk/fedora-mingw-ardour
  13
  14
  15 Configuring
  16
  17 After all the necessary packages are installed the next step is to call
  18 one of the configure scripts configure-debug.sh or configure-release.sh.
  19
  20 The configure-debug.sh script will enable debugging support and install
  21 the tests to the package directory. It will also mean the GDB debugger
  22 is packaged.
  23
  24 The configure-release.sh is intended for releases only, none of the tests
  25 will be built and all the binaries will be optimized and stripped.
  26
  27 These scripts both source the mingw-env.sh script to setup the appropriate
  28 environment variables and then call waf with a specific set of parameters
  29 that are appropriate to configure for the windows build.
  30
  31 There is also configure-distcc-debug.sh and configure-distcc-release.sh that
  32 configure to use distcc for building.
  33
  34 Building
  35
  36 After the build is configured the waf.sh script is used to build the Ardour
  37 application and all necessary libraries. The waf.sh script is not strictly
  38 needed, it just saves having to change working directories.
  39
  40
  41 Packaging
  42
  43 When the build is successful the package.sh script will call waf install
  44 and then move some of the installed files to appropriate locations for a
  45 windows executable. This could probably be done in the waf scripts specifically
  46 for the windows build but I felt it simpler to do it in the packaging script
  47 for now.
  48
  49 --------- NOTE --------------------
  50
  51 package_win32.sh is an updated/extended version of package.sh from Valeriy. It
  52 should probably be merged with package.sh at some point. It uses a number of
  53 additional resources located under mingw64/
  54
  55 -----------------------------------
  56
  57 The packaging script then copies the JACK deamon and all the required mingw
  58 shared libraries from the host system into the packaging directory. The
  59 shared libraries or dll's are placed in the same directory as the Ardour
  60 executable so they are found at runtime.
  61
  62 Once the package.sh script has been run then the package directory located
  63 in the Ardour source root directory will contain everything necessary to run
  64 the Ardour executable.
  65
  66 The make-installer.sh script is only really relevant when configure-release.sh
  67 has been used to configure the build. The script creates a basic and little
  68 tested windows installer for Ardour using the Nullsoft Scriptable Installer
  69 System(NSIS).
  70
  71
  72 Running
  73
  74 The Ardour windows binary is intended to be run and tested on windows. Testing
  75 is mainly performed using Windows XP, but should work on Vista/7. It is only
  76 a 32bit binary at the moment but that may change with mingw64.
  77
  78 The binary does not run successfully under WINE but that may change with updates
  79 and or bug fixes.
  80
  81 When running Ardour for debugging purposes it is best to start the jack server
  82 in a separate terminal(Command Prompt) before starting Ardour so that they are
  83 not both writing to the same terminal. This will probably be fixed at some point
  84 so when jackd is started by Ardour the output is redirected etc.
  85
  86 The cptovmshare.sh script will copy the package to a directory specified in the
  87 ARDOUR_VM_SHARE_DIR for testing in a virtual machine.
  88
  89
  90 Testing
  91
  92 When configured for debugging there are a number of test programs(prefixed with
  93 test_) included in the package.
  94
  95 The tests for libpbd, libevoral and libardour can be run under wine from the
  96 windows packaging directory using the wine-*-tests.sh scripts
  97
  98 Debugging
  99
 100 Ardour has some verbose logging/debugging output that can be useful that is used
 101 with the -D option.
 102
 103 When configured for debugging the package contains gdb along with a .gdbinit
 104 file to automatically set the source directory so that the "list" gdb command
 105 will show the source code corresponding to the current stack frame.
 106
 107 New versions of gdb will not load a .gdbinit file unless it is located in the directory
 108 set in the HOME environment variable and auto-load safe-path is set appropriately.
 109
 110 So the gdbinit_home file needs to be moved to directory set in %USERPROFILE% and
 111 gdb started via gdb.bat for source file listing to work.
 112
 113 The gdb batch scripts cannot be used if the package directory is on a network share
 114 so the package will need to be copied to a local drive first.
 115
 116 When starting gdb using gdb.bat the Ardour executable needs to be set as the program
 117 to be debugged with the "file" command
 118
 119 e.g (gdb) file ardour-3.5.exe
 120
 121 You can then set a break point at main() with the "break" command as usual
 122
 123 e.g (gdb) break main
 124
 125 To set a breakpoint in a dll/shared library like libardour you need to wait for
 126 the symbols to be loaded which only occurs once the program has been executed using
 127 the "run" command
 128
 129 You can set a breakpoint at a function
 130
 131 e.g break `Somenamespace::somepartialsymbolname + tab to list symbols
 132
 133 then remove ` to set the breakpoint.
 134
 135 If you press tab with when there are thousands of possible matching symbols be
 136 prepared to wait a long time(this can also cause gdb to use a lot of memory).
 137 For this reason I prefer to set breakpoints by specifying the source file and line
 138 number.
 139
 140 e.g (gdb) break audiosource.cc:976
 141
 142 using "catch throw" or "catch catch" can be useful to break at points where exceptions
 143 are thrown or caught.
 144
 145 They are a number of glib debugging options see
 146
 147 http://developer.gnome.org/glib/2.30/glib-running.html
 148
 149 use $ set G_DEBUG=fatal_warnings to get backtrace
 150