2014-09-26 15:02:46 +00:00
|
|
|
=======
|
|
|
|
|
abilint
|
|
|
|
|
=======
|
|
|
|
|
|
|
|
|
|
abilint parses the native XML representation of an ABI as emitted by
|
|
|
|
|
:doc:`abidw`. Once it has parsed the XML representation of the ABI,
|
|
|
|
|
``abilint`` builds and in-memory model from it. It then tries to save
|
|
|
|
|
it back to an XML form, to standard output. If that read-write
|
|
|
|
|
operation succeeds chances are the input XML ABI representation is
|
|
|
|
|
meaningful.
|
|
|
|
|
|
|
|
|
|
Note that the main intent of this tool to help debugging issues in the
|
|
|
|
|
underlying Libabigail library.
|
|
|
|
|
|
|
|
|
|
Note also that ``abilint`` can also read an `ELF`_ input file, build the
|
|
|
|
|
in-memory model for its ABI, and serialize that model back into XML to
|
|
|
|
|
standard output. In that case, the `ELF`_ input file must be
|
|
|
|
|
accompanied with its debug information in the `DWARF`_ format.
|
|
|
|
|
|
|
|
|
|
Invocation
|
|
|
|
|
==========
|
|
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
2015-10-05 06:40:20 +00:00
|
|
|
abilint [options] [<abi-file1>]
|
2014-09-26 15:02:46 +00:00
|
|
|
|
|
|
|
|
Options
|
|
|
|
|
=======
|
|
|
|
|
|
2015-07-17 09:14:46 +00:00
|
|
|
* ``--help``
|
2014-09-26 15:02:46 +00:00
|
|
|
|
|
|
|
|
Display a short help message and exits.
|
|
|
|
|
|
Add --version option to several libabigail tools
This patch changed the revision number of the libabigail library to
make it reflect the fact that we are not in "release candidate" mode,
before the first 1.0 release. So the revision number is now "rc0".
The configuration manager has been updated to support version numbers
that are strings, so that it can supports things like "rc0".
Then, several libabigail tools have been modified to support the
--version option to display their version number.
* configure.ac: Set the version revision to "rc0".
* doc/manuals/abicompat.rst: Adjust manual for new --version
option.
* doc/manuals/abidiff.rst: Likewise.
* doc/manuals/abidw.rst: Likewise.
* doc/manuals/abilint.rst: Likewise.
* doc/manuals/abipkgdiff.rst: Likewise.
* include/abg-config.h (config::{m_format_minor, m_format_major}):
Make these be strings.
(config::{get,set}_format_minor_version_number): Make these return
strings.
(config::{get,set}_format_major_version_number): Make these return
or take strings.
(abigail_get_library_version): Make this take strings.
* src/abg-config.cc (config::config): Adjust.
(config::{get,set}_format_major_version_number): Make these return
or take strings.
(config::{get,set}_format_minor_version_number): Make these return
strings.
(abigail_get_library_version): Make this take strings.
* include/abg-version.h.in: Make the version variables be strings.
* src/abg-writer.cc (write_translation_unit): The version numbers
are now strings so adjust.
* tools/{abicompat,abidiff,abidw,abilint,abipkgdiff,abisym}.cc
(options::display_version): New data member.
(options::options): Initialize it.
(display_usage): Add documentation for new --version option.
(parse_command_line): Parse new --version option.
(main): Support --version.
Signed-off-by: Dodji Seketeli <dodji@redhat.com>
2015-11-16 10:39:15 +00:00
|
|
|
* `--version | -v`
|
|
|
|
|
|
|
|
|
|
Display the version of the program and exit.
|
|
|
|
|
|
2015-07-17 09:14:46 +00:00
|
|
|
* ``--debug-info-dir`` <*path*>
|
|
|
|
|
|
2014-09-26 15:02:46 +00:00
|
|
|
When reading an `ELF`_ input file which debug information is split
|
|
|
|
|
out into a separate file, this options tells ``abilint`` where to
|
|
|
|
|
find that separate debug information file.
|
|
|
|
|
|
|
|
|
|
Note that *path* must point to the root directory under which the
|
|
|
|
|
debug information is arranged in a tree-like manner. Under Red
|
|
|
|
|
Hat based systems, that directory is usually
|
|
|
|
|
``<root>/usr/lib/debug``.
|
|
|
|
|
|
|
|
|
|
Note also that this option is not mandatory for split debug
|
|
|
|
|
information installed by your system's package manager because
|
|
|
|
|
then ``abidiff`` knows where to find it.
|
|
|
|
|
|
2015-07-17 09:14:46 +00:00
|
|
|
* ``--diff``
|
2014-09-26 15:02:46 +00:00
|
|
|
|
|
|
|
|
For XML inputs, perform a text diff between the input and the
|
|
|
|
|
memory model saved back to disk. This can help to spot issues in
|
|
|
|
|
the handling of the XML format by the underlying Libabigail library.
|
|
|
|
|
|
2015-07-17 09:14:46 +00:00
|
|
|
* ``--noout``
|
2014-09-26 15:02:46 +00:00
|
|
|
|
|
|
|
|
Do not display anything on standard output. The return code of
|
|
|
|
|
the command is the only way to know if the command succeeded.
|
|
|
|
|
|
Drop suppressed ABI artifacts from the IR
This patch allows dropping suppressed ABI artifacts from the in-memory
internal representation right during the DWARF or abixml reading.
In practise, this means that abidw and abilint now have a
--suppressions options to give them suppression specifications. If a
suppression specification that has the "drop" property matches an ABI
artifact (type, function or variable) then that artifact is dropped
from the internal representation. This also applies to abidiff.
Note that now, by default, ABI artifacts (types) that are suppressed
due to the --headers-dir{1,2} option of abidiff are now also dropped
from the IR as well. Incidentally, abidw and abilint tools now have a
--header-dir option too.
* doc/manuals/abidw.rst: Document the new --suppressions and
--headers-dir options off the abidw tool.
* doc/manuals/abilint.rst: Document the new --suppressions and
--headers-dir options on the abilint tool.
* doc/manuals/libabigail-concepts.rst: Document the new "drop" and
"name_not_regexp" properties on suppression directives.
* include/abg-corpus.h (corpus::corpus): Add a default argument to
the path parameter.
* src/abg-suppression-priv.h: New private header file.
* src/Makefile.am: Add the new abg-suppression-priv.h file to
source distribution.
* include/abg-suppression.h ({suppression_base, type_suppression,
function_suppression, variable_suppression}::priv): Make these
public.
(suppression_base::{g,s}et_drops_artifact_from_ir): Declare new
member functions.
(type_suppression::{suppressed_type}): Likewise.
(suppression_base::{names,sonames}_of_binaries_match): Remove
member functions.
(function_suppression::{get_name, set_name, get_name_regex_str,
set_name_regex_str}): Renamed get_function_name,
set_function_name, get_function_name_regex_str,
set_function_name_regex_str into these.
({variable,function}_suppression::{g,s}et_name_not_regex_str):
Declare new member functions.
* src/abg-suppression.cc: Include the new abg-suppression-priv.h
private header.
(class suppression_base::priv, class type_suppression::priv, class
function_suppression::parameter_spec::priv, class
function_suppression::priv, class variable_suppression::priv):
Move these types to that new private header.
(suppression_base::{g,s}et_drops_artifact_from_ir)
(function_suppression::{g,s}et_name_not_regex_str)
(variable_suppression::{g,s}et_name_not_regex_str): New member
functions.
(sonames_of_binaries_match): New static function, taken from
suppression_base::sonames_of_binaries_match.
(names_of_binaries_match): New static function, taken from
suppression_base::names_of_binaries_match.
(suppression_matches_type_no_name): New static function.
(type_suppression::suppresses_type): Adjust
(function_suppression::suppresses_function)
(variable_suppression::suppresses_variable): Adjust. Evaluate the
new "name_not_regexp" property.
(suppression_matches_type_name)
(suppression_matches_type_location)
(suppression_matches_type_name_or_location)
(suppression_matches_function_name)
(suppression_matches_function_sym_name)
(suppression_matches_variable_name)
(suppression_matches_variable_sym_name, suppression_matches_type):
New functions.
(read_type_suppression): Support the new "drop_artifacts" and
"drop" properties.
(read_function_suppression, read_variable_suppression): Support
the new "drop_artifacts", "drop", and "name_not_regexp"
properties.
(function_suppression::{g,s}et_name): Renamed
{g,s}et_function_name into these.
(function_suppression::set_name_not_regex_str): Renamed
{g,s}et_name_regex_str into this.
(function_suppression::suppresses_function_symbol): Adjust.
* include/abg-dwarf-reader.h (add_read_context_suppressions):
Declare new function.
* src/abg-dwarf-reader.cc: Use the new private
abg-suppression-priv.h header file.
(read_context::supprs_): New data member.
(read_context::get_suppressions): New member function.
(read_context::get_die_source): Make this const.
(read_context::tu_die_imported_unit_points_map): Add a const
overload.
(read_context::cur_transl_unit): Renamed current_translation_unit
unit into this;
(read_context::cur_tu): Remove or rename into cur_transl_unit.
(get_scope_for_die, build_translation_unit_and_add_to_ir)
(build_enum_type, build_pointer_type_def, build_reference_type)
(build_function_type, build_array_type, build_function_decl):
Adjust.
(read_context::{suppression_can_match,
suppression_matches_function_sym_name,
suppression_matches_function_name,
suppression_matches_variable_sym_name,
suppression_matches_variable_name,
suppression_matches_type_name_or_location,
suppression_matches_type_name}): Add member functions.
(die_signed_constant_attribute): Remove this as dead code.
(die_location, die_loc_and_name)
(find_import_unit_point_between_dies)
(find_import_unit_point_before_die, get_parent_die): Make the
read_context& parameter be const and adjust as required.
(build_var_decl_if_not_suppressed, function_is_suppressed)
(variable_is_suppressed, type_is_suppressed): Define new static
functions.
(add_read_context_suppressions): Define new function.
(build_class_type_and_add_to_ir): Do not add suppressed static
data members to the IR.
(build_ir_node_from_die): Do not add suppressed enum types, class
types, variables or functions to the IR. Adjust for the
read_context::cur_tu -> read_context::cur_transl_unit rename.
* include/abg-reader.h (read_context_sptr): Declare new type.
(create_native_xml_read_context, read_corpus_from_input)
(add_read_context_suppressions): Declare new functions.
* src/abg-reader.cc: Include the new private
abg-suppression-priv.h header file.
(read_context::m_exported_decls_builder): Renamed
m_exported_decls_builder_ into this.
(read_context::get_exported_decls_builder): Adjust.
(read_context::get_cur_scope): Make this const.
(read_location): Take a const read_context and adjust.
(read_corpus_from_input): Make this non-static.
(build_namespace_decl): Don't abort if trying to add an artifact
to the IR doesn't succeed. It might be suppressed now.
(read_context::{m_path, m_supprs}): New data members.
(read_context::{g,s}et_path): New member functions.
(read_context::{get_suppressions,
suppression_matches_function_name, suppression_can_match,
suppression_matches_function_name,
suppression_matches_function_sym_name,
suppression_matches_variable_name,
suppression_matches_variable_sym_name,
suppression_matches_type_name_or_location}): Likewise.
(add_read_context_suppressions, create_native_xml_read_context)
(read_corpus_from_native_xml): New functions.
(build_function_decl_if_not_suppressed, function_is_suppressed)
(type_is_suppressed, build_var_decl_if_not_suppressed)
(variable_is_suppressed, build_enum_type_decl_if_not_suppressed)
(build_class_decl_if_not_suppressed): New static functions.
(build_class_decl): Add member types that are being built early,
so that their sub-types can be evaluated for suppression. Do not
add suppressed static data members or suppressed member functions
to the IR.
(build_type): Do not add an enum type or a class type to the IR if
they are suppressed.
(handle_enum_type_decl): Do not add an enum type to the IR if its
suppressed.
(handle_var_decl): Likewise for a variable decl.
(handle_function_decl): Likewise for a function decl.
(handle_class_decl): Likewise for a class decl.
* src/abg-tools-utils.cc (handle_fts_entry): Drop suppressed ABI
from the IR.
* tools/abidiff.cc (display_usage): Fix help strings for
--headers-dirs{1,2}.
(set_suppressions): New static function.
(main): Adjust. Release the memory used by read_context early.
* tools/abidw.cc (options::{headers_dir, suppression_paths}):
(display_usage): New help strings for the new --header-dir and
--suppressions options.
(parse_command_line): Parse the new --header-dir and
--suppressions options.
(maybe_check_suppression_files, set_suppressions): New static
functions.
(main): Use the two new functions above. Free the memory used by
the read context before working with the corpus.
* tools/abilint.cc (options::suppression_paths):
(display_usage): New help strings for the new --header-dir and
--suppressions options.
(parse_command_line): Parse the new --header-dir and
--suppressions options.
(maybe_check_suppression_files, set_suppressions): New static
functions.
(main): Use the two new functions above. Free the memory used by
the read context before working with the corpus.
* tests/data/test-diff-suppr/test24-soname-suppr-{2,3].txt:
Adjust.
* tests/data/test-diff-suppr/test29-suppr-6.txt: Likewise.
* tests/data/test-diff-suppr/test29-suppr-8.txt: Likewise.
* tests/data/test-diff-suppr/libtest31-v{0,1}.so: New test input.
* tests/data/test-diff-suppr/libtest31.suppr: Likewise
* tests/data/test-diff-suppr/libtest32-v{0,1}.so: Likewise.
* tests/data/test-diff-suppr/libtest32-0.suppr: Likewise.
* tests/data/test-diff-suppr/libtest33-v{0,1}.so: Likewise.
* tests/data/test-diff-suppr/test31-report-{0,1}.txt: Likewise.
* tests/data/test-diff-suppr/test31-v{0,1}.cc: Likewise.
* tests/data/test-diff-suppr/test32-report-{0,1}.txt: Likewise.
* tests/data/test-diff-suppr/test32-v{0,1}.c: Likewise.
* tests/data/test-diff-suppr/test33-suppr-1.txt: Likewise.
* tests/data/test-diff-suppr/test33-v{0,1}.cc: Likewise.
* tests/data/test-diff-suppr/test33-v{0,1}.h: Likewise.
* tests/data/test-read-dwarf/libtest24-drop-fns-2.so.abi:
Likewise.
* tests/data/test-read-dwarf/libtest24-drop-fns.so: Likewise.
* tests/data/test-read-dwarf/libtest24-drop-fns.so.abi: Likewise.
* tests/data/test-read-dwarf/test24-drop-fns-0.suppr: Likewise.
* tests/data/test-read-dwarf/test24-drop-fns.cc: Likewise.
* tests/data/test-read-write/test28-drop-std-fns.abignore:
Likewise.
* tests/data/test-read-write/test28-drop-std-vars.abignore:
Likewise.
* tests/data/test-read-write/test28-without-std-fns-ref.xml:
Likewise.
* tests/data/test-read-write/test28-without-std-fns.xml: Likewise.
* tests/data/test-read-write/test28-without-std-vars-ref.xml:
Likewise.
* tests/data/test-read-write/test28-without-std-vars.xml:
Likewise.
* tests/data/test-read-write/test28.xml: Likewise.
* tests/data/Makefile.am: Add the new test artifacts to source
distribution.
* tests/test-diff-suppr.cc (in_out_spec): Take the new test inputs
into account.
* tests/test-read-dwarf.cc (Inoutspec::in_suppr_spec_path): New
data member.
(in_out_spec): Adjust. The new test inputs into account.
(set_suppressions): New static function.
(handle_in_out_spec): Adjust.
* tests/test-read-write.cc (Inoutspec::{in_suppr_spec_path,
ref_out_path}): New data members.
(in_out_spec): Adjust. Take new test inputs into account.
(main): Adjust.
Signed-off-by: Dodji Seketeli <dodji@redhat.com>
2016-09-19 16:03:19 +00:00
|
|
|
* ``--suppressions | suppr`` <*path-to-suppression-specifications-file*>
|
|
|
|
|
|
|
|
|
|
Use a :ref:`suppression specification <suppr_spec_label>` file
|
|
|
|
|
located at *path-to-suppression-specifications-file*. Note that
|
|
|
|
|
this option can appear multiple times on the command line. In
|
|
|
|
|
that case, all of the provided suppression specification files are
|
|
|
|
|
taken into account. ABI artifacts matched by the suppression
|
|
|
|
|
specifications are suppressed from the output of this tool.
|
|
|
|
|
|
|
|
|
|
* ``--headers-dir | --hd`` <headers-directory-path-1>
|
|
|
|
|
|
|
|
|
|
Specifies where to find the public headers of the first shared
|
|
|
|
|
library that the tool has to consider. The tool will thus filter
|
|
|
|
|
out types that are not defined in public headers.
|
|
|
|
|
|
2015-07-17 09:14:46 +00:00
|
|
|
* ``--stdin | --``
|
2014-09-26 15:02:46 +00:00
|
|
|
|
|
|
|
|
Read the input content from standard input.
|
|
|
|
|
|
2015-07-17 09:14:46 +00:00
|
|
|
* ``--tu``
|
2014-09-26 15:02:46 +00:00
|
|
|
|
|
|
|
|
Expect the input XML to represent a single translation unit.
|
|
|
|
|
|
|
|
|
|
.. _ELF: http://en.wikipedia.org/wiki/Executable_and_Linkable_Format
|
|
|
|
|
.. _DWARF: http://www.dwarfstd.org
|
