Jun 212013

In the previous blog post, some areas remained unexplored. Specifically, how to observe the values of variables with versions of the IDE that don’t include debug information. In this guest post by Robert Bracko (robert [dot] bracko [at] vip [dot] hr), he describes his experiences with building the NetBeans IDE source code to overcome this obstacle.

Step 1: Building NB sources

  1. Create local disk folder C:\nb6_9_1

  2. Download NB platform sources (netbeans-6.9.1-201007282301-src.zip) and extract it into C:\nb6_9_1\src

  3. Download NB binaries (netbeans-6.9.1-201007282301-ml-javase.zip). This step is necessary for getting the appropriate Ant builder. Extract only netbeans\java\ant into C:\nb6_9_1\ant. Result of that operation should be that C:\nb6_9_1\ant contains ant subfolders binetcextralib

  4. Create batch file (buildenv.bat) inside the folder C:\nb6_9_1. Put the following lines (adjust JAVA_HOME to match your Java JDK path!):
    set JAVA_HOME=C:\Program Files\Java\jdk1.6.0_12
    set ANT_HOME=C:\nb6_9_1\ant
    set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%PATH%
    set ANT_OPTS=-Xmx1g

  5. Open command shell and change directory to C:\nb6_9_1. Execute buildenv.bat. Then change directory to NetBeans source which is to be built (C:\nb6_9_1\src). Execute ant (without any cmd-line params). Please be patient; depending on your machine power, the process can take up to hour!

As a result of above-described procedure, new folder is created: C:\nb6_9_1\src\nbbuild.

General notes

  • For some reason, path of Ant installation directory must not contain spaces!
  • If building for the first time, disable Windows Firewall because for some reason it prevents Ant from downloading jars from web.
  • Possible build error “java.lang.OutOfMemoryError” can be overridden by following batch command: set ANT_OPTS=-Xmx1g

Note on building NB 6.9.1 sources:

During build process, you will probably encounter the following error:
C:\nb6_9_1\src\o.jruby.distro\unpatched_source\jruby-1.5.0\build.xml:1141: Java returned: 1

Please check https://netbeans.org/bugzilla/show_bug.cgi?id=186736 for a workaround.

Step 2: Debugging specific NB platform and/or NB module that was developed for that platform

Open your development IDE (in my case, it’s NB 7.3).
There are two possible ways to debug NB module that was developed for specific NB target-platform (in our case, it’s for NB 6.9.1). I prefer the first one ("Adding target platform through NetBeans Platform Manager") because it’s not necessary to install NBM inside target-IDE.

  1. Adding target platform through NetBeans Platform Manager

    1. Choose from main menu Tools > NetBeans Platforms. Press button “Add Platform…”. Choose the folder C:\nb6_9_1\src\nbbuild\netbeans. Let NB decide on the name of platform (“nb691”).

    2. Choose tab “Sources” and add the following folder: C:\nb6_9_1\src

    3. Choose tab “Harness” and check whether radio-button “Harness supplied with Platform” is selected

    4. Open your NBM project.
      The following is important! Open Project Properties > Libraries and adjust the field “NetBeans Platform” to hold the value nb691!

    5. Set the breakpoint inside your NBM code.

    6. Optionally, you can set the breakpoint inside NB platform source code. For instance, let’s imagine that your NBM uses functionality of NB class AbsoluteLayoutSupport and you want to check the interaction. Make a Windows file-search inside the folder C:\nb6_9_1\src. That results in containing folder C:\nb6_9_1\src\form\src\org\netbeans\modules\form\layoutsupport\delegates. So open the folder C:\nb6_9_1\src\form as another project in your development-IDE(uncheck the checkbox “Open Required Projects:”). Expand Projects window node Form Editor > Source Packages > org.netbeans.modules.form.layoutsupport.delegates. Double click on AbsoluteLayoutSupport.java and set the breakpoint.

    7. Inside Projects window, right click on your NBM and choose Debug from the context menu. That makes target-IDE (6.9.1) to launch. Choose Tools > Plugins from target-IDE main menu, then choose tab “Installed”. You should see your NBM inside the list of installed plugins. Nice, isn’t it?

    8. Make some action that affects your NBM and enjoy debugging 🙂

  2. Opening src\nbbuild as a project

    1. Open your NBM project and set the breakpoint anywhere inside the code.

    2. Open the following folder as a project: C:\nb6_9_1\src\nbbuild. The node “NetBeans Build System” appears inside Projects window.

    3. Right-click the subnode build.xml and choose the following from context menu: Run Target > tryme-debug. That makes target-IDE (6.9.1) to launch. Choose Tools > Plugins from target-IDE main menu, then choose tab Downloaded. Press button “Add Plugins…”, find NBM on disk and then press button “Install”. Finish the installation process, then close Plugins window.

    4. Make some action that affects your NBM and enjoy debugging 🙂

    5. Optionally, you can set the breakpoint inside NB platform source code. Follow the same approach as given in “Adding target platform through NetBeans Platform Manager” step 6.
Jun 072013

Much has been written about the NetBeans Platform. But the ultimate resource still remains the source code of the Platform itself! I have used plenty of open source libraries over the years. And I have ventured into the source code numerous times. Quite often the experience is one that leaves one dazed and confused. But I have found that the NetBeans source code is well structured and easy to follow. So even on your very first adventure, you can gain much wisdom! 🙂

Reading source code is like reading a Physics text book. You can try to keep all of that information in your head, or you can experience it in practice. So in most cases, the easy way to find an answer is to debug into the source instead of just perusing it.

How to set up the source code to be able to debug into it, depends on what type of project you are working with. For Ant-based module projects, download the source code of the same version as the platform that you are building on, and configure the platform to use it in the NetBeans Platform Manager (Tools > NetBeans Platforms). This gives you access to all of the source code in all of the modules.

For Maven-based projects, you have to attach the source code for each of the dependencies. In project view, right-click on one of the NetBeans module dependencies and choose Download Sources.

Now put a breakpoint somewhere in your own module to start from. So for example, if you wanted to explorer the behaviour of the TopComponent class, put a breakpoint into the constructor of a TopComponent subclass (created using the Window wizard). And step into for example the setName() method.

Using this methodology, you can explore how the platform loads and uses things like nodes and actions and windows. That will provide you with much deeper insight into how these things work!

Robert Bracko (robert [dot] bracko [at] vip [dot] hr) explored the behaviour of an old third party IDE module from the 6.9.1 days. He sent me the following points, describing his fascinating first adventure!

  1. Downloaded NB 6.9.1 (Build Type: Release) from https://netbeans.org/downloads/6.9.1/zip.html:
    1. netbeans-6.9.1-201007282301-ml-javase.zip (description: NetBeans 6.9.1 Java SE OS Independent Zip/English)
      Extracted (not installed!) into directory netbeans-6.9.1-201007282301-ml-javase
    2. netbeans-6.9.1-201007282301-src.zip
      Extracted into directory netbeans-6.9.1-201007282301-src
  2. Inside Development IDE (NB 7.3), added platform nb691 as new NB platform, based on directory netbeans-6.9.1-201007282301-ml-javase\netbeans.
    Sources linked for that platform, based on directory netbeans-6.9.1-201007282301-src
    So far so good 🙂
  3. Project opened inside Development IDE: KoalaLayoutSupport. Project properties changed: NetBeans platform set to nb691
    Attempt to build the project fails:
    The following error occurred while executing this line:
    X:\netbeans\netbeans-6.9.1-201007282301-ml-javase\netbeans\harness\testcoverage.xml:22: C:\Program Files\NetBeans 7.3\harness\testcoverage\cobertura does not exist.What is strange here is that error message refers to C:\Program Files\NetBeans 7.3 directory. Why does it look into NB 7.3 installation directory?
    Next step was to investigate exactly what’s going on during build process. So I’ve selected project’s node Important Files > Build Script and from the pop-up menu chose Debug Targer > netbeans. I found out that file nbproject/build-impl.xml refers to file nbproject/private/platform-private.properties which further defines property user.properties.file with value C:\\Documents and Settings\\Administrator\\Application Data\\NetBeans\\7.3\\build.properties. Nothing wrong with that, right? Because at the same time debugger’s variables-window shows that property nbplatform.active contains value nb691, so the whole process of building should be (at least I think so) controlled by NB 6.9.1. platform.
    But then one suspicious thing: build-impl.xml tries to define the property harness.dir with value nbplatform.${nbplatform.active}.harness.dir. After having executed that line, debugger’s variables-window shows the value C:\Program Files\NetBeans 7.3/harness for that variable! And that’s obviously wrong.
    So the next step was to change harness dir for platform nb691. I have done that through NB Platform Manager: inside tab Harness, choosing “Harness supplied with Platform” instead of “Harness supplied with IDE”. And then the build passed OK! 🙂
  4. Next thing, module debugging. Breakpoint set inside of module’s class works OK, also a breakpoint set inside of a class of NB 6.9.1 source. But… For the latter one, debugger’s variable window shows the error message “variable information not available, source compiled without -g option”. I know what it means but how to resolve it?….. For me it’s rather important to see how NB Form Editor source code interact with my module…

Thanks for sharing, Robert! Some questions still remain unanswered in the steps above. Stay tuned for more about his next adventure!