Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8279121

Improve clhsdb help output

    XMLWordPrintable

    Details

    • Type: Enhancement
    • Status: Open
    • Priority: P3
    • Resolution: Unresolved
    • Affects Version/s: 19
    • Fix Version/s: tbd
    • Component/s: hotspot
    • Labels:

      Description

      I'd like to see the help output for clhsdb improved. Clhsdb help is currently very minimal, and often you need to experiment or look at the code to figure out how a command really works. The "help" command only gives you the syntax of each command. It does not explain what the command does, nor provide details describing the contents of the options passed. For example:

      hsdb> help
      Available commands:
        assert true | false
        attach pid | exec core
        buildreplayjars [ all | app | boot ] | [ prefix ]
        class name
        classes
        detach
        dis address [length]
        disassemble address
        ...

      Using "help <cmd>" just provides the above output for the individual command:

      hsdb> help assert
      Usage: assert true | false

      Note we have no other documentation for clhsdb, other than the unpublished clhsdb.html file. You might be able to find some blogs that talk about some of the more useful commands, but that's about it.

      The main improvement I'd like to make is to provide more details when "help <cmd>" is used. For example:

      hsdb> help classes
      Usage: classes
        Prints the entire dictionary of loaded classes. The output includes the class name and
        address of each VM Klass object, including for array classes. The Klass object can be passed
        to other commands that take a VM object such as "inspect".

      Another change I'd like to make is to the naming of arguments. Besides being more consistent with the naming across different commands, I'd like to bracket them with "<>". This makes it easier to describe the arguments in the help output:

      hsdb> help dis
      Usage: dis <address> [<length>]
        Disassemble the native code located at <address>. <length> byte are disassembled.

      Next I want to add an options to the "help" command that will dump commands together based on their logical grouping. First the syntax of help would become:

      hsdb> help { <cmd> | topics | -t <topic> }

      hsdb> help topics
        The following topics are available for help. Use "help -t <topic>" for more informaton about the topic:
          vmstructs: commands related to vmstructs
          compiler: commands useful for debugging the hotspot compiler
          heap: commands useful for debugging the java heap
          memory: commands useful for to searching and examining memory
          ...

      hsdb> help -t heap
        The following commands are useful for debugging the java heap:
          dumpheap [filename]
          g1regiondetails
          jhisto
          inspect expression
          revptrs address
          scanoops start end [ type ]
          universe
          search [ heap | perm | rawheap | codecache | threads ] value

      Some commands may appear under more than one topic, such as the inspect command.

      Lastly, some sort of "recipes" help would be useful. For example "How to display the value of static fields of a java class". I haven't quite figured out how to work this part into the help output.

      Before embarking on the code changes, we first need a source document that will contain all the needed help info. I started on this a while back but never completed it and probably won't get back to it. I'm attaching it as a reference in case this is picked up in the future.

      Note an alternative to improving the help output is to just have a more complete clhsdb document (something that is a lot better than clhsdb.html) and actually publish it. See JDK-8279122 which suggest that we improve clhsdb.html and publish it.

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              Unassigned Unassigned
              Reporter:
              cjplummer Chris Plummer
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Dates

                Created:
                Updated: