Thursday, July 12, 2007

Tip: 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.

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'.

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&rt;.

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.

23 comments:

Anonymous said...

Is there a way to just share a part of the launch configuration.

KD said...

What do you mean by part of the launch configuration?

Anonymous said...

Thanks for the how-to, we were wondering how to do this!

KD said...

Nice to hear that it is useful for you.

Seat21A said...

We have a project that has many releases (e.g. branches) in production. We'd like to share the launch configuration, but we already have the projects imported. Is there a way to just import the launch configurations from the shared directory, without reimporting the entire project?

Anonymous said...

Sean:

It is possible. Eclipse recognizes .launch files automatically. Just keep them along with .classpath and .project - no need to reimport the project.

Anonymous said...

Thanks!! Especially using the 'Execution environment' instead of a JRE helps alot :)

Anonymous said...

you really helped, thanks

KD said...

Glad it helped you.

KD said...

Glad it helped you.

Anonymous said...

+1 Thanks!

Anonymous said...

+1 Thanks!!!

Anonymous said...

Thanks Man . a very useful post :)

Amir Gal-Or said...

This is a great article.
But - after launching an application (Actually Tomcat Server) for the first time the variables in "VM Arguments" get run-over by hard-coded values (paths) instead of staying flexible, thus the launch file is also changed and developers see it in there sync-view (i can add svn:ignore, but i rather have a better solution)

MyStuff said...

Is it possible to set Launch Configurations for entire Eclipse project? For example, I want to add a certain external folder for resources (property files etc..) for each main class or Junit class. Can I do this one place (e.g. a configuration on the project) or do I need to do it for each class?

Anonymous said...

Is it possible to set Launch Configurations for entire Eclipse project? For example, I want to add a certain external folder for resources (property files etc..) for each main class or Junit class. Can I do this one place (e.g. a configuration on the project) or do I need to do it for each class?

Anonymous said...

Is it possible to set Launch Configurations for entire Eclipse project? For example, I want to add a certain external folder for resources (property files etc..) for each main class or Junit class. Can I do this one place (e.g. a configuration on the project) or do I need to do it for each class?

Anonymous said...

Is it possible to set Launch Configurations for entire Eclipse project? For example, I want to add a certain external folder for resources (property files etc..) for each main class or Junit class. Can I do this one place (e.g. a configuration on the project) or do I need to do it for each class?

Unknown said...

Eclipse supports variables that you can use to define your properties. Use these variables while defining your launch configurations.
You need to create separate launch configurations for each main/junit class. I don't know of any way by which you can define a launch configuration 'template' at the project level.

Anonymous said...

Hi,
Nice article.
On rightclick of new popup menu item at project level, I need to read the *.launch files from workspace .metedata folder, but I couldnt able to do it. Any thoughts on this?

Cuck2Bused said...

will that work on Mac’s?

KD said...

Yup. This should work with OSX also. Though I wrote this sometime back - it is still valid.

Anonymous said...

Is there any way to define the base directory based on the location of the share launch file ? I mean, is there any variable that points to the shared launch file ?