MathLink Development in C (Unix and Linux)

Supported Development Platforms

Installing the MathLink Components

Recommended Installation

CompilerAdditions Installation

MathLinkExamples Installation

Components of the MathLink Developer's Kit

CompilerAdditions Directory

mathlink.h

libML32i3.a/libML64i4.a

libML32i3.so/libML64i3.a/(.sl on HPUX)

mprep

mcc

MathLinkExamples Directory

PrebuiltExamples Folder

Building MathLink Programs

Using MathLink Template Files

mprep  addtwo.tm  -o addtwotm.c

addtwotm.c  :  addtwo.tm
    mprep  addtwo.tm  -o addtwotm.c

Building MathLink programs

make addtwo

Using a Makefile

# This makefile can be used to build all or some of the sample
# programs. To build all of them, use the command
# 'make all'. To build one, say addtwo, use the command
# 'make addtwo'.

MLINKDIR = /usr/local/Wolfram/Mathematica/6.0/SystemFiles/Links/MathLink/DeveloperKit
SYS = Linux  # Set this value with the result of evaluating $SystemID
CADDSDIR = ${MLINKDIR}/${SYS}/CompilerAdditions

INCDIR = ${CADDSDIR}
LIBDIR = ${CADDSDIR}

EXTRALIBS = -lm -lpthread -lrt # Set these with appropriate libs for your system.
MLLIB = ML32i3 # Set this to ML64i3 if using a 64-bit system

MPREP = ${CADDSDIR}/mprep

all : addtwo bitops counter factor factor2 factor3 quotient reverse sumalist

addtwo : addtwotm.o addtwo.o
    ${CC} -I${INCDIR} addtwotm.o addtwo.o -L${LIBDIR} -l${MLLIB} ${EXTRALIBS} -o $@

bitops : bitopstm.o bitops.o
    ${CC} -I${INCDIR} bitopstm.o bitops.o -L${LIBDIR} -l${MLLIB} ${EXTRALIBS} -o $@

counter : countertm.o
    ${CC} -I${INCDIR} countertm.o -L${LIBDIR} -l${MLLIB} ${EXTRALIBS} -o $@

factor : factor.o
    ${CC} -I${INCDIR} factor.o -L${LIBDIR} -l${MLLIB} ${EXTRALIBS} -o $@

factor2 : factor2.o
    ${CC} -I${INCDIR} factor2.o -L${LIBDIR} -l${MLLIB} ${EXTRALIBS} -o $@

factor3 : factor3.o
    ${CC} -I${INCDIR} factor3.o -L${LIBDIR} -l${MLLIB} ${EXTRALIBS} -o $@

quotient : quotient.o
    ${CC} -I${INCDIR} quotient.o -L${LIBDIR} -l${MLLIB} ${EXTRALIBS} -o $@

reverse : reversetm.o
    ${CC} -I${INCDIR} reversetm.o -L${LIBDIR} -l${MLLIB} ${EXTRALIBS} -o $@

sumalist : sumalisttm.o sumalist.o
    ${CC} -I${INCDIR} sumalisttm.o sumalist.o -L${LIBDIR} -l${MLLIB} ${EXTRALIBS} -o $@

.c.o :
    ${CC} -c -I${INCDIR} $<

addtwotm.c : addtwo.tm
    ${MPREP} $? -o $@

bitopstm.c : bitops.tm
    ${MPREP} $? -o $@

countertm.c : counter.tm
    ${MPREP} $? -o $@

reversetm.c : reverse.tm
    ${MPREP} $? -o $@

sumalisttm.c : sumalist.tm
    ${MPREP} $? -o $@

Use the following table to determine the extra libraries needed for linking MathLink programs on your system.

Using mcc

mcc addtwo.tm addtwo.c -o addtwo

Running MathLink Programs

Running a Prebuilt Example from the Mathematica Kernel

:Begin:
:Function:       addtwo
:Pattern:        AddTwo[i_Integer, j_Integer]
:Arguments:      { i, j }
:ArgumentTypes:  { Integer, Integer }
:ReturnType:     Integer
:End:

:Evaluate: AddTwo::usage = "AddTwo[x, y] gives the sum of two machine integers x and y."

int addtwo( int i, int j)
{
    return i+j;
}

int main(int argc; char* argv[])
{
    return MLMain(argc, argv);
}

Edit the path string and evaluate the following two cells.

To see a list of the newly available functions, evaluate this cell.

This displays the usage message for the AddTwo[] function as defined in the file "addtwo.tm".

Now try it.

See what happens if the sum of the two machine integers will not fit in a machine integer or if either argument is not a machine integer. (2^31-1 is the largest machine integer. If your compiler uses 2-byte integers, the 2^15-1 is the largest C int.)

The "addtwo" program is not prepared for big integers:

This does not match AddTwo[_Integer, _Integer]:

Install[] called LinkOpen[] and then exchanged information with the external program to set up the definition for AddTwo[]. You really do not have to worry about these details, but if you are curious, evaluate the following.

When you are finished using the external program, evaluate the following.

Invoking the Mathematica Kernel from Within a Prebuilt Example

factor -linkmode launch -linkname 'math -mathlink'

Integer to factor:

Integer to factor: 123456789
3 ^ 2
3607 ^ 1
3803 ^ 1

Supported Link Protocols

Troubleshooting

• Turn off compiler optimization until your program is working. This makes compiling faster, debugging easier, and, besides, the optimizer may be broken and the cause of some problems. (Optimized code uses the stack and registers differently than unoptimized code in such a way that may expose or mask a bug in your code. For example, the common mistake of returning a pointer to a local variable may or may not cause a problem depending on stack and register use.)

• Check the return values from the MathLink library functions or call MLError() at key points in your program. MathLink will often be able to tell you what has gone wrong.

• The files "mathlink.h", "libML32i3.a", and "libML32i3.so" (libML64i3.* on 64-bit platforms) are a matched set. If you have used an earlier release of MathLink, you should take care that you do not mix components when building your application.

• Check whether the C compiler you are using supports prototypes. If it does not, you will need to change your code and the way you build your project. This is explained in the section "Building MathLink Programs".

MORE ABOUT

• MathLink C Language Functions

• MathLink Connection Management

• MathLink C Functions for Exchanging Data

• MathLink C Functions for Exchanging Expressions

• MathLink C Functions for Exchanging Integers

• MathLink C Functions for Exchanging Multidimensional Arrays

• MathLink C Functions for Exchanging Reals

• MathLink C Functions for Exchanging Strings

• MathLink C Functions for Exchanging Symbols

• MathLink Expression Packet Handling

• MathLink Packets

• Alphabetical Listing of MathLink C Functions

RELATED TUTORIALS

• MathLink C API Developer Guide (Mac OS X)

• MathLink C API Developer Guide (Windows)