Max 5 API Reference
00001 /** 00002 @page chapter_platform Development System Information 00003 00004 00005 @section chapter_platform_building Building 00006 00007 This SDK documentation is accompanied by a series of projects for compiling some example Max external objects. 00008 The details of how to build these projects are documented below in separate sections for the @ref chapter_platform_mac and @ref chapter_platform_win. 00009 00010 When you build the example projects, the resulting Max external will be located in a folder called "sdk-build" two folder-levels up from the project. If you leave the arrangement of folders intact, sdk-build will be found in the MaxSDK folder. 00011 00012 We recommende that you add the sdk-build folder to your Max search path using the File Preferences window. This permits you to put the MaxSDK folder wherever you like and load the objects in Max after building them without copying them to your Cycling '74 folder. 00013 00014 00015 @section chapter_platform_mac Mac 00016 00017 Max external objects for the Mac are Mach-O bundles (folders that appear to be files) whose filenames must end with the .mxo extension. The example projects are in Xcode 3.x format. To download Xcode, you need to open a free Apple Developer account. For more information, visit http://developer.apple.com/ 00018 00019 @subsection chapter_platform_mac_xcodeproj XCode Project Setup 00020 00021 The example projects are set up to have Development and Deployment build configurations. The Development configuration does not optimize and builds only for the target platform you are using (i.e., PPC on a PPC machine, Intel on an Intel machine). The Deployment configuration creates a universal binary and performs optimization. 00022 00023 The files required for this projects are included in the project folders with the except of the following two files: 00024 - Info.plist 00025 - maxmspsdk.xcconfig 00026 00027 These two files are located one folder-level up from the project folder, and are required for the Xcode project to build the Max external. 00028 00029 00030 @subsection chapter_platform_mac_linking Linking and Frameworks 00031 00032 External objects use dynamic linking to access the API functions provided by the Max application. When an objects is loaded, calls to functions inside the application are resolved by the operating system to the correct memory address. Each external object Xcode project must reference MaxAPI.framework in order to link with the application. Frameworks are libraries that define the functions in the Max API. Due to the fact that "Max" could exist as an application, a standalone you create, or a library inside another application, the MaxAPI.framework does not actually contain the code to implement the functions of the Max API for external objects. It serves instead to isolate external objects from the specific library or application implementation that contains the real code. 00033 00034 Audio objects will link against MaxAudioAPI.framework and Jitter objects link against JitterAPI.framework. Unlike MaxAPI.framework, these frameworks are real libraries. The most recent version of all frameworks will be found inside the application you are using (they are found inside the application bundle in Contents/Frameworks). In addition, there are versions inside the c74support folder provided with the SDK. These will be used only to link your objects; they are never actually executed. 00035 00036 Xcode uses something called the Frameworks Search Path to locate frameworks when linking. The example SDK projects use a frameworks search path with a c74support folder two levels up from your the folder containing your Xcode project. If you rearrange the SDK folders, projects may not find the frameworks and will fail to link properly. Furthermore, even though we specify the frameworks search path, Xcode seems to look in /Library/Frameworks first. If you have installed a version of the Max SDK for version 4.6 or ealier, you may have older versions of MaxAPI.framework and MaxAudioAPI.framework in /Library/Frameworks. When you try to link objects that contain references to functions only defined in the newest MaxAPI.framework, the link may fail because the projects are using the old frameworks. To fix this, you'll need to remove the Max frameworks from /Library/Frameworks. If you want to develop objects for both the Max 4.6 and Max 5 SDKs on the same machine, you'll need to modify your 4.6 projects to specify a Frameworks Search Path, and relocate the 4.6 frameworks to the specified location. 00037 00038 @section chapter_platform_win Windows 00039 00040 Max external objects for Windows are Dynamic Link Libraries (DLLs) whose filenames must end with the .mxe extension. These DLLs will export a single function called "main" which is called by max when the external object is first loaded. Generally these DLLs will import functions of the Max API from the import library "MaxAPI.lib" which is located in the c74support\\max-includes\ folder. External objects that use audio functionality will import functions from the import library "MaxAudio.lib" which is located in c74support\\msp-includes\. 00041 00042 The example projects are in Visual C++ 2008 format. A free version of Visual C++ can be obtained from Microsoft at http://www.microsoft.com/express/. 00043 The projects are set up to have both a Debug and a Release configuration. The Release configuration is optimized whereas the Debug one is not. 00044 Note that for debugging purposes you can exercise your object in the Max Runtime since the copy protection for the Max Application will interfere when run under the debugger. 00045 00046 Another thing to note is that Max has a private build of the Microsoft C Runtime Library. By linking with this version of the C runtime library you won't have to worry about deployment issues due to dependencies your external may have on Microsoft's C Runtime. When you include "ext.h" from the max API it will include ext_prefix.h which for the release build will automatically cause your project to use the max C runtime library. If you prefer to use the Microsoft C Runtime you can do that by defining the C preprocessor macro MAXAPI_USE_MSCRT before including ext.h. 00047 00048 00049 @subsection chapter_platform_win_cygwin Compiling with Cygwin 00050 00051 It is also possible to compile Max external objects on Windows using Cygwin. 00052 The following steps show how to build the simplemax project from the MaxMSP SDK using Cygwin's gcc (Gnu Compiler Collection). 00053 This provides access to a high quality, free C compiler using the Cygwin Unix tools for Windows. 00054 00055 00056 @subsubsection chapter_platform_win_cygwin_requirements Requirements 00057 00058 Install the following Cygwin packages. 00059 Feel free to add on any other Cygwin packages that strike your fancy. 00060 The Cygwin installer and more information can be found at http://www.cygwin.com/ 00061 00062 - Base (ALL) 00063 - Devel 00064 - binutils 00065 - gcc "GCC Compiler" 00066 - gcc-mingw "Mingw32 support headers and libraries for GCC" 00067 - gcc-mingw-core "Mingw32 support headers and libraries for GCC" 00068 - mingw-runtime 00069 00070 00071 @subsubsection chapter_platform_win_cygwin_steps Build Steps 00072 00073 STEP 0: cd to the directory containing the minimum SDK example project 00074 00075 STEP 1: 00076 @code 00077 gcc -c -mno-cygwin -DWIN_VERSION -DWIN_EXT_VERSION -I../../c74support/max-includes simplemax.c 00078 @endcode 00079 00080 Description of gcc arguments: 00081 00082 "-c" means compile. 00083 00084 "-mnocygwin" means use the Microsoft standard C libraries, instead of Cygwin standard C libraries. 00085 This step is important if you wish to distribute your extern to people that might not have Cygwin installed. 00086 00087 "-DWIN_VERSION" and "-DWIN_EXT_VERSION" define these preprocessor definitions on the command line to guarantee that the header files and source code know it is being compiled for a Windows machine, instead of Macintosh. 00088 00089 "-I../../c74support/max-includes" specifies an additional directory where the necessary headers files will be found. 00090 00091 "simplemax.c" is the compiler input. 00092 00093 00094 STEP 2: 00095 @code 00096 gcc -shared -mno-cygwin -o simplemax.mxe simplemax.o simplemax.def -L../../c74support/max-includes -lMaxAPI 00097 @endcode 00098 00099 Description of gcc arguments: 00100 00101 "-shared" means link files to make a DLL. 00102 00103 "-mnocygwin" means use the Microsoft standard C libraries, instead of Cygwin standard C libraries. This step is important if you wish to distribute your extern to people that might not have Cygwin installed. 00104 00105 "-o simplemax.mxe" specifies the name of the output file. 00106 00107 "simplemax.o" and "simplemax.def" are the linker input. The .def file is necessary to ensure that the function main will be exported. 00108 00109 "-L../../c74support/max-includes" specifies an additional directory where library files will be found. 00110 00111 "-lMaxAPI" means link to the MaxAPI.lib linker library for MaxAPI.dll. 00112 00113 00114 STEP 3: copy your file to a directory in your search path. For example: 00115 @code 00116 cp minimum.mxe c:\Program Files\Common Files\Cycling '74\myexterns\ 00117 @endcode 00118 00119 00120 @subsubsection chapter_platform_win_cygwin_notes Additional Notes 00121 00122 You can ignore the warning that main() does not return int. 00123 This message is harmless, and only relevant to applications, not shared libraries. 00124 00125 00126 00127 00128 00129 @section chapter_platform_settings Important Project Settings 00130 00131 The easiest way to create a new external is to choose one of the existing SDK examples, duplicate it, and then change only the settings that need to be changes (such as the name of the project). This will help to guarantee that important project settings are correct. Project settings of particular importance are noted below. 00132 00133 @subsection chapter_platform_settings_mac Mac 00134 00135 Particularly important for Max externals on the Mac are that the Info.plist is correct set up and that the "Force Package Info Generation" is set to true. Without these your object may fail to load on some machines. 00136 00137 @subsection chapter_platform_settings_win Windows 00138 00139 In the preprocessor definitions for the Visual Studio project it is important to define WIN_VERSION and EXT_WIN_VERSION to ensure that the 00140 headers are set up properly. 00141 00142 00143 00144 @section chapter_platform_specificity Platform-specificity 00145 00146 If you are writing a cross-platform object and you need to do something that is specific to one platform, the Max API headers provide some predefined symbols you can use. 00147 00148 @code 00149 #ifdef MAC_VERSION 00150 // do something specific to the Mac 00151 #endif 00152 #ifdef WIN_VERSION 00153 // do something specific to Windows 00154 #endif 00155 @endcode 00156 00157 Another reason for conditional compilation is to handle endianness on the Mac platform. If you are still supporting PowerPC, you may have situations where the ordering of bytes within a 16- or 32-bit word is important. ext_byteorder.h provides cross-platform tools for manipulating memory in an endian-independent way. 00158 00159 00160 00161 */
Copyright © 2008, Cycling '74