Alias / Macro Support for JDB (Java Debugger) and Other Command Line Programs

Alias / Macro Support for JDB (Java Debugger) and Other Command Line Programs

Copyright (c) 2022, Geoff Mottram
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Contact: geoff at minaret dot biz

Keywords: alias, macro, jdb

Contents

Introduction
Using macro
Installing and Compiling macro
Debugging a Java Program with macro

Introduction

macro was written to solve a simple problem: the Java Debugger (jdb) is such an excellent tool but doesn't support single-letter commands or command repetition (pressing the ENTER key to repeat the last command).

macro can be used as a front end to any interactive command line program (the target program) which reads from standard input. macro provides an alias substitution mechanism on the first word of the input line. The subsituted line is sent to the standard input of the target program.

By default, macro supports command repetition whereby if you input a blank line (press ENTER and nothing else), the last line that was sent to the target program is resent.

Using macro

macro is invoked as follows:
Usage: macro [-rv] PROGRAM ARGS...
Where: -r Turn off ENTER key repeats last command
       -v Verbose output (debugging aid)
The -r option will turn off command repetition for target programs that already support this feature or when you just don't want this behavior.

The -v option may be useful if you are trying to use macro with a progam other than jdb and it doesn't seem to work. The most likely cause of failure will be programs that insist that standard input be a terminal (by calling something like isatty()).

The following macro commands are not forwarded to the target program:

alias

List all defined aliases.

alias NAME=SUBSTITUTION

Define the alias NAME to mean SUBSTITUTION (which can be any string).
Unlike the Linux shell, quotation marks are not used when defining an alias unless you want them to be part of the alias.
The = sign is required.

unalias NAME

Remove the alias NAME.

When macro starts running, it reads and executes the contents of "macro.ini" in the current directory as if you had typed the lines yourself. This is the fastest way to define a set of aliases to use with the target program. Any lines that do not contain a macro command are passed onto the target program. Lines that start with a # are comments and are ignored.

The distributed "macro.ini" file is written to be used with jdb and defines the following single-letter aliases (note that the alias command itself has been given an alias of a):
alias a=alias
a c=cont
a d=dump
a h=help
a n=next
a p=print
a q=quit
a r=run
a s=step
a w=where
Installing and Compiling macro

macro is a "C" program that runs under Linux. Download the source code zip file here:

macro.zip
Checksums: sha256sum | md5sum

After you unzip the contents of the zip file to a local directory, compile the program by running the following command:

sh compile.sh

The executable will be called macro. Copy this file so that it is in your executable path (such as ~/bin or /usr/local/bin, etc.).

Debugging a Java Program with macro

Whether the program you want to debug is a command line program (which will be reading from and writing to the console) or not, it is usually easiest to run your program in one terminal window and jdb in another.

The following command will prepare your program for debugging without actually running it:
java -Xmx100m -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,address=8008,server=y,suspend=y CLASS_NAME $@
Where CLASS_NAME is the name of the Java Class with main(). The suspend=y option tells Java to not run the program just yet.

In a separate window, start the Java debugger as follows:
macro jdb -sourcepath SOURCE_DIR -attach localhost:8008
Where SOURCE_DIR is the directory where your source code is located. The -sourcepath option is only necessary if you are using package names and your current directory isn't the top-level package directory.

Make sure you copy the file "macro.ini" from the macro installation directory to your current directory before you run the macro command. Create a jdb.ini file in your current directory if you will be running jdb more than once to define your usual breakpoints using stop in and stop at.

Start the program you are debugging with r (run), single step with either s (step into) or n (next / step over), print variables with p and exit with q (quit).

Tip: It is often easiest to create a temporary Java method in your code called debug() and call it from some place in your code where you want the program to stop. This way, you don't have to worry about line numbers in your break points. Next, set a breakpoint with the jdb command stop in CLASS_NAME.debug.

Tip: The jdb print command calls the toString() method of the object being printed. Override the toString() method in your objects to add any custom debugging information you want to see easily when debugging your program.

Technical Tips