| 25 | | |
| 26 | | == Windows == #windows |
| 27 | | We use Windows XP for builds (other Windows versions may work too). |
| 28 | | |
| 29 | | === Microsoft Visual Studio === #vs |
| 30 | | |
| 31 | | Go to boinc/win_build. If you're using Visual Studio 2005/2008, open boinc_samples.sln. |
| 32 | | Select 'Build/Build Solution', or hit F7. |
| 33 | | That's it! |
| 34 | | |
| 35 | | There is a free version, [http://msdn2.microsoft.com/en-us/express/aa975050.aspx Visual C++ 2008 Express Edition], |
| 36 | | which works with the BOINC project file (after it is converted). |
| 37 | | You'll also need the [http://www.microsoft.com/downloads/details.aspx?FamilyId=A55B6B43-E24F-4EA3-A93E-40C0EC4F68E5&displaylang=en Microsoft Platform SDK] |
| 38 | | and some [http://msdn.microsoft.com/en-us/vstudio/aa700755.aspx changes to your Visual Studio Express] |
| 39 | | installation to include the SDK. |
| 40 | | Warning: you cannot use more recent versions of the SDK (which do not include glaux). |
| 41 | | |
| 42 | | If you use your own project file: |
| 43 | | |
| 44 | | * If your application uses graphics, go to Properties -> Linker -> Input. In Delay Loaded DLLs add |
| 45 | | {{{ |
| 46 | | GDI32.DLL;OPENGL32.DLL;GLU32.DLL |
| 47 | | }}} |
| 48 | | and in Additional Dependencies add |
| 49 | | {{{ |
| 50 | | delayimp.lib |
| 51 | | }}} |
| 52 | | * Configure your project to use ANSI strings rather than Unicode. |
| 53 | | |
| 54 | | ==== Microsoft Specific Changes ==== |
| 55 | | |
| 56 | | Recent versions of Visual Studio include changes to the C Runtime Library which throw up this error when an invalid parameter is passed to various functions: |
| 57 | | |
| 58 | | [[Image(runtimerror.png)]] |
| 59 | | |
| 60 | | To prevent this dialog from being displayed and presenting a bad user experience on the BOINC platform, please add this to your applications initialization: |
| 61 | | {{{ |
| 62 | | #if defined(_MSC_VER) && (_MSC_VER >= 1400) |
| 63 | | _set_invalid_parameter_handler(AppInvalidParameterHandler); |
| 64 | | #endif |
| 65 | | }}} |
| 66 | | |
| 67 | | Where AppInvalidParameterHandler() is defined as: |
| 68 | | {{{ |
| 69 | | #if defined(_MSC_VER) && (_MSC_VER >= 1400) |
| 70 | | void AppInvalidParameterHandler(const wchar_t* expression, const wchar_t* function, const wchar_t* file, unsigned int line, uintptr_t pReserved ) { |
| 71 | | DebugBreak(); |
| 72 | | } |
| 73 | | #endif |
| 74 | | }}} |
| 75 | | |
| 76 | | |
| 77 | | === MinGW and Dev-C++ === #devcpp |
| 78 | | |
| 79 | | If you can't or don't want to use Visual Studio to build applications, |
| 80 | | the easiest alternative is |
| 81 | | [http://www.bloodshed.net/devcpp.html Dev-C++], an open-source development environment based on the GCC compilers. |
| 82 | | Use the MinGW compile option. |
| 83 | | |
| 84 | | SETI@home uses Dev-C++ for its Windows build; |
| 85 | | you can get the project file |
| 86 | | [https://setisvn.ssl.berkeley.edu/trac/browser/seti_boinc/client/win_build/seti_boinc.dev here]. |
| 87 | | |
| 88 | | === MinGW command-line === #mingw-cli |
| 89 | | |
| 90 | | To build the BOINC library and API for Windows using [http://www.mingw.org/ MinGW] (on MSYS, Cygwin or cross-platform) compile with "make -f Makefile.mingw" while in the "lib" folder. |
| 91 | | |
| 92 | | Per default the targets ''libboinc_api.a'' ''libboinc.a'' and ''libboinc_graphics2.a'' are built. |
| 93 | | Optional targets are ''libboinc_zip.a'' (requires the boinc_zip tree), |
| 94 | | and the usual ''clean'', ''install'' and ''uninstall'' targets. |
| 95 | | |
| 96 | | The following environment variables influence the build: |
| 97 | | * CC and CXX : set to MinGW C and C++ compiler |
| 98 | | * AR and RANLIB : set to ''ar'' and ''ranlib'' of the ''target'' system when cross-compiling |
| 99 | | * BOINC_SRC : set to the root of the boinc source tree, defaults to .. (i.e. 'make -f Makefile.mingw' should work within lib/) |
| 100 | | * BOINC_PREFIX : set to destination if you want to use ''install'' and ''uninstall'' targets; defaults to /usr/local/boinc |
| 101 | | * NOCYGWIN : set to '-mno-cygwin' if you are building on Cygwin but for use on plain Windows (i.e. w/o cygwin.dll) |
| 102 | | |
| 103 | | === Cygwin === #cygwin |
| 104 | | |
| 105 | | [http://www.cygwin.com/ Cygwin] may be another alternative for building Windows apps. |
| 106 | | There are several issues: |
| 107 | | |
| 108 | | * If you build the API library directly, it will use use shared memory |
| 109 | | to communicate with the BOINC client. |
| 110 | | This won't work if you use the standard Windows client, |
| 111 | | which uses memory-mapped files rather than shared memory. |
| 112 | | * In order to run a cygwin application from BOINC, |
| 113 | | you need to supply all the cygwin DLLs that the application requires |
| 114 | | in addition to the executable. |
| 115 | | You can get LISTDLLS from http://www.sysinternals.com/. |
| 116 | | It will tell you what DLLs a running executable has loaded. |
| 117 | | * Cygwin is GPL software. |
| 118 | | If you link to the cygwin DLL, |
| 119 | | then either your application has to be GPL as well, |
| 120 | | or you will have to buy a commercial license from Red Hat. |
| 121 | | |
| 122 | | However, it can be done. |
| 123 | | Check the [https://twiki.cern.ch/twiki/bin/view/LHCAtHome/BoincPort cookbook from CERN] |
| 124 | | (search for "Instructions to Port the application to Windows"). |
| 125 | | |
| 126 | | === Symbol Stores === #symbol-stores |
| 127 | | |
| 128 | | To obtain useful stack traces in the event of an application crash, symbols are needed. |
| 129 | | Normally symbols are "stripped" from executables. |
| 130 | | Without symbols, callstacks are just a list of memory addresses. |
| 131 | | You then must load the un-stripped executable in memory using the |
| 132 | | same operating system and similar processor to jump to that memory address in order |
| 133 | | to determine the function name and parameters. |
| 134 | | This is very labor intensive. |
| 135 | | |
| 136 | | Microsoft created a technology called a 'Symbol Store' which allows Windows debuggers |
| 137 | | to locate and download compressed symbol files to diagnose problems |
| 138 | | and convert function pointers into human readable text. |
| 139 | | This greatly speeds up the process of diagnosing and fixing bugs. |
| 140 | | |
| 141 | | With the BOINC Runtime Debugger for Windows framework a project can publish their |
| 142 | | symbol files and only have to distribute the application to each of the BOINC clients. |
| 143 | | When a crash event occurs the runtime framework will download the symbol |
| 144 | | file from the symbol store and then proceed to dump as much diagnostic information |
| 145 | | as possible to help projects diagnose the failure. |
| 146 | | |
| 147 | | ==== Requirements ==== |
| 148 | | You'll need the latest stable release of the [http://www.microsoft.com/whdc/devtools/debugging/default.mspx Debugging Tools for Windows. ] |
| 149 | | |
| 150 | | Verify that your executable is setup to generate PDB debugging symbols for a release build. |
| 151 | | |
| 152 | | Verify that the advance linker option to generate a checksum is enabled for a release build. |
| 153 | | |
| 154 | | You'll need to explicitly name both your EXE and PDB before compilation since the debugger bases the name of the PDB file off of information that is stored in the executable header. |
| 155 | | |
| 156 | | ==== Project Symbol Store ==== |
| 157 | | |
| 158 | | Add a symstore element to your config.xml file for the project: |
| 159 | | |
| 160 | | {{{ |
| 161 | | <boinc> |
| 162 | | <config> |
| 163 | | <symstore>http://sample.example.com/symstore</symstore> |
| 164 | | </config> |
| 165 | | </boinc> |
| 166 | | }}} |
| 167 | | |
| 168 | | ==== Adding symbols to the symbol store ==== |
| 169 | | [http://msdn.microsoft.com/en-us/library/cc266480.aspx Symstore] is a utility to manage symbol stores. You'll want to create a local symbol store on your Windows build machine in which you'll initially add new symbol files with each revision of your application. |
| 170 | | |
| 171 | | Symstore will compress the symbol file and then copy it into your local symbol store. |
| 172 | | |
| 173 | | Below is an example command which you can run from the Windows command line or cygwin command line. |
| 174 | | |
| 175 | | {{{ |
| 176 | | symstore.exe add /l /f c:\SampleSrc\*.pdb /s c:\symstore /compress /t "Sample" /v "5.02" /o /c "Application Release" |
| 177 | | }}} |
| 178 | | |
| 179 | | ==== Uploading symbols to the symbol store ==== |
| 180 | | |
| 181 | | Most projects tend to use scp to copy files between Windows machines and their project server. |
| 182 | | |
| 183 | | The example below copies the entire symstore to the target location. After the copy operation you can delete all the subdirectories except '000Admin' to save time uploading for future application symbols. |
| 184 | | |
| 185 | | {{{ |
| 186 | | pscp.exe -r -C -batch c:\symstore sample@project.example.com:projects/sample/html/user/symstore |
| 187 | | }}} |
| 188 | | |
| 189 | | |
| 190 | | == Mac OS X == #mac |
| 191 | | |
| 192 | | Instructions for building applications on Mac OS X are on a [BuildMacApp separate page]. |
| 193 | | |
| 194 | | == Linux/x86 == #linux |
| 195 | | |
| 196 | | If you build an application on a recent Linux distribution, it won't run on older Linux distributions because of library incompatibilities. The only solution we've discovered is to build applications on a host with an old Linux and an old GCC. Setting up such a host, however, is a giant pain. |
| 197 | | |
| 198 | | Our recommended approach is not to build directly on a Linux host, but rather: |
| 199 | | |
| 200 | | * Download the [VmCompatibility Compatibility] virtual machine module. This is a Debian Linux system with the appropriate (old) version of GCC. |
| 201 | | * Run this system under Virtual PC. |
| 202 | | * Install the [SourceCodeGit stable server code] on the virtual host. |
| 203 | | * Build the BOINC libraries by going to the 'boinc' directory and typing: |
| 204 | | {{{ |
| 205 | | _autosetup |
| 206 | | ./configure --disable-client --disable-server LDFLAGS=-static-libgcc |
| 207 | | make |
| 208 | | }}} |
| 209 | | For x86-64 builds, it's possible to take SSE2 for granted, as long as GCC is version 4.0+, then type instead: |
| 210 | | {{{ |
| 211 | | _autosetup |
| 212 | | ./configure --disable-client --disable-server LDFLAGS=-static-libgcc CFLAGS=-ftree-vectorize CXXFLAGS=-ftree-vectorize FFLAGS=-ftree-vectorize |
| 213 | | make |
| 214 | | }}} |
| 215 | | |
| 216 | | Do not 'make install'. |
| 217 | | * Go to the boinc/samples/example_app directory and type: |
| 218 | | {{{ |
| 219 | | ln -s `g++ -print-file-name=libstdc++.a` |
| 220 | | make |
| 221 | | }}} |
| 222 | | |
| 223 | | == Other UNIX systems == #other-unix |
| 224 | | |
| 225 | | * [SoftwarePrereqsUnix Software prerequisites] |
| 226 | | * [BuildSystem configure/build] |
| 227 | | |
| 228 | | === GLUT notes === #glut-notes |
| 229 | | |
| 230 | | Freeglut 2.2, freeglut 2.4 and OpenGL Utility Toolkit (GLUT) libraries are supported. |
| 231 | | |
| 232 | | === X11 notes === #x11-notes |
| 233 | | |
| 234 | | To get the X11 support, select the relevant options when you're installing Linux, or (Redhat) go to System Settings/Add Software. |
