README_MAC.txt (5528B)
1 README_MAC.txt for PortMidi 2 Roger Dannenberg 3 20 nov 2009 4 revised 20 Sep 2010 for Xcode 3.2.4 and CMake 8.2-2 5 6 To build PortMidi for Mac OS X, you must install Xcode and 7 CMake. 8 9 CMake can build either command-line Makefiles or Xcode projects. 10 These approaches are described in separate sections below. 11 12 ==== CLEANING UP ==== 13 (Skip this for now, but later you might want start from a clean 14 slate.) 15 16 Start in the portmedia/portmidi directory. 17 18 make -f pm_mac/Makefile.osx clean 19 20 will remove .o, CMakeFiles, and other intermediate files. 21 22 Using "cleaner" instead of "clean" will also remove jni-related 23 intermediate files. 24 25 Using "cleanest" instead of "clean" or "cleaner" will also remove 26 application binaries and the portmidi libraries. (It will not 27 uninstall anything, however.) 28 29 ==== USING CMAKE (AND COMMAND LINE TOOLS) ==== 30 31 Start in the portmedia/portmidi directory. 32 33 make -f pm_mac/Makefile.osx 34 35 (Begin note: make will invoke cmake to build a Makefile and then make to 36 build portmidi. This extra level allows you to correctly build 37 both Release and Debug versions. Release is the default, so to get 38 the Debug version, use: 39 40 make -f pm_mac/Makefile.osx configuration=Debug 41 ) 42 43 Release version executables and libraries are now in 44 portmedia/portmidi/Release 45 46 Debug version executables and libraries are created in 47 portmedia/portmidi/Debug 48 The Debug versions are compiled with PM_CHECK_ERRORS which 49 prints an error message and aborts when an error code is returned 50 by PortMidi functions. This is useful for small command line 51 applications. Otherwise, you should check and handle error returns 52 in your program. 53 54 You can install portmidi as follows: 55 56 cd Release; sudo make install 57 58 This will install /usr/local/include/{portmidi.h, porttime.h} 59 and /usr/local/lib/{libportmidi.dylib, libportmidi_s.a, libpmjni.dylib} 60 61 You should now make the pmdefaults.app: 62 63 make -f pm_mac/Makefile.osx pmdefaults 64 65 NOTE: pmdefaults.app will be in pm_mac/Release/. 66 67 Please copy pmdefaults.app to your Applications folder or wherever 68 you would normally expect to find it. 69 70 ==== USING CMAKE TO BUILD Xcode PROJECT ==== 71 72 Before you can use Xcode, you need a portmidi.xcodeproj file. 73 CMake builds a location-dependent Xcode project, so unfortunately 74 it is not easy to provide an Xcode project that is ready to use. 75 Therefore, you should make your own. Once you have it, you can 76 use it almost like any other Xcode project, and you will not have 77 to go back to CMake. 78 79 (1) Install CMake if you do not have it already. 80 81 (2) Open portmedia/portmidi/CMakeLists.txt with CMake 82 83 (3) Use Configure and Generate buttons 84 85 (4) This creates portmedia/portmidi/portmidi.xcodeproj. 86 87 Note: You will also use pm_mac/pm_mac.xcodeproj, which 88 is not generated by CMake. 89 90 (5) Open portmidi/portmidi.xcodeproj with Xcode and 91 build what you need. The simplest thing is to build the 92 ALL_BUILD target. The default will be to build the Debug 93 version, but you may want to change this to Release. 94 95 NOTE: ALL_BUILD may report errors. Try simply building again 96 or rebuilding specific targets that fail until they build 97 without errors. There appears to be a race condition or 98 missing dependencies in the build system. 99 100 The Debug version is compiled with PM_CHECK_ERRORS, and the 101 Release version is not. PM_CHECK_ERRORS will print an error 102 message and exit your program if any error is returned from 103 a call into PortMidi. 104 105 CMake (currently) also creates MinSizRel and RelWithDebInfo 106 versions, but only because I cannot figure out how to disable 107 them. 108 109 You will probably want the application PmDefaults, which sets 110 default MIDI In and Out devices for PortMidi. You may also 111 want to build a Java application using PortMidi. Since I have 112 not figured out how to use CMake to make an OS X Java application, 113 use pm_mac/pm_mac.xcodeproj as follows: 114 115 (6) open pm_mac/pm_mac.xcodeproj 116 117 (7) pm_java/pmjni/portmidi_JportmidiApi.h is needed 118 by libpmjni.jnilib, the Java native interface library. Since 119 portmidi_JportmidiApi.h is included with PortMidi, you can skip 120 to step 8, but if you really want to rebuild everything from 121 scratch, build the JPortMidiHeaders project first, and continue 122 with step 8: 123 124 (8) If you did not build libpmjni.dylib using portmidi.xcodeproj, 125 do it now. (It depends on portmidi_JportmidiApi.h, and the 126 PmDefaults project depends on libpmjni.dylib.) 127 128 (9) Returning to pm_mac.xcodeproj, build the PmDefaults program. 129 130 (10) If you wish, copy pm_mac/build/Deployment/PmDefaults.app to 131 your applications folder. 132 133 (11) If you want to install libportmidi.dylib, first make it with 134 Xcode, then 135 sudo make -f pm_mac/Makefile.osx install 136 This command will install /usr/local/include/{porttime.h, portmidi.h} 137 and /usr/local/lib/libportmidi.dylib 138 Note that the "install" function of xcode creates portmidi/Release 139 and does not install the library to /usr/local/lib, so please use 140 the command line installer. 141 142 143 CHANGELOG 144 145 20-Sep-2010 Roger B. Dannenberg 146 Adapted to Xcode 3.2.4 147 20-Nov-2009 Roger B. Dannenberg 148 Added some install instructions 149 26-Sep-2009 Roger B. Dannenberg 150 More changes for using CMake, Makefiles, XCode 151 20-Sep-2009 Roger B. Dannenberg 152 Modifications for using CMake 153 14-Sep-2009 Roger B. Dannenberg 154 Modifications for using CMake 155 17-Jan-2007 Roger B. Dannenberg 156 Explicit instructions for Xcode 157 15-Jan-2007 Roger B. Dannenberg 158 Changed instructions because of changes to Makefile.osx 159 07-Oct-2006 Roger B. Dannenberg 160 Added directions for xcodebuild 161 29-aug-2006 Roger B. Dannenberg 162 Updated this documentation. 163