Eclipse : Creating and Sharing Launch Configurations

This happened again. I downloaded a Java product from sourceforge. It came with a .project, so it is easy enough to import it into the eclipse workspace. Now, comes the humdinger of the problem. How in the world should I launch the application. I can also see a tests package, how can I launch the tests?
Fortunately, eclipse solves this problem through launch configurations. If you are developing on eclipse there is no reason for not sharing the launch configurations along with the code. A launch configuration is a way to inform a fellow developer how to invoke the application. It is like providing a helping hand in during the initial stages - till he/she grows up and find how to launch the application, tests or whatever by themselves.

Temporary launch configurations

If you rightclick on a test case or a main class and used 'Run as...', eclipse creates a launch configuration and invokes the application for you. While developing an application (if you are like me) - you will accumulate a lot of launch configurations. These launch configurations are saved along with the workspace and not shared.

Creating a launch configuration

For creating a launch configuration start with a temporary launch configuration. Open the Run -> Run dialog... option from the eclipse menu, i.e. right click on the file Run As-> Run configuration:

Now select the run or launch script you want (by noting the program name )

  Change the launch configuration name. Use a name that includes atleast the project name and the type of launch it is. No one can understand what 'Main' or 'AllTests' stand for. It is easy to understand 'SampleApp - Main' or 'SampleApp - AllTests'. Here is H2Test, which says we are testing whether program can connect to H2 database.

  You can set the arguments for the VM as well as application from the (surprise!) Arguments tab.

 As far as possible parameterize the arguments. Do not ever use hard coded file names or directory names in a launch configuration that is shared. Eclipse has predefined variables 'file_prompt', 'folder_prompt' and 'string_prompt' for this purpose. When a launch configuration with such parameters is launched, Eclipse prompt the user to either select a file/folder or enter a string.
If your launch is dependent on a particular Java version (suppose you need atleast JDK 1.5 to work) - use the JRE tab to select the JRE. It is advisable to select a particular 'Execution environment' rather than an installed JRE.
The rest of the tabs are self explanatory. If you added any environment variables, remember to parameterize them wherever needed. Launch the configuration using the 'Run' option in the dialog and check everything works fine.

Sharing a launch configuration

If you want to share a launch configuration, you do it through the 'Run dialog'. For opening the run dialog use Run -> Run dialog... option from the eclipse menu. The sharing option is in the 'Common' tab of the run dialog.

 Select the 'Shared file' option. Select the project to which this launch configuration belongs. I suggest the launch configurations to be saved at the root of the project directory. You can also add the launch configuration to the favorites menu (either to Run or Debug). Just click on 'Apply' and the launch configuration is saved. From now onwards, anyone who imports your project can launch the application by just clicking on the launch configuration file and selecting Run as -> <launch name>.

Also if you want you can direct console output to some log file on the file system, under this common tab:

Now you can choose any option like workspace, filesystem or variable. Save the log file location.

Launch configuration best practices

• Provide launch configurations for all modes of launch. For example, if your application can be launched in UI and command line mode, provide two launch configurations one for each.
• Do not proliferate the project with temporary launch configurations. I have a separate project where I save all of my temporary launch configurations. This will be checked into the SCM, but not shared along with the project.
• Provide a launch configuration for running all the tests (if exists).
• Do not add optional launch configurations into the favorites. My suggestion is to add only the application and all tests into the favorite menu.
• Parameterize the launch configurations using eclipse variables - folder_prompt, file_prompt and string_prompt.
• Select an appropriate JRE using the JRE tab and an execution environment.

Finally, launch configurations are for fellow developers and not for end users. Keep it in mind when you create a configuration. Too much of hand-holding might not be needed.