\documentclass[11pt]{article}
\usepackage{graphicx}

\newcommand{\puma}{{\large {\bf \lbrack 10.1.x\rbrack}}}
\newcommand{\jaguar}{{\large {\bf \lbrack 10.2.x\rbrack}}}
\title{{\Huge Octave on Mac~ OS~ X}\\ A survival guide}
\author{Per Persson}
\begin{document}

\DeclareGraphicsExtensions{.eps, .jpg}

\maketitle
\pagebreak
\tableofcontents
\pagebreak
\section{Introduction}
This document assumes that you have a working knowledge of Mac~ OS~ X, the command line interpreter (CLI) i.e. ``Terminal.app'' and a general understanding of computers. It is not a ``How-To'' in the ordinary sense, since I'm not knowlegeble enough to author such a document, but hopefully it could be the start of a good ``How-To''.  While I'm at it I might as well add the standard disclaimer: I'm not a UNIX programmer, just a Ph. D. student, and therefore I take no responsibility whatsoever for any damage (mental or physical, direct or indirect) that might be the consequnce of following any instructions in this document.

That said, let's rock!

\subsection{Prerequisits}
Check that the following criteria is met:
\begin{itemize}
  \item Mac~ OS~ X v10.1 or later. Parts of this document specific to v10.1 through 10.1.5 will be marked \puma \\ while parts specific to 10.2 (Jaguar) will be marked \jaguar
  \item Apples developer tools,\\ {\tt http://developer.apple.com/macosx/gettingstarted/}\\ corresponding to your system version. They are free of charge but you are required to register.
  \item Fink, a package manager for Mac~ OS~ X, \\ {\tt http://fink.sourceforge.net/} \\ÊNot strictly necessary but will save you a lot of time.
  \item dlcompat, a package providing dlopen family functionality on Mac~ OS~ X \\ÊInstall via fink: {\tt fink install dlcompat} \\ (For an overview of Mac~ OS~ X native dynamic loading, see \cite{overview})
  \item f2c or g77 FORTRAN compiler \\ÊInstall via fink: {\tt fink install [g77 | f2c]}
  \item tetex or texinfo for generating documentation\\ÊInstall via fink: {\tt fink install [tetex | texinfo]}
\end{itemize}  
%\flushleft N.B. As of April 2002 Apple supplies an experimental gcc 3.1 with the developer tools as an option to the default gcc 2.95.2 compiler. This document is {\em particular to gcc 2.95.2}. If you want to try gcc 3.1 {\em you are on your own}, good luck!
\flushleft N.B. \puma If you are using 10.1.x you must use the gcc 2.95.2 compiler when following the instructions, verify by typing gcc -v at the prompt.
 
%\section{Octave}
With Mac~ OS~ X being unix-based, one would expect that octave would compile out-of-the-box. It doesn't. instead, it has exposed a lot of problems with the modified gcc that Apple inherited from NeXT\cite{next} and especially C++ templates have caused problems. This situation should improve as Apple merges more code with the FSF\cite{gcc} gcc codebase.

The explicit purpose of this chapter is of course to provide information such that this chapter can be eliminated in future versions of this document! 

\section{Building octave on Mac OS X 10.1}
The following instructions refer to octave version 2.1.35 {\em exclusively}.
\subsection{Problems and fixes}\label{sect:fixes}
\subsubsection{config.\{guess, sub\}}
{\bf Configure} script doesn't recognize Mac~ OS~ X, a.k.a. Darwin-5.x.
 
\flushleft {\bf Replace} config.guess and config.sub with the ones in /usr/libexec/ by issuing the command:
{\tt \\
cp /usr/libexec/config.* .\\
cp /usr/libexec/config.* kpathsea/.\\}
N.B. This could probably be fixed upstream. % by updating the files in octave CVS.
\subsubsection{Dynamic loading}
\textbf{Mac OS X} has different kind of dynamic linking compared to e.g. Linux, octave requires dlopen() etc.

\textbf{Some clever} people has written a wrapper, called dlcompat, around the .dylib  dynamic loading. It is available under GPL from the Fink project.
\subsubsection{Preprocessor}
{\bf CPP complains} about code that is correct.

\flushleft {\bf Apple supplies} a standard CPP as well as CPP-precomp\cite{unixport} (which is default) but to compile octave (and other C++ code) the standard CPP must be used.
{Set the environment variable CPPFLAGS:
{\tt \\
setenv CPPFLAGS -no-cpp-precomp \\}
\subsubsection{Character-escapes}
In Makeconf, the line:\\ 
{\tt UGLY\_DEFS = \ldots \  -DSEPCHAR\_STR=\textbackslash \textbackslash \textbackslash":\textbackslash \textbackslash \textbackslash " \ldots }\\
must be changed to \\ %
{\tt UGLY\_DEFS = \ldots \  -DSEPCHAR\_STR=\textbackslash \textbackslash \textbackslash \textbackslash \textbackslash":\textbackslash \textbackslash \textbackslash \textbackslash \textbackslash " \ldots }\\
N.B. This could probably be fixed upstream.
\subsubsection{Compiler flags}
The following are the settings I've used for the compiler et al.:\\
\begin{description}
  \item[CXXFLAGS] \texttt{= -O2 -Wall} 
  \item[XTRA\_CXXFLAGS] \texttt{= -fno-coalesce-templates -fno-implicit-templates} \\
	\textit{this deals with the C++ template issues}
  \item[LDFLAGS] \texttt{= -Xlinker -m} \\
	\textit{this forces the linker to link with the first of any multiply-defined symbols. Multiply-defined symbols are {\bf not allowed} in Mac~ OS~ X, this is a scary work-around\ldots}\cite{overview}
  \item[SH\_LDFLAGS] \texttt{= -bundle -bundle\_loader /usr/local/bin/octave} \\
	\textit{a bundle is an aggregation of executables, headers, resources, images etc. that can be dynamically loaded}\cite{overview}
  \item[RDYNAMIC\_FLAG] = \\
	\textit{dynamic loading is default} %  and the -rdynamic flag doesn't exist
\end{description} 

% There are other peculiarites to Mac~ OS~ X such as the \texttt{-lm} directive which is not needed, since it is libm is provided through libSystem anyway. A stub is implemented for compatibility with all makefiles that have a hardcoded libm, but IMHO it is good style to remove such unnecessary code.
\subsubsection{libstdc++ bug}
This is a really nasty bug in the libstdc++ that comes with Mac~ OS~ X which manifests itself when building with -fno-coalesce-templates {\em and} -O2. The workaround is to extract all object files from libstdc++ and the explicitly link with them instead of libstdc++.

By extracting the object files using \\
\texttt{ar -x /usr/lib/libstdc++.a}\\
and creating a variable \texttt{LIBSTDC++\_OBJ} that contains a reference to all the files\\
{\tt LIBSTDC++\_OBJ := PlotFile.o filebuf.o iofscanf.o iostream.o \textbackslash \\
	pfstream.o SFile.o filedoalloc.o iofsetpos.o \textbackslash \\
	iostrerror.o procbuf.o builtinbuf.o fileops.o \textbackslash \\
	iogetc.o ioungetc.o sbform.o cleanup.o floatconv.o \textbackslash \\ 
	iogetdelim.o iovfprintf.o sbgetline.o cmathi.o \textbackslash \\
	fstream.o iogetline.o iovfscanf.o sbscan.o cstdlibi.o \textbackslash \\
	indstream.o ioignore.o isgetline.o stdexcepti.o cstringi.o \textbackslash \\
	initio.o iomanip.o isgetsb.o stdiostream.o cstrio.o \textbackslash \\
	ioassign.o iopadn.o isscan.o stlinst.o cstrmain.o ioextend.o \textbackslash \\
	iopopen.o ldcomio.o stream.o dcomio.o iofclose.o ioprims.o \textbackslash \\
	ldcomplex.o streambuf.o dcomplex.o iofeof.o ioprintf.o \textbackslash \\
	strops.o editbuf.o ioferror.o ioputc.o outfloat.o \textbackslash \\
	strstream.o osform.o fcomio.o iofgetpos.o ioseekoff.o \textbackslash \\
	parsestream.o valarray.o fcomplex.o iofread.o ioseekpos.o \textbackslash \\ peekc.o\\}
which is added to the rules for making targets \texttt{octave} and \texttt{munge-texi} the linking will work.\\	
N.B. This is where my unix weaknesses shows the most\ldots It is obvious that this could be done using some kind of wildcard, e.g.:\\
{\tt LIBSTDC++\_OBJ :=\$(wildcard tmpobj/*.o)}\\
but I can't get the dependencies right.

{\bf It is not likely that all of the above *.o files must be linked separately, but nobody has volonteered to pick a subset...}


\subsubsection{tempnam}
Mac~ OS~ X has a broken tempnam() function and it is recommended that mkstemp() is used instead. Problem is that overriding \texttt{HAVE\_TEMPNAM} with \texttt{-DHAVE\_TEMPNAM=0} at compile time doesn't help. Seems like a new implementation of octave's tmpnam() using mkstemp() is needed. 
\subsection{Installation}
Since fink has a working package that can be installed by simply typing:\\
\texttt{fink install octave} \\
or \\
\texttt{fink install octave-atlas} for octave linked with the Atlas math libraries, \\Ê
I recommend that means of installation, but by applying the fixes in section \ref{sect:fixes} a simple configure \& make should suffice.
% \subsubsection{Fink}
% \subsubsection{Manually}
\subsubsection{DejaGNU results}\label{sect:DejaGNUpuma}
Does it work? Well, according to DejaGNU we have 3 unexpected failures (residue-1.m, rename-1.m, getgrgid-1.m) which are listed below.

\texttt{[per octave-2.1.35/test] \% make check | grep FAIL \\
FAIL: octave.test/eval-catch/eval-catch-9.m \\
FAIL: octave.test/eval-catch/eval-catch-10.mÊ\\
FAIL: octave.test/poly/residue-1.m \\
FAIL: octave.test/system/rename-1.m \\
FAIL: octave.test/system/getgrgid-1.m \\
FAIL: octave.test/try/try-9.m \\
FAIL: octave.test/try/try-10.m \\
}

\subsubsection{mkoctfile}
Since mkoctfile is used to compile C++ files to .oct files that can be dynamically linked to octave, mkoctfile must also work around the bug in libstdc++. One way to do this is to set\\
\texttt{objfiles=`ls -1 /path/to/tmpobj/*.o`}.

\section{Building octave on Mac OS X 10.2}
Currently, octave knows of Mac OS X 10.2 and a statically linked version of octave will buid from CVS HEAD by doing a ./configure + make. If you need to load .oct files see section \ref{dyload}.

The following instructions refer to octave version 2.1.40 {\em exclusively}.

\subsection{Problems and fixes}\label{sect:fixes}
\subsubsection{Preprocessor}
{\bf cpp complains} about code that is correct.

\flushleft {\bf Apple supplies} a standard cpp as well as cpp-precomp\cite{unixport} (which is default) but to compile octave (and other C++ code) the standard cpp must be used.
{Set the environment variable CPPFLAGS:
{\tt \\
setenv CPPFLAGS -no-cpp-precomp \\}
\subsubsection{Dynamic loading}\label{dyload}
\textbf{Mac OS X} has different kind of dynamic linking compared to e.g. Linux, octave requires dlopen() etc.

As of version 2.1.40 octave has a native implementation of dynamic linking using the dyld API.

Dynamic loading of .oct files work, but is presently not fully supported.
Do {\em not} add {\tt --enable-dl} to the configure options load .oct files. Instead run configure and then open {\tt config.h} and change  
{\tt \\/* \#undef HAVE\_DYLD\_API */} to {\tt \#define HAVE\_DYLD\_API 1\\}
to activate the native loader. 
\subsubsection{Known bugs}
A bug in libstdc++ affects reading binary files.

\subsection{Installation}
Get the octave-2.1.40.tar.gz file from http://www.octave.org/download.html and
unpack it by issuing {\tt gnutar xzf octave-2.1.40.tar.gz}


\subsubsection{Building}\label{building}
Run configure.
Do {\em not} add {\tt --enable-dl} to the configure options load .oct files, see section \ref{dyload}. 

Now is the time to open {\tt config.h} and edit HAVE\_DYLD\_API according to section \ref{dyload}. 

Then issue the command 
{\tt \\ make} followed by {\tt \\ make install}
 

\subsubsection{DejaGNU results}\label{sect:DejaGNUjag}
Does it work? Well, according to DejaGNU we have 1 unexpected failure (binary-io-1.m) which are listed below.

\texttt{[per octave-2.1.40/test] \% make check | grep FAIL \\
FAIL: octave.test/eval-catch/eval-catch-9.m \\
FAIL: octave.test/eval-catch/eval-catch-10.mÊ\\
FAIL: octave.test/io/binary-io-1.m \\
FAIL: octave.test/try/try-9.m \\
FAIL: octave.test/try/try-10.m \\
}
\subsubsection{mkoctfile}

\section{Octave-forge}
Octave-forge\cite{forge} is a set of extensions to octave that provides lots of useful functions and a great deal of MatLab\texttrademark compatibility. 
\subsection{Considerations}
Some of the files in octave-forge assumes that you have an X11 installation, something not all Mac OS X systems have (but could easily install\cite{xonx, fink}). \\ More to come\ldots
\subsection{Installation}
Conflict with 'strip' and mkoctfile '-s' options.\\
\textbf{This is resolved by using 'strip -r -u' instead of just 'strip'.} 

X11 installed.\\
Did not install:\\
\texttt{
./extra/mex/NOINSTALL \\
./extra/NaN/NOINSTALL \\
./extra/patches/NOINSTALL \\
./extra/perl/NOINSTALL \\
./extra/tk\_octave/NOINSTALL \\
./extra/ver20/NOINSTALL \\
./extra/Windows/NOINSTALL \\
./main/audio/NOINSTALL \\
./main/sparse/NOINSTALL \\
./nonfree/gpc/NOINSTALL \\
./nonfree/splines/NOINSTALL
}

\texttt{./configure --with-path=\$HOME/Library/Octave/octave-forge --prefix=\$HOME/Library/Octave}\\
N.B. see section \ref{sect:osx} for a discussion on choice of \texttt{--path} and \texttt{--prefix}

\texttt{make}\\
\texttt{make check}, failed for:\\
\texttt{assert(c \textbackslash(c'\textbackslash [1;1]),[0;1]);\\
assert(typeinfo(c),"tri");}
%\subsubsection{Fink}
%\subsubsection{Manually}
\section{Mac~ OS~ X customization}\label{sect:osx}
\subsection{General guidelines}
The preferred location in OS X for things like octave-forge is \$HOME/Library/ rather than /usr/local/.  
If you dig around in /usr/local all day long, then by all means, install octave-forge in /usr/local. For those of you who still feel a bit uncomfortable with /usr/\ldots I recommend to create a folder named Octave in your Library folder and then add the following path to the file .octaverc (create if necessary) in your home folder:
{\tt \\
PATH=\ldots}
 
\subsection{Plotting - X11 \& AquaTerm}
Regardless of whether you are using X11 or not, you might want to install AquaTerm, and a version of gnuplot that supports it (as well as X11). See http://aquaterm.sf.net or fink.

If you use aquaterm, an augmented {\tt figure.m} exists in octave-forge, directory extra/MacOSX/plot.

\subsection{Images}
By installing {\tt convert} you can augment {\tt image.m} to have Preview.app, or any other app of your choice, display bitmaps.

\subsection{Editors}
Plugin for BBEdit, carbon emacs, Cocoa emacs, GNU Emacs

\section{Information sources}
Links, links, links

\pagebreak
\begin{thebibliography}{99}
% OK!
\bibitem{overview} \verb"http://developer.apple.com/macosx/pdf/macosx_overview.pdf"
\bibitem{next} \verb"http://www.macdevcenter.com/pub/a/mac/2002/05/03/cocoa_history_one.html"
\bibitem{gcc} \verb"http://gcc.gnu.org"
\bibitem{unixport} \verb"http://developer.apple.com/techpubs/macosx/Darwin/PortingUNIX/PortingUNIXToOSX.pdf"
\bibitem{forge} \verb"http://octave.sourceforge.net/"
\bibitem{fink} \verb"http://fink.sourceforge.net/"
\bibitem{xonx} \verb"http://xonx/"
\bibitem{aquaterm} \verb"http://aquaterm. sourceforge.net/"
\end{thebibliography}

\end{document}
\end

