README_MAC.txt for PortMidi
Roger Dannenberg
20 nov 2009
revised 20 Sep 2010 for Xcode 3.2.4 and CMake 8.2-2

To build PortMidi for Mac OS X, you must install Xcode and
CMake.

CMake can build either command-line Makefiles or Xcode projects.
These approaches are described in separate sections below.

==== CLEANING UP ====
(Skip this for now, but later you might want start from a clean
slate.)

Start in the portmedia/portmidi directory.

make -f pm_mac/Makefile.osx clean

will remove .o, CMakeFiles, and other intermediate files.

Using "cleaner" instead of "clean" will also remove jni-related 
intermediate files.

Using "cleanest" instead of "clean" or "cleaner" will also remove
application binaries and the portmidi libraries. (It will not 
uninstall anything, however.)

==== USING CMAKE (AND COMMAND LINE TOOLS) ====

Start in the portmedia/portmidi directory.

make -f pm_mac/Makefile.osx

(Begin note: make will invoke cmake to build a Makefile and then make to
build portmidi. This extra level allows you to correctly build 
both Release and Debug versions. Release is the default, so to get
the Debug version, use:

make -f pm_mac/Makefile.osx configuration=Debug
)

Release version executables and libraries are now in
    portmedia/portmidi/Release

Debug version executables and libraries are created in
    portmedia/portmidi/Debug
The Debug versions are compiled with PM_CHECK_ERRORS which
prints an error message and aborts when an error code is returned
by PortMidi functions. This is useful for small command line 
applications. Otherwise, you should check and handle error returns
in your program.

You can install portmidi as follows:

cd Release; sudo make install

This will install /usr/local/include/{portmidi.h, porttime.h}
and /usr/local/lib/{libportmidi.dylib, libportmidi_s.a, libpmjni.dylib}

You should now make the pmdefaults.app:

make -f pm_mac/Makefile.osx pmdefaults

NOTE: pmdefaults.app will be in pm_mac/Release/. 

Please copy pmdefaults.app to your Applications folder or wherever 
you would normally expect to find it.

==== USING CMAKE TO BUILD Xcode PROJECT ====

Before you can use Xcode, you need a portmidi.xcodeproj file.
CMake builds a location-dependent Xcode project, so unfortunately
it is not easy to provide an Xcode project that is ready to use.
Therefore, you should make your own. Once you have it, you can
use it almost like any other Xcode project, and you will not have
to go back to CMake.

(1) Install CMake if you do not have it already.

(2) Open portmedia/portmidi/CMakeLists.txt with CMake

(3) Use Configure and Generate buttons

(4) This creates portmedia/portmidi/portmidi.xcodeproj.

Note: You will also use pm_mac/pm_mac.xcodeproj, which
is not generated by CMake.

(5) Open portmidi/portmidi.xcodeproj with Xcode and 
build what you need. The simplest thing is to build the
ALL_BUILD target. The default will be to build the Debug
version, but you may want to change this to Release. 

NOTE: ALL_BUILD may report errors. Try simply building again
or rebuilding specific targets that fail until they build
without errors. There appears to be a race condition or
missing dependencies in the build system.

The Debug version is compiled with PM_CHECK_ERRORS, and the
Release version is not. PM_CHECK_ERRORS will print an error
message and exit your program if any error is returned from
a call into PortMidi.

CMake (currently) also creates MinSizRel and RelWithDebInfo
versions, but only because I cannot figure out how to disable
them.

You will probably want the application PmDefaults, which sets
default MIDI In and Out devices for PortMidi. You may also
want to build a Java application using PortMidi. Since I have
not figured out how to use CMake to make an OS X Java application,
use pm_mac/pm_mac.xcodeproj as follows:

(6) open pm_mac/pm_mac.xcodeproj

(7) pm_java/pmjni/portmidi_JportmidiApi.h is needed
by libpmjni.jnilib, the Java native interface library. Since
portmidi_JportmidiApi.h is included with PortMidi, you can skip
to step 8, but if you really want to rebuild everything from 
scratch, build the JPortMidiHeaders project first, and continue
with step 8:

(8) If you did not build libpmjni.dylib using portmidi.xcodeproj,
do it now. (It depends on portmidi_JportmidiApi.h, and the 
PmDefaults project depends on libpmjni.dylib.)

(9) Returning to pm_mac.xcodeproj, build the PmDefaults program.

(10) If you wish, copy pm_mac/build/Deployment/PmDefaults.app to
your applications folder.

(11) If you want to install libportmidi.dylib, first make it with 
Xcode, then
    sudo make -f pm_mac/Makefile.osx install
This command will install /usr/local/include/{porttime.h, portmidi.h} 
and /usr/local/lib/libportmidi.dylib
Note that the "install" function of xcode creates portmidi/Release
and does not install the library to /usr/local/lib, so please use
the command line installer.


CHANGELOG

20-Sep-2010 Roger B. Dannenberg
    Adapted to Xcode 3.2.4
20-Nov-2009 Roger B. Dannenberg
    Added some install instructions
26-Sep-2009 Roger B. Dannenberg
    More changes for using CMake, Makefiles, XCode
20-Sep-2009 Roger B. Dannenberg
    Modifications for using CMake
14-Sep-2009 Roger B. Dannenberg
    Modifications for using CMake
17-Jan-2007 Roger B. Dannenberg
    Explicit instructions for Xcode
15-Jan-2007 Roger B. Dannenberg
    Changed instructions because of changes to Makefile.osx
07-Oct-2006 Roger B. Dannenberg
    Added directions for xcodebuild
29-aug-2006 Roger B. Dannenberg
    Updated this documentation.