h1. Setting-up your preferred IDE

Working with Play is easy. You don’t even need a sophisticated IDE as Play compiles and refreshes the modifications you make to your source files automatically. So you can easily work using a simple text editor.

However, using a modern Java IDE provides cool productivity features like auto-completion, on-the-fly compilation, assisted refactoring and debugging. Play supports the "NetBeans":http://www.netbeans.org, "IntelliJ IDEA":http://www.jetbrains.com/idea/index.html and "Eclipse":http://www.eclipse.org platforms.


h2(#eclipse). <a>Eclipse</a>

h3. Generate configuration

Play provides a command to simplify Eclipse configuration. To transform a Play application into a working Eclipse project, use the @eclipsify@ command:

bc. # play eclipsify myApp

You then need to import the application into your Workspace with the **File/Import/General/Existing project…** menu.

!images/eclipse!

If you make any important changes to your application, such as changing the classpath, use @eclipsify@ again to regenerate the configuration files.

p(note). **Do not commit Eclipse configuration files when you work in a team!**

The generated configuration files contain absolute references to your framework installation. These are specific to your own installation. When you work in a team, each developer must keep his Eclipse configuration files private. 

h3. Launchers

The @eclipsify@ command generates several launchers for the application. For example, running @eclipsify@ on an application called **Nice app** (see screen shot above) will create the following launchers in the @eclipse/@ folder:

* @Nice app.launch@ - the main launcher, equivalent to the @play run@ command, which you can use to run your application by right-clicking it and selecting **Run As > Nice app**
* @Test Nice app.launch@ - the test launcher, equivalent to the @play test@ command, which you also run by right-clicking it and selecting **Run As > Test Nice app**
* @Connect JPDA Nice app.launch@ - the JPDA debugging session connector, which you can use to connect the Eclipse debugger to an already-running Play instance and start a debugging session, by right-clicking the launch file and selecting **Debug As > Connect JPDA Nice app**. Stopping the debugging session will not stop the server.

h3. Play Eclipse plug-in

Additionally, Play comes with an Eclipse plug-in that provides editors for HTML view templates, @application.conf@ and the @routes@ file.

To install, copy the JAR file from @$PLAY_HOME/support/eclipse@ to @$ECLIPSE_HOME/dropins@.


h2(#netbeans). <a>NetBeans</a>

Play provides a command to simplify NetBeans configuration. To transform an existing application to a valid NetBeans project, use the @netbeansify@ command:

bc. # play netbeansify myApp

Then you can just open the application as a NetBeans project.

!images/netbeans!

Use the standard *Run* button to start the application. When the application is started you can attach a debugging session at any time using the *Debug* button. Stopping the debugging session doesn’t stop the server.

If you make any important change to your application such as changing the classpath, use @netbeansify@ again to regenerate the configuration files. 

p(note). **Do not commit the @nbproject/@ directory when you work in a team!**
 
The generated configuration files contains absolute references to your framework installation. These are specific to your own installation. When you work in a team on the same application, each developer must keep his NetBeans configuration files private.

h2(#intellij). <a>IntelliJ IDEA</a>

Play provides a command to simplify IntelliJ IDEA configuration. To transform an existing application to a valid IntelliJ IDEA module, use the @idealize@ command:

bc. # play idealize myApp

To create a single module project, do the following in IntelliJ IDEA.

# On the command line, use the @play new@ command to create the Play project.
# On the command line, use the @play idealize@ command to create an IntelliJ IDEA module.
# In IntelliJ IDEA, on the *File* menu, select *Open Project…* and select the generated @.ipr@ file.

!images/intellij!

To add a run configuration:

# In IntelliJ IDEA, on the *Run* menu, select *Edit Configurations*.
# Right-click on *Application* under *Defaults* and select *Add New Configuration*.
# Under *Main class*, enter @play.server.Server@.
# Under *VM parameters*, enter @-Dapplication.path="."@.
# Under *Working directory*, enter the application path.
# Under *Before launch*, remove @Make@ if exists.

To run Play in test mode in IntelliJ:

# Edit the run configuration and in *VM parameters*, append *-Dplay.id=test*.
# Right-click on your module and select *Open Module Settings*.
# Select the *Dependencies* tab.
# Click *Add…* and select *Single-Entry Module Library*.
# Select @$PLAY_HOME/modules/testrunner/lib/play-testrunner.jar@ and click *OK*.

p(note). **Do not commit the .iml files when you work in a team!**
 
The generated configuration files contains absolute references to your framework installation. These are specific to your own installation. When you work in a team on the same application, each developer must keep his IntelliJ IDEA configuration files private.


h2(#textmate). <a>Textmate</a>

Install the "Textmate":http://macromates.com/ bundle provided at @$PLAY_HOME/support/textmate.zip@ to enable syntax coloring and auto-completion. The bundle also eases navigation between controllers and views.

!images/editor!


h2(#vim). <a>Vim</a>

Inspired by Textmate, the "snipMate":http://www.vim.org/scripts/script.php?script_id=2540 plug-in provides keyword auto-completion in "Vim":http://www.vim.org/. Play provides snippets files for HTML and Java: to use them, install snipMate and copy @$PLAY_HOME/support/vim/*.snippets@ to @~/.vim/snippets/@.


h2(#custom). <a>Custom configuration</a>

As Play applications are standard Java applications, you don’t need a specific plug-in to work with your preferred editor. This, however, requires a little bit of knowledge of how Play works.

h3. Classpath settings

A Play application classpath is built as follows (in this order): 

* The @conf/@ directory for the application
* The @$PLAY_PATH/framework/play-$version.jar@
* All JAR files found in your application’s @lib/@ directory
* All JAR files found in the @$PLAY_PATH/framework/lib/@ directory

p(note). *Tip*
 
If you have any modules enabled, you will need to add all modules’ libraries (from the @$module/lib/@ directory) to the classpath as well.


h3. Main class to run

To start a Play application, just run the @play.server.Server@ class. Play uses the @"application.path"@ system property to locate the application to run. Typically you pass this value with:

bc. java -Dapplication.path="/app/path"…


h3. Java agent

To enable HotSwap reloading you have to load a Java agent packaged in the @play.jar@ library. Typically like this:

bc. java -javaagent:"$PLAY_PATH/framework/play.jar" …

It’s not required, but will speed-up class reloading when it is possible.


h2. <a>Debugging issues</a>

Play automatically reloads Java classes when the Java sources are modified. However as Java does not fully support class reloading, the JDPA debugger can easily get confused: breakpoint submission may fail or the debugger may stop on the wrong line when you step into the code.

To avoid this behavior, a better way is to start a fresh debugging session after a code modification. Luckily, JPDA supports the ability to connect and disconnect the debugger at any time without restarting the JVM.

So the correct workflow for debugging is:

# <span>Make changes to your source code.</span>
# <span>Refresh the browser to see the results. (At this time Play will reload your code modifications and redefine classes in the JVM.)</span>
# <span>If something goes wrong and you need to debug, start a new debug session.</span>
# <span>Debug and correct your code.</span>
# <span>Disconnect the debugger.</span>

By using this work-flow you will always have a debugger synchronized with the code loaded in the JVM.

p(note). Next: %(next)"‘Hello World’ tutorial":firstapp%.
