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 for a detailed description of each project build property.
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.
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.
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 IDL Compile Order page of the Project Properties dialog. 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.
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 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.