Re: Python pretty-printing [5/6]

[Tom Tromey <tromey at redhat dot com>]

Eli> I couldn't quite understand the importance of the version numbers, and
Eli> how that would allow GDB to have multiple versions of the same
Eli> pretty-printer.  I asked myself how the ``right'' version will be
Eli> selected in that case.  Is the way this works documented somewhere
Eli> else? if so, a cross-reference here would be good.  If not, I think we
Eli> need to say a few words about that.

I modified a couple of paragraphs; the text now reads:

    We recommend that you put your core pretty-printers into a Python
    package.  If your pretty-printers are for use with a library, we
    further recommend embedding a version number into the package name.
    This practice will enable @value{GDBN} to load multiple versions of
    your pretty-printers at the same time, because they will have
    different names).

    You should write auto-loaded code (@pxref{Auto-loading}) such that it
    can be evaluated multiple times without changing its meaning.  An
    ideal auto-load file will consist solely of @code{import}s of your
    printer modules, followed by a call to a register pretty-printers with
    the current objfile.

    Taken as a whole, this approach will scale nicely to multiple
    inferiors, each potentially using a different library version.
    Embedding a version number in the Python package name will ensure that
    @value{GDBN} is able to load both sets of printers simultaneously.
    Then, because the search for pretty-printers is done by objfile, and
    because your auto-loaded code took care to register your library's
    printers with a specific objfile, @value{GDBN} will find the correct
    printers for the specific version of the library used by each
    inferior.

    To continue the @code{std::string} example (@pxref{Pretty Printing}),
    this code might appear in @code{gdb.libstdcxx.v6}:

    @smallexample
    [...]


>> +You should write auto-loaded code such that it can be evaluated
>> +multiple times without changing its meaning.

Eli> Here, I suggest a cross-reference to where auto-loading is described.

I added this.

Tom