How to configure Netbeans to compile and debug Jitsi
On this page… (hide)
Netbeans is a pure java open source project that should (in principle) run on any platform that has a supported java SDK. It is a feature-rich IDE that has been undergone an impressive series of changes during recent years, so you should not contemplate running anything older than the latest stable release. You can get the latest version from http://www.netbeans.org.
Note: This procedure is applicable to NetBeans 6.0, which was released in late 2007 and includes support for SVN. Most of the procedure is also valid for the previous release, version 5.5.
Install and test the Anagrams Sample Project
NetBeans uses Ant to perform many of its own IDE functions and is tightly integrated with it. We strongly recommend that you install, build, test and debug the sample Anagrams project before starting to work with Jitsi. This will prove that you have successfully configured your IDE before you begin work on our complex project. Jitsi has its own complex build.xml file, while Anagrams allows NetBeans to create a boiler-plate project. Most of your work will be associated with the integration of the Jitsi build.xml and the NetBeans IDE configuration.
Note: It is currently (April 2008) not possible to checkout the project under NetBeans. This is because the SSL server certificate is not issued by a trusted certificate authority AND NetBeans does not handle the SSL alert condition gracefully. Therefore, you should perform the SVN checkout from a command prompt as described in RetrievingAndBuildingTheSources. (You will be able to use NetBeans for all subsequent SVN operations once you have completed these procedures).
From the NetBeans Versioning menu, select Subversion and then Check Out from the submenu. The Subversion Check Out Options window will open. Enter the Repository URL of:-
https://sip-communicator.dev.java.net/svn/sip-communicator/trunk
Enter your own project userid and password - our SVN repository does not provide anonymous access. If you check the box, your credentials will be saved in your sandbox for future use.
Click the Next button and a progress bar will appear while NetBeans connects to the repository. If the operation ends with both Next and Back buttons greyed-out, check the NetBeans log… you should see a message about the reason for the failure. If the connection was successfuly, you will have moved onto the second stage, where you specify the project to checkout and where to create your sandbox. We recommend that you choose a location outside the netbeans installation directory to make upgrades simpler. The default will be the value of your HOME environment variable. (n.b. you are specifying the root where your sip-communicator sandbox will be created, not the sandbox itself).
Note: If you already use Netbeans to maintain CVS or SVN Sandboxes for projects NOT resident at dev.java.net, we strongly advise you to setup a NEW sandbox. NetBeans works well with multiple folders holding multiple project sandboxes, so maintaining and switching between projects is much simpler if you adopt this structure. For example, I have three directories off my HOME directory: netbeans (for the ide itself), SandBox (for my own projects) and sandBoxJavaNet (for Jitsi).
Define your new SVN sandbox as a Netbeans Project
The SVN repository includes the files you need to identify your new sandbox as a NetBeans project. However, we need to make provision for you to customise your own configuration if necessary, so SVN properties have been defined to ignore any changes that you will make to the ./nbproject/ subdirectory in your sandbox.
Make sure you do not already have the Jitsi project open on your NetBeans workbench. Use your favourite operating system tool to create a ./nbproject/ directory if one does not already exist. Then copy ONLY the ./nbproject/project.xml and ./nbproject/ide-targets.xml files to the ./nbproject/ directory. Danger! You should NOT copy the entire ./nbproject/ directory. (It will contain a subdirectory called .svn/, which might contain history information that will confuse your subversion client if it is found in the wrong place. On Unix operating systems this directory will be hidden from standard views. It will also contain a directory called private that holds project data created by your own netbeans workbench.)
You can safely customise ./nbproject/project.xml (i.e. your own copy!) if necessary, but it should already be suitably preconfigured to work in your new sandbox. (Windows users might find the classpath lines towards the bottom of the file need to be changed if the unix syntax is not accepted.)
Go to the NetBeans workbench and open an existing project. Browse your file system to open the new sandbox and then select the sip-communicator project, which should appear as a folder called trunk in your sandbox. The project should open successfully because NetBeans will find your project.xml and ide-targets.xml files, as well as the associated ant build.xml control file. If you look at ./nbproject/project.xml from the Files view, you should see that its name is greyed-out, which means the repository will be protected from any local changes in the case where you inadvertently perform a project-wide commit.
Clean and Build the project
Right-click the sip-communicator project object (from the Projects tabbed pane) and then choose the ‘Clean and Build Project’ sub-option from the pop-up menu (this ide-action will run the paranoid clean and make ant targets). Focus should switch to the Output pane on the bottom part of the workbench and you should see the Ant build messages as they are produced. The build should complete successfully after creating all the “bundle” jar files.
Note: the Projects view might show a red exclamation mark icon on the test source folder after a clean and build. This seems to be a bug in NetBeans where the contents of the src and test folders are compiled by the IDE, but some references cannot be resolved. The only way to get them recompiled is to open each source file in each package, then close them individually once their red exclamation marks disappear! Once you have done this, they do not seem to re-appear.
Test the project
Before you can run the full set of unit tests, you must create a properties file that defines your own testing account credentials for the various protocols. This process is described in TestingProperties.
Right-click the sip-communicator project object (from the Projects tabbed pane) and then choose the ‘Test Project’ sub-option from the pop-up menu (this ide-action will run the test and its pre-requisite ant targets). Focus should switch to the Output pane on the bottom part of the workbench and you should see the Ant build messages as they are produced.
You can also restrict the test run to a subset of the suites if, for example, you are interested in a specific protocol and do not have test accounts for some of the other protocols. The process is described in TestSelection.
The build should complete successfully and all unit tests should run without error. You can examine the results of individual tests or suites by opening a web browser page on the newly created file ‘./test-reports/html/index.html’ in your sandbox and exploring the various reports.
Note: If your tests fail the first time after you create the project, you should check the FAQ for known problems.
Running individual tests
The build.xml file for Jitsi includes some targets that are particularly useful when working with Netbeans (they can be used outside the IDE provided you manually set the Ant test.name property). These targets are automatically wired up to the project settings when you installed the project.xml file from CVS. (For background information, refer to Editing The Netbeans Project File).
You can execute an individual test class under Netbeans by selecting a source file (e.g. ConfigurationServiceLick.java), right-click it and choose the Run File ide action.
Debugging the application under Netbeans
The ide-targets.xml file for Jitsi includes an Ant target that is used to debug the project under Netbeans. This target is already “wired up” to Netbeans in the project.xml file that you copied from SVN.
To check that debugging is properly configured, open the SipCommunicator.java source file (in the src/net.java.sip.communicator.launcher package). You should be able to confirm there are NO compilation errors (indicated by red underlining and red marks in the scroll margin). If you see any unresolved import statements, you should shut down Netbeans with the source file still open, then restart it. The classpaths will be re-scanned and the errors should be resolved. (If any imports are still unresolved, please report the problem - it is probably because we have missed a new jar file from the project.xml file).
Note: You can still successfully debug code that shows these errors in the source display window. However, you will not be able to step into any of the methods associated with a red-underlined import statement - if you try, Netbeans will simply step over the method instead.
Set a breakpoint by single-clicking the first statement in the main() method - it should then be highlighted in pink, with a small pink blob in the left margin. Next, click on the Jitsi project and choose the Debug Application action. Ant will start running, and then the debug windows should open on the bottom section of the screen. Execution should halt at your breakpoint, and be highlighted in green. You should be able to step into other source files within the project and display objects and fields, as well as the call stack.
Debugging unit tests under Netbeans
The build.xml file for Jitsi includes an Ant target that is used to debug the project under Netbeans. This target is already “wired up” to Netbeans by the project.xml that you copied from CVS. (For more details, see Editing The Netbeans Project File).
To check that debugging is properly configured, open the TestConfigurationService.java source file (in the test/net.java.sip.communicator.slick.configuration package). You should be able to confirm there are NO compilation errors (indicated by red underlining and red marks in the scroll margin). If you see any unresolved import statements, you should shut down Netbeans with the source file still open, then restart it. The classpaths will be re-scanned and the errors should be resolved. (If any imports are still unresolved, please report the problem - it is probably because we have missed a new jar file from the project.xml file).
Note: You can still successfully debug code that shows these errors in the source display window. However, you will not be able to step into any of the methods associated with a red-underlined import statement - if you try, Netbeans will simply step over the method instead.
Set a breakpoint by single-clicking the first statement in the testSetGetProperty() method - it should then be highlighted in pink, with a small pink blob in the left margin. Next, click on the ConfigurationServiceLick source file and choose the Debug File action. Ant will start running, and then the debug windows should open on the bottom section of the screen. Execution should halt at your breakpoint, and be highlighted in green. You should be able to step into other source files within the project and display objects and fields, as well as the call stack.
Resetting a Jitsi Configuration
Whenever you change something related to your sip-communicator environment, e.g. using an accelerated JMF or the all-java implementation, you must make sure Jitsi goes through the process of detecting the change. See Resetting the Jitsi Configuration for details.