[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
pkgsrc/doc/guide/files/buildlink.xml: 1.26 -> 1.28
以下のページの更新をしました。ツッコミをお願いします。
pkgsrc/doc/guide/files/buildlink.xml: 1.26 -> 1.28
> revision 1.28
> date: 2011/08/30 15:21:46; author: wiz; state: Exp; lines: +2 -2
> Fix an editoro.
> ----------------------------
> revision 1.27
> date: 2011/08/30 15:18:56; author: wiz; state: Exp; lines: +34 -30
> Update documentation of ABI/API depends variables.
木曜日までに異議がなければ、 commit します。
以下、訳と原文それぞれの新旧の差分です。
--- buildlink.xml.orig 2011-08-31 01:15:45.000000000 +0900
+++ buildlink.xml 2011-08-31 01:15:45.000000000 +0900
@@ -1,6 +1,6 @@
-<!-- $NetBSD: buildlink.xml,v 1.26 2009/03/20 19:33:28 joerg Exp $ -->
+<!-- $NetBSD: buildlink.xml,v 1.28 2011/08/30 15:21:46 wiz Exp $ -->
<!-- Based on english version: -->
-<!-- NetBSD: buildlink.xml,v 1.26 2009/03/20 19:33:28 joerg Exp -->
+<!-- NetBSD: buildlink.xml,v 1.28 2011/08/30 15:21:46 wiz Exp -->
<chapter id="buildlink">
<title>buildlink 方法論</title>
@@ -228,7 +228,7 @@
この変数の既存のリストを残したまま追加するために、
かならず <command>+=</command> を使って設定します。
この変数の設定値は、
- パッケージの API が現行のものになった以降の最初 (最古) のバージョンにします。
+ パッケージの API が後方互換性のない変更によって現行のものになった以降の最初 (最古) のバージョンにします。
</para>
</listitem>
@@ -338,38 +338,42 @@
</sect2>
<sect2 id="updating-buildlink-depends">
- <title><filename>buildlink3.mk</filename> ファイルの <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname> を更新する</title>
+ <title><filename>buildlink3.mk</filename> ファイルの
+ <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
+ および
+ <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
+ を更新する</title>
- <para>パッケージを更新した際に
- <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
- に列挙されている依存性のバージョンを上げる必要があるのは、
- その更新で API やヘッダーファイルへのインターフェースが変わった場合です。</para>
+ <para>この二つの変数の違いは、一方はソースの互換性 (API) を記述するものであり、
+ もう一方はバイナリーの互換性 (ABI) を記述するものであることです。
+ API の変更はプログラムのコンパイルをできなくするのに対して、
+ ABI の変更はコンパイル後のプログラムが実行できなくなるという点が異なります。
+ </para>
- <para>このような場合は、
+ <para><filename>buildlink3.mk</filename> ファイル中の
<varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
- を調節して、最低限、新しいパッケージのバージョンを要するようにします。
- 場合によっては、新しいバージョンに依存するパッケージの
- <varname>PKGREVISION</varname> を上げる必要があることがあります。
- また、依存しているパッケージに <filename>buildlink3.mk</filename>
- ファイルがある場合は、
- <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
- も調節します。これは、pkgsrc が適切なパッケージの依存性を求めるようにして、
- ソースからの構築時に古いパッケージに依存したりしないようにするために、
- 必要なことです。</para>
+ 変数を変更するような事態になることは、ごく稀です。
+ このような変更をすることとなりうる場合のひとつとしては、
+ このパッケージに依存している全パッケージが、新バージョンを必要としている場合があります。
+ この変数を変更する場合については、このあとの説明をご覧ください。</para>
- <para><varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
- を上げるのは、バイナリーインターフェースや、
- インストールされている共有ライブラリーのいずれかの soname
- (ライブラリーのバージョンのメジャー番号) が変わった場合です。
- これは、これらを使うバイナリーパッケージが、
- 適切なパッケージの依存性を求めるようにして、
- 必要な共有ライブラリーをもたない古いパッケージに依存したりしないようにするために、
+ <para>ABI の変更としてもっともありがちなのは、
+ 共有ライブラリーのメジャーバージョンが上がった場合です。このような場合は、
+ <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
+ を調整して、最低限必要なパッケージの新バージョンとします。
+ そして、当該パッケージに依存している各パッケージの
+ <varname>PKGREVISION</varname> を上げることが必要ですし、
+ もしそれらのなかに <filename>buildlink3.mk</filename> ファイルを持つパッケージがある場合は
+ <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
+ もあわせて調節することが必要です。これは、ソースからの構築時に
+ pkgsrc が適切なパッケージの依存性を求めるようにして、
+ 古いパッケージに依存したりしないようにするために、
必要なことです。</para>
<para><varname>BUILDLINK_ABI_DEPENDS</varname> および
- <varname>ABI_DEPENDS</varname> の定義を含めた、
- 他のパッケージへの依存性について、さらなる情報は、
- <xref linkend="dependencies"/>をご覧ください。</para>
+ <varname>ABI_DEPENDS</varname> の定義を含めた、
+ 他のパッケージへの依存性について、さらなる情報は、
+ <xref linkend="dependencies"/> をご覧ください。</para>
<para>なお、必要もないのにパッケージを削除したり再構築したりするようなことのないよう、
<varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
@@ -380,9 +384,9 @@
従前の依存性のままでも問題なく動作します。</para>
<para>また、
- <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
- は、
- <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
+ <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
+ は、
+ <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
と同じ値となる場合には設定する必要はありません。 </para>
</sect2>
</sect1>
Index: buildlink.xml
===================================================================
RCS file: /cvsroot/pkgsrc/doc/guide/files/buildlink.xml,v
retrieving revision 1.26
retrieving revision 1.28
diff -u -r1.26 -r1.28
--- buildlink.xml 20 Mar 2009 19:33:28 -0000 1.26
+++ buildlink.xml 30 Aug 2011 15:21:46 -0000 1.28
@@ -1,4 +1,4 @@
-<!-- $NetBSD: buildlink.xml,v 1.26 2009/03/20 19:33:28 joerg Exp $ -->
+<!-- $NetBSD: buildlink.xml,v 1.28 2011/08/30 15:21:46 wiz Exp $ -->
<chapter id="buildlink">
<title>Buildlink methodology</title>
@@ -224,7 +224,7 @@
<command>+=</command> to ensure that
we're appending to any pre-existing list of values. This
variable should be set to the first version of the
- package that had an API change.
+ package that had an backwards-incompatible API change.
</para>
</listitem>
@@ -334,36 +334,40 @@
</sect2>
<sect2 id="updating-buildlink-depends">
- <title>Updating <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname> in <filename>buildlink3.mk</filename> files</title>
+ <title>Updating
+ <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
+ and
+ <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
+ in <filename>buildlink3.mk</filename> files</title>
- <para>The situation that requires increasing the dependency listed in
- <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
- after a package update is when the API or interface to the
- header files change.</para>
+ <para>These two variables differ in that one describes source
+ compatibility (API) and the other binary compatibility (ABI).
+ The difference is that a change in the API breaks compilation of
+ programs while changes in the ABI stop compiled programs from
+ running.</para>
- <para>In this case,
+ <para>Changes to the
<varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
- should be adjusted to require at least the new package
- version. In some cases, the packages that depend on this new
- version may need their <varname>PKGREVISION</varname>s
- increased and, if they have <filename>buildlink3.mk</filename>
- files, their
- <varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>
- adjusted, too. This is needed so pkgsrc will require the
- correct package dependency and not settle for an older one
- when building the source.</para>
-
- <para><varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
- should be increased when the binary interface or sonames
- (major number of the library version) of any installed
- shared libraries change. This is needed so that binary
- packages made using it will require the correct package
- dependency and not settle for an older one which will not
- contain the necessary shared libraries.</para>
+ variable in a <filename>buildlink3.mk</filename> file happen
+ very rarely. One possible reason is that all packages depending
+ on this already need a newer version. In case it is bumped see
+ the description below.</para>
+
+ <para>The most common example of an ABI change is that the major
+ version of a shared library is increased. In this case,
+ <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
+ should be adjusted to require at least the new package version.
+ Then the packages that depend on this package need their
+ <varname>PKGREVISION</varname>s increased and, if they have
+ <filename>buildlink3.mk</filename> files, their
+ <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
+ adjusted, too. This is needed so pkgsrc will require the correct
+ package dependency and not settle for an older one when building
+ the source.</para>
<para>See <xref linkend="dependencies"/> for
- more information about dependencies on other packages,
- including the <varname>BUILDLINK_ABI_DEPENDS</varname> and
+ more information about dependencies on other packages,
+ including the <varname>BUILDLINK_ABI_DEPENDS</varname> and
<varname>ABI_DEPENDS</varname> definitions.</para>
<para>Please take careful consideration before adjusting
@@ -375,8 +379,8 @@
fine with older dependencies.</para>
<para>Also it is not needed to set
- <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
- when it is identical to
+ <varname>BUILDLINK_ABI_DEPENDS.<replaceable>pkg</replaceable></varname>
+ when it is identical to
<varname>BUILDLINK_API_DEPENDS.<replaceable>pkg</replaceable></varname>. </para>
</sect2>
</sect1>