define_external(..., LIB=libName)
connect to an external wrapper shared library
Calling Sequence
Parameters
Description
libName
-
name of external library containing the function
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 Mac 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
$JAVA/jre/bin/classic;$JAVA/jre/bin
Linux
LD_LIBRARY_PATH
$JAVA/jre/lib/amd64:$JAVA/jre/lib/amd64/server
Note for macOS: No path needs to be added for macOS. 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
examples/ExternalCalling
WRAPPER
Download Help Document