Development System Information

Building

This SDK documentation is accompanied by a series of projects for compiling some example Max external objects. The details of how to build these projects are documented below in separate sections for the Mac and Windows.

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.

We recommend 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.

Build Script

We have provided a basic script that will build all of the projects in the SDK at once. This script is written using the Ruby language. A Ruby interpretter is standard on the Mac. On windows you can download and install Ruby (1.9.3 recommended) from http://rubyinstaller.org/ .

Run from Terminal.app (Mac) or "Developer Command Prompt for VS2012" (Windows) by cd'ing into the examples directory, and then running:

    ruby build.rb

Mac

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, and compatible with Xcode 4.x. Xcode is available through the Apple Mac Store.

After installing Xcode, if you wish to run the aforementioned Ruby script, you will also need to install the Command Line Tools. This is done from Xcode's preferences window in the "Download" tab.

XCode Project Setup

The example projects are set up to have Development and Deployment build configurations. The Development configuration does not optimize and ensures debugging symbols are present. The Deployment configuration creates a universal binary and performs optimization.

The files required for the projects are included in the project folders with the exception of the following two files:

  • Info.plist
  • maxmspsdk.xcconfig

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.

Linking and Frameworks

External objects use dynamic linking to access the API functions provided by the Max application. When an object is loaded, calls to functions inside the application are resolved by the operating system to the correct memory address. Due to the fact that "Max" could exist as an application, a standalone you create, or a library inside another application, an object's Xcode project does not link directly to a framework, library, or application. Instead, the list of permitted symbols is provided to the linker. This list defined in the aforementioned maxmspsdk.xcconfig file.

Audio objects will link against MaxAudioAPI.framework and Jitter objects link against JitterAPI.framework. Alternatively, you could also provide linker flags as we have provided for Max itself. 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.

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.

Windows

Max external objects for Windows are Dynamic Link Libraries (DLLs) whose filenames must end with the .mxe extension (for 32-bit builds) or .mxe64 (for 64-bit builds). 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\. External objects that use Jitter functionality will import functions from the import library "jitlib.lib" which is located in c74support\jit-includes\.

Compiling with Visual Studio

The example projects are in Visual C++ 2010/2012 format (vcxproj files). A free version of Visual C++ can be obtained from Microsoft at http://www.microsoft.com/express/. You will want to choose "Visual Studio Express for Window Desktop". Visual Studio 2012 is recommended. All projects will build for both 32-bit and 64-bit architectures using VS2012 Express.

Using Visual Studio 2010 only 32-bit versions of the objects will build unless you also install the Windows 7.1 SDK and subsequently set the projects to use that as the "Platform Toolset".

Additionally, we are providing projects in the older Visual Studio 2008 (vcproj) format. Visual Studio 2008 Express can only build 32-bit binaries. Future versions of the SDK may no longer provide this older format.

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. 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.

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.

Compiling with Cygwin

It is also possible to compile Max external objects on Windows using Cygwin. The following steps show how to build the simplemax project from the Max SDK using Cygwin's gcc (Gnu Compiler Collection). This provides access to a high quality, free C compiler using the Cygwin Unix tools for Windows.

Requirements

Install the following Cygwin packages. Feel free to add on any other Cygwin packages that strike your fancy. The Cygwin installer and more information can be found at http://www.cygwin.com/

  • Base (ALL)
  • Devel
    • binutils
    • gcc "GCC Compiler"
    • gcc-mingw "Mingw32 support headers and libraries for GCC"
    • gcc-mingw-core "Mingw32 support headers and libraries for GCC"
    • mingw-runtime

Build Steps

STEP 0: cd to the directory containing the minimum SDK example project

STEP 1:

        gcc -c -mno-cygwin -DWIN_VERSION -DWIN_EXT_VERSION -I../../c74support/max-includes simplemax.c

Description of gcc arguments:

"-c" means compile.

"-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.

"-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.

"-I../../c74support/max-includes" specifies an additional directory where the necessary headers files will be found.

"simplemax.c" is the compiler input.

STEP 2:

        gcc -shared -mno-cygwin -o simplemax.mxe simplemax.o simplemax.def -L../../c74support/max-includes -lMaxAPI

Description of gcc arguments:

"-shared" means link files to make a DLL.

"-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.

"-o simplemax.mxe" specifies the name of the output file.

"simplemax.o" and "simplemax.def" are the linker input. The .def file is necessary to ensure that the function main will be exported.

"-L../../c74support/max-includes" specifies an additional directory where library files will be found.

"-lMaxAPI" means link to the MaxAPI.lib linker library for MaxAPI.dll.

STEP 3: copy your file to a directory in your search path. For example:

        cp minimum.mxe c:\Program Files\Common Files\Cycling '74\myexterns\

Additional Notes

You can ignore the warning that main() does not return int. This message is harmless, and only relevant to applications, not shared libraries.

Additional information is available in the advanced/collect example project.

Important Project Settings

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.

Mac

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.

Windows

In the preprocessor definitions for the Visual Studio project it is important to define WIN_VERSION and EXT_WIN_VERSION to ensure that the headers are set up properly.

Platform-specificity

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.

    #ifdef MAC_VERSION
    // do something specific to the Mac
    #endif
    #ifdef WIN_VERSION
    // do something specific to Windows
    #endif

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.

Configuration

As the Max API evolves, the use of a number of older legacy functions are discouraged. Use of said functions will issue a 'deprecation' warning when you try to compile the code. To disable these deprecation warnings you can define the preprocessor symbol C74_NO_DEPRECATION in the target preprocessor section of your IDE.