define_external(COMPILE_OPTIONS)
get and set C compiler options for generating wrappers used by define_external
Calling Sequence
Description
Examples
When the WRAPPER option is used with define_external, a C file is created, compiled and linked into Maple. This new library, called a wrapper library, contains the code necessary to translate Maple data types into data types recognized by C programs.
To compile the wrapper library a compiler must be installed and recognized by the system. In most cases, if the compiler is in the system PATH, and all associated environment variables are set, then the wrapper generation and compilation will work "out of the box". Maple is preprogrammed to use the vendor supplied C compiler to compile most wrappers on most platforms. To use a non-standard compiler, alternate version of a compiler, or custom setup, change the COMPILE_OPTIONS Record.
The COMPILE_OPTIONS argument by itself in a call to define_external returns a Record module containing default or current compile and link settings used for building the generated wrapper library. These options are globally settable by changing any of the module exports, or locally by passing the equation moduleExportName=value as an argument to define_external.
The compile and link commands are assembled by calling the COMPILE_COMMAND and LINK_COMMAND procedures defined in the COMPILE_OPTIONS Record. These procedures make use of the other definitions in the COMPILE_OPTIONS Record to formulate a command string that is executed by the ssystem command.
The COMPILE_OPTIONS available are:
NAME
TYPICAL-VALUE
EXPLANATION
COMPILER
"cc"
name of the compiler executable
CFLAGS
""
miscellaneous flags passed to the compiler
COMPILE_ONLY_FLAG
"-c"
indicates that the file is only to be compiled. The compiler will generate an object file. A separate linker command is needed to create a shared library from the object file.
COBJ_FLAG
"-o"
used by the compiler to specify the object file name. The compiler command uses COBJ_FLAG || FILE || OBJ_EXT to name the object file.
COMPILE_COMMAND
proc
the procedure that generates the compile command. This procedure must return a string that will be executed by ssystem. It is not usually necessary to change the default.
DLL_EXT
".dll" or ".so"
the shared library name extension.
EXPORT_FLAG
NULL
used in combination with the FUNCTION option to name the function to be exported from the shared library. This is unassigned or set to NULL on platforms that export all symbols by default.
FILE
generated
the base name of the file to be complied. The file extension is filled in (ie. to compile "foo.c", set FILE="foo" and FILE_EXT=".c"). When FILE is set to NULL the system generates a file name based on the function name.
FILE_EXT
".c"
the file extension.
FUNCTION
the name of the external function defined in the wrapper library. The system generates a FUNCTION name if this is left unassigned or is set to NULL.
INC_FLAG
"-I"
precedes directories in the INC_PATH.
INC_PATH
"/maple/extern/include"
specifies directories to search for header files. Use an expression sequence to specify more than one directory. For example, INC_PATH=( "/maple/extern/include", "/users/jdoe/include").
LIB
name of the library which contains the external function to call. This option must be specified in every call to define_external. Manually assigned values will be ignored.
LIBS
specifies other libraries that need to be linked with the wrapper library to resolve all external symbols. Use an expression sequence to specify more than one directory. For example, LIBS=( "/opt/compiler/libext.so", "/users/jdoe/lib/libtools.so").
LIB_FLAG
"-L"
precedes directories in the LIB_PATH.
LIB_PATH
"/maple/bin.SYS"
specifies the directories to search for libraries. Use an expression sequence to specify more than one directory. For example, LIB_PATH=( "/maple/bin.SYS", "/users/jdoe/lib").
LINKER
"ld"
specifies the name of the linker executable.
LINK_COMMAND
the procedure that generates the linker command. The procedure must return a string that will be executed by ssystem. Set this to NULL if the compile command also does the linking.
LINK_FLAGS
"-G"
specifies the miscellaneous flags passed to the linker, including those that cause the linker to build a shared library.
LOBJ_FLAG
used by the linker to specify the target library name. The linker uses cat(LOBJ_FLAG,FILE,DLL_EXT) to name the shared library.
OBJ_EXT
".o" or ".obj"
the object file extension.
SYS_LIBS
"-lc -lmaplec"
specifies the system libraries to link with the wrapper library to resolve all external symbols.
To view the generated compiler and linker commands when executing define_external, set infolevel to 3 or higher.
The following example shows how to set up the GNU compiler on a machine running Solaris. The gcc compiler requires a space between -o and the object name. Modifying the COBJ_FLAG allows this to be easily done.
p≔define_externalCOMPILE_OPTIONS:
pCOMPILER≔gcc
pCOBJ_FLAG≔-o
Subsequently a command like the following will use the new options.
define_externalmat_mult,WRAPPER,LIB=libtest.so
See Also
CustomWrapper
define_external
define_external/types
Record
SharedLibrary
WRAPPER
Download Help Document
