 |
jTracer
1.03
Stack trace visualization tool
|
|
jTracer
1.03
Stack trace visualization tool
|
Project jTracer is a stack trace visualization utility for
libcsdbg. In other
words, it acts as a TCP/IP server for libcsdbg clients, that connect to it and
transfer their trace data, either C++ exception stack traces or generic thread
stack traces and whole process stack dumps. This functionality is generally very
useful during the development cycle of any C++ application, to have a way to
collect centrally, organize and process libcsdbg-related debug data, but it is
essential when doing cross-platform development (on a development board,
a remote system, an embedded/mobile device e.t.c), where dumping data to a
terminal console or a file, is not often a commodity. The rationale and motive
to develop jTracer was the gdb/gdbserver pair used in that very scenario.
Project jTracer fully mirrors the capabilities of libcsdbg, to debug single or
multithreaded or even multiprocess applications, with any kind of binary formats
and easy integration of shared, dynamic link libraries.
This is a comprehensive list of current and planned jTracer features:
Future versions are planned to support other interfaces, both through a serial line, UDP/IP and Unix sockets and pipes.
jTracer is currently published as an Open Source project, licenced under the
GNU General Public License
version 3.0 (GPLv3), copyright belongs to
Tasos Parisinos who
develops, maintains and documents the project. Version numbering uses three
numbers, major, minor and subminor. The subminor version is often omitted if it
is zero. The current jTracer version is 1.03. Major project updates are
related with multiple feature addition, significant changes in the GUI, major
bug fixes or overall optimizations. Minor updates usually add minor features (or
major features that were almost ready to be included in the major release
but didn't), minor bug fixes, typos and documentation updates or entities that
need to be tested for feedback. Subminor releases are stable beta snapshots of
the current code development status, with the last additions since the last
minor update.
The following are locations essential to the development of jTracer:
The current (beta) version of jTracer, version 1.03 (release date February 11th
2014).
This beta release adds an installer (jar autodeflated executable) that is
expected to work well (although not all its features are implemented) with Linux
and Windows (both 32 and 64) systems. The implementation of the installer
mandates the use of Java 1.7. Apart from the source code and the old build
system that is kept as it was, now two precompiled distributions for
jTracer-1.03 are also downloadable one for Linux and one for Windows platforms.
Next releases will embed these two installers into one. The installer itself
will gradually involve to a separate generic purpose jar installer.
The latest source distribution is
jTracer-1.03.tar.bz2
Alternatively, if you've already got the previous version (1.02) you can patch
it to upgrade it to the latest release:
If you have both these files in the same directory, to apply the patch, execute:
tar -xjpf jTracer-1.02.tar.bz2 cd jTracer-1.02 patch -p1 < ../upgrade-1.03.patch
The project documentation can be recreated (with
doxygen) in the source code
distributions. It can also be separately downloaded in HTML:
api-ref-jTracer-1.03.tar.bz2
The new binary distributions (installers) are available for Windows and Linux
systems as two individual files:
If you want an overview of all project files check the libcsdbg project repository at sourceforge.net. Click on any file's info icon and obtain its SHA1 or MD5 checksum to verify the file you've downloaded.
After you download any project file, remember to subscribe/follow jTracer in order to receive notification about new releases, updates, news, announcements and other jTracer related material in your mailbox. The easiest way to do so is to visit the jTracer project page at freecode.com and click on 'follow'
jTracer although portable to all Java capable platforms at source level, as this
is still a beta version, expect the build system and setup tools to be a little
rough. Currently only a Makefile and a build script for Linux or Cygwin are
offered for source level compilation. If you know how to use the Java
Development Kit (JDK) it will be easy for you to replicate the steps needed
to compile and install jTracer on your system.
After you download the source distribution, you need at least the following to
compile the application or generate the project documentation:
Unpack the archive, unless you already have done that. If you want to recreate the documentation you must unpack the tarball in /devel (or change the paths in the doxygen configuration files, more on this later):
mkdir -p /devel mv jTracer-$VERSION.tar.bz2 /devel cd /devel tar -xjpf jTracer-$VERSION.tar.bz2
Then compile and install it (the JDK programs, javac, java and jar must be in your path!):
cd jTracer-$VERSION sh ./build
The build script should compile without problems and install jTracer application and other project files with /usr as the prefix and your home directory as the resource, theme, log and configuration prefix (~/.jTracer). For an overview of all build script options and modes of operation use:
sh ./build -h
Usage: build [-c] [-k] [-s] [-d] [-h] build will compile and install its target by default. The following options change the default behaviour: -c Clear the source tree (make clean) -k Keep the current installation -s Don't parallelize compilation on multicore systems -d Create/update the documentation (make doc) -h Show this message
Although the build script can do all that you may need, to compile and
install or uninstall, recreate the documentation or clear the source tree by
calling the equivalent Makefile targets (in the right order), it
is essential to describe these individual targets.
First of all clear the source tree from built binaries and documentation:
make clean
Compile the sources (the result binaries are stored in ./.bin):
make
Install:
make install
Optionally, generate the user manuals. This will create the API reference in HTML under ./doc. To see the HTML documentation, just point a browser to the file index.html in the ./doc/api-ref-jTracer-$VERSION directory.
make doc
Finally, if you need to uninstall all jTracer-related files from your system:
make uninstall
To install from the binary distribution, all you have to do after you download
the proper file for your platform and execute it (double click must suffice).
Your system must be equiped with at least jre (Java Runtime Environment)
1.7
. Follow the wizard, to complete the installation. Currently desktop or
other links (except a Linux bash script) are not created so to start jTracer,
you must navigate to the installation prefix directory and invoke
jTracer-1.03.jar (via console or double click).
Bugs are tracked in the
tickets
section of the libcsdbg page at sourceforge.net. Before submitting a new
bug, first search through all the tickets (open and closed), if the same
bug has already been submitted by others. If you believe you have found a new
bug, please report it! If you are unsure whether or not something is a bug, you
may ask help on the
users forums
first (subscription is not required, the forums are moderated).
So, you think you found a bug? You should report it either on the user forums or
by sending an email to the project admin
tasos42@users.sourceforge.net.
If you send only a (vague) description of a bug you are usually not very helpful
and it will cost much more time to figure out what you mean. In the worst-case,
your bug report may even be completely ignored, so always try to include the
following information in your bug report:
The easiest way for us to fix bugs is if you can attach a small example that
demonstrates the problem you have to the bug report, so we can reproduce it on
our machines. Please make sure the example is valid source code and that the
problem is really captured by the example. If you intend to send more than one
file please zip or tar the files together into a single file for easier
processing.
You can (and are encouraged to) add a patch for a bug. If you do so please use
PATCH as a keyword in the bug entry form or in the email subject. If you
have ideas how to fix existing bugs and limitations please discuss them on the
users forums.
For patches please use diff -uprN or include the files you modified.
Donate time
You can contribute your time by helping with programming, testing and filing bug
reports, improving documentation, translations or by answering questions on the
mailing list. We always welcome users whose only contribution is simply using
jTracer, giving us feedback on how to improve it and telling others about it.
Thank you for supporting jTracer.
Donate money
If you don't have time to help but do find jTracer useful, then please consider
making a financial donation. This will help to pay the bills and motivate us to
contine working on jTracer. You can do so using the Paypal account indicated on
the project page at sourcefore.net, or contact us for other payment methods.
Execute jTracer (/usr/bin/jTracer by default), this launches the application. As during compilation/installation, the JDK or the Java Runtime Environment (JRE) (version 1.6+) executables (java) must be in your path. The GUI is really very straightforward. All you have to do is start a server (The default configuration, binds the server to all local interfaces at port 4242). Then it's up to libcsdbg debugged applications to start sending trace data to jTracer. The easiest way to test functionality and get used to the jTracer GUI, is to try the libcsdbg example executables that implement LDP clients. You must have installed version 1.21 (at least) of libcsdbg for this to function properly.
1.8.5