|
|
7 ベスト・プラクティスと要件この章では、すべての開発者が遵守しなければならない標準と手続きを説明します。これらの規則は、Sun のエンジニアが Solaris を開発する際に遵守しなければならない規則と同じで、これにより Solaris およびこれからの OpenSolaris が、世界の利用可能なソフトウェアの中で最も優れたソフトウェアの 1 つとなっています。
7.1 互換性と可視性の制約OpenSolaris には、インタフェースを統括する規則の包括的なセットがあります。インタフェースは、ユーザまたは開発者が確認または使用できる、システムのさまざまな側面です。例としては、ライブラリにおける関数と変数、特定の実行可能プログラムの位置、実行可能プログラムの出力内容、形式、および引数の意味、およびヘッダー・ファイルのファイルシステムにおける位置が含まれます。OpenSolaris は数千というインタフェースを提供し、各インタフェースにはある種の可視性、ドキュメント、および互換性の制約があります。
7.1.1 インタフェースの安定性の分類多くの Solaris のマニュアル・ページに含まれている属性の 1 つに「インタフェースの安定性」があります。この属性の値は、そのインタフェースに依存できるユーザ、および将来のメンテナンスに対してそのユーザが持つ可能性のある期待を定義しています。取りうる値とその説明についてはここに記載します。Private レベルは、ユーザに提供されるマニュアル・ページには記載されていないことに注意してください。 あるインタフェースの安定性レベルに関する証拠が存在しない場合、ある種の仮定を行う必要があります。「自らが作成するものには厳しく、受け入れるものには寛大であれ」という一般的な規則に従うと、文書化されたインタフェースは Stable であり、非公開のインタフェースはおそらくほかの開発者により使用され、知らされることなくいつでも変更される可能性がある (たとえば、それらは同時に Project Private と Unstable の両方である)、ということになります。そのため、そのインタフェースを変更したり、そのインタフェースの現在の実装に依存したりしてはなりません。安定性レベルを判断できない、非公開のインタフェースに依存、または非公開のインタフェースを変更する必要がある場合は、そのインタフェースの所有者 (存在する場合) を探し、関連する ARC により承認されたアクションを行う必要があります。インタフェースの所有者が見つかる場合は、通常、そのインタフェースを Open (パブリック) ステータスに格上げするか、Contracted Private 安定性レベルのいずれかを使用する必要があります。 次に、安定性レベルとそれぞれの意味のリストを示します。追加情報は 安定性レベル: Standard
----------------------------------------------------------------
仕様 Open
----------------------------------------------------------------
互換性のない変更 メジャー・リリース (X.0)
----------------------------------------------------------------
互換性のある変更 マイナー・リリース (x.Y)
----------------------------------------------------------------
ARC による仕様のレビュー 通常は正確な参照が記録される
----------------------------------------------------------------
例 POSIX、ANSI-C、ABI、SCD、SVID、XPG、X11、DKI、VMEbus、
Ethernet、NFS プロトコル、DPS
----------------------------------------------------------------
これらのインタフェースの大部分は公式標準により定義され、標準化機構により管理されます。これらのインタフェースに対する互換性のない変更はほとんど行われません。 この安定性の分類は、「業界の慣例」(X/Open、MIT X-Consortium、OMG) により (正規標準なしで) 採用されてきたインタフェースにも適用可能で、デファクト・スタンダードが互換性のない形で変更されることはまずないと想定した場合、1 つのソース (Adobe の Display PostScript、Novell の NetWare プロトコル、Legato のネットワーク・バックアップ・プロトコル、Berkeley の sendmail) によって採用されたインタフェースにも適用可能です。 可能であれば、標準仕様または参照システムに対する参照が必要ですが、そのような参照が不可能な場合もあります。ユーザは通常、同じ仕様を参照するよう指示されます。 サポートは、ある標準の特定の 標準の中には、特定のプログラミング言語に拘束されていないものがあります。プロジェクト・チームが名前、番号、拡張子、またはそのほかの実装固有の詳細を選択する場合、アーキテクチャ上のレビューのためにそれらを呼び出す必要があります。 安定性レベル: Stable
----------------------------------------------------------------
仕様 Open
----------------------------------------------------------------
互換性のない変更 メジャー・リリース (X.0)
----------------------------------------------------------------
互換性のある変更 マイナー・リリース (x.Y)
----------------------------------------------------------------
ARC による仕様のレビュー Yes
----------------------------------------------------------------
例 cc オプション、Sbus、XGL API、多くのバンドルされた
コマンド
----------------------------------------------------------------
これらのインタフェースの仕様は、通常はマニュアル・ページなどの製品ドキュメントとして公開されます。またユーザには、これらの互換性を維持することも通知されます。 Stable インタフェースはすべてのサード・パーティがこれらのインタフェースに対するアプリケーションを開発し、リリースし、変更または再コンパイルすることなく製品のすべてのマイナー・リリース (インタフェースが導入され、同じメジャー・リリース内において) で必ず動作できるようにします。メジャー・リリースの時点であっても、互換性のない変更はまれであり、また互換性のない変更にははっきりとした正当な理由があることが想定されています。Stable インタフェースは、ToolTalk (現在は X/Open 標準) の場合のように、業界標準に提案されることもあります。 ARC では仕様のレビューとアーカイブを行う必要があり、また適切なユーザ用ドキュメントも存在する必要があります。 これらは、通常は仕様が OpenSolaris プロジェクトにより管理されているインタフェースで、外部提供のプロジェクトには依存しません。 安定性レベル: Evolving
----------------------------------------------------------------
仕様 Open
----------------------------------------------------------------
互換性のない変更 マイナー・リリース (x.Y)、および影響
評価
----------------------------------------------------------------
互換性のある変更 マイナー・リリース (x.Y)
----------------------------------------------------------------
ARC による仕様のレビュー Yes
----------------------------------------------------------------
例 core および .il ファイル形式、Solaris DDI &
DGA、多くの GUI、管理ユーティリティ、構成
ファイル、デーモン、多数の PAM
----------------------------------------------------------------
Evolving インタフェースは、メジャー・リリースまたはマイナー・リリースの時点で互換性のない変更を受ける可能性がありますが、Evolving インタフェースは慎重に (おそらくゆっくりと) 変更されると想定されます。インタフェースの発展とともに、すべての変更がソースおよびバイナリ互換性を持つよう適切に尽力します。 ARC では、(特に、想定される発展を互換性を維持しつつ吸収する能力に関して) インタフェースの仕様をレビューする必要があります。適切なユーザ用ドキュメントも存在する必要があります。Evolving インタフェース は、ISV が新しいテクノロジを利用できるようにし、これらのインタフェースに依存する製品を出荷することを想定する必要があります。その結果、Evolving インタフェースに対する互換性のない変更はすべて、潜在的なユーザへの影響の評価と、通知および移行プランを必要とします。次に、このようなプランの要素を示します。 * インタフェースが変更される環境に関するユーザの想定を明確に設定する。 * 影響を受けるリリースのリリース・ノートで、そのような変更をすべて説明する。 * バイナリ互換性/継続的なソース開発のための移行支援を提供する。 Evolving インタフェースに依存するリスクを受け入れようとするプロジェクトは、ARC により評価され明示的に承認される必要があります。 注: Evolving であると宣言されているインタフェースが、後で Stable または Standard に分類し直されることはよくありますが、先を見越した格上げは、Evolving 分類レベルの必要な属性ではありません。あるインタフェースが Evolving に分類され、いつまでもそのままのこともあります。 安定性レベル: Unstable
----------------------------------------------------------------
仕様 Open
----------------------------------------------------------------
互換性のない変更 マイナー・リリース (x.Y)
----------------------------------------------------------------
互換性のある変更 マイクロ・リリース (x.y.Z)
----------------------------------------------------------------
ARC による仕様のレビュー Yes
----------------------------------------------------------------
例 SUNW* パッケージの短縮、
一部の構成ユーティリティ
----------------------------------------------------------------
Unstable インタフェースは、実験段階または移行段階のものです。通常 Unstable インタフェースは、開発者に新しいテクノロジや急速に変化するテクノロジへの早期アクセスを提供するためや、より一般的なソリューションが期待される問題に対する暫定的なソリューションを提供するために使用されます。あるマイナー・リリースから次のマイナー・リリースへのソース互換性またはバイナリ互換性に関して、何も要求されません。 Unstable インタフェースは、インタフェース実装としてプロトタイプ、および同じ CD (またはリリース・メディアにかかわらず) 上の製品によってのみインポートされます。Unstable インタフェースをインポートしようとするプロジェクトは、早期に ARC で検討する必要があります。インタフェースの安定性の分類は上げられる場合があります (または代替インタフェースが提供されます)。プロジェクトに Unstable インタフェースのインポートを許可すると主張する場合は、その Unstable インタフェースが受け入れ可能である理由を説明する必要があります。 Unstable インタフェースに関するすべてのドキュメントは、これらのインタフェースは警告なく変更される場合があり、また非バンドル製品では使用してはならないという警告を記載する必要があります。場合によっては、標準の製品ドキュメントではなく、ホワイト・ペーパーで Unstable インタフェースを解説した方が適切である場合があります。 このような注意事項が記載してあれば、メジャー・リリースまたはマイナー・リリースにおける Unstable インタフェースに対する互換性のない変更を考慮する際に、ユーザへの影響を考慮の要因にする必要はありません。ただし、そのような変更を導入する場合は、影響を受けるリリースのリリース・ノートで、そのような変更を記載する必要があります。 ARC では、仕様のレビューとアーカイブを行う必要があります。インタフェースに対して提案されるすべての変更は、ARC の承認を受ける必要があります。 注: 原案標準の実装を提供することを選択し、標準 (または技術上妥当である、または標準化される可能性が高いと判断される部分) を追跡することを表明すると、インタフェースを Unstable に分類することにより互換性のない変更に対するユーザの想定を設定することになります。標準が最終決定した時点で、そのインタフェースを Standard に再分類する必要があります。再分類する場合は「Unstable->Standard」に変換できます。 安定性レベル: External ---------------------------------------------------------------- 仕様 Open ---------------------------------------------------------------- 互換性のない変更 マイクロ・リリース (x.y.z) ---------------------------------------------------------------- 互換性のある変更 マイクロ・リリース (x.y.z) ---------------------------------------------------------------- Arc による仕様のレビュー 通常は正確な参照が記録される ---------------------------------------------------------------- 例 OpenSSL ---------------------------------------------------------------- これらのインタフェースは Sun および OpenSolaris プロジェクト以外の団体により管理されていますが、Standard とは異なり、インタフェースに対する互換性のない変更が極めてまれであるとは断言できません。場合によっては、管理している団体を明らかにすることさえ不可能である場合があります。一般的にこの分類は、コミュニティ・ソフトウェア、フリー・ソフトウェア、オープン・ソースなどに使用されます。 External インタフェース安定性レベルを使用すると、Sun により提供されるフリーウェア・インタフェースは、流動的な外部仕様を迅速に追跡することができます。多くの場合、この安定性レベルはコミュニティの期待に添う傾向があるため、インタフェースに安定性を追加する場合に優先されます。ただし、External インタフェースは、少なくとも次の領域において、OpenSolaris の標準に従う必要があります。 * セキュリティ、認証 * マニュアル・ページ・セクションのナンバリング * ファイル・システムのセマンティクス (/usr は読み取り専用である場合があり、/var は実行時にデータが大幅に増大する場所である、など) すべての External インタフェースは、関連するすべてのドキュメントで External インタフェースのラベルを付ける必要があり、またそのようなインタフェースを使用した結果は、そのドキュメントの一部またはリファレンスにより説明する必要があります。デフォルトの検索パスは External インタフェースに到達してはなりません。ユーザが External インタフェースにアクセスするには、単純かつ明示的なアクションを行う必要があります。 パッチで互換性のない変更を配布することは避けてください。次の 2 つの理由により、厳しく禁止はされていません。 * 変更を明示的に制御できる立場にないため、特定されていない非互換性が存在しないことを正当な確信をもって保証することはできません。 * 新しいバージョンが重要なエスカレーションを終了する場合、新しいバージョンをパッチとして配布する、強力なビジネス・ケースが存在する場合があります。 一般的には、パッチで変更を許可しようとすることは、更新リリースで変更を許可することになります。 インタフェースを制御する団体が OpenSolaris 以外の団体である場合でも、より流動性の低いインタフェース分類をあるインタフェースに適用した方が好ましい場合もあることに注意してください。Unstable 分類を使用すると、マイクロ/パッチ・リリースで安定性のコミットが拡張され、更新頻度の低下という潜在的な代償を払って、これらのインタフェースに依存するソフトウェアに対して追加のサポート・モデルを使用できるようになります。ただし、外見上同じソフトウェアの分類として External と Unstable を区別することは難しいため、注意が必要です。External の使用と、(契約を通じた) Unstable としての動作をお勧めします。Evolving 分類を使用すると、外部仕様から分かれるという潜在的な代償を払って、これらのインタフェースはファースト・クラスの OpenSolaris インタフェースに格上げされます。Evolving を使用することで、本質的にはインタフェースを制御していますが、インタフェースは外部参照から自由にインポートを行える場合があります。Stable 分類の使用はお勧めできません。 安定性レベル: Contracted External インタフェースの提供元と利用者との間で契約が結ばれている点を除き、この安定性レベルは External と同じです。契約は、インタフェースの安定性に対してなされた特別な取り決めを規定します。これはたとえば、External の通常の規則が利用者の要件を満たさない場合、いつどのようにしてインタフェースが変更されるかに対して制限を課すために使用できます。 ARC では、インタフェースの提供元と利用者との間の契約をレビュー、承認、およびアーカイブする必要があります。契約、インタフェース、または仕様に対する変更はすべて再承認が必要です。 安定性レベル: Obsolete
----------------------------------------------------------------
仕様 Open、廃止の警告が付属
----------------------------------------------------------------
互換性のない変更 マイナー・リリース (x.Y)
----------------------------------------------------------------
互換性のある変更 前の分類による、ただし可能性は低い
----------------------------------------------------------------
ARC による仕様のレビュー 通常はより高い安定性からダウングレード
される。インタフェースまたは機能の削除
は ARC による承認も必要となる。
----------------------------------------------------------------
例 RFS、System-V LP プロトコル
----------------------------------------------------------------
「廃止」または一般的にはもはや使用されていないインタフェースです。ある既存のインタフェースが、そのインタフェースが削除される (または変更により互換性がなくなる) 前にそれから移行するようユーザに促すために、(Stable や Standard などの) 別のステータスから Obsolete にダウングレードされる場合があります。 インタフェースを Obsolete に再分類し、ユーザ用ドキュメントで新しい分類を記載することだけでなく、マイナー・リリースにおける互換性のない変更や削除の前に、コミットにおいて変更をユーザに通知する事前プログラムを実行する必要があります。一部のインタフェースについてメジャー・リリースの時点であっても、ARC がインタフェースを削除する前にこのようなプログラムを実行することを適切であると判断する場合があります。 次に、コミットにおいて変更を通知する標準的なプログラムの要件を示します。 1. そのインタフェースを含む 2. カスタマ・ベースおよび Sun 製品開発コミュニティに対する、予定されるインタフェース廃止の 1 年前からの通告。この要件により、そのインタフェースに対しては今後コミットメントが作成されなくなり、機能が将来削除されることの影響を受ける当事者は代わりの取り決めを行う機会が得られます。 通知して、1 年経過してからインタフェースの現在のステータスと互換性のない変更が含まれる製品を提供する必要があります。 ユーザへの通知として認められる手段には、サポート契約に基づくユーザへの手紙、リリース・ノートまたは製品ドキュメント、または該当するインタフェースに適切なユーザ・フォーラムへの告知があります。 廃止の通知は、ユーザが自由に利用できるという点において、「公的な」情報であると考えられます。これには、プレス・リリースや同じような形式の発表など、情報を「公開する」特別なアクションは必要ではありません。 3. 技術的に可能な場合、インタフェースが Obsolete であると宣言されたリリースに、インタフェースを使用した場合の警告メカニズムを含めること。このメカニズムは、「The application uses interface which has been declared obsolete and may not be present in versions of released after [event]. Please notify your support person. See in [reference] for more information.」という形式のメッセージを出力する必要があります。推奨方法の 1 つとしては、レベル「LOG_WARNING」と共に syslog(3) を使用する方法があります。警告メッセージをオフにするための方法も提供する必要があります。警告の出現頻度の決定は、一般の常識に従ってください。 4. 次の内容を含むユーザ・ドキュメント内の情報。 * Obsolete の意味の説明。 * 出現する場合がある警告メッセージの種類の明示。 * ユーザがサポート担当者に、そのような警告を出現させるアプリケーションの提供元と連絡を取るよう依頼する提案。 * 警告メッセージをオフにするための一般的な指示。 * 当該リリースに含まれる Obsolete インタフェース、最も早くなくなる可能性のあるインタフェース、出現する場合のある警告の種類、および警告をオフにするための方法のリスト。 インタフェースを Obsolete であると特定するために主要なドキュメントが変更される前に、このメカニズムを通じてインタフェースをダウングレードする提案は、ARC により承認される必要があります。リリース・ノートでは、ARC または運営委員会の承認により削除される可能性があるという警告を記載することがあります。インタフェースが将来削除される「可能性がある」という警告は ARC の承認なしに含めることができますが、ARC はそのような通知だけではユーザに対する「1 年間の猶予」という十分な通知とは見なさない場合があります。 タイムアウト期間が終了した後で今後のマイナー・リリースまたはメジャー・リリースにおいて実際の機能削除を実行する後続プロジェクトは、廃止ポリシーの要件が満たされていることを確認するためのアーキテクチャ上の承認を必要とします。それらが満たされていれば、承認は問題なく行われます。 安定性レベル: Committed Private
----------------------------------------------------------------
仕様 Closed
----------------------------------------------------------------
互換性のない変更 メジャー・リリース (X.0)
----------------------------------------------------------------
互換性のある変更 マイクロ・リリース (x.y.Z)
----------------------------------------------------------------
ARC による仕様のレビュー Yes
----------------------------------------------------------------
例 UFS メディア・フォーマット、
Calendar Manager RPC プロトコル
----------------------------------------------------------------
ほかの点において Private なインタフェースでは、これらのインタフェースを使用するプログラムの互換性に対するユーザの期待を満たすために、リリース間で互換性を維持する必要があります。ただし、ユーザがこれらのインタフェースに直接依存するのは好ましくなく、またこれらのインタフェースをユーザに直接公開するのは好ましくありません。これらのインタフェースは Committed Private として分類されます。 コミットメントは、ユーザによる「通常の」システム機能の使用では、これらのインタフェースに対する互換性のない変更を見せないようにすることです。一般的にこれらのインタフェースは、メディアまたはプロトコルに組み込まれることにより複数のマシンに及ぶため (またユーザはすべてのマシンを同時にアップグレードできるわけではないため)、これらのインタフェースは自由に使用できるプライベート・インタフェースで変更できません。ただし、ユーザに対するコミットメントが維持されている限り、インタフェースの詳細に対する変更は劇的なものになる可能性があります。一般的に、Committed Private インタフェースはバージョン管理する必要があります。 ARC では、仕様のレビューとアーカイブを行う必要があり、また少なくともインタフェースはその目的を満たし、前述のパラグラフで説明で説明されている発展をサポートしていることを保証します。インタフェースに対して提案される変更、またはインタフェースに対する新しい依存性はすべて、ARC の承認を受ける必要があります。 安定性レベル: Contracted Committed Private インタフェースの提供元と利用者との間で契約が結ばれている点を除き、この安定性レベルは Committed Private と同じです。契約は、インタフェースの安定性に対してなされた特別な取り決めを規定します。これはたとえば、Sun のパートナーへのインタフェースの公開を許可するために使用できます。 ARC では、インタフェースの提供元と利用者との間の契約をレビュー、承認、およびアーカイブする必要があります。契約、インタフェース、または仕様に対する変更はすべて再承認が必要です。 安定性レベル: Sun Private ---------------------------------------------------------------- 仕様 Closed ---------------------------------------------------------------- 互換性のない変更 マイナー・リリース (x.Y) ---------------------------------------------------------------- 互換性のある変更 マイクロ・リリース (x.y.Z) ---------------------------------------------------------------- ARC による仕様のレビュー Yes ---------------------------------------------------------------- 例 trap 40 (gethrtime) ---------------------------------------------------------------- これらは、1 つの統合が依存し、別の統合が提供するインタフェースです。これらのインタフェースに対する変更は、インタフェースのすべての提供元とユーザの間で調整される必要があります。一部の内部カーネル・インタフェースは Sun Private インタフェースです。 場合によってインタフェースは、Unstable または Stable インタフェースとしてより広く使用されるよう公開される前に、インタフェースを使用した経験を得るために Sun Private にされます。ただし、発展がはるかに容易になるため、そのようなインターフェスを Consolidation Private にする方が好ましくなります。 Sun Private インタフェースは可能な限り使用しないでください。1 つの統合内でこれらのインタフェースに対する変更を調整することは通常可能ですが、非同期的にリリースされる異なる統合間で変更を調整することは極めて困難です。Sun Private インタフェースにはインタフェース・バージョン管理をお勧めします。 ARC ではこれらのインタフェースのレビューとアーカイブを行い、必要に応じてインタフェースがどのように発展するかに特に注意します。インタフェースに対して提案されるすべての変更は、ARC の承認を受ける必要があります。 安定性レベル: Contracted Sun Private インタフェースの提供元と利用者との間で契約が結ばれている点を除き、この安定性レベルは Sun Private と同じです。契約は、インタフェースの安定性に対してなされた特別な取り決めを規定します。これはたとえば、パートナーへのインタフェースの公開を許可するために使用できます。 ARC では、インタフェースの提供元と利用者との間の契約をレビュー、承認、およびアーカイブする必要があります。契約、インタフェース、または仕様に対する変更はすべて再承認が必要です。 安定性レベル: Consolidation Private ---------------------------------------------------------------- 仕様 Closed ---------------------------------------------------------------- 互換性のない変更 マイクロ・リリース (x.y.Z) または「ジャンボ・パッチ」 ---------------------------------------------------------------- 互換性のある変更 マイクロ・リリース (x.y.Z) または「ジャンボ・パッチ」 ---------------------------------------------------------------- ARC による仕様のレビュー 不要 ---------------------------------------------------------------- 例 libdeskset、kernel nameslists ---------------------------------------------------------------- これらは、統合の 1 部分が依存し、同じ統合の別の部分が提供する統合に対して内部にあるインタフェースです。これらのインタフェースに対する変更は、インタフェースのすべての提供元とユーザの間で調整される必要があります。多くの内部カーネル・インタフェースは Consolidation Private インタフェースです。 一般的に、これらは統合のビルドに便利であることが判明しているインタフェースですが、非常に頻繁に変更されるため、外部使用のためにこれらを文書化したり、その安定性の面において望ましくないインタフェースです。libdeskset がそのようなインタフェースの例です。libkvm API は Public ですが、そのインタフェースを通じてアクセス可能な非公開の名前は Consolidation または Project Private です。 ARC ではこれらのインタフェースのレビューとアーカイブを行なったり、また独自の内部でのコミットメントを監視するため統合をそのままにする場合もあります。ARC により Consolidation Private インタフェースをレビューする場合は、そのインタフェースへの後の変更をレビューするかどうかを ARC に問い合わせてください。 Consolidation 以外のプロジェクトによりそのインタフェースをインポートするには、インタフェースの提供元との「契約」を交渉する必要があります。ARC は、Contracted Consolidation Private に対する分類の変更、および契約の条項をレビューおよび承認する必要があります。 安定性レベル: Contracted Consolidation Private インタフェースの提供元と利用者との間で契約が結ばれている点を除き、この安定性レベルは Consolidation Private と同じです。契約は、インタフェースの安定性に対してなされた特別な取り決めを規定します。これはたとえば、別の統合における特定の利用者へのインタフェースの公開を許可するために使用できます。 ARC では、インタフェースの提供元と利用者との間の契約をレビュー、承認、およびアーカイブする必要があります。契約、インタフェース、または仕様に対する変更はすべて再承認が必要です。 安定性レベル: Project Private
----------------------------------------------------------------
仕様 Closed
----------------------------------------------------------------
互換性のない変更 マイクロ・リリース (x.y.Z)
----------------------------------------------------------------
互換性のある変更 マイクロ・リリース (x.y.Z) またはパッチ
----------------------------------------------------------------
ARC による仕様のレビュー No
----------------------------------------------------------------
例 Metamucil ioctl、nfssys システム・コール、
uadmin cpu 制御関数
----------------------------------------------------------------
Project Private インタフェースが通常使用されるのは、プロジェクトがシステム内の境界を超えてそのコンポーネント間で通信しなければならない場合です。たとえば、Metamucil には、UFS ファイルシステム上で処理を行うために複数の新しい ioctl が含まれています。Metamucil ufsdump プログラムはこれらの ioctl を使用します。ioctl は Metamucil 製品でのみ使用されることを目的としているため、プライベート・インタフェースです。Metamucil 製品に、将来これらの ioctl を変更する必要が生じた場合、これらの ioctl を使用できるプロジェクトはほかに存在しないため、ほかのプロジェクトと調整することなく変更できます。同様に、nfssys システム・コールは、NFS のカーネル・レベルおよびユーザ・レベルの部分の間での通信に使用されます。 Project Private インタフェースは、あるモジュールが同じライブラリ内の別のモジュールのプライベート・ルーチンを呼び出す必要があるライブラリでも使用されます。 また、Project Private インタフェースは、暫定的インタフェースまたは移行中のインタフェースにすることもできます。uadmin cpu 制御関数は Project Private です。これは、これらのインタフェースが Standard インタフェースとして出現する前に形式を変化させ、その間どのようなユーザにもそれらに依存することが好ましくないためです。 残念なことに、多くのカーネル・プロシージャは (Internal インタフェースではなく) Project Private インタフェースです。これは、動的に読み込まれるカーネル・モジュールがこれらを参照できるためです。 ARC によりインタフェースが Project Private に分類されれば、そのインタフェースに対する変更は ARC により承認される必要はありません。 プロジェクトの外部からこのインタフェースを使用するには、インタフェースの提供元との「契約」交渉を必要とします。ARC は、Contracted Project Private に対する分類の変更、および契約の条項をレビューおよび承認する必要があります。 安定性レベル: Contracted Project Private インタフェースの提供元と利用者との間で契約が結ばれている点を除き、この安定性レベルは Project Private と同じです。契約は、インタフェースの安定性に対してなされた特別な取り決めを規定します。これはたとえば、別の統合における特定の利用者へのインタフェースの公開を許可するために使用できます。 ARC では、インタフェースの提供元と利用者との間の契約をレビュー、承認、およびアーカイブする必要があります。契約、インタフェース、または仕様に対する変更はすべて再承認が必要です。
7.1.2 ライブラリの考慮事項ON により提供されるライブラリには、プライベート・インタフェースの公開を制限し、パブリック・インタフェースに対する変更を追跡する、シンボル・バージョン管理情報が含まれます。このバージョン管理情報は、
7.2 スタイル・ガイド多くのプロジェクトと同様に、OpenSolaris はソースに関係なく、提供されたコードにコーディング・スタイルを強制します。このコーディング・スタイルは、Linux カーネル、BSD システム、およびそのほかの GNU 以外の多くのプロジェクトにより使用されるコーディング・スタイルに非常によく似ています (GNU プロジェクトは独自のコーディング・スタイルを使用しています)。このスタイルの詳細は http://opensolaris.org/os/community/onnv/ で説明されていますが、このスタイル・ガイドの一部の要素はかなり旧式になっています (特に K&R C と ANSI (現在は ISO) C との対比に関連するため)。また、
7.2.1 自動スタイル・ツールOpenSolaris ディストリビューションの一部として、コーディング・スタイルの多くの要素をチェックするために 2 つのツールが使用できます。これらのツールは、ほとんどのスタイルのガイドラインについて C コードが準拠しているかを確認するための すべてのヘッダーは「hdrchk」をパスすると想定されています。すべての C ファイルとヘッダーは「cstyle -P -p」をパスすると想定されています。チェックされる 7.2.2 スタイルの例現在のところツールでは捕捉されない、不正なスタイルの共通例をいくつか示します。 * 同一行での初期化された変数と初期化されていない変数の宣言の混合。次に例を示します。
int a, b = 16, c = -4, d;
その代わりに、初期化されてない変数は 1 行で 1 つまたは複数宣言できますが、初期化されている各変数は独自の行で宣言する必要があります。
int a, d;
int b = 16;
int c = -4;
または
int a;
int b = 16;
int c = -4;
int d;
* 有効なスタイルの矛盾した使用。上記の例では、変数を宣言する 2 つの有効な方法が提示されています。正しいスタイルでは、使用されるすべての要素がファイル内のどの場所でも使用されることを指示します。ただし、ツールはこのような一貫性をチェックしません。 * if/else コンストラクトを囲む中括弧の間違った配置および使用。デフォルトではこのような使用に対するヒューリスティック・テストは実行されず、完全に信頼できるものではありません。説明を簡単にするため、ここでは、両方の代替手段が複合ステートメントである if/else の正しい書式を示します。
if (x != SOME_CONSTANT) {
do_stuff();
return (x);
} else {
do_other_stuff();
x = OTHER_CONSTANT;
}
どちらの代替手段も複合ステートメントではない場合、次のように使用します。
if (x != SOME_CONSTANT)
do_stuff();
else
do_other_stuff();
最後に、1 つの代替手段のみが複合ステートメントである場合、次に示す書式のように、両方の代替手段には中括弧が必要です。
if (x != SOME_CONSTANT) {
do_stuff();
return (x);
} else {
do_other_stuff();
}
中括弧の配置に注意してください。中括弧は「else」のみを囲む必要があり、右中括弧は単独で 1 行にならなければならないことに注意してください。 * 条件付きコンパイル指示と関連付けられたコメントの使用。#else および #endif 指示の後に、参照先の条件を説明する末尾のコメントを含めることは正しいスタイルです。次に例を示します。
#ifdef __FOO
...
#else /* !__FOO */
...
#endif /* !__FOO */
スタイル・ツールはこれらの末尾のコメントの存在、有効性、または正確性をチェックしませんが、特に間にあるコード・ブロックが長い場合や、テストが、入れ子になったプリプロセッサ条件分岐の複雑なセットの一部である場合には、通常末尾のコメントを含める必要があります。 * ヘッダー・ファイルの正しくないガード。ガード名はヘッダー・ファイルから派生する必要がありますが、hdrchk はこれをチェックしません。たとえば、<sys/scsi/foo_impl.h> にインストールされているヘッダーには、次のようなガードが必要です。
#ifndef _SYS_SCSI_FOO_IMPL_H
#define _SYS_SCSI_FOO_IMPL_H
...
#endif /* _SYS_SCSI_FOO_IMPL_H */
ただし、hdrchk は実際のガード・トークン名や、#endif に続くコメントを確認しません。 * コメントのスタイルは部分的にしかチェックされません。たとえば、ブロック・コメントの正しいスタイルは次のようになります。
/*
* Some comment here.
* More here.
*/
/*
Some comment here.
We conserve asterisks even though it's harder to read.
Our comment is nonconforming.
*/
コメントの正しいインデントもチェックされません。関数内のブロックおよび単一行コメントは、記載されるコードと同じレベルでインデントされる必要があります。末尾のコメントは、関連するコード内でそのほかの末尾のコメントに揃えて位置合わせする必要があります。これらのスタイルのガイドラインは、ツールによりチェックされません。 コメントの内容は全くチェックされないことは、おそらく言うまでもないでしょう。必ず、スタイル・ガイドのコメント内容のガイドラインに従ってください。
7.2.3 書式以外の考慮事項
#pragma ident "@(#)devref-ext.pod 1.4 05/03/22 SMI" /* optional comment */
この文字列には、実際には複数のタブが埋め込まれていることに注意してください。これらのタブを \t として表示すると、キーワードは次のようになります。
#pragma ident\t"@(#)devref-ext.pod\t1.4\t05/03/22 SMI"\t/* optional comment */
C (または C++) 実装またはヘッダーではないファイルは、「pragma」部分が不要であり、次のように #ident のみを使用します。
#ident\t"@(#)devref-ext.pod\t1.4\t05/03/22 SMI"\t/* optional comment */
また、各ファイルは最上部に著作権関連の文を含む必要があります。このような著作権に関する有効なテキストと書式は、usr/src/prototypes のサンプル・ファイルに示してあります。ソース・ファイルがかなり更新された場合には、著作権の年または年の範囲は、変更時の現在の年のみに置き換える必要があります。重要な更新には書式の変更は含まれません。ただし、変更が重要な更新をするかどうかを考慮しない場合や、自らの判断を信用できない場合は、常に年を更新することができます。プロトタイプでは常に Sun が唯一の著作権保持者であると想定されているため、著作権関連の文の変更はごくわずかにとどめる必要があります。たとえば、最初の時点ではファイルに次の文が含まれているとします。
/*
* Copyright (c) 1992-1998 by Sun Microsystems, Inc.
* All rights reserved.
*/
この注記は次のように置き換える必要があります。
/*
* Copyright 2005 Sun Microsystems, Inc.
* All rights reserved. Use is subject to license terms.
*/
また、貢献者が Sun の社員でない場合は、次のように追加する必要もあります。
/*
* Copyright 2005 J. Random Hacker
* All rights reserved. Use is subject to license terms.
*/
または貢献者の著者権の類似の文を追加します。著作権の注記は結合しないでください。また、(特別に指示された場合を除き) 既存の著作権の注記は削除しないでください。
7.2.4 統合の要件OpenSolaris に追加する前にコードのレビュー用に変更を提示する前には、(意味が正しいかだけでなく) スタイルが正しいかコードを自分でレビューする必要があります。このプロセスの一部として
7.3 テストのガイドライン変更には適切なテストを行う必要があります。一部の変更のテストは複雑であり、テスト・スイートが利用できないため、スポンサーは適切なテストに対するガイダンスを提供します。
7.4 lint を使用するSolaris カーネル全体と多くのライブラリおよびコマンドは、pass1 と pass2 の両方において、完全に lint エラーがありません (lint クリーン) です。高品質のリリースを保証するさらにもう 1 つのツールとして、この lint クリーンであることを維持することは重要です。すべての非カーネル・コードが lint クリーンであるわけではありませんが、新しいコードは lint クリーンでなければならず、またすべての新しいコマンドとライブラリは全体が lint クリーンでなければなりません。lint クリーンであるコードは、ビルド・システムに対し、コードに lint が適用される必要があることを示す必要があります。lint クリーンへの移行中であるコードの例として、usr/src/cmd/cmd-inet/usr.sbin/Makefile およびその関連コードを参照してください。 変更をチェックインする前に、(SPARC と x86 の両方で) 次の手順に従い、新しいエラーがないかチェックします。
% cd $SRC/uts
% ( make && make lint ) > ERRS 2>&1
% grep "warning:" ERRS
すべての警告メッセージを修正する必要があります。 lint 出力の生成には ビルド・システムでは、lint は「ノーマル」ビルドに非常によく似てますが、それよりも複雑な面があります。lint pass2 から重要な出力を取得するには、すべてのモジュールをまとめて lint する必要があります。これは、独自の pass1 出力を生成する役割がある各モジュールにより行われます (file.ln、.c/.s ファイルごとに 1 つ)。このモジュールは、lint ライブラリ (llib-lMODULE) を uts/MACHINE/lint-libs ディレクトリに配置する役割もあります。最終的な完全な lint は、すべての lint ライブラリを相互に lint することで、uts/MACHINE ディレクトリの makefile により行われます。 アセンブリでのみ定義されている関数に関する lint の問題をなくすため、.s ファイルには C プロトタイプもあります。次に例を示します。
#if defined(lint)
int
blort(int, int)
{ return 0 }
#else /* lint */
ENTRY(blort)
ld [%i0],....
....
SET_SIZE(blort)
#endif /* lint */
コードを lint クリーンに保ち、lint の問題を回避するために、いくつかの追加規則があります。 * OpenSolaris カーネル・ソースでは、絶対に /* LINTLIBRARY */ を使用しないでください。 * 直接、またはマージの結果としてヘッダー・ファイルが変更されても、常に lint ライブラリがリビルドされるわけではありません。これにより、2 つの異なる宣言を持つ関数の (発生するとは考えられない) エラーが生じる場合があります。ヘッダー・ファイルのマージまたは変更の後には、必ず「make clean.lint」を実行してください。 * 戻り値を持つ関数を呼び出して、それを使用しない場合は、前に (void) キャストを配置してください。共通する関数には、sprintf と strcpy があります。関数の戻り値を何度も無視すると、エラー状態が表示されなくなる可能性があります。常に値が無視される関数の場合、仕様を void として再宣言することを検討しなければならない場合があります。もちろん、通常これはパブリック・インタフェースには適用されません。 * long 整数用の書式指定文字列は、「%ld」、「%lx」、または「%lu」のいずれかを使用します。 * unsigned 整数用の書式指定文字列は、「%u」または「%x」のいずれかを使用します。 * long long 整数用の書式指定文字列は、「%lld」または「%llx」を使用します。 * ポインタ用の書式指定文字列は、(void *) にキャストされるポインタと共に「%p」を使用する必要があります。%d または %x の使用、および (int) へのキャストは、64 ビット・カーネルではエラーが発生します。 * ILP32 と LP64 のいずれかで動作すると想定されているコードの場合、書式指定文字列で使用できるいくつかのマクロがあるため、int に対して #ifdef long を使用する必要はありません。<sys/int_fmtio.h> を参照してください。 * カーネルは常に __STDC__ が定義された状態でコンパイルされるため、関数宣言では完全な ANSI/ISO プロトタイプを使用してください。新しいコードでは K&R スタイルの宣言を使用しないでください。 * マシンに依存する関数の宣言は、プラットフォーム間で一貫性を持たせるようにしてください。 * 必ず、(ビルド・マシンにインストールされたヘッダーではなく) プロト・エリアのヘッダーに対して lint を実行してください。
7.5 ヒントと推奨事項フィードバックと推奨事項を提供してください。 |