define_external(..., LIB=libName) - Maple Help

Online Help

All Products    Maple    MapleSim


Home : Support : Online Help : Programming : Calling External Routines : SharedLibrary

define_external(..., LIB=libName)

connect to an external wrapper shared library

 

Calling Sequence

Parameters

Description

Calling Sequence

define_external(..., LIB=libName)

Parameters

libName

-

name of external library containing the function

Description

• 

Before any C or Fortran function can be used with define_external, it must first be compiled into a shared library. Java functions must be compiled into .class files.

• 

A shared library is also known as a dynamic link library (DLL). Typically the .dll extension is used on Windows. One Macintosh convention uses the .dylib extension.

• 

If the sources are downloaded from the internet or purchased, a DLL may already have been built. Otherwise, consult the compiler's documentation for help on how to build a DLL.

• 

For Maple the external library functions must be compiled using the __stdcall calling convention, since this is the only convention recognized by Maple. Windows C compilers can use any one of three conventions, __cdecl, __fastcall, or __stdcall. The Microsoft Visual C/C++ compiler allows you to specify this convention globally (on all functions) with the flag /Gz. Individual functions can be declared to use this convention by inserting the word __stdcall between the return type and function name.

• 

When building the DLL, ensure that you export the function that Maple is intended to be able to call. Functions that are not exported cannot be accessed.

• 

Some compilers will export, or make public, all functions in your program. This means programs using the shared library can find all functions in order to make use of them. Other compilers need explicit decorations on the function declaration, and/or a file that lists all the functions that should be exported. The MSVC compiler can export functions in a variety of ways. Exports can be listed in a .def file. The name __declspec(dllexport) can be inserted before the return type in the functions declaration. The /export:name compiler command-line option can be used.

• 

Microsoft Visual C/C++ on Windows uses -LD (or -link -dll) to create a dll. It needs -Gz to use standard calling convention. It also uses -export:name to declare which functions are to be exported. The following MSVC command line creates test.dll.

  

cl test.c -Gz -LD -link -export:myfunc

• 

To use the MSVC command line, you need to set the %LIB% and %INCLUDE% environment variables. Running vcvars32.bat will do this for you.

• 

Using the GNU gcc C compiler on Linux, the -shared option creates a shared library. For example, the following command line creates libtest.so.

  

gcc -shared test.c -olibtest.so

• 

Fortran compilers use several different calling conventions. Fortran external call has been tested only with the GNU g77 compiler on various platforms. There are known incompatibilities with other compilers, especially when using string arguments. Try to get a simple example working before moving to a more complicated one. Test to ensure your Fortran compiler uses compatible calling conventions.

• 

To call Java functions, the path to jvm.dll needs to be added to the appropriate environment variable for your operating system. You may need to install a Java Developer's Kit (JDK) to get this dll. Typically the following directories need to be added to your PATH.

OS

Environment Variable

PATH

Windows

PATH

$JAVA/jre/bin/classic;$JAVA/jre/bin

Linux

LD_LIBRARY_PATH

$JAVA/jre/lib/amd64:$JAVA/jre/lib/amd64/server

  

Note (Mac OS X): No path needs to be added for Mac OS X. By default, it exists on all Macintosh systems.

• 

The above paths may differ depending on the version and supplier of the JDK you install. $JAVA is the base directory where the JDK was installed.

See Also

COMPILE_OPTIONS

CustomWrapper

define_external

define_external/types

WRAPPER

 


Download Help Document

Was this information helpful?



Please add your Comment (Optional)
E-mail Address (Optional)
What is ? This question helps us to combat spam