Configure IntelliJ

IntelliJ (tested with v9-v13)

Run ant ivy-bootstrap from the command line to install the ivy jar in ~/.ant/lib/.

Run ant idea from the command line to populate your working copy with the configuration files IntelliJ needs to be able to compile, test, and debug Lucene and Solr.

To then open the code in IntelliJ IDEA, simply hit File->Open (File->Open Project in IntelliJ v11 and previous) and Choose the directory containing the checked out source (i.e. the top level directory that contains both the lucene and solr directories.)

The project configuration will have:

1. An IntelliJ module for each Solr/Lucene module, with jar and inter-module dependencies defined.
2. A JUnit test run/debug configuration defined for each module's tests, including the runtime directory and required JVM parameters. All tests run and pass. IntelliJ allows more than one of these to run simultaneously, so you can gain some test parallelism by starting up more than one at a time.
3. Ant integration: from the "Run" menu, you can invoke any Ant task defined in any module's build.xml file.
   

After ant idea runs, it will print out instructions on how to configure the project SDK, currently this consists of setting the JDK level.

Running ant clean-idea from the command line removes all IntelliJ configuration files. If you already have an existing configuration, but want to replace it with the one provided by ant idea, it's a good idea to run ant clean-idea first. WARNING: IntelliJ apparently uses the .idea/ directory, which is removed by ant clean-idea, to store shelved changes - do not run ant clean-idea if you have shelved any changes.

An alternative approach to use symbolic links instead of copying the IntelliJ files is to run the following on a Unix/Linux based OS:

ln -s dev-tools/idea/.idea; (cd dev-tools/idea/; find . -name '*.iml' -exec ln {} ../../{} \; )

The great thing about this is that when the IntelliJ files get updated, you get those changes. You may need to remember to tell IntelliJ to ignore changes to dev-tools/idea, and you still may want to re-sync just your .iml files from time to time.

Code Style

If you use the "ant idea" target, the correct code style file will be automatically installed. But if you simply must do this yourself, use the link below. You'll have to change the file a bit for it to show up in your drop-down...

IntelliJ 14.1.3 (and perhaps earlier) doesn't automatically install the code style file as of 22-May-2015 so you should do this manually. You'll see a very annoying dialog box pop up that talks about indenting being 2 spaces rather than 4. Solr/Lucene use 2-space indentation.

IntelliJ (and other IDEs) have a nifty "reformat code" choice. IntelliJ has a very nifty checkbox in in the dialog box that pops up "only VCS changed text". Please use this! Be careful you don't reformat the entire file though, that's rarely A Good Thing as it makes diffs very hard to read.

The IntelliJ anonymous code style file is here: (Intellij-Lucene-Codestyle.xml)

Debugging

There are two main ways to debug Solr in IntelliJ.

First and easiest is to write/use one of the jUnit tests. Once IntelliJ is set up, it's very easy to just set a breakpoint in a likely unit test and right-click on that test and just start up the test in debug mode and you're on your way. This has the advantage of not requiring a running Solr server. It has the disadvantage of it not always being obvious what test to run to see the Solr/Lucene code path of interest.

However, it is strongly recommended that when you develop new code you also create unit tests, so if you're developing new code this is very often the easiest way to step through code.

The second way is to create a "remote debug" session. To debug remotely, follow the instructions above for setting up IntelliJ.

Next, in IntelliJ, create a remote debugging session. Do do this, there's a little click the chicklet and then the "edit configurations" setting. Now, click the little plus sign and click "remote". This will bring up a dialog and enter the host and port, usually "localhost" and "some port", I use 5900.

When you do this, you should see something like this appear in the entry field above:

-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5900

Solr 4x You take that string and use it to start solr by going to the <solr home>/solr/example and entering something like:

java -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5900 -jar start.jar

Solr 5x For the new script-driven (Solr 5.x) start/stop, you can start Solr in debug mode with something like the below. This particular example will start up a node in a SolrCloud setup for debugging, of course for stand-alone you can just leave out the '-c -z localhost:2181' bits and point the -s parameter appropriately. Usually it's easiest to set up the instance with, perhaps, one of the examples (-e option), stop the instance, then start up a debug session like below once the structure has been created.

bin/solr start -c -z localhost:2181 -p 8981 -s ./example/cloud/node1/solr -a "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=6900"

Now go back into IntelliJ and execute the configuration you just created. At that point, you'll be able to set breakpoints in Solr and all sorts of good stuff. One note here: setting "suspend=y" in the above causes the Solr instance to wait around and do nothing until you invoke the remote configuration in IntelliJ. If you set "suspend=n" in the above, then Solr will start up and load all the configs etc. You can still attach the debugger and set breakpoints which you'll hit when you execute the code path. This process seems more complex than it really is, but at that it is far easier than starting up the servlet container within IntelliJ. The downside is that to make code changes you need to re-build Solr after making changes and attach again. Which is why jUnit tests are such a good idea.....