A Callable IDL application is written in another programming language, such as C or C++, and calls IDL as a subroutine. The process of creating Callable IDL applications is described in External Development.

Unlike applications written entirely in IDL, the process of creating an application distribution for a Callable IDL application is the same whether the application’s end user has an IDL development license or not. This section describes the packaging process for Callable IDL applications using any licensing mechanism.

Callable IDL applications are packaged for distribution in much the same way as native IDL applications. Before beginning the process of packaging your Callable IDL application, you should be familiar with the concepts described in Runtime Mode Applications.

This section describes the additional steps necessary to create and distribute a Callable IDL application.

To create and distribute a Callable IDL application, do the following:

  1. Review Limitations of Runtime Mode Applications.
  2. Create your application using an IDL development license. Test the application using the type of license you expect your end user to have. See the External Development for information on creating Callable IDL applications.
  3. Decide on a licensing option and obtain licenses for your application.
  4. Create an application distribution.
  5. Create invocation and use instructions for your application.
  6. Create an installer, if desired, and installation instructions for your application.

Also see Preferences for Callable IDL Applications.

Creating a Callable IDL Application Distribution

This section discusses the process of creating an application distribution that includes the files necessary to run IDL, allowing you to distribute your application to users who do not already have IDL installed.

First, see Creating an Application Distribution for information on creating an IDL application distribution. The steps you will take after creating the IDL runtime distribution depend on the platform on which your Callable IDL application will run.

Windows

Once you have created an IDL runtime distribution, you must do the following:

  1. Add your Callable IDL application executables to the bin/bin.platform subdirectory of the distribution where platform is the name of the platform for which you created the application.
  2. If your application uses preferences, edit the resource/pref/idl.pref file to contain the correct preference values.
  3. If you are using the launch script generated by the MAKE_RT procedure, modify the launcher’s .ini file to invoke your Callable IDL application rather than the idlrt.exe executable. Alternately, you can provide instructions detailing how to execute your Callable IDL executable file.

UNIX

Once you have created an IDL runtime distribution, you must do the following:

  1. Add your Callable IDL application executables to the bin.platform directory, where platform is the name of the platform for which you created the application. If you are distributing your application on multiple platforms, copy the executable for each platform to the corresponding bin.platform directory. Placing your executables in the bin.platform directory offers a couple of advantages:
    • It simplifies application startup, especially if your application is distributed for multiple platforms. The application startup script calls a script in the bin directory. This script is designed to start the correct executable, depending on the platform on which it is being executed. This allows the user to start the application on any platform by executing the startup script in the top-level directory, thereby saving the user from having to know the directory in which the executable is located.
    • It saves the user, or your installation script, from having to set the LD_LIBRARY_PATH environment variable because sharable libraries are located in the bin.platform directory.
  2. Rename the idl script. It is located in the bin directory of your distribution. For Callable IDL applications, this script must use the same name as your application executable in the bin.platform directory. For example, if your application executable in the bin.platform directory is called myapp, rename the idl script in the bin directory to myapp.
  3. Edit the startup script. In the top-level directory of your application distribution, there is a startup script with the name specified by the startcommand parameter you specified when you ran the make_rt script. Make the following changes to this script:
    • Edit the startup script to execute the script in the bin directory that you renamed in the previous step. For example, if your application executable in the bin.platform directory is called myapp, and you therefore renamed the idl script in the bin directory to myapp, you would edit the startup script in the top-level directory as follows:
      • ./bin/myapp

      Note: The above command requires the user to execute the startup script from the top-level directory of your application distribution. To allow the user to launch your application from a different directory, the user (or your installation script) could change the command to use the full path to the script in the bin directory. See the example after the following step.

    • In order to allow your application to find the correct executable (either IDL or a Callable IDL executable), the IDL_DIR environment variable must be set on the user’s machine to point to the top-level directory of your application. Because this location is not known until the user installs your application, IDL_DIR must be set by either an installation script or by the user.

      • If there are other NV5 Geospatial Solutions products installed on the user’s machine, IDL_DIR may already be set. For this reason, IDL_DIR should be set for the instance of the shell that will be used to start your application, but should not be set in the user’s login scripts such as .cshrc or .profile. This allows IDL_DIR to be set properly for your application, without conflicting with the IDL_DIR setting for other products the user may have installed.

      The most convenient way to set IDL_DIR on the user’s machine is to have your installation script (or the user) edit the startup script. This saves the user from having to manually set IDL_DIR prior to launching your application. You can either provide the user with instructions on adding the necessary commands to the startup script, or you can have your installation script modify the startup script. For example, if an application called myapp is installed in the /home/apps directory, your startup script would resemble the following:

      IDL_DIR=/home/apps
      export IDL_DIR
      /home/apps/bin/myapp

      If you do not modify the startup script, the user must set IDL_DIR at the command prompt prior to launching your application. For example, if your application is installed in the user’s /home/myapp directory, the user could execute the following command at the C shell prompt:

      setenv IDL_DIR /home/myapp
  4. If your application uses preferences, edit the resource/pref/idl.pref file to contain the correct preference values.

Starting a Callable IDL Application

You must provide your end users with instructions describing how to start your application. You may choose to provide users with the name and location of your application executable along with a launch command to execute, or (if you are using an installer for your application) with shell scripts, shortcuts, or Start menu items. The specific instructions you provide will depend on your end user’s platform.

Windows

To start a Callable IDL application if you have exported an IDL runtime distribution using the MAKE_RT procedure, change directories to the application\IDL_DIR\bin\bin.platform directory (where application is the name of the directory that contains your exported distribution, IDL_DIR is the IDL directory inside your application directory, and platform is either x86 or x86_64, depending on the verison of IDL your application relies on) and double-click on the executable file you created.

Alternately, you can use the Windows launch script.

The executable file must reside in the bin\bin.platform subdirectory of your exported application distribution. For your users’ convenience, you may want to create a Windows shortcut to the executable file in another location.

UNIX

To start a Callable IDL application if you have exported an IDL runtime distribution using the MAKE_RT procedure, change directories to the application/IDL_DIR/bin directory (where application is the name of the directory that contains your exported distribution and IDL_DIR is the IDL directory inside your application directory) and execute the renamed idl script file.

Preferences for Callable IDL Applications

IDL’s preference system allows developers, administrators, and individual users to control default values for many aspects of IDL’s environment and configuration. Creators of runtime applications can take advantage of the preference system to customize the environment in which a particular application runs.

See Preferences for Runtime Applications for a discussion of using preferences in the context of a IDL runtime application.

The process of specifying preferences for a Callable IDL application is complicated by the fact that users never launch IDL directly. This means that in order to specify preference values, you must do one of the following:

  • Modify the idl.pref file in the resource/pref subdirectory of the application distribution. This method is only useful if you are distributing an IDL distribution to support your application; do not modify an existing idl.pref file in your end user’s installed IDL distribution.
  • Instruct your users to set environment variables that correspond to the preferences you need to specify, or explicitly set the variables yourself in a startup script or batch file.