Provided by: dpkg-dev_1.18.4ubuntu1.7_all 
名前
dpkg-gensymbols - シンボルファイル (共有ライブラリの依存情報) の生成
書式
dpkg-gensymbols [option...]
説明
dpkg-gensymbols は一時的なビルドツリー (デフォルトでは debian/tmp) 以下にあるライブラリを
探しだし、それらの情報を記載した symbols ファイルを生成する。このファイルが空でない場
合、ファイルはビルドツリーの DEBIAN サブディレクトリにインストールされ、最終的にパッケージ
の制御情報ファイルに含まれる。
これらのファイルの生成の際には、入力情報として、メンテナによって提供されるシンボルファイル
が用いられる。シンボルファイルとして、以下のファイルが確認される (最初に見つかったファイル
が用いられる):
• debian/package.symbols.arch
• debian/symbols.arch
• debian/package.symbols
• debian/symbols
The main interest of those files is to provide the minimal version associated to each
symbol provided by the libraries. Usually it corresponds to the first version of that
package that provided the symbol, but it can be manually incremented by the maintainer if
the ABI of the symbol is extended without breaking backwards compatibility. It's the
responsibility of the maintainer to keep those files up-to-date and accurate, but
dpkg-gensymbols helps with that.
生成されたシンボルファイルがメンテナが提供するものと異なっていた場合、dpkg-gensymbols は双
方の差分を表示する。相違点が大量の場合は、処理を失敗させる (どの程度の量を大量と見なすかに
ついては調整可能である。-c オプションを参照のこと)。
シンボルファイルのメンテナンス
The symbols files are really useful only if they reflect the evolution of the package
through several releases. Thus the maintainer has to update them every time that a new
symbol is added so that its associated minimal version matches reality. The diffs
contained in the build logs can be used as a starting point, but the maintainer,
additionally, has to make sure that the behaviour of those symbols has not changed in a
way that would make anything using those symbols and linking against the new version, stop
working with the old version. In most cases, the diff applies directly to the
debian/package.symbols file. That said, further tweaks are usually needed: it's
recommended for example to drop the Debian revision from the minimal version so that
backports with a lower version number but the same upstream version still satisfy the
generated dependencies. If the Debian revision can't be dropped because the symbol really
got added by the Debian specific change, then one should suffix the version with ‘~’.
シンボルファイルに何らかのパッチを適用する前に、メンテナは本当にそれが必要かどうかを再度確
認すること。公開シンボルが削除されることは想定されていないため、パッチは新しい行を追加する
だけに留めるのが理想である。
Note that you can put comments in symbols files: any line with ‘#’ as the first character
is a comment except if it starts with ‘#include’ (see section Using includes). Lines
starting with ‘#MISSING:’ are special comments documenting symbols that have disappeared.
Do not forget to check if old symbol versions need to be increased. There is no way
dpkg-gensymbols can warn about this. Blindly applying the diff or assuming there is
nothing to change if there is no diff, without checking for such changes, can lead to
packages with loose dependencies that claim they can work with older packages they cannot
work with. This will introduce hard to find bugs with (partial) upgrades.
#PACKAGE# 置換の使用
稀ではあるが、アーキテクチャによってライブラリ名が異なる場合がある。シンボルファイルにパッ
ケージ名をハードコードすることを避けるため、#PACKAGE# マークを使用することができる。これは
シンボルファイルのインストール時に実際のパッケージ名に置換される。#MINVER# マークと異な
り、#PACKAGE# がバイナリパッケージ内のシンボルファイルに現れることは決してない。
シンボルタグの使用
Symbol tagging is useful for marking symbols that are special in some way. Any symbol can
have an arbitrary number of tags associated with it. While all tags are parsed and stored,
only some of them are understood by dpkg-gensymbols and trigger special handling of the
symbols. See subsection Standard symbol tags for reference of these tags.
タグはシンボル名の前に設置され (空白文字を間にいれることはできない)、( から始まり) で終わ
り、間に最低 1 つのタグを記載する必要がある。複数のタグは | 文字で区切る。各タグには、タグ
名との間を = 文字で区切った形式で値を設定することもできる。タグ名と値には、特別な文字 ) |
= を除き、任意の文字を含めることができる。タグに続くシンボル名には、' もしくは " 文字でク
オートすることで、空白文字を含めることができる。ただし、シンボルにタグが設定されていなかっ
た場合、クオートはシンボル名の一部と見なされ、最初のスペースまでがシンボル名と認識される。
(tag1=i am marked|tag name with space)"tagged quoted symbol"@Base 1.0
(optional)tagged_unquoted_symbol@Base 1.0 1
untagged_symbol@Base 1.0
設定例の 1 番目のシンボルは tagged quoted symbol という名前であり、i am marked という値を
持つ tag1 というタグと tag name with space という値を持たないタグの 2 つが設定されてい
る。2 番目のシンボルは tagged_unquoted_symbol という名前で optional という名前のタグが設定
されている。最後のシンボルは一般的なタグのないシンボルの例である。
Since symbol tags are an extension of the deb-symbols(5) 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
dpkg-gensymbols is called without the -t option, it will output symbols files compatible
to the deb-symbols(5) 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
(-t) all symbols and their tags (both standard and unknown ones) are kept in the output
and are written in their original form as they were loaded.
標準シンボルタグ
optional
A symbol marked as optional can disappear from the library at any time and that
will never cause dpkg-gensymbols 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, suddenly reappears in the next revision,
it will be upgraded back to the “existing” status with its minimum version
unchanged.
このタグはシンボルの削除が ABI の互換性を損なわないようなプライベートなシンボルに有
用である。例えば、C++ テンプレートのインスタンス化の多くがこれに分類される。その他
のタグと同様、このタグには任意の値を設定することができる。これはシンボルが optional
と見なされる理由を示すために使用することができる。
arch=architecture-list
arch-bits=architecture-bits
arch-endian=architecture-endianness
These tags allow one to restrict the set of architectures where the symbol is
supposed to exist. The arch-bits and arch-endian tags are supported since dpkg
1.18.0. 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 dpkg-gensymbols 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 or does not
match the endianness and bits), it is made arch neutral (i.e. the arch, arch-bits
and arch-endian tags are dropped and the symbol will appear in the diff due to this
change), but it is not considered as new.
デフォルトの非テンプレートモードで動作する際には、アーキテクチャ固有のシンボルの中
で、現在のホストのアーキテクチャに合致するもののみがシンボルファイルに書き込まれ
る。一方、テンプレートモードで動作している場合は、アーキテクチャ固有のシンボルのす
べて (異なるアーキテクチャのものも含む) がシンボルファイルに書き込まれる。
The format of architecture-list is the same as the one used in the Build-Depends
field of debian/control (except the enclosing square brackets []). For example, the
first symbol from the list below will be considered only on alpha, any-amd64 and
ia64 architectures, the second only on linux architectures, while the third one
anywhere except on armel.
(arch=alpha any-amd64 ia64)a_64bit_specific_symbol@Base 1.0
(arch=linux-any)linux_specific_symbol@Base 1.0
(arch=!armel)symbol_armel_does_not_have@Base 1.0
The architecture-bits is either 32 or 64.
(arch-bits=32)a_32bit_specific_symbol@Base 1.0
(arch-bits=64)a_64bit_specific_symbol@Base 1.0
The architecture-endianness is either little or big.
(arch-endian=little)a_little_endian_specific_symbol@Base 1.0
(arch-endian=big)a_big_endian_specific_symbol@Base 1.0
Multiple restrictions can be chained.
(arch-bits=32|arch-endian=little)a_32bit_le_symbol@Base 1.0
ignore-blacklist
dpkg-gensymbols は、ツールチェインの詳細な実装の副作用以外では通常存在しないた
め、シンボルファイル中に存在すべきではないシンボルからなる内部的なブラックリストを
持っている。なんらかの理由により、シンボルファイルにこうしたシンボルの一つを本気で
加えたい場合は、ignore-blacklist タグをシンボルに付ける必要がある。これは、 libgcc
のような低レベルなツールチェインのライブラリの一部で必要な場合がある。
c++ c++ シンボルパターンを示す。以下の シンボルパターンの使用 サブセクションも参照のこ
と。
symver symver (シンボルバージョン) シンボルパターンを示す。以下の シンボルパターンの使用
サブセクションも参照のこと。
regex regex シンボルパターンを示す。以下の シンボルパターンの使用 サブセクションも参照の
こと。
シンボルパターンの使用
標準シンボルと異なり、パターンにはライブラリがエクスポートする複数の実シンボルが含まれう
る。dpkg-gensymbols は、シンボルファイルによって特定のシンボルと関連付けられていない各実シ
ンボルについて、パターンとのマッチングを行う。最初にパターンにマッチした時点で、シンボルの
基本的な機能として、パターンのタグおよび属性が用いられる。パターンにマッチしなかった場
合、そのシンボルは新しいシンボルと見なされる。
A pattern is considered lost if it does not match any symbol in the library. By default
this will trigger a dpkg-gensymbols failure under -c1 or higher level. However, if the
failure is undesired, the pattern may be marked with the optional tag. Then if the pattern
does not match anything, it will only appear in the diff as MISSING. Moreover, like any
symbol, the pattern may be limited to the specific architectures with the arch tag. Please
refer to Standard symbol tags subsection above for more information.
Patterns are an extension of the deb-symbols(5) format hence they are only valid in symbol
file templates. Pattern specification syntax is not any different from the one of a
specific symbol. However, symbol name part of the specification serves as an expression to
be matched against name@version of the real symbol. In order to distinguish among
different pattern types, a pattern will typically be tagged with a special tag.
現在のところ、dpkg-gensymbols は 3 つの基本的なパターンタイプをサポートしている:
c++
このパターンは c++ タグを示す。これは (c++filt(1) ユーティリティによって出力された) デ
コードされた (demangled) シンボル名による C++ シンボルにのみマッチする。このパターン
は、デコードされた名前は同一であるが、エンコードされたシンボル名がアーキテクチャによっ
てばらばらであるようなシンボルにマッチさせたい場合に非常に有用である。こうしたシンボル
の一つのグループが、non-virtual thunks と呼ばれるもので、エンコードされた名前にアーキテ
クチャ依存のオフセットが埋め込まれるシンボルである。このパターンの実例として、ダイアモ
ンド継承において、仮想継承でないサンクシンボルを必要とする仮想デストラクタが挙げられ
る。32 ビットアーキテクチャ上で _ZThn8_N3NSB6ClassDD1Ev@Base となるシンボルが 64 ビット
では _ZThn16_N3NSB6ClassDD1Ev@Base となってしまう場合であっても、これらを単一の c++ パ
ターンでマッチさせることができる。
libdummy.so.1 libdummy1 #MINVER#
[...]
(c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0
[...]
上記のデコードされた名前は、以下のコマンドを実行することで取得できる:
$ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt
エンコードされた名前がライブラリ内で一意に定義されていた場合であっても、デコードされた
名前が一位である必要はない。幾つかの実シンボルのデコードされた名前が同じである場合もあ
る。これは、例えば仮想継承でないサンクシンボルに複雑な継承の設定が行われている場合
や、大半のコンストラクタとデストラクタについて言える (ただし、g++ は、これらに対して通
常 2 つの実シンボルを生成する)。ただし、こうした衝突は ABI レベルで発生しているものであ
り、シンボルファイルの品質を低下させるものではない。
symver
このパターンは、symver タグを示す。きちんとメンテナンスされているライブラリでは、シンボ
ルがバージョン管理されており、各バージョンがシンボルの追加されたアップストリームのバー
ジョンに対応付けられている。この場合、symver パターンを使用することで、特定のバージョン
に対応付けられた任意のシンボルにマッチさせることが可能である。以下に例を示す:
libc.so.6 libc6 #MINVER#
(symver)GLIBC_2.0 2.0
[...]
(symver)GLIBC_2.7 2.7
access@GLIBC_2.0 2.2
GLIBC_2.0 および GLIBC_2.7 のバージョンに対応付けられたすべてのシンボル
は、access@GLIBC_2.0 シンボルを除き、最低バージョンが各々 2.0 および 2.7 となる。後者
は、"(symver)GLIBC_2.0" パターンにマッチするが、libc6 バージョン 2.2 が最低限の依存関係
となる。これは、シンボルの指定がパターンによるマッチより優先されるためである。
古い形式のワイルドカードのパターン (シンボル名フィールドで "*@version" を指定)
は、"(symver|optional)version" は、まだサポートされているが、廃止予定となっている点に留
意すること。例えば、"*@GLIBC_2.0 2.0" という表記は、同じ動作をさせたいのであれ
ば、"(symver|optional)GLIBC_2.0 2.0" に修正すべきである。
regex
正規表現パターンは regex タグで指定される。これは、シンボル名フィールドで指定された
perl 形式の正規表現にマッチする。正規表現であるため、^ 文字から始めることを忘れないこ
と、さもなくば、実シンボル name@version の任意の部分にマッチする可能性がある。以下に例
を示す:
libdummy.so.1 libdummy1 #MINVER#
(regex)"^mystack_.*@Base$" 1.0
(regex|optional)"private" 1.0
1 番目のパターンには、"mystack_new@Base", "mystack_push@Base", "mystack_pop@Base" のよ
うなシンボルがマッチするが、"ng_mystack_new@Base" はマッチしない。2 番目のパターンに
は、"private" という文字列を含む名前のすべてのシンボルにマッチし、マッチしたシンボル名
が optional タグに引き継がれる。
前述した基本的なパターンは、整合性がとれる限り複合して用いてもよい。その場合、パターンはタ
グで指定された順に処理される。以下の例において、
(c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0
(regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0
両方のパターンとも、"_ZN3NSA6ClassA7Private11privmethod1Ei@Base" シンボルと
"_ZN3NSA6ClassA7Private11privmethod2Ei@Base" シンボルにマッチする。1 番目のパターンで
は、本来のシンボル名が 1 番目に C++ シンボルにデコードされ、デコードされたシンボル名を用い
て正規表現によりマッチが行われる。一方、2 番目のパターンにマッチした場合、正規表現が本来の
シンボル名にマッチし、その後そのシンボル名がデコードされた上で、C++ シンボル名として評価さ
れる。いずれかの基本パターンのマッチングに失敗すると、全体が失敗と見なされる。そのため、例
えば "__N3NSA6ClassA7Private11privmethod\dEi@Base" は、正しい C++ シンボルでないため、どち
らのパターンにもマッチしないと見なされる。
一般的に、すべてのパターンはエイリアス (基本的な c++ と symver) と汎用パターン (regex およ
び任意の基本パターンの組み合わせ) という 2 つのグループに大別される。基本的なエイリアス
ベースのパターンに対するマッチングは (O(1)) であるため高速であるが、汎用パターンは各シンボ
ルに対して O(N) (N - 汎用的なパターンの数) となる。そのため、汎用パターンを多用しすぎない
ことを推奨する。
組み合わせのパターンが同じ実シンボルにマッチした場合、エイリアス (c++、symver の順) が汎用
パターンよりも優先される。汎用パターンは、マッチングに成功するまで、シンボルファイルのテン
プレートに記載された順にマッチングを試みる。ただし、テンプレートファイルのエントリに記載さ
れた順序を手作業で修正することは推奨されない。これは、dpkg-gensymbols が差分を生成する際
に、名前が英数字順になっていることを前提としているためである。
include の使用
エクスポートされた一連のシンボルがアーキテクチャにより異なっている場合、単一のシンボルファ
イルでは不便な場合がある。その場合、include ディレクティブにより、以下のような方法で、利便
性を向上させることができる場合もある:
• 外出ししたファイルの共通部分を取り出した上で、include ディレクティブを次にように用い
て、該当ファイルを package.symbols.arch ファイルに挿入する:
#include "packages.symbols.common"
• include ディレクティブには、他のシンボル同様タグを付加してもよい:
(tag|..|tagN)#include "file-to-include"
結果として、file-to-include から挿入されるすべてのシンボルが tag ... tagN にデフォルト
でタグづけされたと見なされる。この機能を用いて、以下のように共通の package.symbols
ファイルを作成した上で、それをアーキテクチャ固有のシンボルファイルに挿入することもでき
る:
common_symbol1@Base 1.0
(arch=amd64 ia64 alpha)#include "package.symbols.64bit"
(arch=!amd64 !ia64 !alpha)#include "package.symbols.32bit"
common_symbol2@Base 1.0
シンボルファイルは 1 行ずつ読み取られ、include ディレクティブがあれば、都度処理される。つ
まり、挿入されるファイルの設定で include ディレクティブの前に存在していた設定が上書きされ
る可能性もあり、include ディレクティブの後に存在している設定により、挿入されたファイルの設
定が上書きされることもある。挿入されるファイルに存在する任意のシンボル (別の #include ディ
レクティブを含む) では、新しいタグを追加することも、継承されたタグの値を上書きすることもで
きるが、シンボルから継承されたタグを削除することはできない。
挿入されたファイルで、ライブラリの SONAME を含むヘッダ行を繰り返すことも可能である。その場
合、そこまで読み込んだヘッダ行はすべて上書きされる。ただし、一般的に、ヘッダ行の重複は避け
るべきである。これを避ける方法の一つを以下に示す:
#include "libsomething1.symbols.common"
arch_specific_symbol@Base 1.0
推奨されるライブラリ管理
適切に維持されているライブラリの特徴を以下に示す:
• API の変更がなく (公開シンボルの消失は一切なく、新しい公開シンボルが追加されるのみであ
る)、SONAME の変更以外に互換性を損なう API の変更が行われない。
• 理想的には、ABI の安定性を維持するため、内部的な変更と API の拡張を除いてシンボルの
バージョン管理が行われている。
• 非公開シンボルをエクスポートしない (そうしたシンボルは暫定で optional のタグづけをして
おくこともできる)。
シンボルファイルをメンテナンスする上で、追加されたり削除されたりしたシンボルを把握すること
は難しくないが、互換性のない API や ABI の変更を把握するのは難しい。メンテナにはアップスト
リームの changelog を読み込んで、推奨されるライブラリ管理のルールが守られていない点を探し
だすことが求められる。潜在的な問題が発見されたら、アップストリームの開発者に通知するこ
と。Debian 独自の暫定対処よりも、アップストリーム側での修正が常に望ましい。
オプション
-Ppackage-build-dir
debian/tmp の代わりに package-build-dir 内を確認する。
-ppackage
パッケージ名を定義する。debian/control ファイルに複数のバイナリパッケージが記載され
ている (もしくは debian/control ファイルが存在しない) 場合は必須である。
-vversion
パッケージのバージョンを定義する。デフォルトは debian/changelog から取得されたバー
ジョンが用いられる。ソースパッケージツリー以外で呼び出された際は必須である。
-elibrary-file
Only analyze libraries explicitly listed instead of finding all public libraries.
You can use shell patterns used for pathname expansions (see the File::Glob(3perl)
manual page for details) in library-file to match multiple libraries with a single
argument (otherwise you need multiple -e).
-Ifilename
filename を、パッケージに同梱するシンボルファイルを生成する際のリファレンスファイル
として使用する。
-O[filename]
Print the generated symbols file to standard output or to filename if specified,
rather than to debian/tmp/DEBIAN/symbols (or package-build-dir/DEBIAN/symbols if -P
was used). If filename is pre-existing, its contents are used as basis for the
generated symbols file. You can use this feature to update a symbols file so that
it matches a newer upstream version of your library.
-t Write the symbol file in template mode rather than the format compatible with
deb-symbols(5). 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 deb-symbols(5) file (according to the tag
processing rules) while all symbols are always written to the symbol file template.
-c[0-4]
生成されたシンボルファイルをベースとして用いたテンプレートファイルと比較する際の
チェック項目を定義する。デフォルトのレベルは 1 である。レベルを上げるとより低いレベ
ルのチェック項目すべてに加えて、より多くのチェックが行われる。レベル 0 を指定した場
合、常に失敗しない。レベル 1 は、幾つかのシンボルが消失した場合に失敗となる。レベル
2 は新しいシンボルが出現しても失敗となる。レベル 3 はライブラリが消失すると失敗とな
る。レベル 4 はライブラリが出現した場合にも失敗となる。
This value can be overridden by the environment variable
DPKG_GENSYMBOLS_CHECK_LEVEL.
-q Keep quiet and never generate a diff between generated symbols file and the
template file used as starting point or show any warnings about new/lost libraries
or new/lost symbols. This option only disables informational output but not the
checks themselves (see -c option).
-aarch シンボルファイルの処理の際に、arch をホストのアーキテクチャと見なす。このオプション
は、バイナリファイルが既に利用可能な場合に、シンボルファイルや差分情報を生成する際
に使用する。
-d デバッグモードを有効化する。dpkg-gensymbols の動作を示す大量のメッセージが表示され
る。
-V 冗長モードを有効化する。生成されたシンボルファイルには、廃止されたシンボルがコメン
トとして残される。さらにテンプレートモードの場合、パターンシンボルについて、パター
ンとマッチした実シンボルの一覧もコメントとして残される。
-?, --help
利用方法を表示して終了する。
--version
バージョン情報を表示して終了する。
関連項目
https://people.redhat.com/drepper/symbol-versioning
https://people.redhat.com/drepper/goodpractice.pdf
https://people.redhat.com/drepper/dsohowto.pdf
deb-symbols(5), dpkg-shlibdeps(1).
翻訳者
高橋 基信 <monyo@monyo.com>. 喜瀬 浩 <kise@fuyuneko.jp>. 関戸 幸一 <sekido@mbox.kyoto-
inet.or.jp>. 鍋谷 栄展 <nabe@debian.or.jp>. 倉澤 望 <nabetaro@debian.or.jp>. 石川 睦
<ishikawa@linux.or.jp>. 鵜飼 文敏 <ukai@debian.or.jp>. 中野 武雄
<nakano@apm.seikei.ac.jp>.
翻訳校正
Debian JP Documentation ML <debian-doc@debian.or.jp>.