NOTE: The native cocoa port is deprecated and unmaintained and will be removed
      when the GTK3 port is ready for prime time.


Building VICE on Mac OS X
-------------------------

This document describes how to build your own MacVICE binaries from the source
code.

1. Prerequisites

1.1 XCode

If you wan to compile VICE yourself then you first need to install Apple's
XCode Development kit. It is available on your Mac OS X Installation DVD or
can be downloaded for free (after registration) from the Apple Developer
Network (connect.apple.com). Make sure to install at least the "Universal SDK
10.4" or a newer SDK from the "Cross Development" section if you want to
create a universal binary of VICE.

The XCode IDE itself is not required, but the command line tools (compiler,
linker...) and other development files (SDKs).

1.2 Platypus

For the X11 and Gtk+ port the Platypus bundle creation tool is required.

Download it from here:

 http://www.sveinbjorn.org/platypus

This script bundler is used to embed the launcher script of VICE into an
application bundle. Additionally, Platypus supports simple drag and drop on
application start up.

If Platypus is not available then a launcher replacement is installed. This
script does not support drag and drop and quits immediately afert start up
(i.e. the VICE application icon disappears after the launch)!

1.3 Required Library Sources

VICE for Macs relies on a number of external libraries. You have to get their
source code as they are missing on a default Mac system. Some libs are
optional, i.e. if they are available then some extra features of VICE are
available.

- HID Utilities  (optional) (Joystick support)
- Gtk+ Libraries  (required only for Gtk+ port)
- Network Libraries  (optional) (Ethernet Emulation)
- FFMPEG  (optional) (Video and Sound Capture)

1.4 Building Required Libraries

First, build all external libraries. The VICE source distribution contains
build scripts to automatically perform this step.

Copy all library source archives into a single directory and call a build
script found in "build/macosx/" of the VICE source tree.

The convenience script "build-allext.sh" builds all external libs given in
section 1.3 for all supported architectures: intel (i386, x86_64) and power pc
(ppc). This is required for a universal binary build of VICE. The script takes
only a single argument: the library installation directory.

Have a look at the build scripts to find out what libraries are required for
the build.

Example:

 > mkdir extlib-src
 > mkdir extlib
 > cp <all lib source archives> extlib-src/
 > cd extlib-src
 > sh <VICE srcdir>/build/macosx/build-allext.sh ../extlib

If all went well then the libraries are compiled and installed in the "extlib"
directory. The libraries are now ready for the VICE build.


2. Building VICE

The following variables are used in the next sections:

VICE_SRC_PATH     base directory of the VICE source/SVN work directory
EXTLIB_PATH       installation directory of the external libraries
EXTLIB_SPEC       the specification of the current port
                  contains machine architecture, Mac OS X release, compiler

In the following it is assumed that the VICE source code is located in
$VICE_SRC_PATH and the external libraries are located in $EXTLIB_PATH.

2.1 Simple Cocoa Build with configure

A very simple approach to building is to use configure and make:

 > mkdir build
 > $VICE_SRC_PATH/configure --with-cocoa
 > make all bindist

This builds VICE with the cocoa port and generates application bundles for
all emulators. However, features might be missing as they rely on the external
libs. Adding these is simple:

 > export CPPFLAGS=-I$EXTLIB_PATH/$EXTLIB_SPEC/include
 > export LDFLAGS=-L$EXTLIB_PATH/$EXTLIB_SPEC/lib
 > $VICE_SRC_PATH/configure --with-cocoa
 > make all bindist

Now all features should be enabled.


2.2 Use the build script "build-vice-release.sh"

The build process for MacVICE is quite complex as it supports various ports
(X11, Gtk+, Cocoa, SDL), different architectures (i386, ppc, x86_64),
different Mac OS X versions (10.4, 10.5, 10.6) and different compilers (gcc
4.0, gcc 4.2, clang).

To facilitate the build process, a build script "build-vice-release.sh" is
shipped with the source that can perform all necessary steps to build one or
more full ports of MacVICE.

It is required for the script to use the source code checked out from SVN.
See http://sourceforge.net/projects/vice-emu/develop for more information
on how to check out the source.

Run the script with no arguments to see the help text:

 > $VICE_SRC_PATH/build/macosx/build-vice-release.sh
 
 --- build VICE release from SVN repository ---
 mode:           RELASE
 ERROR: no repository given!

   Usage:
     ./build-vice-release.sh [options] <vice-svn-repository>

     Build a VICE Release or Snapshot for a set of uis, archs, sdks, and compilers

   Options:                                                                 Default:
     -s                       do snapshot build                             [release build]
     -l                       link repository directory and use it directly [fresh svn export]
     -b                       only binaries and no source package           [with source package]
     -f                       force delete target directory if it exists    [abort if exists]
     -e <path to extlib>      set path of external library directory        [extlib]
     -o <target dir>          set target directory                          [BUILD-snapshot/release]
     -d                       build debug version                           [release]
     -i                       create distribution in directory              [create DMG]

     -u <uis>                 set default ui:       sdl x11 gtk cocoa       [cocoa]
     -a <arch>                set default arch:     i386 ppc x86_64 i386+ppc i386+x86_64 [i386+ppc]
     -k <sdk_version>         set default sdk:      10.4 10.5 10.6          [10.4]
     -c <compiler>            set default compiler: gcc40 gcc42 clang       [gcc40]
     -j <jobs>                set build jobs
                              [sdl x11 gtk cocoa cocoa-10.5 cocoa-i386+x86_64-10.6-gcc42 cocoa-i386+x86_64-10.6-clang]

     -D                       quick debug preset: -slbfdi -j cocoa-i386-10.4

You see the only required argument is the path where the vice source code
was checked out from SVN.

 > $VICE_SRC_PATH/build/macosx/build-vice-release.sh $VICE_SRC_PATH
 
If no options are given then all release binaries are built and placed in a
new sub directory called "BUILD-release".

Use -s to build a snapshot, i.e. use another target directory "BUILD-snapshot"
and tag the release with the current SVN revision.

Use -l to link in the SVN source directory. This ensures that local changes
made to the repository in the working copy are used in the build. Otherwise
the last checked-in state is used.

Use -b to skip the generation of a tarball with the source.

Use -f to first delete the target build directory if it already exists.
Otherwise the script will abort if the directory exists.

Use -e to specify the path where the external libraries (see section 1.4) are
found.

Use -o to select another target output directory. On default "BUILD-snapshot"
or "BUILD-release" is chosen.

Use -i to skip the generation of a disk image (dmg) that conains the
distribution. Only a directory with all files is created.

A port of MacVICE is specified by four parameters:

 1. The UI defines the graphical user interface.
    Available are "cocoa", "gtk", "x11", "sdl"
    
 2. The arch defines the processor architecture.
    Available are "ppc", "i386", "x86_64"

    You can choose to create a Universal Binary containing multiple
    architectures by adding them with a plus "+" sign.
    E.g. ppc+i386
    
 3. The SDK version defines the minimal Mac OS X version that is supported.
    Available are "10.4", "10.5", "10.6"

 4. The compiler that is used to compile the binary
    Available are "gcc40", "gcc42", "clang"

A port is described by giving all four parameters connected with a minus "-"
sign (the order of the parameters does not matter):

E.g. cocoa-ppc+i386-10.4-gcc40

For all four parameters the build script has built-in default values. So
you can omit parameters in a port and then the default is used.

E.g. cocoa-gcc40  -> default: arch=pcc+i386, sdk=10.4

Use the -u, -a, -k, -c options to alter the default value of a parameter.

The script uses jobs to describe what MacVICE builds should be created. You
can specify a list of ports with the -J option:

E.g.   -J "sdl x11 cocoa"   <- 3 ports, use default values for arch, sdk, compiler
       -J "cocoa-10.5"      <- use default values for arch, compiler

Please note that not all combinations of parameters are valid, e.g. 10.4 does
not support the clang compiler.


2.3 Inner Workings

This section is only relevant if you want to skip the main build script and
want to call helper scripts directly.

The build process of VICE contains the following steps: Call "configure" in
the source tree to determine the required "make" system setup and find
available libs. Then compile the source tree to get binaries of all emulators
and tools.

A release is started by creating a distribution directory. Then the emulator
binaries are embedded in the VICE application bundle. Furthermore, the tools,
external libraries and documentation is added and finally, a release disk
image (dmg) is created.

If you want to create a universal binary of VICE then the "configure" and
"make" stages are repeated multiple times: e.g. for i386 and ppc. The
resulting binaries are then united into single universal binaries. This is
also done for all external libraries.

All the necessary steps for a successful build are integrated in the build
script "build/macosx/build-vice-dist.sh". It has the following usage and must
be run from the VICE source base directory:

Usage: 

  build/macosx/build-vice-dist.sh <arch> <sdk_ver> <compiler> <ui-type> <dist-type> <extlib-dir> <build-dir> <debug>

  arch        Build architecture       i386 ppc x86_64 ubi i386+ppc i386+x86_64
  sdk-ver     Select SDK version       10.4 10.5 10.6
  compiler    Select compiler suite    gcc40 gcc42 clang
  ui-type     User Interface Type      sdl x11 gtk cocoa
  dist-type   Type of Distribution     dmg dir
  extlib-dir  External Libraries
  build-dir   Where VICE is built
  debug       Build debug version      0

arch: Choose the target architecture. Make sure the external libs are compiled
similar! (a+b=universal binary, i386=32 Bit Intel Mac, ppc=PowerPC Mac, x86_64=64 Bit Intel Mac)

sdk-ver: Choose the Mac OS X SDK

compiler: Choose the compiler

ui-type: Select the User Interface: either cocoa, SDL, X11 (x11) or Gtk+ (gtk)
based. Gtk+ requires the external Gtk+ libraries.

dist-type: Either create a disk image with the everthing embedded inside (dmg)
or create a directory with all files (dir) for direct access.

ext-lib: Where are the external libraries installed? Use same path as in
section 3.4.

build-dir: The newly created directory where all compilation takes place. The
created distribution is found inside this directory and all intermediate
files.

Example:

  > cd [VICE src dir]
  > sh build/macosx/build-vice-dist.sh i386+ppc 10.4 gcc40 x11 dmg ../extlib TEMP

This creates the TEMP directory in the VICE source tree and builds a universal
binary VICE distribution with X11 interface. The result is a *.dmg release
disk image found in the "TEMP/x11/ub/" directory.

EOF

