The MAKE_DLL procedure builds a sharable library from C language code which is suitable for use by IDL’s dynamic linking features such as CALL_EXTERNAL, LINKIMAGE, and dynamically loadable modules (DLMs). MAKE_DLL reduces the complexity of building sharable libraries by providing a stable cross-platform method for the user to describe the desired library, and issuing the necessary operating system commands to build the library.
Although MAKE_DLL is very convenient, it is not intended for use as a general purpose compiler. Instead, MAKE_DLL is specifically targeted to solving the most common IDL dynamic linking problem: building a sharable library from C language source files that are usable by IDL. Because of this, the following requirements apply:
- You must have a C compiler installed on your system. It is easiest to use the compiler used to build IDL, because MAKE_DLL already knows how to use that compiler without any additional configuring. To determine which compiler was used, query the !MAKE_DLL system variable with a print statement such as the following:
- MAKE_DLL only compiles programs written in the C language; it does not understand Fortran, C++, or any other languages.
- MAKE_DLL provides only the functionality necessary to build C code intended to be linked with IDL. Not every possible option supported by the C compiler or system linker is addressed, only those commonly needed by IDL-related C code.
MAKE_DLL solves the most common IDL-centric problem of linking C code with IDL. To do more than this or to use a different language requires a system-specific building process (e.g. make files or projects).
For more information on using MAKE_DLL, see Additional Examples.
The IDL distribution contains an example of a simple DLM (dynamically loadable module) in the external/dlm subdirectory. This example consists of a single C source file, and the desired sharable library exports a single function called IDL_Load. The following MAKE_DLL statement builds this sharable library, leaving the resulting file in the directory given by !MAKE_DLL.COMPILE_DIRECTORY:
; Locate the source file:
INDIR = FILEPATH('', SUBDIRECTORY=['external', 'dlm'])
; Build the sharable library:
MAKE_DLL, 'testmodule', 'IDL_Load', INPUT_DIRECTORY=INDIR
MAKE_DLL, InputFiles [, OutputFile], ExportedRoutineNames [, CC=string] [, COMPILE_DIRECTORY=path] [, DLL_PATH=variable] [, EXPORTED_DATA=string] [, EXTRA_CFLAGS=string] [, EXTRA_LFLAGS=string] [, INPUT_DIRECTORY=path] [, LD=string] [, /NOCLEANUP] [, OUTPUT_DIRECTORY=path] [, /PLATFORM_EXTENSION] [, /REUSE_EXISTING] [, /SHOW_ALL_OUTPUT] [, /VERBOSE]
A string (scalar or array) giving the names of the input C program files to be compiled by MAKE_DLL. These names should not include any directory path information or the .c suffix, they are simply the base file names.
The input directory is specified using the INPUT_DIRECTORY keyword, and the .c file suffix is assumed.
The base name of the resulting sharable library. This name should not include any directory path information or the sharable library suffix, which differs between platforms (for example: .so, .a, .sl, .exe, .dll).
The output directory can be specified using the OUTPUT_DIRECTORY keyword.
If the OutputFile argument is omitted, the first name given by InputFile is used as the base name of output file.
A string (scalar or array) specifying the names of the routines to be exported (i.e., that are visible for linking) from the resulting sharable library.
If present, a template string to use in generating the C compiler commands to compile InputFiles. If CC is not specified, the value given by the !MAKE_DLL.CC system variable is used by default.
To build a sharable library, MAKE_DLL requires a place to create the necessary intermediate files and possibly the final library itself. If COMPILE_DIRECTORY is specified, the directory specified is used. If COMPILE_DIRECTORY is not specified, the directory given by the !MAKE_DLL.COMPILE_DIRECTORY system variable is used.
If present, the name of a variable to receive the complete file path for the newly created sharable library. The location of the resulting sharable library depends on the setting of the OUTPUT_DIRECTORY or COMPILE_DIRECTORY keywords as well as the !MAKE_DLL.COMPILE_DIRECTORY system variable, and different platforms use different file suffixes to indicate sharable libraries. Use of the DLL_PATH keyword makes it possible to determine the resulting file path in a simple and portable manner.
A string (scalar or array) containing the names of variables to be exported (i.e., are visible for linking) from the resulting sharable library.
If present, a string supplying extra options for the command used to execute the C compiler to compile the files given by InputFiles. This keyword is frequently used to specify header file include directories. This text is inserted in place of the %X format code in the compile string.
If present, a string supplying extra options for the command used to execute the linker when combining the object files to produce the sharable library. This keyword is frequently used to specify libraries to be included in the link, and is inserted in place of the %X format code in the linker string.
If present, the path to the directory containing the source C files listed in InputFiles. If INPUT_DIRECTORY is not specified, the directory given by COMPILE_DIRECTORY is assumed to contain the files.
If present, a template string to use when generating the linker command to generate the resulting sharable library. If LD is not specified, the value given by the !MAKE_DLL.LD system variable is used by default.
To produce a sharable library, MAKE_DLL produces several intermediate files:
- A shell script (UNIX) or batch file (Windows) that is then executed via SPAWN to build the library.
- A linker options file. This file is used to control the linker. MAKE_DLL uses it to cause the routines given by the ExportedRoutineNames argument (and EXPORTED_DATA keyword) to be exported from the resulting sharable library. The general platform terminology is shown below.
Linker Options File Terminology
export file, or linker map file
a .DEF file
- Object files, resulting from compiling the source C files given by the InputFiles argument.
- A log file that captures the output from executing the script, and which can be used for debugging in case of error.
By default, MAKE_DLL deletes all of these intermediate files once the sharable library has been successfully built. Setting the NOCLEANUP keyword prevents MAKE_DLL from removing them.
Note: Set the NOCLEANUP keyword (possibly in conjunction with VERBOSE) for troubleshooting, or to read the files for additional information on how MAKE_DLL works.
By default, MAKE_DLL creates the resulting sharable library in the compile directory specified by the COMPILE_DIRECTORY keyword or the !MAKE_DLL.COMPILE_DIRECTORY system variable. The OUTPUT_DIRECTORY keyword can be used to override this and explicitly specify where the library file should go.
Set this keyword to use a platform-specific library naming scheme. Using platform-specific library names allows IDL to select the correct library for the current platform from multiple library files residing in the same directory. See DLMs for details.
If this keyword is set, and the sharable library file specified by OutputFile already exists, MAKE_DLL returns without building the sharable library again. Use this keyword in situations where you wish to ensure that a library exists, but only want to build it if it does not. Combining the REUSE_EXISTING and DLL_PATH keywords allows you to get a path to the library in a platform independent manner, building the library only if necessary.
MAKE_DLL normally produces no output unless an error prevents successful building of the sharable library. Set SHOW_ALL_OUTPUT to see all output produced by the spawned process building the library.
If set, VERBOSE causes MAKE_DLL to issue informational messages as it carries out the task of building the sharable library. These messages include information on the intermediate files created to build the library and how they are used.
IDL is built with the standard vendor-supported C compiler in order to get maximum integration with the target system. MAKE_DLL assumes that you have the same compiler installed on your system and its defaults are targeted to use it. To use other compilers, you tell MAKE_DLL how to use them.
For example, many IDL users have the gcc compiler installed on their systems. This example (tested under 32-bit Solaris 7 using gcc 2.95.2) shows how to use gcc to build the testmodule sharable library from the previous example:
; We need the include directory for the IDL export.h header
; file. One way to get this is to extract it from the
; !MAKE_DLL system variable using the STREGEX function
INCLUDE=STREGEX(!MAKE_DLL.CC, '-I[^ ]+', /EXTRACT)
; Locate the source file
INDIR = FILEPATH('', SUBDIRECTORY=['external', 'dlm'])
; Build the sharable library, using the CC keyword to specify gcc:
MAKE_DLL, 'testmodule', 'IDL_Load', INPUT_DIRECTORY=INDIR, $
CC='gcc -c -fPIC '+ INCLUDE + '%C -o %O'
Added REUSE_EXISTING keyword
Deprecated VAX_FLOAT keyword
Added PLATFORM_EXTENSION keyword