Development

Remote debugging of sipXconfig components

It is possible to configure sipXconfig Java applications for remote debugging (JDWP). "Remote" in this context means that Java debugger attaches to process started by sipX watchdog, and not by the debugger. Debugger can actually run on the same machine as sipX services.

While it's not strictly required, the first step should be building Java code with debug information:

mkdir debug
cd debug
JAVAC_DEBUG=on JAVAC_OPTIMIZED=off ../configure
make
make install
To launch the program in the debugging mode you need to specify debug mode and communication port for the debugger. Each server's startup script lets you pass the necessary information through environment variables.
  export JAVA_DEBUG_OPTS="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5498"

In the example above we use port 5498. You can use other ports as long as the number you pass to Java application is the same as the number you pass to the debugger.

Depending on which component you want to debug you will need to set only one of the following environment variables.

  export PROFILEGENERATOR_OPTS=${JAVA_DEBUG_OPTS}
or  
  export PROFILEPUBLISHER_OPTS=${JAVA_DEBUG_OPTS}
or  
  export PROFILEWRITER_OPTS=${JAVA_DEBUG_OPTS}

Once the process is running you can attach your favorite debugger. If you use jdb, your command line should look like that:

$JAVA_HOME/bin/jdb -connect com.sun.jdi.SocketAttach:hostname=localhost,port=5498

Other debuggers and IDEs are also supported. Information on how to configure your favorite IDE can be usually found under Remote Java Debugging in user manual.

Building using Ant

Only a small subset of build targets is available through make build system. It is possible however to use Ant directly when developing sipXconfig. Our build.xml files retrieve most of the required properties from config.properties file generated by autoreconf. Since Ant needs to load optional jars on startup one also has to specify -lib option.
The full command line looks something like that:

ant -lib /path/to/sipXconfig/lib my-target-name

Please note that Ant needs to be executed from the source directory (directory in which build.xml file is located) and not from you build directory. If you run ./configure from the root directory of sipXconfig, then source and build directories are one in the same.

If you happen to use ant builds a lot it may be useful to set ANT_ARGS environment variable instead of typing the full command line every time. ANT_ARGS is a standard ant variable that allows passing extra command options to ant.

export ANT_ARGS="-lib /path/to/sipXconfig/lib my-target-name"
If ANT_ARGS is set properly you can call build targets just by typing ant target. For example you can list all possible targets by typing:
    ant -p

Checking code coverage using Clover

sipXconfig build files are prepared for Clover instrumentation. Clover instrumentation and reports assist in assessing effectiveness of unit tests. We will attempt to achieve 80% of coverage for newly written code.

Download Clover, unzip it to local directory and set CLOVER_HOME environment variable. Reconfigure your build directory (run configure script) and verify that Clover has been installed properly check if clover.jar property is set in config.properties file.

  grep clover.jar config.properties

In order to instrument the code on has to run ant directly (and not through the make system). You have to pass the location of clover.jar to ant, for example by appending it to ANT_ARGS variable.

    export ANT_ARGS="-lib $CLOVER_HOME/lib/clover.jar $ANT_ARGS"

Below you can find the typical scenario:

Clean and rebuild your sources with Clover instrumentation:
    ant -Dwith.clover=true clean default 
Run unit tests
    ant test
Run clover GUI to check code coverage
    ant clover.viewer
Alternatively generate HTML report:
    ant clover.report
    htmlview /path/to/build/directory/clover/html/index.html
Last modified: Thu Dec 9 13:20:14 EST 2004