Create a MacOS X App Bundle Using MacPorts

Install MacPorts

MacPorts, formerly called DarwinPorts, is a package management system that simplifies the installation of software on the MacOS X and Darwin operating systems. It is a free/open source software project to simplify installation of other free/open source software. Similar in aim and function to Fink and the BSDs' ports collections.

An itemized overview of a MacPorts install is below.

Install XCode: This is done via the MacOS X App Store.
Follow MacPorts' installation instructions.
MacPorts has good support for Octave. A list of what MacPorts has available for Octave is here. To install the most recent version of Octave, type sudo port install octave-devel at the Terminal's command line. Octave has many dependencies which will be downloaded and installed prior to Octave. The entire installation process can take a few hours.

MacPorts has historically been rather good a maintaining their Octave portfiles. However, there are times when the maintainer fall behind. If the current version of the octave-devel port isn't current, it will be necessary to produce a local portfile. For the remainder of this page, it is assume a local portfile is being used and that the port name is octave-local.

Install an Octave Port

For the purpose of creating an App bundle using MacPorts, an Octave port must be installed. A standard MacPorts port or a local port may be used. For a local portfile it is first required that a local portfile repository be created and the local portfile placed there.

MacPorts' Octave port includes the non-GPL METIS. To avoid license violations do not bundle Metis with Octave and then distribute to others. A second motivation to use a local portfile is that the portfiles for the 3.4.x and 3.6.x series did not include all dependencies for the print feature. The missing dependencies are epstool, pstoedit, and transfig. A prototype portfile which does not depend upon METIS and does depend upon epstool, pstoedit, and transfig has been prepared.

After creating a local portfile repository an Octave portfile may be added to the local repository using the commands below.

mkdir -p ~/ports/math/octave-local
cp ~/Desktop/portfile ~/ports/math/octave-local

This assumes the Octave portfile had been placed on the users Desktop, and that the local portfile repository is located in the users home folder and named ports. After adding the portfile, the local repository must be indexed for MacPorts to recognize it.

cd ~/portfile
portindex -f

Once indexed the local Octave port may be installed.

sudo port install octave-local +accelerate+gcc45

As a precaution against unexpected problems and a bloated App bundle, using consistent variants for Octave and its dependents is suggested. For example, when using +accelarate make sure none of the dependents are using +atlas. Also, make sure no dependents are using the +universal variant. Using the +gcc45 variant is also recommended as all of Octave's dependents have a +gcc45 variant. At the very least, following these suggestions will reduce the size of the bundle. The name of Octave's dependent ports may be determined by the command below.

port deps octave-local

The installed variants for each port may be determined by the command below. Be sure to replace "portname" with the name of the port.

port installed portname

Once an Octave port is installed the command below may be used to determine / verify the version and variants of octave-local which are installed.

port installed octave-local

Create the MacOS X App Bundle

There are effectively four tasks needed to produce the App bundle. First, Octave and all its build and run-time dependencies must be extracted from the MacPorts installation. Second a App bundle template for running a shell script is required. This may be done using the MacOS X AppleScript Editor. Third, the shell script which the App bundle runs is needed. This script will be used to launch the MacOS X Terminal app. This script is referred to as the App's shell script. Finally, a script for setting up the shell environment for Octave and running Octave is required. This script is referred to as the Octave shell script.

Produce a DMG for Octave and its dependencies

MacPorts provides a feature for producing binary packages with standalone binary installers that are precompiled; they do not require MacPorts on the target system. Binary files created with MacPorts may be either .pkg (Mac OS X Installer Packages), or RPM (RPM Package Manager) format. MacPorts may also process a .pkg package into a Mac OS X .dmg disk image file. The port command shown below will create a DMG type binary installer for the Octave port and all its dependencies.

sudo port mdmg octave-local

If more than one version of Octave is installed, or if more than one variant of Octave has been installed, the version and variant should be included.

sudo port mdmg octave-local @<version>+variant1+variant2

The DMG will be placed in the port's work directory. If a local portfile is used, a symbolic link to the work directory will be placed in the directory containing the portfile. In this instance the DMG can be found in ~/ports/math/octave-local/work.

The DMG produced using the prototype portfile's does not include everything needed for Octave. Both macros.texi, octave.info, and the octave.info-# files are missing. Until the cause for these missing files is identified and resolved, they will have to be copied manually to the App bundle.

Create an Application Template for Octave

Apple Script Editor Dialog (click to enlarge)

The itemized instructions below describe how to create an application template for Ocave using the AppleScript Editor.

Run the "AppleScript Editor" and enter the script below.

# Run the octave shell script that has be bundled.
tell application "Terminal"
	# The script "launch_octave" will call the octave shell script and then close
	# this AppleScript when octave exits.
	do script quoted form of POSIX path of (path to me) & "Contents/Resources/bin/launch_octave '" & (name of me) & "'; sleep 1; exit"
end tell

Choose "Save As..." from the File menu.
- Specify the application name in the Save As: field. For this example, use "Octave-3.7.0+.app".
- The Where: field specifies the location the application template will be saved to.
- The File Format: pull down should be set to "Application".
- Of the Options, only "Stay Open" should be checked.
- Click on Save.

The launch_octave shell script runs the Octave shell script and uses AppleScript to tell the App bundle to quit when Octave exits.

The default applet.icns file which is included in the App bundle template by the AppleScript editor should be replaced by a MacOS X version of Octave's icon. This MacOS version was produced using the Icon Composer developers utility and a png with a transparent background. The Icon Composer is part of Xcode's developer's tools. Its home is /Developer/Applications/Icon Composer.app.

Populate the App Bundle

To populate the App bundle template with Octave and its dependencies, from MacPorts, follow the itemize instructions below.

Move the MacPorts Octave DMG to the Desktop. If a local portfile was used and the location of the local repository was ~/ports, the DMG will be located in ~/ports/math/octave-local/work.
Save the original MacPorts installation.

sudo mv /opt /opt-save

Install the MacPorts Octave DMG, which as placed on the MacOS X Desktop. Installing the DMG will create a new /opt directory containing Octave and all its build and run-time dependencies. To avoid conflict with the original MacPorts installation.
Place the Octave shell script in the same directory as the App bundle template created using the AppleScript Editor.
Populate the App bundle by running the script below from the directory containing the App bundle template and the Octave shell script.

#! /bin/sh
VERSION=3.7.0+
APP=Octave
FULLAPP="${APP}-${VERSION}.app"
MACPORTS_PREFIX="/opt/local/"
cp -pRf ${MACPORTS_PREFIX} ${FULLAPP}/Contents/Resources/.
rm ${FULLAPP}/Contents/Resources/lib/*.a
rm ${FULLAPP}/Contents/Resources/bin/octave
cp launch_octave ${FULLAPP}/Contents/Resources/bin/.
cp octave ${FULLAPP}/Contents/Resources/bin/.
mkdir ${FULLAPP}/Contents/Resources/Applications
cp /Applications/MacPorts/AquaTerm.app ${FULLAPP}/Contents/Resources/Applications

Restore the original MacPorts installation.

sudo rm -r /opt
sudo mv /opt-save /opt

The Octave App bundle for MacOS X is now ready to run.

Running Octave from the Terminal's Command Line

The bundled Octave may be run from a terminal command line using the command below.

/Applications/Octave-3.7.0+.app/Contents/Resources/bin/octave

To create a symbolic link in your path that runs the bundled Octave, us the command below.

ln -s /Applications/Octave-3.7.0+.app/Contents/Resources/bin/octave /usr/local/bin/octave

If the link does not work, be sure that /usr/local/bin is in your shell path. If it is not in your path, it may be added by editing ~/.profile. Just add the line below to the end of the file.

export PATH="${PATH}:/usr/local/bin"

Problems, Restrictions, and Annoyances of the App Bundle

In the past, the App bundle did not run if there were spaces in its path. A solution to this problem has been applied, but is not fully tested.
The Octave shell script used to run Octave is designed to ensure that the bundled version of AquaTerm is used by Octave. This was done because binary incompatibilities have been encountered between the bundled Gnuplot and AquaTerm applications provided by other sources. If Octave/Gnuplot appear to have a problem producing a plot using AquaTerm, verify that Aquaterm is running. If it is not, then quit and relaunch the Octave App. If an Aquaterm application is running, please verify that it is the one bundled with Octave.
Executables built by MacPorts may include features specific to the MacOS X version the executables were build on. As a result, the Octave App bundle may not run on a different version of MacOS X.
The mex and mkoctfile functions have not been tested. Although the App bundle does include a gcc toolset, some debugging is expected before this will work reliably.
When Octave is running, clicking on Octave's icon in the dock has no effect. This is because the App bundle runs a shell script which launches Terminal.app which runs Octave. To locate the Octave session, click on the Terminal.app.
Only one instance of the App may be run by clicking on the app. Multiple instances may be run from the command line.
The Octave binary may attempt to load an library whose version number is older than the one it intended to link to (at build time). This will produce an error like to one below. If this happens, please report the error.

dyld: Library not loaded: /opt/local/libiconv.2.dylib

Fixing "`dyld: Library not loaded`" Errors

If an error such as the one above is encountered, it is likely due to the Bundle looking in the original install path rather than in the App bundle for the library. This can be fixed using the developer utility install_name_tool.

To point to the correct location for the library, first determine the library's location in the App bundle. In this instance the library's path is Octave-3.7.0+.app/Contents/Resources/lib/libiconv.2.dylib. Next open a Terminal session, cd to the Resources directory and repair Octave's binary.

cd /Applications/Octave-3.7.0+.app/Contents/Resources/bin
install_name_tool -change /opt/local/libiconv.2.dylib @executable_path/../lib/libiconv.2.dylib Octave-3.7.0+

To check the binary for other occurances of this problem, type the command below.

otool -L Octave-3.7.0+

Some m-file functions has been written to automate the application of the otool utility toward making the binary executable and dynamically loadable libraries included in the App bundle relocatable. The four m-file functions to accomplish this are itemized below.

dylibs_fix.m

 -- Function File: fix_dylibs (EXEBIN, LIBDIR, DRYRUN)
     Make the executable and dynamic libraries relocatable. The inputs
     are;

    EXEBIN
          The full file name of the executable binary for the App
          bundle.  The default is `bin/Octave-3.7.0+';

    LIBDIR
          The full path to the directory containing the App bundle's
          dynamic libraries.  The default is `lib'.

    DRYRUN
          If TRUE, the `install_name_tool' commands are printed to the
          command line and are not executed (i.e. the install names and
          paths to the dependent libraries are not changed).  The
          default is TRUE.

     Using `install_name_tool' the portion of the built in dynamic
     library paths external to the App bundles are replaced with the
     token `@executable_path'.  Ths will modify the paths in both the
     EXEBIN and the the dynamic libraries and allow the application to
     be relocated with no risk that the binary executable and libraries
     are unable to locate the dynamic libraries they depend upon.

     In addition to correcting the location information for the
     dependent's of EXEBIN, the LIBDIR is searched recursively to
     locate all dynamic libraries present in the App bundle.  Both
     their install names and the locations of their dependents will
     also be fixed.

     Using the default, this script expects to find a `bin' and `lib'
     directory in the current working directory.

dylibs_find.m

 -- Function File: dylibs = dylibs_find (DIRECTORY)
     Recursively finds all dylibs in DIRECTORY, and returns a structure
     with fields `name', `location', and `dependents'.  The DIRECTORY
     defaults to the present working directory.

    `name'
          Is the name of a dynamic library.

    `location'
          Is the path to the named dynamic library.

    `dependents'
          Is a cellstr array listing the dynamic libraries the named
          library depends upon.

    `islink'
          Logical scalar indicating whether the file is a symbolic link
          to a dynamically loadable library.

dylibs_get_deps.m

 -- Function File: dylibs = dylibs_get_deps (NAME)
 -- Function File: = dylibs_get_deps (NAME, ROOT)
     Extracts the dependent libary names from the named binary, NAME.
     If ROOT is specified, the only libraries returned will have paths
     which begin with one of the cell-strings contained by ROOT.

     The defaults for ROOT are `{"/opt/local/", "/sw/", "/usr/local/",
     "@executable_path"}'.  These root paths are intended to match all
     the relocatable libraries which should be included in an App
     bundle.  The first and second entries correspond to the MacPorts
     and Fink installation directories, respectively.

dylibs_isdylib.m

 -- Function File: result = dylibs_isdylib (FILENAME)
     Determines if the filename qualifies as a dynamically loaded
     library.  The RESULT is TRUE for dylib-files, oct-files, and
     mex-files.  The result is FALSE for all other files.

     This function isn't sophisticated. It only examines the file
     extension.

To apply these scripts, change the current directory to Octave-3.7.0+.app/Contents/Resources, and enter the command below.

dylibs_fix ("bin/octave-3.7.0+", "lib", false)

The script will mirror each of the otool commands to the screen. Errors and/or warnings are given if any libraries are found to be missing in the bundle.

Reducing the Size

The App bundle is large. It's size may be significantly reduced by deleting the static libraries.

find "Octave-3.7.0+.app/Contents/Resources/lib/." -name "*.a" -exec rm -f {} \;

Testing

Those interested in testing an App bundle can try Octave-X86_64-3.7.0+v7.dmg (Dated: Jul 02, 2012 09:35 AM). The link will be periodically updated. The DMG is large (325+ MB). I kindly ask those with the patience to download it, to report results to bpabbott at mac dot com. Alternatively, if a bug is found file a bug report. When reporting on your experience, please include;

The version of MacOS X you are running.
- Note: This App bundle will not run on Mac OS 10.5 or earlier.
The Mac's processor (found under "About This Mac").
- Note: This App bundle will only run on 64 bit Intel processors (X86_64).
- If the App bundle doesn't run, it may necessary to enable 64 bit mode. See Apple's support page for instructions ⇒ OS X: Starting up with the 32-bit or 64-bit kernel;
Whether you have Fink, Homebrew, or MacPorts installed.
For intricate problems, please provide enough information so that others may duplicate it.

Testing Results

Results reported by some volunteers testing an App bundle are below. As some of the reported results are inconsistent, individuals are cautioned to not interpret these results as definitive.

An App bundle built for arch=X86_64 on an Intel Core i7 MacBook Pro running MacOS 10.7 was found to run on the following;

MacBook Pro (Intel Core i7) running MacOS 10.7 with MacPorts installed.
MacBook Pro (Intel Core i7) running MacOS 10.7 with no MacPorts, and no Fink, installed.
Macbook Pro (Intel Core-2 Duo 2.5 GHz) MacOS 10.6.8 with 64 bit support enabled, and with MacPorts installed.

To enable 64bit see Apple's support page ⇒ OS X: Starting up with the 32-bit or 64-bit kernel.

The App bundle did not run on;

MacBook (Intel Core Duo) running MacOS 10.6 with no MacPorts, and no Fink, installed. The error encountered is below.

$ cd /Applications/Octave-3.7.0+.app/Contents/Resources/bin/
$ ./octave
The application cannot be opened because it has an incorrect executable format.
./octave: line 124: /Applications/Octave-3.7.0+.app/Contents/Resources/bin/octave-3.7.0+: Bad CPU type in executable

MacMini (Intel Core 2 Duo) running MacOS 10.6 with Fink installed. The error encountered is below. Enabling 64 bit did not effect this problem. It may be possible for resolved this as the bundled AquaTerm.app functions properly.

terminate called after throwing an instance of '__gnu_cxx::__concurrence_lock_error'
what():  __gnu_cxx::__concurrence_lock_error

MacMini (Intel Core 2 Duo) running MacOS 10.6 with no Fink or MacPorts installed. The error encountered is below.

terminate called after throwing an instance of '__gnu_cxx::__concurrence_lock_error'
what():  __gnu_cxx::__concurrence_lock_error

If anyone has advice on how to resolve any of the above errors, please send an email to bpabbott at mac dot com.

TODO List

List of what can be done to improve the MacOS X App bundle.

Resolve the __gnu_cxx::__concurrence_lock_error error.
- What is the source/cause of the __gnu_cxx::__concurrence_lock_error error?
  - Made sure -pthreads is included in CPPFLAGS, CXXFLAGS, CFLAGS, FFLAGS, and LDFLAGS, and the error remains.
Test the ability to compile mex-files and oct-files.
- Necessary changes
  - Use the environment variable OCTAVE_HOME in mkoctfile to point to the bundled developer tools and libraries.
  - Same for octave_confgure-3.7.0+
  - Over-ride the built-in octave_configure_info and use an m-file version that replaces the original MacPorts prefix with the OCTAVE_HOME environment variable set by the bundle.
  - The bundled mkoctfile references the gcc4.4 libraries instead of the gcc4.5 libraries that are actually bundled. This needs to be corrected.
- With the above changes mkoctfile helloworld.cc fails with the error below. Unable to locate the source of -lgcc in in either mkoctfile, octave_configure_info, or octave-config-3.7.0+.
  - Rely on mkoctfile to setup the oct-file build environment (i.e. don't set any of it up in the .../Octave-3.7.0+.app/Contents/Resources/bin/octave script.
  - Since mkoctfile uses it, gsed needs to be added as a run time dependency in the MacPorts portfile. Check to verify that other build time dependencies are not also need.

mkoctfile -v helloworld.cc

ld: library not found for -lgcc
collect2: ld returned 1 exit status

"/Applications/Octave-3.7.0+.app/Contents/Resources/bin/g++-mp-4.5" \
-c -I"/Applications/Octave-3.7.0+.app/Contents/Resources/include/curl" \
-I"/Applications/Octave-3.7.0+.app/Contents/Resources/include/readline" -fPIC \
-I"/Applications/Octave-3.7.0+.app/Contents/Resources/include/Octave-3.7.0+/octave"/.. \
-I"/Applications/Octave-3.7.0+.app/Contents/Resources/include/Octave-3.7.0+/octave" \
-I"/Applications/Octave-3.7.0+.app/Contents/Resources/include/Octave-3.7.0+" \
-I"/Applications/Octave-3.7.0+.app/Contents/Resources/include/curl" \
-I"/Applications/Octave-3.7.0+.app/Contents/Resources/include/readline" \
helloworld.cc -o helloworld.o

"/Applications/Octave-3.7.0+.app/Contents/Resources/bin/g++-mp-4.5" -bundle -bundle_loader \
"/Applications/Octave-3.7.0+.app/Contents/Resources/bin/octave-3.7.0+" -o helloworld.oct helloworld.o \
-L"/Applications/Octave-3.7.0+.app/Contents/Resources/lib/octave/3.7.0+" \
-L"/Applications/Octave-3.7.0+.app/Contents/Resources/lib" -loctinterp -loctave -lcruft \
"/Applications/Octave-3.7.0+.app/Contents/Resources/lib/gcc45/libstdc++.6.dylib"

Should the contents of the la-files, in Octave-3.7.0+.app/Resources/lib, be changed to reflect to use the @executable_path token.
- These files are from libtool. For limited development, such as building oct-files and mex-files, are they needed at all?
Use AppleScript Editor to record the creation of the App bundle template.
- This will allow for a fully automatic build of an App bundle from a shell script.
Also use an AppleScript to record the creation of a MacOS X Octave icon.