tools/dev/parrot_api.pl - Verify Parrot API (symbols)
% perl tools/dev/parrot_api.pl [libfile]
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.
/^\w+\s+(Parrot_\w+)\(/
Good things are listed with +++ (at the moment the only good thing is Parrot APIs definitions their declarations), bad things are listed with ---.
+++
---
The API is listed in the public headers but not defined in the Parrot lib.
Either the API listing is wrong or the implementation is missing.
The API is implemented but has no Parrot_ prefix (or prefix deemed Parroty enough, like PDB_, PF_, PIO_, and PackFile).
Parrot_
PDB_
PF_
PIO_
PackFile
If code: see "Public or Private".
If data: at least consider limiting its scope by making it file static or function static, but see "Data is not an API".
The API is defined in the lib but not defined in the public headers.
If data: see "Data is not an API".
Data symbol that is not initialized with any data.
See "Data is not an API".
Data symbol that is initialized with data, but modifiable.
You can sometimes use C preprocessor defines to shorten the API names but please do carefully contain the effect so that only the Parrot itself sees those shortened definitions, the defines must not leak to the outside world.
If the API is really meant to be public, prefix it with <Parrot_>, or something else specific enough, preferably specific to Parrot, not some generic term. Currently acceptable prefixes are /^(Parrot|PDB|PF|PIO|PackFile)_/.
/^(Parrot|PDB|PF|PIO|PackFile)_/
If the API is not meant to be public, considering making it private (file static, and prefix it with S_, but still do have a prototype for it).
S_
Consider making the data const(ant), or moving it into the heap (and accessed through a real API that takes care of synchronization, data as such is not a good API unless it's constant).
Think multithreaded access, or just plain reentrancy (think recursion).
Often you can collect a group of data fields into a "context" (or "descriptor", "handle", "session", "state") structure that is either explicitly passed between functions or implicitly retrieved from a global API. Encapsulating data like this is good: it allows passing, synchronzing, and duplicating state much easier, and makes it clearer into which context the data belongs.
For APIs purely internal to Parrot, try using const in function prototypes as often as possible to catch inadvertent data modification by callers. For APIs that cross into the operating system and/or external libraries, you usually cannot go overly const because of portability issues.
const
Make your strings and arrays of strings (or similar inlined data) const -- for the latter, remember that you need two consts:
const char* const foo[] = { "foo", "bar" };
Uses tools/dev/nm.pl to list the symbols.
Write a pollution detector also for the C preprocessor: also in that namespace, Parrot should only present Parrot_ (and similar) symbols to the outside world. Be careful to only scan Parrot's defines, not system's or third parties'.
Author: Jarkko Hietaniemi.
To install Ruby, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Ruby
CPAN shell
perl -MCPAN -e shell install Ruby
For more information on module installation, please visit the detailed CPAN module installation guide.