1. 開発者ガイド

1.1 API

• libavcodec はコーデック(エンコーディングおよびデコーディングの両方) を含むライブラリです。それをどのように使うかを知るためには ‘libavcodec/apiexample.c’ を見てください。
• libavformat はファイルフォーマットの取り扱い(さまざまなフォーマットの ための mux および demux コード)を含むライブラリです。これをプレーヤーの中で使うには ‘ffplay.c’ を見てください。オーディオまたはビデオストリームを生成するために使うには ‘libavformat/output-example.c’ を見てください。

1.2 libavcodec または libavformat をあなたのプログラムで統合する

バージョン問題を避けるよう静的にリンクすることで、ライブラリの全ての ソースコードを統合することができます。必要なことは親ディレクトリで ’config.mak’ と ’config.h’ を与えることだけです。必要とされるものを 理解するためには ./configure によって生成される define を見てください。

libavcodec または libavformat を商用プログラムに使うことができますが、 作成したパッチはすべて公開されなければなりません。着手するための 最も良い方法は FFmpeg メーリングリストにパッチを送ることです。

1.3 コーディング規則

FFmpeg は ISO C90 言語に少しだけ ISO C99 からの追加的な機能を加えた形 でプログラムされています。それらは以下のものです:

• ‘inline’ キーワード;
• ‘//’ コメント;
• 指定構造体初期化子 (‘struct s x = { .i = 17 };’)
• 複合リテラル (‘x = (struct s) { 17, 23 };’)

これらの機能は我々が関知する全てのコンパイラーでサポートされており、 そのため、明確さと性能を絶対に損なわない場合を除いてそれらの使用を 取り除くためのパッチは受理されません。

全てのコードは GCC 2.95 と GCC 3.3 でコンパイルされなければなりません。 現時点では、FFmpeg は Compaq ccc コンパイラーや Sun Studio 9 などの いろいろな他のコンパイラーでコンパイルされますが、それが非常に厄介に ならない限りはこのまま維持していきたいと考えています。互換性を保証する ために、別の C99 の機能や GCC 拡張は使用しないでください。特に次に 警戒してください:

• ステートメントと宣言を混ぜる;
• ‘long long’ (代わりに ‘int64_t’ を使ってください);
• ‘#ifdef __GNUC__’ で保護されていない ‘__attribute__’ や類似のもの;
• GCC 複合式 (‘(x = ({ int y = 4; y; })’).

インデントサイズは 4 です。 表示状態は ’indent -i4 -kr -nut’ によって特定されるものです。 タブ文字は Makefile のほかでは行末の空白文字と同様に禁止されます。 このどちらかを含むコミットは Subversion レポジトリに拒否されます。

FFmpeg での主な優先事項はバグの個数を最小化するための単純さと小さなコードサイズ です。

コメント: JavaDoc/Doxygen を使ってください。 コードのドキュメントが自動的に生成できるように(以下の例を見て)書式化してください。 自明でない関数はすべてその直前に、その関数が行うことを説明するコメントを持つべき です。たとえそれが単なる1行の文であっても。 すべての構造体とそのメンバー変数にもドキュメントがあるべきです。

/**
 * @file mpeg.c
 * MPEG codec.
 * @author ...
 */

/**
 * Summary sentence.
 * more text ...
 * ...
 */
typedef struct Foobar{
    int var1; /**< var1 description */
    int var2; ///< var2 description
    /** var3 description */
    int var3;
} Foobar;

/**
 * Summary sentence.
 * more text ...
 * ...
 * @param my_parameter description of my_parameter
 * @return return value description
 */
int myfunc(int my_parameter)
...

fprintf と printf は libavformat や libavcodec では禁止されています、 代わりに av_log() を使ってください。

必要なときだけキャストを使うべきです。コードを理解しやすくするのでないなら 不要な括弧も避けるべきです。

1.4 開発ポリシー

1. 貢献は LGPL 2.1、 もしくは LGPL 2.1 で "or any later version" 条項を含んだもの、 もしくは MIT ライセンスで使用許諾されているべきです。"or any later version" 条項 を含んだ GPL 2 も受け入れられますが、 LGPL の方が望ましいです。
2. FFmpeg を壊すコードをコミットしてはいけません! (つまりコンパイルを壊す、 またはコンパイルできるが動作しない、または回帰テストで失敗するような 未完成なのに有効になっているコードのことです) 未完成なものを(テストその他のため)コミットしてもいいですが、デフォルトで (#ifdef などで)無効にし他の開発者の仕事を妨げないようにしなければ なりません。
3. 過剰にテストを行わなくてもかまいません。あなたにとって機能しており、他でも 機能するはずと考えられる場合には、コミットしてください。もしあなたのコードに 問題(移植可能性、コンパイラーのバグを誘発する、独特な環境等)があるとしても、 それらは報告され結局は修正されるでしょう。
4. 無関係な変更を一緒にコミットしないで、それらを自己完結した断片に分けてください。 また、部分 A に 部分 B が依存しているが A は B に依存していない場合には、 A が先に B とは別にコミットすることができ、かつそうするべきだということを 忘れないでください。変更を自己完結した部分にきちんと分けておくことで、コミット ログのメーリングリスト上にあるそれらをレビューし理解することがより容易に なります。またこれによって後々にデバッグする場合に助かります。 また、分けるか分けないかが不確かな場合には、開発者メーリングリスト上でそれに ついて尋ねる/議論することをためらわないでください。
5. ffmpeg-devel メーリングリスト上でまず議論することなしにプログラムの 振舞い(リネーミングオプション等)を変えないでください。コードから 機能を削除しないでください。ただ改善してください!

   注意: 冗長なコードは削除してもかまいません。

6. 振る舞いや既定値などを変えるビルドシステム(Makefile や configure スクリプト) に対する変更を先に問い合わせることなしにコミットしないでください。 コンパイラーの警告の修正、自明に見える修正、他の開発者によってメンテナンス されているコードに対しても同じことが言えます。たいていの場合、そういった やり方をとっている理由があります。あなたの変更をパッチとして ffmpeg-devel メーリングリストに送ってください。そしてコードのメンテナが OK と言ったとき にはコミットできます。これはあなたが書いた、かつ/または維持しているファイル には該当しません。
7. 機能的な変更と混ぜられている場合にはソースのインデントやその他の表面的な変更は 拒否します。そういったコミットは認められず削除されるでしょう。いずれの開発者 も自分のインデントのスタイルを持っており、それを変更するべきではありません。 もちろんあなたが何かを書く(書き換える)場合には、たとえ我々が FFmpeg を通して インデントが一貫していることを望むとしても、あなたは自分のスタイルを用いて かまいません(多くのプロジェクトが特定のインデントスタイルを強制します - 我々は 強制しません。)。あなたが本当にインデントを変更する(これは避けるように試みて ください)必要があるなら、実質の変更とそれらを厳密に分けてください。

   注意: コードの大きな(5行以上の)塊を越えて if(){ .. } に入れる場合には、 内部の部分のインデントを変更しないでください(右に移動させないでください)! また別々のコミットでそれをしないでください。

8. 常にコミットログメッセージを埋めてください。数行で変更したものとその理由を 説明してください。特定のバグを修正した場合にはメーリングリストへの投稿を参照 してもいいでしょう。"fixed!" や "Changed it." といったコメントは受け入れられません。
9. 他の誰かによるパッチを適用する場合には、その名前とメールアドレスをログメッセージに 含めてください。ffmpeg-cvslog メーリングリストは公然と保管されているので、 そのメールアドレスにスパム防御を加えておくべきです。ffmpeg-devel (もしくは パッチを得たところ)へパッチを適用した旨の回答を送ってください。
10. メーリングリスト上で(長い間)議論されたパッチを適用する場合には、ログメッセージ でそのスレッドを参照してください。
11. 許可なしに他の人が積極的にメンテナンスしているコードをコミットしないでください。 代わりに ffmpeg-devel にパッチを送ってください。適当な時間枠(ビルドの失敗や セキュリティフィクスなら12時間、小さな変更なら3日、大きい変更なら1週間)以内で 誰も返答しない場合には、あなたが OK と考えるならそのパッチをコミットしてください。 また、メンテナは単にもっとレビューする時間を求めることもあることに注意してください!
12. ffmpeg-cvslog メーリングリストを購読してください。全てのコミットの diff が そこで送られており、他の開発者全員によってレビューされています。バグや 可能な改善、コミットに関する一般的な質問がそこで議論されています。我々は あなたのコードで問題が明らかになった場合にはあなたが反応することを期待して います。
13. 振舞いを変更または機能を追加する際にはドキュメントを更新してください。 更新する最善の方法が不確かな場合には、ffmpeg-devel にパッチを送ってください、 ドキュメントのメンテナがあなたのものをレビューしコミットするでしょう。
14. 公開の開発者メーリングリスト上で重要な議論や(さらに)要求を維持するよう 試みてください。全ての開発者がそこから恩恵を受けることができるように。
15. アロケートされていないメモリに決して書き込まないでください。 配列の終端を越えて書き込まないでください。 信用できないソースから読み込んだ値を配列のインデックスやその他のリスクの あるものとして使う前に確認してください。
16. あなたが変更している特定の libav パーツ(libavutil、libavcodec、libavformat)に ついてバージョンを上げる必要があるかどうか確認することを忘れないでください。 バージョン整数を変更する必要があります。 最初の構成要素をインクリメントすることは、以前のバージョンに対する後方互換性が ない(例えば公開 API からの関数の削除)ことを意味します。 2番目の構成要素をインクリメントすることは、後方互換である変更 (例えば公開 API に関数を追加する、または既に存在するデータ構造の拡張)を意味します。 3番目の構成要素をインクリメントすることは、注目に値するバイナリ互換である変更 (例えばデコーダーにとって重要であるエンコーダーのバグ修正)を意味します。
17. コンパイラの警告は潜在的なバグ、または良くないスタイルのコードを示唆しています。 ある種の警告が正しく潔白なコードを指摘する場合には、その警告を無効にすべきであり、 コードを変更するべきではありません。 したがって依然として残っている警告はバグ、もしくは正しいコードであるはずです。 それがバグなら、修正されなくてなりません。そうでないなら、そのコードは警告を 生まないように変更すべきです(それが速度低下や曖昧化を引き起こさない限りは)。
18. 新しいファイルを追加したら、それに正式なライセンスヘッダーを与えてください。 でたらめな場所からコピーアンドペースとしないでください。 テンプレートとしての存在しているファイルを使ってください。

我々は自分たちの規則がそれほど厳しくないと考えています。意見がありましたら、我々に連絡してください。

注意、これらの規則は大部分 MPlayer プロジェクトから借りています。

1.5 パッチを提出する

まず最初に、まだ未読なら上の (see Coding Rules) を読んでください。

パッチを提出する際には、unified diff(diff の’-up’ オプション)を送ることを 試みてください。他の diff は読めません :-)

また、各種の無関係な変更が含まれているパッチを提出しないでください。 それを個々の自己完結したパッチに分割してください。これはファイル1つ1つに 分割するということではありません。代わりに、出来る限りパッチを小さくし、 たとえ複数のファイルに渡るとしても1つの個別の変更を含む論理的な1単位として 保つようにしてください。これによってパッチは我々にとってさらにレビュー しやすくなり、パッチが適用される機会が大幅に増えます。

パッチを調査するための FFmpeg の patcheck ツールを使ってください。 このツールは tools ディレクトリにあります。

大きな問題がないことを調べられるように、パッチを提出する前に回帰テストを 実行してください。

パッチは base64 (またはパッチが伝送中にだめにならないことが保証されて いるその他のエンコーディングで)エンコードされた添付ファイルとして、 ffmpeg-devel メーリングリスト (http://lists.mplayerhq.hu/mailman/listinfo/ffmpeg-devel) を見てください)に投稿されるべきです。

また、そのパッチが行うこと(例えば ’lrint を lrintf で置き換える’)、および その理由(例えば ’*BSD は C99 準拠でなく lrint() がない’)を教えていただけたら 大いに助かります。

また、複数のパッチを送る際には、それぞれのパッチを別々のメールとして送って ください。同じメールに無関係な複数のパッチを添付しないでください。

あなたのパッチはメーリングリストでレビューされます。あなたはいくつかの変更を 求められたり、レビューからのリクエストを組み入れた修正版を送ることを期待されます。 このプロセスは複数回繰り返されて進むことがあります。パッチが十分よいと判断され次第、 開発者のだれかがそれを取り上げて公式の FFmpeg ツリーにコミットします。

反応するのに数日ください。しかし反応なしにいくらか時間が経過したら、 思い出すようメールを送ってください。いずれパッチは取り扱われるでしょう。

1.6 新しいコーデックまたはフォーマットチェックりすと

1. コーデックの初期化および完了の関数に av_cold を使いましたか?
2. AVCodec または AVInputFormat/AVOutputFormat 構造体に対し NULL_IF_CONFIG_SMALL の下に long_name を追加しましたか?
3. ‘avcodec.h’ または ‘avformat.h’ のマイナーバージョンナンバーを 上げ(、かつマイクロバージョンナンバーをリセットし)ましたか?
4. ‘allcodecs.c’ または ‘allformats.c’ の中にそれを登録しましたか?
5. ‘avcodec.h’ に CodecID を追加しましたか?
6. fourcc がある場合、たとえデコーダーのみの場合でもそれを ‘libavformat/riff.c’ に追加しましたか?
7. Makefile で適切なファイルがコンパイルされるように規則を追加しましたか? raw demuxer のような、ほかのいくつかの規則によって既にコンパイルされるファイルに単にフォーマットを追加するだけという場合でも、 これを忘れないようにしてください。
8. ‘doc/general.texi’ の中のサポートされているコーデックまたはフォーマットの一覧にエントリを 追加しましたか?
9. Changelog にエントリを追加しましたか?
10. それがあるパーサーまたはライブラリに依存する場合には、configure にその依存関係を 追加しましたか?
11. コミットする前に適切なファイルを "svn add" しましたか?

1.7 パッチ提出チェックリスト

1. そのパッチを適用して回帰テストに通りますか?
2. そのパッチを当てて make checkheaders が通りますか?
3. そのパッチは unified diff ですか?
4. そのパッチは最新の FFmpeg SVN に対するものですか?
5. ffmpeg-dev を購読していますか? (スパム対策のためリストは購読者のみです)
6. その変更が最小であること、そのためより小さなパッチや/またはより単純な最終的な コードでは同じことが達成できないことを確認しましたか?
7. その変更が重要なコードを速くするためのものなら、それをベンチマークで測りましたか?
8. そのパッチがバッファオーバーフローまたは他のセキュリティの問題を持ち込まない ことを確認しましたか?
9. decoder または demuxer を壊れたデータでテストしましたか? していない場合は tools/trasher や noise bitstream filter を見てください。decoder や demuxer は 壊れたデータを入力された際にクラッシュしたり無限ループ(に近い形)で終わるべきではありません。
10. そのパッチはソースツリーのルートから作成されていて、そのため patch -p0 で適用できるようになっていますか?
11. そのパッチには機能的な変更と表面的な変更を混ざっていませんか?
12. タブまたは行末の空白をコードに加えましたか? どちらも禁止されています。
13. そのパッチはあなたが送るメールに添付されていますか?
14. そのパッチの mime type は正しいですか? それは text/x-diff または text/x-patch であるべきで、text/plain は許されますが、application/octet-stream は許されません。
15. そのパッチがバグを修正しているなら、そのバグの詳しい分析を与えましたか?
16. そのパッチがバグを修正しているなら、サンプルを含めた十分な情報を与えており、 そのためバグを再現することができ修正を調べることができますか? 100kを越えるサンプルをメールに添付するのではなく、代わりに URL の形で提供するように 注意してください。ftp://upload.ffmpeg.org にアップロードできます。
17. そのパッチが変更することについて詳しい要約を与えましたか?
18. そのパッチがそのように変更を行う理由について詳しい説明を与えましたか?
19. そのパッチが適用された場合にユーザーから見える利点と欠点についての詳しい要約 を与えましたか?
20. そのパッチによって追加される新しい機能を簡単に調べられるよう例を与えましたか?
21. ベンチマークを取ったなら、それをメールの中で与えましたか?
22. 新しいファイルを追加したなら、ライセンスヘッダーを入れましたか? それは FFmpeg から取ってこられるべきで、どこか他からでたらめにコピーアンド ペーストされるべきではありません。
23. API/ABI 互換性を壊さない限り、アルファベット順に並んでいるリストでは その順序を維持するべきです。
24. そうすることで可読性が改善される場合には、似た内容の行は垂直に並べられる べきです。
25. 明確なコミットログメッセージについての提案を与えましたか?

1.8 パッチのレビューの過程

ffmpeg-devel に投稿された全てのパッチはレビューされるでしょう、そのパッチが SVN 向けでないという明確な注意が含まれていない限り。 レビューとコメントはパッチへの回答としてメーリングリスト上に投稿されます。 そしてパッチの提出者は全てのコメントに対処しなければならず、 それは変更したパッチの再提出や議論によってなされます。 パッチの再提出はそれ自体他のパッチと同様にレビューされます。 どこかの時点でコメントなしでレビューを通過したら、それは承認されます。 これは単純で小さなパッチについてはすぐに起こるでしょうが、 大きなパッチは一般的に承認される前に何回も変更されそしてレビューされるに違いありません。 パッチは承認された後でレポジトリにコミットされるでしょう。

我々は全ての提出されたパッチをレビューするでしょうが、ときおりとても忙しく、 特に大きなパッチに対しては数週間に及ぶことがあります。

パッチを再提出する場合には、レビューの間に受けたコメントに関係しない 重要な変更をしないでください。そういったパッチは拒絶されます。 代わりに、重大な変更または新しい機能を別のパッチとして提出してください。

1.9 回帰テスト

パッチを提出する(またはレポジトリにコミットする)前に、少なくとも あなたが何も壊さなかったかどうかテストするべきです。

回帰テストは合成のビデオストリームと合成のオーディオストリームをビルドします。 そしてこれらは 全てのコーデックまたはフォーマットでエンコードおよびデコード されます。生成された各ファイルの CRC (または MD5) は結果ファイルに記録 されます。参照結果とその結果ファイルとを比較するために ’diff’ が起動 されます。各テストが走った直後に出力が検査されます。

そして続けて、回帰テストは限られたストリームの集合で FFserver のコードを テストします。このステップが同様に正確に運ぶことが重要です。

全てのコーデックおよびフォーマットをテストするには ’make test’ を実行してください。 ’make regtest-mpeg2’ のようなコマンドが単一のテストを走らせるために使えます。 既定では、どのテストが失敗しても make は異常終了します。とにかくすべてのテストを 走らせるには、make -k を使ってください。より饒舌な出力を得るには、make ’V=1 test’ または ’make V=2 test’ を使ってください。

全てのコーデック、フォーマット、そして FFserver をテストするには ’make fulltest’ を実行してください。

[もちろん、回帰テストの結果を変更するようなパッチもあるでしょう。こういった 場合には、回帰テストの参照結果をそれに従って修正される方がよいでしょう]。

About This Document

This document was generated by Takeshi Abe on September 1, 2010 using texi2html 1.82.

The buttons in the navigation panels have the following meaning:

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

• 1. Section One
  • 1.1 Subsection One-One
    • ...
  • 1.2 Subsection One-Two
    • 1.2.1 Subsubsection One-Two-One
    • 1.2.2 Subsubsection One-Two-Two
    • 1.2.3 Subsubsection One-Two-Three     <== Current Position
    • 1.2.4 Subsubsection One-Two-Four
  • 1.3 Subsection One-Three
    • ...
  • 1.4 Subsection One-Four

This document was generated by Takeshi Abe on September 1, 2010 using texi2html 1.82.