abimap package

Submodules

abimap.main module

Entrypoint used to generate the command line application

abimap.main.main()

abimap.symver module

class abimap.symver.Map(filename=None, logger=None)

Bases: object

A linker map (version script) representation

This class is an internal representation of a version script. It is intended to be initialized by calling the method read() and passing the path to a version script file. The parser will parse the file and check the file syntax, creating a list of releases (instances of the Release class), which is stored in releases.

Variables:

• init – Indicates if the object was initialized by calling read()
• logger – The logger object; can be specified in the constructor
• filename – Holds the name (path) of the file read
• lines – A list containing the lines of the file

all_global_symbols()

Returns all global symbols from all releases contained in the Map object

Returns:A set containing all global symbols in all releases

check()

Check the map structure.

Reports errors found in the structure of the map in form of warnings.

dependencies()

Construct the dependencies lists

Contruct a list of dependency lists. Each dependency list contain the names of the releases in a dependency path. The heads of the dependencies lists are the releases not refered as a previous release in any release.

Returns:A list containing the dependencies lists

duplicates()

Find and return a list of duplicated symbols for each release

If no duplicates are found, return an empty list

Returns:A list of tuples [(release, [(scope, [duplicates])])]

guess_latest_release()

Try to guess the latest release

It uses the information found in the releases present in the version script read. It tries to find the latest release using heuristics.

Returns:A list [release, prefix, suffix, version[CUR, AGE, REV]]

guess_name(new_release, abi_break=False, guess=False)

Use the given information to guess the name for the new release

The two parts necessary to make the release name:

• The new prefix: Usually the library name (e.g. LIBX)
• The new suffix: The version information (e.g. _1_2_3)

If the new release is not provided, try a guess strategy:

If the new prefix is not provided:

1. Try to find a common prefix between release names
2. Try to find latest release

If the new suffix is not provided:

1. Try to find latest release version and bump

Parameters:

• new_release – String, the name of the new release. If this is
• abi_break – Boolean, indicates if the ABI was broken
• guess – Boolean, indicates if should try to guess

Returns:

The guessed release name (new prefix + new suffix)

parse(lines)

A simple version script parser.

This is the main initializator of the releases list. This simple parser receives the lines of a given version script, check its syntax, and construct the list of releases. Some semantic aspects are checked, like the existence of the * wildcard in global scope and the existence of duplicated release names.

It works by running a finite state machine:

The parser states. Can be:

0. name: The parser is searching for a release name or EOF
1. opening: The parser is searching for the release opening {
2. element: The parser is searching for an identifier name or }
3. element_closer: The parser is searching for : or ;
4. previous: The parser is searching for previous release name
5. previous_closer: The parser is searching for ;

Parameters:lines – The lines of a version script file

read(filename)

Read a linker map file (version script) and store the obtained releases

Obtain the lines of the file and calls parse() to parse the file

Parameters:filename – The path to the file to be read Raises:ParserError – Raised when a syntax error is found in the file

sort_releases_nice(top_release)

Sort the releases contained in a map file putting the dependencies of top_release first. This changes the order of the list in releases.

Parameters:top_release – The release whose dependencies should be prioritized

exception abimap.symver.ParserError(filename, context, line, column, message)

Bases: exceptions.Exception

Exception type raised by the map parser

Used mostly to keep track where an error was found in the given file

Variables:

• filename – The name (path) of the file being parsed
• context – The line where the error was detected
• line – The index of the line where the error was detected
• column – The index of the column where the error was detected
• message – The error message

class abimap.symver.Release

Bases: object

A internal representation of a release version and its symbols

A release is usually identified by the library name (suffix) and the release version (suffix). A release contains symbols, grouped by their visibility scope (global or local).

In this class the symbols of a release are stored in a list of dictionaries mapping a visibility scope name (e.g. “global”) to a list of the contained symbols:

([{"global": [symbols]}, {"local": [local_symbols]}])

Variables:

• name – The release name
• previous – The previous release to which this release is dependent
• symbols – The symbols contained in the release, grouped by the visibility scope.

duplicates()

class abimap.symver.Single_Logger

Bases: object

A singleton logger for the module

This class is a singleton logger factory. It takes advantage of the uniqueness of class attributes to hold a unique instance of the logger for the module. It logs to the default log output, and prints WARNING and ERROR messages to stderr. It allows the caller to provide a file to receive the log (the messages will be logged by all handlers: to stderr if WARNING or ERROR, to default log, and to the provided file)

Variables:__instance – Holds the unique instance given by the factory when called.

classmethod getLogger(name, filename=None)

Get the unique instance of the logger

Parameters:name – The name of the module (usually just __name__) Returns:An instance of logging.Logger

abimap.symver.bump_version(version, abi_break)

Bump a version depending if the ABI was broken or not

If the ABI was broken, CUR is bumped; AGE and REV are set to zero. Otherwise, CUR is kept, AGE is bumped, and REV is set to zero. This also works with versions without the REV component (e.g. [1, 4, None])

Parameters:

• version – A list in format [CUR, AGE, REV]
• abi_break – A boolean indication if the ABI was broken

Returns:

A list in format [CUR, AGE, REV]

abimap.symver.check(args)

‘check’ subcommand

Check the content of a symbol version script

Parameters:args – Arguments given in command line parsed by argparse

abimap.symver.check_files(out_arg, out_name, in_arg, in_name, dry)

Check if output and input are the same file. Create a backup if so.

Parameters:

• out_arg – The name of the option used to receive output file name
• out_name – The received string as output file path
• in_arg – The name of the option used to receive input file name
• in_name – The received string as input file path

abimap.symver.clean_symbols(symbols)

Receives a list of lines read from the input and returns a list of words

Parameters:symbols – A list of lines containing symbols Returns:A list of the obtained symbols

abimap.symver.get_arg_parser()

Get a parser for the command line arguments

The parser is capable of checking requirements for the arguments and possible incompatible arguments.

Returns:A parser for command line arguments. (argparse.ArgumentParser)

abimap.symver.get_info_from_args(args)

Get the release information from the provided arguments

It is possible to set the new release name to be used through the command line arguments.

Parameters:args – Arguments given in command line parsed by argparse

abimap.symver.get_info_from_release_string(release)

Get the information from a release name

The given string is split in a prefix (usually the name of the lib) and a suffix (the version part, e.g. ‘_1_4_7’). A list with the version info converted to ints is also contained in the returned list.

Parameters:release – A string in format ‘LIBX_1_0_0’ or similar Returns:A list in format [release, prefix, suffix, [CUR, AGE, REV]]

abimap.symver.get_version_from_string(version_string)

Get the version numbers from a string

Parameters:version_string – A string composed by numbers separated by non alphanumeric characters (e.g. 0_1_2 or 0.1.2) Returns:A list of the numbers in the string

abimap.symver.new(args)

‘new’ subcommand

Create a new version script file containing the provided symbols.

Parameters:args – Arguments given in command line parsed by argparse

abimap.symver.update(args)

Given the new list of symbols, update the map

The new map will be generated by the following rules:

• If new symbols are added, a new release is created containing the new symbols. This is a compatible update.
• If a previous existing symbol is removed, then all releases are unified in a new release. This is an incompatible change, the SONAME of the library should be bumped

The symbols provided are considered all the exported symbols in the new version. Such set of symbols is compared to the previous existing symbols. If symbols are added, but nothing removed, it is a compatible change. Otherwise, it is an incompatible change and the SONAME of the library should be bumped.

If –add is provided, the symbols provided are considered new symbols to be added. This is a compatible change.

If –remove is provided, the symbols provided are considered the symbols to be removed. This is an incompatible change and the SONAME of the library should be bumped.

Parameters:args – Arguments given in command line parsed by argparse

abimap.symver.version(args)

‘version’ subcommand

Prints and returns the program name and version.

Parameters:args – Arguments given in command line parsed by argparse Returns:A string containing the program name and version

Module contents