Tips on Creating New IDL Projects in the IDL 7.0 Workbench

Topic
This Help Article is designed for IDL programmers seeking advice on how to organize new IDL Projects in their file system to optimize compatibility with the Eclipse-based IDL 7.0 Workbench. It is most specifically for IDL programmers, who are not sure what file system structure might provide the best view and access to the various files that make up their applications. The guidelines proposed in this article may not be optimal for all IDL applications, but, for solo programmers who have never thought through their own system for structuring projects, these guidelines will always provide an easy-to-maintain and easy-to-share result.

This Help Article is focused on IDL Projects that are built from scratch in the new IDL 7.0 Workbench. If you are interested in how you might import existing projects from earlier versions of IDL into the new Workbench, you might want to start your reading in Help Article #4307 ("Tips on Importing pre-7.0 IDL Projects into the New IDL 7.0 Workbench").

Discussion
There are really two kinds of Projects one might store in the IDL Workbench. The most prevalent is probably the "Project For Easy Viewing". Programmers create this kind of project just to have a picture of their personal IDL source code directories sitting right in their IDL Workbench next to their Command Line and their Editor. The second type is "Application Projects", projects that are organized for building into '.sav' programs. These look the same in the Project Explorer View window, but differ in their specifications for Project Properties. The discussion below provides sensible guidelines for how to set up both types of projects and a workaround or two for the first release (version 7.0) of the IDL Workbench.

Our first tips are valid for both types of projects:

Projects are first created with the Workbench's 'File->New->IDL Project' menu button.

TIP #1: Store all new source code and all new application root directories in your IDL Workbench "workspace" directory. If you are using the default workspace created when IDL 7.0 first started, this will be a directory named "IDLWorkspace" in your login's home directory.

TIP #2: Let the IDL Workbench make your new project directory for you.

'File->New->IDL Project' is the Workbench menu button to use. To be consistent with Tip #1 always use the Location option 'Create the new project in the workspace'. Now whatever name you enter in that dialog will not only create a folder in the Workbench's Project Explorer view, but in your file system's 'IDLWorkspace' directory as well. Whatever you move around with your mouse in the Project Explorer window will simultaneously be moved around in your file system as well.

TIP #3: Give your project an all lower-case name with no blank spaces in the name. Use underscores instead of blank spaces, if you want to separate words. This makes your Project more easily portable to UNIX-type operating systems, should you be sharing it with others in the future. If you are making a project for a '.sav' program (an "Application Project") use as your project name the name of the applications's "main" '.pro' (which should also be all lower-case for portability's sake).

At this point our recommendations for what to do differ depending on whether you are creating a "Project For Easy Viewing" or an "Application Project".

PROJECTS FOR EASY VIEWING

TIP #4: You do not need to put all IDL routines in an IDL Project! As long as your '.pro' is in the IDL Search Path set in your IDL preferences, it will be found whether or not it is in a Workbench Project. Having that code in a Project has two advantages: a) it has maximum easy access for viewing, and b) it can be included in Workbench 'Search' actions. The only disadvantage of putting all your code in IDL Projects is that your Project Explorer may eventually become overpopulated. (Thus, you may think twice before you create an IDL Project out of NASA's IDL library 'astrolib'.) Note that the Workbench has a special menu button for non-Project '.pro's: 'File->Save to External Location ...'

Below is a screen shot of how we recommend you set IDL Project Properties for "Projects For Easy Viewing." You access this dialog by right-clicking on the project folder in the Project Explorer view, selecting 'Properties' from the context menu and going to the 'IDL Project Properties' page. In this screenshot the 'Update IDL path preference when project is opened or closed' is unchecked because this project's directory is already in the IDL Search Path defined in the user's preferences.

Recommended Properties for 'Projects For Easy Viewing'

TIP #5: (for Projects For Easy Viewing) Notice above how all the build options that can be turned off ARE turned off. A Project For Easy Viewing should never be built; make sure a '.sav' file is not created in the event that you should accidentally hit the 'Project->Build' button.

That is it for our tips on 'Projects For Easy Viewing.' If you are not building IDL '.sav' programs, then you can probably stop your reading right here.

APPLICATION PROJECTS

'Application Projects' are IDL projects that are typically designed to be built into '.sav' executable programs, so our recommendations for these kinds of projects differ dramatically from our recommendations for 'Projects For Easy Viewing.' The first tip we give on this subject is quite optional.

TIP #6: If your '.sav' program consists of more than just '.pro' files, put the files associated with your project into a lower layer of project subdirectories. Subdirectories can be quickly made in the Workbench by right-clicking on the project "application root directory" node and selecting 'New->Folder' from the context menu. The folders you create in the Project Explorer in the workbench will be duplicated in the 'IDL Workspace' file system hierarchy. The most common first-level subdirectory names we recommend are:

1. "source"
   For all your '.pro's

2. "bin"
   Put the '.sav' you compile for this project in here along with any other this-project-specific '.sav's on which it depends. To make the definition of relative paths within your source code easier and more robust, it is desirable that the final '.sav' program be in a file that is a sibling, not a parent, to the 'source' folder.

3. "data"
   For data files that are specific to this application. Data files are much easier to make dynamic paths for in source code, if they are in a short path relative to the application root directory. They can then be addressed dynamically with calls like:
   
   

   dataFile = filepath('mydata.dat', SUBDIR=['..', 'data'], ROOT_DIR=appRootDir)

4. "resource"
   For non-code and non-data files, on which the source code depends. Good examples are bitmap files that might be used for button graphics or application icons, configuration files that might define the initial state of your application, etc. (Note that many apps will not have any use for a 'resource' directory.)

5. "help" or "docs"
   Store documentation about your application in this separate project node and the matching file system directory that it makes.

Feel free in the IDL Workbench to add further subdirectory hierarchies to any of these first-level directories. Anything you drag into (or "mv"/"rename" into) your Project directory tree via the operating system's file system explorer will appear in the Project Explorer view as soon as you click on 'File->Refresh' in the Workbench menu.

Below are the project property settings that we recommend for 'Application Projects.'

Recommended Properties for 'Application Projects'

TIP #7: 'Application Projects' can usually take advantage of this new IDL development environment feature that allows the IDL Search Path to dynamically append and remove your new project's directory tree depending on whether the Project is open in your Workbench or no. Put a check in the box 'Update IDL path preference when project is opened or closed', and don't worry about whether your new project directory is separately entered in your login's static IDL search path.

TIP #8: We do not recommend automating the .RESET_SESSION call; in some project builds it may execute at an inopportune moment. It is more universally safe to run ".RESET_SESSION" at the IDL> command line before every execution of 'Project->Build Project'.

TIP #9: Unless you have a unique naming convention for the main procedures of your applications, assume that the 'Run command' should be the base name of your application's initializing '.pro' file. Per our earlier tips that should be identical to the name of the Project and its application root directory as well, and should ideally be all lower case.

TIP #10: Similarly, after you check 'Create a .sav file', we recommend that you always enter in the last field a file name identical to your main routine. The field displayed in the Project Properties dialog above demonstrates the use of the 'bin' subdirectory advised in Tip #6 above.

TIP #11: With two caveats we advise taking advantage of new IDL development environment compiler functionality by checking the 'Build in a separate IDL session' checkbox. This option uses the fairly new IDL_IDLBridge class to perform the '.sav' file build in an independent IDL process. No .RESET_SESSION is needed and the entire state of your current IDL Workbench session - all its variables, its open files, its current working directory - is left undisturbed throughout the build. This is a benefit that was not available in earlier 'idlde' versions. The caveats are a) that this setting is incompatible with Projects that have references set on the 'Project References' page of the Project Properties dialog, and b) that the act of unsetting this checkbox can potentially cause instability (a bug) in your current IDL Workbench session, forcing you to exit and restart your IDL session. Consequently, if you are having to debug 'Project->Build Project' problems during an IDL session, we recommend that the 'Build in a separate IDL session' checkbox be unchecked for the duration of your debugging work.

After you click 'OK' on the Project Properties dialog, most projects are ready to build/rebuild into a '.sav' file with a simple right-click on the app's node in the Project Explorer view and a click on the 'Build Project' option. The above tips are, thus, all that most IDL programmers need to follow to create their '.sav' programs. However, some Projects that are based on multiple '.pro's, particularly ones with object class '.pro's or ones that have '.pro's which contain multiple FUNCTIONs, may be in need of a "custom build command". These projects would still observe the recommendations, but require some additional rules for how to fill in the Project Properties field 'Use a custom build command'. Since this requirement affects only a small percentage of IDL programmers, it is handled in separate Help Article #4309 ("Tips on Building a Custom Build Script for IDL 7.0 Projects").