Project Build Concepts

Building an IDL Workbench project is the process of ensuring that all of the .pro files included in the project compile without errors. While neither of the following is required, the build process almost always does the following as well:

Ensures that all routines called by the .pro files in the project are also compiled

Creates an IDL SAVE file containing the compiled routines

While you can use the IDL Workbench build process to compile .pro code contained in a project without also compiling all required routines or creating a SAVE file, these topics assume that you will be doing both.

You can modify an IDL Workbench project's build properties on the IDL Build Properties page of the Project Properties dialog. See IDL Build Properties Page for a detailed description of each project build property.

Build Process

In its simplest form, the process of building an IDL Workbench project requires two steps:

Define project build properties via the IDL Build Properties page of the Project Properties dialog.

Select Project → Build Project.

Building in a Clean Environment

It can be useful to build a project in a "clean" IDL environment, where all data variables and compiled routines are removed from memory. Building a project in a clean environment allows you to be sure that everything your application requires is in fact being compiled into the resulting SAVE file.

You can build your project in a clean environment in two ways: by selecting either the Build in a separate IDL session or Execute .RESET_SESSION before building project property.

If you select the Build in a separate IDL session property, IDL builds the project in a separate IDL session created with the IDL_IDLBridge.

If you select the Execute .RESET_SESSION before building project property, IDL executes the .RESET_SESSION executive command before performing any compile operations.

Note
If you select the Compile Project Files property, all files in the project are recompiled before the project Run Command is executed. There is no need to also reset the session to ensure that the most current source code is compiled before the project is run.

Using the Default Build Process

A normal project build does the following things:

Restores save files from referenced projects

Executes a pre-compile IDL command

Compiles the PRO files

Executes the IDL RESOLVE_ALL command

Executes a post-compile IDL command

The IDL Build Properties page allows you to use a default build process, or use a custom build command of your own devising. If you choose the default build process, you can select all or a subset of the previous options. The following sections describe these default build options.

Restoring Save Files from Referenced Projects

It is common practice to create a SAVE file at the end of the project build process that holds the compiled PRO code. This SAVE file should contain all of the PRO code necessary to run the project application. If the project references other projects, the referenced PRO code should also be compiled and inserted in the final project SAVE file. If a referenced project has an associated SAVE file, the referenced SAVE file content can be incorporated into the SAVE file of the project being built.

Pre- and Post-Compile Build Commands

It is sometimes convenient to execute some code immediately preceeding or following a project build. For example, if you want to copy the newly-created SAVE file to another directory after the build, you could create an IDL script to do so, and execute the script after every build. The IDL Workbench gives you the option of specifying both pre- and post-compile build commands. A pre- or post-build command can be a single IDL command or an IDL script file.

Compiling all Files

Although building a project usually involves compiling the component PRO files, it is not mandatory. If you choose this option, the build process will compile all of the PRO files in the project.

See Changing the Compile Order and Excluding Files from the Build for information on changing a project's file compilation order and including or excluding files from the build.

Resolving All Referenced Routines

To explicitly force IDL to compile all routines referenced by routines in the project or referenced projects, use the RESOLVE_ALL routine or select the Execute RESOLVE_ALL build property. If the project references any other projects, the PRO files in the referenced projects are compiled first.

SAVE Files

An IDL SAVE file created by the project build process contains compiled binary versions of the routines defined in the project PRO code files. The SAVE file can then be distributed to other IDL users or to users who have installed the IDL Virtual Machine. For more information on SAVE files, see Creating SAVE Files of Programs and Data.

By default, the project build process creates an unlicensed SAVE file. Unlicensed SAVE files can be used by anyone with either a licensed version of IDL or a copy of the IDL Virtual Machine. (Applications that run in the IDL Virtual Machine are subject to some limitations; see Distributing Virtual Machine Applications for additional information.) If you have purchased a special IDL Developer's Kit license from ITT Visual Information Solutions, you can create a SAVE file that carries with it its own IDL license, avoiding the IDL Virtual Machine limitations without requiring the end user to purchase an IDL license.

Using a Custom Build Command

The IDL Workbench lets you build a project either by using the default build process, or by using a custom build command. A custom build command is an IDL routine or batch file that executes all of the commands necessary to compile the application contained in your project.

When using a custom build command, the build process is as follows:

Create a new IDL session, or execute the .RESET_SESSION command, as specified on the IDL Build Properties page.

Execute the custom build command.

If specified on the IDL Build Properties page, create a SAVE file.

The custom build command can contain any IDL commands you choose. No files are automatically compiled. See Example Custom Build Routines for examples.

Note
If the specified routine or batch file does not exist in the project directory, IDL will search the directories specified by the !PATH system variable for a matching name, and execute the first match it finds.

Generating a Build Script from the Current Build Settings

The IDL Workbench can create a build script for you that contains all of the functionality of the current build settings. You can use this script as a custom build command, or you can modify it or use pieces of it for your own purposes. For more information about this functionality, see Create Build Script in Editor.

Changing the Compile Order and Excluding Files from the Build

Although you can have any number of files physically residing in your project folder, you do not have to include all of those files in the project build. For the subset of files you do want to include, you can choose the order in which they are compiled. In certain circumstances, the file build order can determine the success or failure of the build (see Solving Build Order Problems for an example of this). See Compile Order Page for details.

Including or excluding files from the project build means flipping a build exclusion value that is attached to the file. You can do this on the Compile Order page of the Project Properties dialog (see Compile Order Page for details) or by selecting a file in the Project Explorer and in the context menu selecting Toggle Exclude from Build.

Solving Build Order Problems

Under some circumstances, the order in which PRO files are compiled during a project build can influence the success of the build. For example, suppose IDL attempts to compile a routine that includes the following line

A = xyz(1, COLOR=1)

If the user-written function XYZ has not yet been compiled, and the filename xyz.pro is not found in the IDL path (where it can be compiled automatically), IDL will report a syntax error, because xyz is interpreted as an array variable instead of a function name.

The obvious way to solve build order problems is to change the build order of the project files through the Compile Order page of the Project Properties dialog. See Compile Order Page for details. You could also create a custom build command, but if there are many dependencies between the files, or if there are many files involved, writing and maintaining the custom build command may be tedious and error-prone.

There are two other ways to solve this problem:

Use the idl2 flag for the COMPILE_OPT routine in each PRO file. This flag forces IDL to assume that array variables use the [ and ] characters (square brackets) rather than parentheses, eliminating confusion as to whether a particular line represents a function or an array variable. This approach requires that all PRO files contain the COMPILE_OPT statement, and that all PRO files use the [ and ] characters when referring to arrays. (Code written for versions of IDL prior to version 5.0 may use the ( and ) characters when referring to arrays; code using the older convention will generate compile errors if the idl2 flag to the COMPILE_OPT routine is set.)

Use the FORWARD_FUNCTION routine in a custom build command to define the names of all functions used in the application. This approach allows you to declare all of the functions first, compile the routine that launches your application, and then call RESOLVE_ALL without concern for the order in which files will be compiled.

Linked Projects

The IDL Workbench allows you to create project references that link one project to another. In practice, this means that PRO files in both the project you have selected to build and any projects referred to by that project will be compiled and included in any SAVE file that is created. See the Project References page of the Project Properties dialog for details.

Building a Project that References other Projects

To ensure that a project that references other projects is compiled correctly, set the following options on the IDL Build Properties page of the Project Properties dialog:

Create a save file

The idea behind using this option is to ensure that all the code from your referenced projects is included in the main project build. If you select this option for every referenced project, a SAVE file is created when every referenced project is built, and the contents of these SAVE files are added to the main project. In this context, the SAVE files are used as part of the internal build process.

If you select the Create a save file option for the main project as well, the resulting SAVE file contains code from both the referenced projects and the main project, and can be used to distribute that code to others.

The safest path is to select this option for the main project and all referenced projects. By doing this, the main project build will always include the code from the main project and all referenced projects.

By default, if you build a main project and all referenced projects in the same session, intermediate SAVE files are automatically created for the referenced projects, and these SAVE files are incorporated into the main project. However, if you build a project in a separate session (by selecting the Build in a separate IDL session property), you must explicitly create a project SAVE file to include the code in the main project because the special session is destroyed after the project is built.

Execute .RESET_SESSION before building project

Build in a separate IDL session

Either of these options creates a clean session, in which previously-compiled routines and previously-defined variables are removed. Creating a clean session ensures that everything your application requires is in fact being compiled and stored in the resulting SAVE file.

Note
If you select the Build in a separate IDL session property, you must also select the Create a save file property in order to include the project code in the main project.

Building Multiple Projects

The IDL Workbench build process allows you to build all projects in the current IDL Workspace at the same time. To build all of the projects:

Define the build properties of each project via the IDL Build Properties page of the Project Properties dialog.

Specify the order in which the projects should be built via the Preferences → General → Workspace → Build Order preferences page, if desired. (In most cases, controlling the order in which IDL Workbench projects are built is unnecessary.)

Select Project → Build All.