NAME

tools/dev/parrot_api.pl - Display Parrot API (symbols)

SYNOPSIS

% perl tools/dev/parrot_api.pl [libfile]

DESCRIPTION

Displays the API (the visible symbols, code or data) of the Parrot lib.

First lists the Parrot public embedding API as described in the public headers include/parrot/embed.h and include/parrot/extend.h (the API is detected using pattern /^\w+\s+(Parrot_\w+)\(/), then finds out the visible symbols in the Parrot lib (by default blib/lib/libparrot.a), and then cross-references the dubious API symbols according to the below categories. Each symbol is listed with the object file it was found in.

Missing Parrot API

API listed in the public headers or but not defined in the Parrot lib.

Either the API listing is wrong or the implementation is missing.

No Parrot Prefix

API implemented but has no Parrot_ prefix.

If code: if the API is really to be public, prefix it with <Parrot_> (and not something else), if not, considering making it private (local) or splitting it off to a Parrot-private library.

If data, consider making the data either constant or heap and accessible only through a real API.

No Parrot API

API implemented in the lib but not defined in the public headers.

If code, consider making the API private (local) or splitting it off to a Parrot-private library.

If data, consider making the data constant and/or heap and accessible only through a real API.

Uninitialized Modifiable Data

Data symbol that is not initialized with data.

Consider making the data constant and/or heap (and accessed through a real API, data as such is not a good API unless it's constant). Think multithreaded access.

Initialized Modifiable Data

Data symbol that is initialized with data, but modifiable.

Consider making the data constant and/or heap (and accessed through a real API, data as such is not a good API unless it's constant). Think multithreaded access.

DEPENDENCIES

Uses tools/dev/nm.pl to list the symbols.

HISTORY

Author: Jarkko Hietaniemi.