================================================================================ Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ================================================================================ Building and Debugging Apache Tomcat under NetBeans Unlike other IDE's, NetBeans is a pure java swing application. It uses Apache Ant to build its projects, and works directly with the class files and jars created by the standard Apache Ant build.xml files. This strength is also its weakness when working with complex projects such as Tomcat that already have their own build.xml files, but which do not use the NetBeans templates. Any of complex Ant project can still be managed under NetBeans by defining it to be something called a Free-Form Project. However, because the build.xml does not conform to all the NetBeans naming and structural conventions, a certain amount of manual customisation is required to achieve a useful level of integration. 1. NetBeans can open a Tomcat source tree as a Free-Form Project, which will allow you to edit, build, and debug Tomcat and its unit tests within the workbench. Even with NetBeans 7.1, integration of a project as complex as Tomcat requires significant configuration. The configuration involves dealing with several quirky aspects of the way NetBeans manages this kind of project. Before you try to open Tomcat as a NetBeans project, you are strongly recommended to successfully build and run the tests using Apache Ant from a command prompt! (see BUILDING.txt in the Tomcat source root directory). 2. Once Tomcat has been built, you can install the default NetBeans project configuration by running the following build target: ant ide-netbeans This uses the Tomcat build.xml to create a new directory called nbproject (this name is reserved by NetBeans). The nbproject directory will then be primed with a self-consistent set of default definitions sufficient to open Tomcat as a Free-Form Project under NetBeans. Note: if you ever open the Project Properties from the NetBeans context menu, even without making any changes, there is a significant risk that NetBeans will modify one or more of these files. You can restore the Tomcat default files at any time by running this target: ant ide-netbeans-replace Only the default files will be overwritten, so any other content such as your own local files, and the NetBeans private directory, will not be affected. 3. NetBeans needs to know where to find the directory where you keep the Tomcat dependencies jars. If you have successfully built Tomcat from a command prompt, you will probably have assigned the base.path property in your build.properties file. Warning: The support for Tomcat in NetBeans will detect and use this property. However, if you have left it to default, you MUST still define this path in the nb-tomcat-project.properties file! Note: The current support for Tomcat in NetBeans does not include the components in the modules directory (e.g. tomcat-lite). 4. Start NetBeans... once it has initialised and scanned your other open projects, just open an existing project and select the location of Tomcat. NetBeans will recognise it as a Free-Form project, then read and validate the nbproject/project.xml file. This file defines how to relate targets in build.xml to NetBeans project-related actions. It also tells NetBeans what classpaths to use for validation and code completion of the various source directories. Warning: do not be tempted to casually click the properties menu item for the Tomcat project. NetBeans might change the contents of these files. (The NetBeans New Project wizard also automatically creates a Free-Form project.xml which carries this same warning). Note: the Tomcat project should open successfully and, after the source packages have been scanned, they should not be flagged with any syntax errors (except in some of the jsp bug unit tests). 5. Verify your work by running the NetBeans project Clean action. It should complete successfully. Next, run the Build action (which calls the Tomcat deploy build target) and confirm that it successfully compiles the Tomcat source files and creates the jars. 6. Next, navigate down to one of the test files and select the compile action. This will compile only your chosen file, although the compiler will find there is nothing to do unless you have deliberately changed it. Note: if you have changed any of the Tomcat source files, they will be recompiled first. However, any changes to test files will not be compiled unless you select those file and explicitly compile them. If you have any doubts about dependencies between unit test classes, you can use the compileAllTests project action and any files that have been changed will be detected and compiled. 7. You can run an individual unit test class by selecting it and choosing the "run selected file" NetBeans action. As the test runs, NetBeans should open a unit test results pane that shows you the progress and final outcome of the test (Note: this feature does not currently work). 8. Next, open the source of the unit test that ran successfully in step 7. Set a breakpoint in one of the test cases, then request NetBeans to debug that class. The class will start running, and then will stop as it hits your breakpoint. You should be able to display variables, then navigate the call stack to open the source files of each method. You should also be able to step through the code. Use the continue icon to resume execution. When the test completes, you should see the same jUnit test result panel as in step 7 (Note: this feature does not currently work). 9. You can also use your Tomcat NetBeans Free-Form project to debug an external Tomcat instance that is executing on the same, or a different machine. (Obviously, the external instance must be running the same version of the source code!) The external Tomcat instance must be started with its jvm enabled for debugging by adding extra arguments to JAVA_OPTS, e.g. -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n To debug the external Tomcat instance under NetBeans, select the "attach debugger" choice from the debug menu. Accept the default JPDA debugger with the SocketAttach connector and the dt_socket transport. Specify the hostname and port where the Tomcat jvm is listening. Your NetBeans workbench should then connect to the external Tomcat and display the running threads. You can now set breakpoints and begin debugging.