Dpkg::Shlibs: code cleanup after merge and documentation update

man/dpkg-gensymbols.1

@@ -67,8 +67,8 @@ inside a binary package.
 .SS Using symbol tags
 .P
 Symbol tagging is useful for marking symbols that are special in some way.  Any
-symbol can have arbitrary number of tags associated with it. While all tags are
-parsed and stored, only a couple of them are understood by
+symbol can have an arbitrary number of tags associated with it. While all tags are
+parsed and stored, only a some of them are understood by
 \fBdpkg-gensymbols\fR and trigger special handling of the symbols. See
 subsection \fBStandard symbol tags\fR for reference of these tags.
 .P
@@ -90,17 +90,21 @@ first space.
 .P
 The first symbol in the example is named \fItagged quoted symbol\fR and has two
 tags: \fItag1\fR with value \fIi am marked\fR and \fItag name with space\fR
-that is valueless. Then second symbol named \fItagged_unquoted_symbol\fR is
-tagged with the only valueless tag named \fIoptional\fR. The last symbol is an
+that has no value. The second symbol named \fItagged_unquoted_symbol\fR is
+only tagged with the tag named \fIoptional\fR. The last symbol is an
 example of the normal untagged symbol.
 .P
-Since symbol tags are an extension to the \fIdeb-symbols(5)\fR format, they can
-only be part of the symbol file template. When \fBdpkg-gensymbols\fR writes a
-symbol file in \fIdeb-symbols(5)\fR compatible non-template mode (default), it
-fully processes symbols according to the requirements of their standard tags
-and strips all tags from the output. On the contrary, in template mode all
-symbols and their tags (both standard and unknown ones) are written in their
-orignal form as they were loaded.
+Since symbol tags are an extension of the \fIdeb-symbols(5)\fR format, they can
+only be part of the symbols files used in source packages (those files
+should then be seen as templates used to build the symbols files that are
+embedded in binary packages). When
+\fBdpkg-gensymbols\fR is called without the \fI\-t\fR option, it will
+output symbols files compatible to the \fIdeb-symbols(5)\fR format:
+it fully processes symbols according to the requirements of their standard tags
+and strips all tags from the output. On the contrary, in template mode
+(\fI\-t\fR) all symbols and their tags (both standard and unknown ones)
+are kept in the output and are written in their orignal form as they were
+loaded.
 .SS Standard symbol tags
 .TP
 .B optional
@@ -109,36 +113,39 @@ will never cause \fBdpkg-gensymbols\fR to fail. However, disappeared optional
 symbols will continuously appear as MISSING in the diff in each new package
 revision.  This behaviour serves as a reminder for the maintainer that such a
 symbol needs to be removed from the symbol file or readded to the library. When
-the optional symbol, which was previously declared as MISSING, suddently
+the optional symbol, which was previously declared as MISSING, suddenly
 reappears in the next revision, it will be upgraded back to the "existing"
 status with its minimum version unchanged.
 
-This tag is useful for symbols which are private or their disappearance does
+This tag is useful for symbols which are private where their disappearance do
 not cause ABI breakage. For example, most of C++ template instantiations fall
 into this category. Like any other tag, this one may also have an arbitrary
-value which could indicate why the symbol is considered optional.
+value: it could be used to indicate why the symbol is considered optional.
 .TP
 .B arch=\fIarchitecture list\fR
-This tag allows to mark a symbol as arch-specific. When matching the symbol
-file against the library, all arch-specific symbols which do not concern
-current host architecture are treated like they do not exist. If an
-arch-specific symbol disappears from the arch it is concerned about, normal
-procedures for missing symbols apply and it may cause \fBdpkg-gensymbols\fR to
-fail. On the other hand, if the arch-specific symbol is found on the arch that
-it is not supposed to appear on, it is made arch neutral (i.e. the arch tag is
-dropped which triggers the symbol to appear in the diff), but it is not
-considered as new.
+This tag allows to restrict the set of architectures where the symbol
+is supposed to exist. When the symbols list is updated with the symbols
+discovered in the library, all arch-specific symbols which do not concern
+the current host architecture are treated as if they did not exist. If an
+arch-specific symbol matching the current host architecture does not exist
+in the library, normal procedures for missing symbols apply and it may
+cause \fBdpkg-gensymbols\fR to fail. On the other hand, if the
+arch-specific symbol is found when it was not supposed to exist (because
+the current host architecture is not listed in the tag), it is made arch
+neutral (i.e. the arch tag is dropped and the symbol will appear in the
+diff due to this change), but it is not considered as new.
 
-When operating in non-templace mode, only symbols concerned for the current
-host architecture are written to the symbol file. On the contrary, all
-arch-specific symbols (including those from foreign arches) are always written
-to the symbol file template.
+When operating in the default non-template mode, among arch-specific symbols
+only those that match the current host architecture are written to the
+symbols file. On the contrary, all arch-specific symbols (including those
+from foreign arches) are always written to the symbol file when operating
+in template mode.
 
-\fIarchitecture list\fR format is the same as the one used in the
-\fIBuild-Depends\fR field of \fIdebian/control\fR (excluding enclosing []
-brackets). For example, the first symbol from the list below will be considered
-only on alpha, amd64 and ia64 architectures while the second one anywhere but
-armel.
+The format of \fIarchitecture list\fR is the same as the one used in the
+\fIBuild-Depends\fR field of \fIdebian/control\fR (except the enclosing
+square brackets []). For example, the first symbol from the list below
+will be considered only on alpha, amd64 and ia64 architectures while the
+second one anywhere except on armel.
 
  (arch=alpha amd64 ia64)a_64bit_specific_symbol@Base 1.0
  (arch=!armel)symbol_armel_does_not_have@Base 1.0
@@ -174,8 +181,8 @@ file can override any content that appeared before the include directive and
 that any content after the directive can override anything contained in the
 included file. Any symbol (or even another #include directive) in the included
 file can specify additional tags or override values of the inherited tags in
-its tag specification. However, there is no way for the symbol to untag itself
-from the inherited tags.
+its tag specification. However, there is no way for the symbol to remove
+any of the inherited tags.
 .P
 An included file can repeat the header line containing the SONAME of the
 library. In that case, it overrides any header line previously read.
@@ -263,7 +270,7 @@ newer upstream version of your library.
 .TP
 .BI \-t
 Write the symbol file in template mode rather than the format compatible with
-\fIdeb-symbols(5)\fR.The main difference is that in the template mode symbol
+\fIdeb-symbols(5)\fR. The main difference is that in the template mode symbol
 names and tags are written in their original form contrary to the
 post-processed symbol names with tags stripped in the compatibility mode.
 Moreover, some symbols might be omitted when writing a standard

scripts/Dpkg/Shlibs/Symbol.pm

@@ -22,9 +22,7 @@ use warnings;
 use Dpkg::Gettext;
 use Dpkg::Deps;
 use Dpkg::ErrorHandling;
-use Storable qw( dclone );
-
-my $arches64bit = qr/amd64|ia64|alpha/;
+use Storable qw(dclone);
 
 sub new {
     my $this = shift;
@@ -170,10 +168,7 @@ sub delete_tag {
     my ($self, $tagname) = @_;
     if (exists $self->{tags}{$tagname}) {
 	delete $self->{tags}{$tagname};
-	for (my $i = 0; $i <= $#{$self->{tagorder}}; $i++) {
-	    delete $self->{tagorder}->[$i];
-	    last;
-	}
+        $self->{tagorder} = [ grep { $_ ne $tagname } @{$self->{tagorder}} ];
 	return 1;
     }
     return 0;
@@ -237,3 +232,5 @@ sub get_symbolspec {
     $spec .= " $self->{dep_id}" if $self->{dep_id};
     return $spec;
 }
+
+1;

scripts/Dpkg/Shlibs/SymbolFile.pm

@@ -81,7 +81,7 @@ sub new {
     bless $self, $class;
     $self->{arch} = get_host_arch() unless exists $self->{arch};
     $self->clear();
-    if (defined($self->{file})) {
+    if (exists $self->{file}) {
 	$self->load($self->{file}) if -e $self->{file};
     }
     return $self;
@@ -107,7 +107,7 @@ sub add_symbol {
     my $object = (ref $soname) ? $soname : $self->{objects}{$soname};
 
     if (!$symbol->{deprecated} && (my $ver = $symbol->get_wildcard_version())) {
-	error(_g("you can't use wildcards on unversioned symbols: %s"), $_) if $1 eq "Base";
+	error(_g("you can't use wildcards on unversioned symbols: %s"), $_) if $ver eq "Base";
 	$object->{wildcards}{$ver} = $symbol;
 	return 'wildcards';
     } else {
@@ -120,12 +120,11 @@ sub add_symbol {
 sub load {
     my ($self, $file, $seen, $current_object_ref, $base_symbol) = @_;
 
-    my $_new_symbol = sub {
-	if (defined $base_symbol) {
-	    return (ref $base_symbol) ? $base_symbol->clone(@_) : $base_symbol->new(@_);
-	}
-	return Dpkg::Shlibs::Symbol->new(@_);
-    };
+    sub new_symbol {
+        my $base = shift;
+        return $base->clone(@_) if defined $base;
+        return Dpkg::Shlibs::Symbol->new(@_);
+    }
 
     if (defined($seen)) {
 	return if exists $seen->{$file}; # Avoid include loops
@@ -151,7 +150,7 @@ sub load {
 	    }
 	    # Symbol specification
 	    my $deprecated = ($1) ? $1 : 0;
-	    my $sym = &$_new_symbol(deprecated => $deprecated);
+	    my $sym = new_symbol($base_symbol, deprecated => $deprecated);
 	    if ($sym->parse($2)) {
 		$sym->process_tags(arch => $self->{arch});
 		$self->add_symbol($object, $sym);
@@ -164,7 +163,7 @@ sub load {
 	    my $dir = $file;
 	    my $new_base_symbol;
 	    if (defined $tagspec) {
-		$new_base_symbol = &$_new_symbol();
+                $new_base_symbol = new_symbol($base_symbol);
 		$new_base_symbol->parse_tagspec($tagspec);
 	    }
 	    $dir =~ s{[^/]+$}{}; # Strip filename
@@ -241,14 +240,15 @@ sub dump {
 	    print $fh "* $field: $value\n";
         }
 	my $syms = $self->{objects}{$soname}{syms};
-	foreach my $sym (sort { $syms->{$a}->get_symboltempl() cmp $syms->{$b}->get_symboltempl() }
-	                      keys %$syms) {
-	    my $info = $self->{objects}{$soname}{syms}{$sym};
-	    next if $info->{deprecated} and not $opts{with_deprecated};
+	foreach my $name (sort { $syms->{$a}->get_symboltempl() cmp
+                                 $syms->{$b}->get_symboltempl() } keys %$syms) {
+	    my $sym = $self->{objects}{$soname}{syms}{$name};
+	    next if $sym->{deprecated} and not $opts{with_deprecated};
 	    # Do not dump symbols from foreign arch unless dumping a template.
-	    next if !$opts{template_mode} && !$info->arch_is_concerned($self->{arch});
+	    next if not $opts{template_mode} and
+                    not $sym->arch_is_concerned($self->{arch});
 	    # Dump symbol specification. Dump symbol tags only in template mode.
-	    print $fh $info->get_symbolspec($opts{template_mode}), "\n";
+	    print $fh $sym->get_symbolspec($opts{template_mode}) . "\n";
 	}
     }
 }
@@ -270,68 +270,77 @@ sub merge_symbols {
 	}
     }
 
-    unless ($self->{objects}{$soname}) {
+    unless (exists $self->{objects}{$soname}) {
 	$self->create_object($soname, '');
     }
     # Scan all symbols provided by the objects
-    foreach my $sym (keys %dynsyms) {
+    foreach my $name (keys %dynsyms) {
 	my $obj = $self->{objects}{$soname};
-	if (exists $obj->{syms}{$sym}) {
+        my $sym;
+	if (exists $obj->{syms}{$name}) {
 	    # If the symbol is already listed in the file
-	    my $info = $obj->{syms}{$sym};
-	    if ($info->{deprecated}) {
-		# Symbol reappeared somehow
-		$info->{deprecated} = 0;
-		$info->{minver} = $minver if (!$info->is_optional());
+	    $sym = $obj->{syms}{$name};
+	    if ($sym->{deprecated}) {
+		# Symbol reappeared somehow
+		$sym->{deprecated} = 0;
+		$sym->{minver} = $minver if (not $sym->is_optional());
 	    } else {
 		# We assume that the right dependency information is already
 		# there.
-		if (vercmp($minver, $info->{minver}) < 0) {
-		    $info->{minver} = $minver;
+		if (vercmp($minver, $sym->{minver}) < 0) {
+		    $sym->{minver} = $minver;
 		}
 	    }
-	    if (!$info->arch_is_concerned($self->{arch})) {
+	    if (not $sym->arch_is_concerned($self->{arch})) {
 		# Remove arch tag because it is incorrect.
-		$info->delete_tag('arch');
+		$sym->delete_tag('arch');
 	    }
 	} else {
 	    # The symbol is new and not present in the file
-	    my $info;
-	    my $symobj = $dynsyms{$sym};
-	    my $w_obj = $obj->{wildcards}{$symobj->{version}};
-	    if ($symobj->{version} and defined $w_obj
-	        and $w_obj->arch_is_concerned($self->{arch})) {
-		# Get the info from wildcards
-		$info = $obj->{wildcards}{$symobj->{version}};
-		$self->{used_wildcards}++;
-	    } else {
-		# New symbol provided by the current release
-		$info = Dpkg::Shlibs::Symbol->new(symbol => $sym, minver => $minver);
-	    }
-	    $self->add_symbol($obj, $info);
+	    my $symobj = $dynsyms{$name};
+            $sym = $self->symbol_match_wildcard($soname, $name, $symobj->{version});
+            if (not defined $sym) {
+                # Symbol without any special info as no wildcard did match
+                $sym = Dpkg::Shlibs::Symbol->new(symbol => $name,
+                                                 minver => $minver);
+            }
+	    $self->add_symbol($obj, $sym);
 	}
     }
 
     # Scan all symbols in the file and mark as deprecated those that are
     # no more provided (only if the minver is bigger than the version where
     # the symbol was introduced)
-    foreach my $sym (keys %{$self->{objects}{$soname}{syms}}) {
-	if (! exists $dynsyms{$sym}) {
-	    my $info = $self->{objects}{$soname}{syms}{$sym};
+    foreach my $name (keys %{$self->{objects}{$soname}{syms}}) {
+	if (not exists $dynsyms{$name}) {
+	    my $sym = $self->{objects}{$soname}{syms}{$name};
 
 	    # Ignore symbols from foreign arch
-	    next if (!$info->arch_is_concerned($self->{arch}));
+	    next if not $sym->arch_is_concerned($self->{arch});
 
-	    if ($info->{deprecated}) {
+	    if ($sym->{deprecated}) {
 		# Bump deprecated if the symbol is optional.
-		$info->{deprecated} = $minver if ($info->is_optional());
-	    } elsif (vercmp($minver, $info->{minver}) > 0) {
-		$info->{deprecated} = $minver;
+                # XXX: Why?
+		$sym->{deprecated} = $minver if $sym->is_optional();
+	    } elsif (vercmp($minver, $sym->{minver}) > 0) {
+		$sym->{deprecated} = $minver;
 	    }
 	}
     }
 }
 
+sub symbol_match_wildcard {
+    my ($self, $soname, $name, $version) = @_;
+    my $obj = $self->{objects}{$soname};
+    if ($version and exists $obj->{wildcards}{$version}) {
+        my $w_sym = $obj->{wildcards}{$version};
+        return undef unless $w_sym->arch_is_concerned($self->{arch});
+        $self->{used_wildcards}++;
+        return $w_sym->clone(symbol => $name . '@' . $version);
+    }
+    return undef;
+}
+
 sub is_empty {
     my ($self) = @_;
     return scalar(keys %{$self->{objects}}) ? 0 : 1;
@@ -427,10 +436,10 @@ sub get_new_symbols {
 	my $mysyms = $self->{objects}{$soname}{syms};
 	next if not exists $ref->{objects}{$soname};
 	my $refsyms = $ref->{objects}{$soname}{syms};
-	foreach my $sym (grep {  not $mysyms->{$_}{deprecated} and
-	                         not $mysyms->{$_}->is_optional() and
-	                         $mysyms->{$_}->arch_is_concerned($self->{arch}) }
-	    keys %{$mysyms})
+	foreach my $sym (grep { not $mysyms->{$_}{deprecated} and
+	                        not $mysyms->{$_}->is_optional() and
+	                        $mysyms->{$_}->arch_is_concerned($self->{arch})
+                              } keys %{$mysyms})
 	{
 	    if ((not exists $refsyms->{$sym}) or
 		$refsyms->{$sym}{deprecated} or