Previous Application Programming: Distributing Virtual Machine Applications Next

Distributing Your Application on a CD-ROM

You can allow your users to run your IDL Virtual Machine application directly from a CD-ROM that you create. This allows users to run your application without needing to install IDL.

This section consists of the following sub-topics:

Creating an Application Distribution

Creating an application distribution for your Virtual Machine application means bundling the appropriate parts of the IDL installation directory hierarchy, the files that make up your application, and a launch script to start your application. The following sections describe how to create the necessary hierarchy.

Create a CD-ROM Image Directory

Begin by creating a CD-ROM image directory on your hard drive. This directory will serve as the root directory of the CD-ROM you create, and will contain both the IDL Virtual Machine distribution and your application files.

Create an IDL Installation

Copy all or part of the IDL installation directory hierarchy to your CD-ROM image directory. Use the idlxx (where xx is the IDL version number) directory as the root of your IDL installation hierarchy.

If space on your CD-ROM is not an issue, you can copy the entire IDL installation directory. For example, if your CD-ROM will only be used on one platform, copying your entire IDL installation directory should be no problem. If, however, your application will run on multiple platforms, or if you want to include a large amount of data on the CD-ROM along with your application, you may want to remove parts of the IDL installation directory hierarchy.

You must copy at least the following directories and files:

  1. The contents of the bin directory and the bin.platform subdirectories for any platform you want your application to support. For example, if you want your application to run on 32-bit Linux and Macintosh systems, you would include the bin.linux.x86, bin.darwin.i386, and bin.darwin.ppc directories.
  2.  


    Note
    Depending on your application, you may be able to remove some of the DLLs and shared libraries from the bin.platform subdirectories. If you choose to remove libraries from the distribution, be sure to test your application thoroughly afterwards. Unless you absolutely need the space, it is safer to leave the contents of the bin.platform directories in place.

     

    If your application runs on Microsoft Windows as well as one or more UNIX/Macintosh platforms, you can create a hybrid bin directory that includes the Windows bin.x86 and bin.x86_64 directories alongside the UNIX/Macintosh bin.platform directories.

     

  3. Any portions of the help directory that might be used by your application. This means that if your application calls the ONLINE_HELP routine to display the IDL online help system, you must include the entire online_help directory. If your application launches an iTool and you want the iTools help to be available, include the idlithelp.xml and itools.xsd files in the help directory as well.
  4.  

  5. The lib/hook directory.
  6.  

  7. If your application uses the IDL_IDLBridge or the Export Bridge technology, the lib/bridges directory.
  8.  

  9. The resource directory. If your application does not display map data, you can delete the resource/maps directory, saving approximately 50 Mbytes.
  10.  

  11. If you wish to specify IDL preference values for your application, you can add a preferences file named idl.pref to each bin/bin.platform subdirectory you include. See Preferences for Virtual Machine Applications for additional information.

Create an Application Directory

Create a separate directory in your CD-ROM image directory to contain the files that make up your Virtual Machine application. Your application directory can have any structure required for your application.

Create Application Launch Scripts

Create scripts to launch your Virtual Machine application for each supported platform, placing them in your CD-ROM image directory. The process of creating launch scripts is described below.

Completed Application Hierarchy

Your finished CD-ROM directory hierarchy will look something like the following:

cdrom_root  
  one or more application launch scripts  
  idlxx directory  
    bin directory  
      bin.platform1 directory  
      bin.platform2 directory  
    help directory  
    lib directory  
      hook directory  
      bridges directory  
    resource directory  
  my_application directory  
    my_application.sav  
    other files?  
    application_resource directory or directories  

Once you have created the CD-ROM directory hierarchy, you should be able to launch your application from each of the launch scripts included in the CD-ROM root directory.

Launching the Application: Windows

The Distributing directory of the IDL Windows CD-ROM includes a small Windows application that you can use to launch your IDL Virtual Machine application.

To use the application launcher, do the following:

Copy and Rename the start_app_win.exe File

Copy the file

X:\Distributing\start_app_win.exe  

(where X is the drive letter of your CD-ROM drive) into your CD-ROM image directory. If you want, rename start_app_win.exe to reflect the name of your application. For example, if your application is named "HydroPlot," you could rename the start_app_win.exe file as hydroplot.exe.


Warning
If you rename start_app_win.exe, be sure to retain the .exe extension.

Copy and Rename the start_app_win.ini File

When the user loads your CD-ROM and clicks on the executable file (start_app_win.exe or whatever you have renamed it), the executable searches for and reads a .ini file with the same base name as the executable. If you renamed start_app_win.exe, you will also need to rename the .ini file with the same base name. For example, if you renamed start_app_win.exe as hydroplot.exe, you would rename start_app_win.ini as hydroplot.ini.

Copy the file

X:\Distributing\start_app_win.ini  

(where X: is the drive letter of your CD-ROM drive) into your CD-ROM image directory. Rename the .ini file to match the name of the executable file, if you have changed it from start_app_win.exe.

Modify the start_app_win.ini File

The .ini file (start_app_win.ini or whatever you have renamed it) specifies what will happen when the user runs the .exe file. You must modify this file to launch your application.

The start_app_win.exe file can either run a single application immediately or display a dialog with up to four buttons, each of which invokes a different application. The configuration of the dialog (including whether or not it is displayed at all) is controlled by the .ini file (start_app_win.ini or whatever you have renamed it).

The .ini file contains five sections, one labelled [DIALOG] and four labelled [BUTTONn] (where n is a number between 1 and 4). The contents of each type of section are described below.

DIALOG Section
[DIALOG]  
Show=False  
BackColor=&H6B1F29  
Caption=<any string>  
Picture=.\splash.bmp  
DefaultAction=<path to application>  
  • Show — this field can contain the string True or the string False. If Show=True, the dialog is displayed, and the DefaultAction is not executed. If Show=False, the dialog is not displayed, and the DefaultAction is executed immediately when the user double-clicks on the start_app_win.exe icon.
  •  

  • BackColor — this field contains an RGB color triplet specified in hexadecimal notation. This color will be used in any part of the dialog that is not covered by the image specified as the value of the Picture field. To make the background white, set BackColor=&HFFFFFF.
  •  

  • Caption — this field contains a string that will be displayed in the title bar of the dialog, if Show=True.
  •  

  • Picture — this field contains the relative path to a Windows bitmap file that will be displayed in the dialog if Show=True. The image will be positioned with its upper left corner in the upper left corner of the dialog window. To completely fill the dialog, the image contained in the bitmap file should be 480 x 335 pixels. Any area of the dialog that is not filled by the image will be displayed in the color specified in the BackColor field.
  •  

  • DefaultAction — this field contains the command that should be executed when start_app_win.exe is run if Show=False. In most cases, you will need to specify the relative path to the idlrt.exe file in the IDL distribution on your CD-ROM, followed by the -vm flag and the relative path to your application's SAVE file.
  •  

    For example, if you have placed the SAVE file for the application hydroplot.sav in the hydroplot directory of the CD-ROM along with the start_app_win.exe application, the following DefaultAction launches hydroplot.sav in the IDL Virtual Machine when the user double clicks on the start_app_win.exe icon:

    DefaultAction=.\idl64\bin\bin.x86\idlrt.exe 
    -vm=hydro\hydroplot.sav  
    

     

    (The DefaultAction specification should be on a single line.)

    BUTTON Sections

    There can be up to four [BUTTON] sections. The format is the same for any section of this type.


    Note
    If the Show field of the [DIALOG] section is set to False, no buttons will be displayed, regardless of the content of the [BUTTON] sections.

    [BUTTON1]  
    Show=True  
    Caption=<any string>  
    Action=<path to application>  
    
  • Show — this field can contain the string True or the string False. If Show=True, the button will be displayed on the dialog.
  •  

  • Caption — this field contains a string that will be displayed on the button, if Show=True.
  •  

  • Action — this field contains the command that should be executed when the user clicks on the button, if Show=True. See Default Action above for an explanation of the format of the command string.
  •  

    To create a button that simply closes the dialog without executing anything, set Action=Exit on the button.

    Copy and Modify the autorun.inf File

    If you want your application to launch automatically when the user inserts your CD-ROM, you must modify the autorun.inf file. The autorun.inf file contains the following lines:

    [autorun]  
    open = start_app_win.exe  
    icon = idl.ico  
    

    If you want your application to launch automatically when the user inserts the CD-ROM, copy the file

    X:\Distributing\autorun.inf  
    

    (where X is the drive letter of your CD-ROM drive) into your CD-ROM image directory and modify the

    open = start_app_win.exe  
    

    line to reflect the name of the executable file you want to launch automatically. For example, if you renamed start_app_win.exe to hydroplot.exe, change the line to read:

    open = hydroplot.exe  
    

    If your executable file displays a dialog, you might want to modify the

    icon = idl.ico  
    

    line to specify an icon that will be displayed in the Windows task bar. If you specify an icon file in your autorun.inf file, you must ensure that the icon file is included in the root directory of your CD-ROM.

    Launching the Application: Macintosh

    The Distributing directory of the IDL Macintosh CD-ROM includes two Applescripts that you can use to launch your IDL Virtual Machine application. To use the Applescripts to launch your application, do the following:

    Copy and Rename the Applescript Files

    Use the Finder to copy the files

    CD_ROM/Distributing/start_app_mac.app  
    CD_ROM/Distributing/Utils_applescripts.scpt  
    

    (where CD_ROM is the name of the mounted IDL CD-ROM) into your CD-ROM image directory. If you want, rename start_app_mac.app to reflect the name of your application. For example, if your application is named "HydroPlot," you could rename the start_app_mac.app file as hydroplot.app. Do not rename Utils_applescripts.scpt.


    Note
    The Applescripts are included in the Distributing directory on the UNIX CD-ROM as well as on the Macintosh CD-ROM. On a UNIX filesystem, the two files listed above are accompanied by two resource files named ._start_app_mac.app and ._Utils_applescripts.scpt. Be sure to copy these files along with the two listed above, and to rename ._start_app_mac.app if you rename its counterpart.

    Modify the start_app_mac.app File

    Use the Applescript editor, modify the value of the idlApp and idlDir variables in the start_app_mac.app file (or whatever you have renamed it) as show below:

    (*  
    Specify the path to the IDL SAVE file that launches the virutal 
    machine application, relative to the location of the script  
    *)  
    set idlApp to "my_vm_app/my_vm_app.sav" as string  
      
    (*  
    Specify the path to the top directory of the IDL distribution,   
    relative to the location of the script.  
    *)  
    set idlDir to "idl64" as string  
    

    where the IDL installation is in the directory idl64 and the Virtual Machine application is in the director my_vm_app.

    Launching the Application: UNIX

    The Distributing directory of the IDL CD-ROM includes a bourne shell script that you can use to launch your IDL Virtual Machine application. To use the script to launch your application, do the following:

    Copy and Rename the start_app_unix File

    Copy the file

    CD_ROM/Distributing/start_app_unix  
    

    (where CD_ROM is the name of the mounted IDL CD-ROM) into your CD-ROM image directory. If you want, rename start_app_unix to reflect the name of your application. For example, if your application is named "HydroPlot," you could rename the start_app_unix file as hydroplot.

    Modify the start_app_unix File

    Using a text editor, modify the value of the idlapp and IDL_DIR variables in the start_app_unix file (or whatever you have renamed it) as show below:

    # Specify the path to the IDL SAVE file that launches  
    # the Virtual Machine application, relative to $topdir.  
    idlapp=$topdir/my_vm_app/my_vm_app.sav  
      
    # Specify the path to the top directory of the IDL  
    # distribution, relative to $topdir.  
    IDL_DIR=$topdir/idl64 ; export IDL_DIR  
    

    where the IDL installation is in the directory idl64 and the Virtual Machine application is in the director my_vm_app.

    Installing Your Application

    The application hierarchy you create on your CD-ROM can be copied directly to your end-user's computer. As long as the launch scripts are located within the copied application hierarchy, your application should function just as if the user were launching it from your CD-ROM.


    Note
    Copying your installation hierarchy onto the user's hard disk does not "install" IDL in the usual sense. No file associations are created or symbolic links are created.

    Installation Issues: Windows

    When you install IDL for Windows, the installation program ensures that all Microsoft Windows system libraries required by IDL are installed. If you are distributing a Virtual Machine application that runs from a CD-ROM or from an application hierarchy copied from your CD-ROM, it is possible (although somewhat unlikely) that the required system libraries will not be present on your end-user's computer.

    If your application does not run correctly from the CD-ROM on your user's machine, the missing system libraries may be the problem. The Distributing directory of the IDL CD-ROM includes two small installation programs that ensure the required system libraries are present. You are free to distribute these to your own users. Instruct your users to run the appropriate system library installer if they have problems:

      IDL Online Help (March 06, 2007)