guestfs-hacking - クラウド上のオンライン

プログラム：

NAME

guestfs-hacking - libguestfs の拡張と貢献

DESCRIPTION

このマニュアル ページは、libguestfs 自体を拡張したいハッカー向けです。

概要 OF ザ SOURCE CODE
Libguestfs ソースは github リポジトリにあります
https://github.com/libguestfs/libguestfs

libguestfs 内の大量の定型コード (RPC、バインディング、ドキュメント) は、
生成された。 これは、多くのソース ファイルがファイルから欠落しているように見えることを意味します。
簡単な git チェックアウト。 ジェネレーターを実行する必要があります ("./autogen.sh && make -C
ジェネレーター") を使用してこれらのファイルを作成します。

Libguestfs は autotools ベースのビルド システムを使用しており、メイン ファイルは次のとおりです。 configure.ac
& Makefile.amを選択します。 ジェネレータ サブディレクトリにはジェネレーターと、それを説明するファイルが含まれています。
API。 の SRC サブディレクトリにはライブラリのソースが含まれています。 の アプライアンス & デーモン
サブディレクトリには、アプライアンスを構築するコードのソースとコードが含まれています。
それぞれアプライアンス内で実行されます。 他のディレクトリについては、このセクションで説明します。
以下の「ソースコードサブディレクトリ」。

すべての API エントリ ポイントが生成されたコードを経由するという事実を除けば、ライブラリは次のようになります。
率直な。 (実際、生成されたコードも読みやすいように設計されており、
通常のコードとして読み取れます)。 一部のアクションは完全にライブラリ内で実行され、C として記述されます。
以下のファイル内の関数 SRC。 他のものはデーモンに転送され、そこで (いくつかの後に
生成された RPC マーシャリング)、これらは以下のファイルに C 関数として表示されます。 デーモン.

ソースからビルドするには、まず「README」ファイルをお読みください。

地元* ファイル
最上位のソース ディレクトリ内の、接頭辞で始まるファイル 地元* git によって無視されます。
これらのファイルには、libguestfs を構築するために必要なローカル構成またはスクリプトを含めることができます。

慣例により、次のようなファイルがあります。 ローカル構成 これは単純なラッパーです
autogen.sh 必要なローカル構成のカスタマイズが含まれています。

。 ローカル環境
./autogen.sh \
--with-default-backend=libvirt \
--enable-gcc-warnings \
--enable-gtk-doc \
-C \
「$ @」

したがって、これを使用して libguestfs をビルドできます。

./localconfigure && make

最上位のビルド ディレクトリに次の名前のファイルがある場合 ローカル環境、その場合、ソースは次のとおりです。
"作る"。 このファイルには、必要なローカル環境変数を含めることができます。 スキップ用
テスト：

# 代替の Python バイナリを使用します。
エクスポート PYTHON=python3
# このテストは壊れているのでスキップしてください。
エクスポート SKIP_TEST_BTRFS_FSCK=1

注意してください ローカル環境 先頭の Makefile にインクルードされます (つまり、Makefile フラグメントです)。 しかし、もし
それもあなたから供給されています ローカル構成 スクリプトを作成すると、シェル スクリプトとして使用されます。

追加 A NEW API ACTION
libguestfs では大量の定型コードが生成されるため、これにより、
libguestfs API を拡張します。

新しい API アクションを追加するには、次の XNUMX つの変更があります。

1. 呼び出しの説明 (名前、パラメータ、戻り値の型、テスト、
ドキュメント）へ ジェネレーター/アクション.ml.

API アクションには、呼び出しが
アプライアンスのデーモン、またはライブラリによって完全にサービスされます (「アーキテクチャ」を参照)
ゲストの内部(3))。 「guestfs_sync」の ゲスト(3)は前者の例です。
同期はアプライアンス内で行われるためです。 「guestfs_set_trace」 ゲスト（3）は
後者の例では、トレース フラグがハンドルとすべてのトレースに維持されるため、
ライブラリ側で行われます。

ほとんどの新しいアクションは最初のタイプであり、「daemon_functions」リストに追加されます。
各関数には、RPC プロトコルで使用される固有のプロシージャ番号が割り当てられています。
libguestfs を公開するときにそのアクションに追加され、再利用できません。 最新のものを取る
手順番号を入力してインクリメントします。

XNUMX 番目のタイプのライブラリのみのアクションの場合は、「non_daemon_functions」リストに追加します。
これらの関数はライブラリによって提供され、RPC を経由しないため、
メカニズムをデーモンに渡す場合、これらの関数にはプロシージャ番号は必要ないため、
手続き番号は「-1」に設定されます。

2. アクションを実装します (C で)。

デーモンアクションの場合、関数「do_」を実装します。 " daemon/" ディレクトリにあります。

ライブラリアクションの場合、関数「guestfs_impl_」を実装します。 「src/」の「
ディレクトリにあります。

いずれの場合も、実行方法の例として別の関数を使用してください。

これらの変更を加えた後、「make」を使用してコンパイルします。

RPC、言語バインディング、マニュアルページなどを実装する必要がないことに注意してください。
それ以外。 これらはすべて OCaml の記述から自動的に生成されます。

追加 TESTS FOR AN API ACTION
API 呼び出しごとに、ゼロまたは必要な数のテストを指定できます。 テストは次のいずれかです
API の説明の一部として追加されました (ジェネレーター/アクション.ml)、または、まれに、
スクリプトを「tests/*/」にドロップするとよいでしょう。 「tests/*/」にスクリプトを追加するのは
速度が遅くなるため、可能であれば最初の方法を使用してください。

APIテストを追加する際に使用するテスト環境について説明します。 アクション.ml.

テスト環境には 4 つのブロック デバイスがあります。

/ dev / sdaに 500MB
テスト用の汎用ブロックデバイスです。

/ dev / sdb 500MB
/ dev / sdb1 ファイルシステム書き込み操作のテストに使用される ext2 ファイルシステムです。

/ dev / sdc 10MB
XNUMX つのブロック デバイスが必要ないくつかのテストで使用されます。

/ dev / sdd
固定コンテンツを含む ISO (「 画像/test.iso).

適切な時間内にテストを実行できるようにするには、libguestfs アプライアンスと
ブロックデバイスはテスト間で再利用されます。 したがって、「guestfs_kill_subprocess」をテストしないでください。
ゲスト(3) :-x

各テストは、「Init*」式の XNUMX つを使用して選択された初期シナリオから始まります。
に記載 ジェネレーター/types.ml。 これらは上記のディスクを初期化します。
に文書化されている特定の方法 タイプ.ml。 については何も想定しないでください。
初期化されていない他のディスクの以前の内容。

前提条件句を個々のテストに追加できます。 これは実行時チェックです。
失敗すると、テストがスキップされます。 コマンドをテストする場合に便利です。
libguestfs ビルドのすべてのバリエーションでは動作しない可能性があります。 前提条件があるテスト
「常に」とは、無条件に実行することを意味します。

さらに、パッケージャは、事前に環境変数を設定することで、個々のテストをスキップできます。
「メイクチェック」を実行します。

スキップ_テスト_ _ =1

例: 「SKIP_TEST_COMMAND_3=1」は、「guestfs_command」のテスト #3 をスキップします。 ゲストとします。

または：

スキップ_テスト_ =1

例: 「SKIP_TEST_ZEROFREE=1」は、すべての「guestfs_zerofree」をスキップします。 ゲスト(3) テスト。

パッケージャは、たとえば次のように設定することで、特定のテストのみを実行できます。

TEST_ONLY="vfs_type ゼロフリー"

見る テスト/c-api/tests.c これらの環境変数がどのように機能するかについて詳しくは、こちらを参照してください。

デバッグ NEW API ACTIONS
新しいアクションを送信する前に、その動作をテストしてください。

guestfish を使用して、新しいコマンドを試すことができます。

デーモンは最小限の環境内で実行されるため、デバッグが問題になります。 しかし
デーモン内のメッセージを stderr に fprintf することができます。これらは、次のコマンドを使用すると表示されます。
「ゲストフィッシュ -v」。

追加 A NEW 言語 バインド
すべての言語バインディングはジェネレーターによって生成される必要があります ( ジェネレータ サブディレクトリ)。

これに関するドキュメントはまだありません。 既存のバインディングを確認することをお勧めします。
ジェネレーター/ocaml.ml or ジェネレーター/perl.ml.

追加 TESTS FOR 言語 バインディング
言語バインディングにはテストが付属する必要があります。 以前は、言語バインディングのテストは
むしろアドホックですが、私たちはあらゆる言語が実行できる一連のテストを形式化しようと努めてきました。
バインディングは使用する必要があります。

現在、実際にテストの完全なセットを実装しているのは OCaml と Perl バインディングだけです。
OCaml バインディングは正規であるため、OCaml テストの動作をエミュレートする必要があります。

これはテストで使用される番号付けスキームです。

- 000 以上の基本テスト:

010 ライブラリをロードする
020 作成する
030 フラグの作成
040 複数のハンドルを作成する
050 テストの設定と構成プロパティの取得
060 明示的に閉じる
065 暗黙的なクローズ (GC 言語の場合)
070 オプトターグ

- 100 回の起動、パーティション、LV、ファイルシステムの作成

- 400以上のイベント:

410クローズイベント
420 ログメッセージ
430 件の進捗メッセージ

- 800 以上の回帰テスト (言語に固有)

- 言語に関する 900 以上のその他のカスタム テスト

テストの実行時間を節約するために、100、430、800+、900+ のみがハンドルを起動する必要があります。

フォーマット CODE
当社の C ソース コードは通常、いくつかの基本的なコード形式規則に従っています。 の
既存のコードベースはこの点で完全に一貫しているわけではありませんが、私たちはそれを好むのです。
提供されたコードも同様にフォーマットされます。 つまり、インデントにはタブではなくスペースを使用します。
インデントレベルごとに 2 つのスペースを使用し、それ以外は K&R スタイルに従います。

Emacs を使用している場合は、起動ファイルの XNUMX つに以下を追加します (例: ~/.emacs),
インデントを正しく行うには、次のようにします。

;;; libguestfs では、すべての場所 (TAB ではなく) をスペースでインデントします。
;;; 例外: Makefile モードと ChangeLog モード。
(追加フック 'ファイルフックの検索
'(lambda () (if (およびバッファファイル名)
(文字列一致 "/libguestfs\\>"
(バッファファイル名))
(not (文字列とモード名が等しい「変更ログ」))
(not (文字列と等しいモード名 "Makefile")))
(setq indent-tabs-mode nil))))

;;; libguestfs で C ソースを編集する場合は、このスタイルを使用します。
(defun libguestfs-c-mode ()
「libguestfs で使用するためにデフォルトが調整された C モード。」
（相互の作用）
(c-setスタイル「K&R」)
(setq c-indent-level 2)
(setq c-basic-offset 2))
(追加フック 'c-モードフック
'(lambda () (if (文字列一致 "/libguestfs\\>"
(バッファファイル名))
(libguestfs-c-mode))))

TESTING サプライヤ CHANGES
コンパイル時の警告を有効にします (そして、検出された問題を修正します)。

./configure --enable-gcc-warnings

有用なターゲットは次のとおりです。

「小切手を作る」
通常のテストスイートを実行します。

これは、通常の automake "TESTS" ターゲットを使用して実装されます。 オートメイクを参照してください
を参照してください。

「チェック-valgrindを作る」
valgrind でテスト スイートのサブセットを実行します。

任意 Makefile.am 「check-valgrind:」ターゲットを持つツリー内はこれによって実行されます
ルール。

「make check-valgrind-local-guests」
ローカルにインストールされた libvirt ゲストを使用して、valgrind の下でテスト スイートのサブセットを実行します
（読み取り専用）。

「チェックダイレクトを行う」
デフォルトのアプライアンスのバックエンドを使用してすべてのテストを実行します。 これは、そうでない場合にのみ効果があります。
デフォルトのバックエンドは「./configure --with-default-backend=...」を使用して選択されました

「チェック-valgrind-directを作成する」
デフォルトのアプライアンス バックエンドを使用して、valgrind でテスト スイートのサブセットを実行します。

「チェックUMLを作る」
ユーザーモード Linux バックエンドを使用してすべてのテストを実行します。

ユーザーモード Linux カーネルには標準の場所がないため、 持ってる 設定します
「LIBGUESTFS_HV」はカーネル イメージを指します。例:

make check-uml LIBGUESTFS_HV=~/d/linux-um/vmlinux

「make check-valgrind-uml」
ユーザーモード Linux バックエンドを使用して、valgrind ですべてのテストを実行します。

上記のように、カーネルを指すように「LIBGUESTFS_HV」を設定する必要があります。

「upstream-qemu でチェックを行う」
ローカルの qemu バイナリを使用してすべてのテストを実行します。 QEMUDIR で qemu バイナリを探します
(デフォルトは $HOME/d/qemu）ですが、コマンドでこれを別のディレクトリに設定できます
行、例:

make check-with-upstream-qemu QEMUDIR=/usr/src/qemu

「アップストリーム libvirt でチェックを行う」
ローカルの libvirt を使用してすべてのテストを実行します。 これは、libvirt バックエンドがサポートされている場合にのみ効果があります。
「./configure --with-default-backend=libvirt」を使用して選択されました

LIBVIRTDIR で libvirt を探します (デフォルトは $HOME/d/libvirt)、ただしこれを設定することもできます
コマンドラインで別のディレクトリに移動します。例:

アップストリーム libvirt でチェックを行う LIBVIRTDIR=/usr/src/libvirt

「チェックを遅くする」
デフォルトでは実行されない、低速または長時間実行されるテストを実行します。

任意 Makefile.am 「check-slow:」ターゲットを持つツリー内は、このルールによって実行されます。

「すべてチェックを入れる」
すべての「make check*」ルールを実行するのと同等です。

「チェック・リリースを行う」
tarball を作成する前に通過する必要がある「make check*」ルールのサブセットを実行します。
解放されました。 現在、これは次のとおりです。

・ チェック

· チェック-valgrind

· 直接チェック

· チェック-valgrind-direct

· チェックが遅い

「インストールチェックを行う」
インストールされた libguestfs のコピーに対して「make check」を実行します。

テスト対象のインストール済み libguestfs のバージョンと libguestfs のバージョン
ソースツリーは同じである必要があります。

操作を行います。

./autogen.sh
きれいにする ||:
make
インストールチェックを行う

デーモン CUSTOM 印刷 フォーマッター
デーモン コードでは、カスタム printf フォーマッタ %Q および %R を作成しました。
シェルクォートを実行します。

%Q 単純なシェル引用符付き文字列。 スペースやその他のシェル文字はエスケープされます。

%R %Q と同じですが、文字列は sysroot がプレフィックスとして付けられたパスとして扱われます。

例：

asprintf (&cmd, "cat %R", パス);

「cat /sysroot/some\ path\ with\ space」が生成されます

注： Do これらは、「command{,r,v,rv}()」にパラメータを渡すときに使用します。
機能。 これらのパラメータは、
シェル (代わりに直接実行)。 おそらく「sysroot_path()」関数を使用するとよいでしょう。
しかし。

送信 サプライヤ NEW API ACTIONS
パッチをメーリング リストに送信します。 http://www.redhat.com/mailman/listinfo/libguestfs &
CCから [メール保護].

国際化 (I18N) サポート
ライブラリでは i18n (とにかく gettext) をサポートしています。

ただし、デーモンから多くのメッセージが送信されるため、現時点ではそれらのメッセージは翻訳されません。
理由の XNUMX つは、通常、アプライアンスからすべてのロケール ファイルが削除されていることです。
それらは多くのスペースを占めます。 したがって、それらのいくつかを再読み込みするだけでなく、
PO ファイルをアプライアンスに転送します。

デバッグ メッセージはプログラマ向けであるため、翻訳されることはありません。

SOURCE CODE サブディレクトリ
整列する
virt-alignment-scan(1) コマンドとドキュメント。

アプライアンス
libguestfs アプライアンス、ビルド スクリプトなど。

bash
Bash のタブ補完スクリプト。

ビルド補助
オートツールによって使用されるさまざまなビルド スクリプト。

ビルダー
仮想ビルダー(1) コマンドとドキュメント。

cat 　 仮想猫（1） virt-ファイルシステム（1） 仮想ログ（1）と virt-ls(1) コマンドと
のドキュメントで詳しく説明されています）。

貢献する
外部からの貢献、実験的な部分。

カスタマイズ
virt-カスタマイズ(1) コマンドとドキュメント。

デーモン
libguestfs アプライアンス内で実行され、アクションを実行するデーモン。

df virt-df(1) コマンドとドキュメント。

ディブ virt-dib(1) コマンドとドキュメント。

差分
仮想差分(1) コマンドとドキュメント。

DOC その他のマニュアルページ。

edit
virt-編集(1) コマンドとドキュメント。

例
C API のサンプル コード。

魚
ゲストフィッシュ(1)、コマンドライン シェル、およびその上に構築されたさまざまなシェル スクリプト
仮想コピーイン（1） 仮想コピーアウト（1） 仮想タールイン（1） 仮想タールアウトとします。

形式でアーカイブしたプロジェクトを保存します．
仮想フォーマット(1) コマンドとドキュメント。

ヒューズ
ゲストマウント(1)、libguestfs 上に構築された FUSE (ユーザー空間ファイルシステム)。

ジェネレータ
大量のデータを自動的に生成するために使用される、非常に重要なジェネレーター。
RPC やバインディングなどの定型的な C コード。

カーネルを取得
virt-get-カーネル(1) コマンドとドキュメント。

グヌーリブ
Gnulib は移植性ライブラリとして使用されます。 gnulib のコピーはここに含まれています。

検査官
virt-インスペクター(1)、仮想マシンイメージインスペクタ。

ロゴ
ウェブサイトで使用されているロゴ。 ちなみにこの魚の名前はアーサーです。

m4 autoconf で使用される M4 マクロ。

メイクアップ
virt-make-fs(1) コマンドとドキュメント。

mllib
で使用されるさまざまなライブラリと共通コード virt-サイズ変更(1) とその他のツール
OCamlで書かれています。

p2v virt-p2v(1) virt-p2v ISO またはディスクを構築するためのコマンド、ドキュメント、およびスクリプト
画像。

po 単純な gettext 文字列の翻訳。

ポドックス
マンページと POD ファイルの翻訳用のインフラストラクチャと PO ファイルを構築します。
最終的にはこれと組み合わせる予定です po ディレクトリですが、それはむしろ
複雑です。

レスキュー用機材
仮想レスキュー(1) コマンドとドキュメント。

リサイズ
virt-サイズ変更(1) コマンドとドキュメント。

まばらにする
仮想スパース化(1) コマンドとドキュメント。

SRC C ライブラリへのソース コード。

sysprepを
virt-sysprep(1) コマンドとドキュメント。

テスト
テスト

テストデータ
テストで使用されるファイルおよびその他のテスト データ。

テストツール
エンド ユーザーが qemu/カーネルの組み合わせが動作するかどうかをテストするためのテスト ツール
libguestfs。

TMP テスト実行時の一時ファイルとして使用されます（代わりに） / tmpに 等）。 その理由は
これにより、XNUMX セットの libguestfs を用意しなくても、libguestfs の複数の並列テストを実行できます。
テストでは、別のアプライアンスが作成したアプライアンスを上書きします。

豊富なツール群
Perl で書かれたコマンド ライン ツール (virt-win-reg(1) およびその他多数)。

v2v virt-v2v(1) コマンドとドキュメント。

ウェブサイト
　 http://libguestfs.org ウェブサイトのファイル。

Cシャープ
アーラン
ゴオブジェクト
ゴラン
ハスケル
ジャワ
ムーン
オカムル
PHP
パール
パイソン
ルビー
言語バインディング。

メイキング A 安定 RELEASE
安定版リリースを作成する場合、ここにいくつかの手順が記載されています。 「LIBGUESTFS」を参照
バージョン番号」 ゲスト(3) 安定版ブランチ ポリシーに関する一般情報。

· 「make && make check」が少なくとも Fedora、Debian、Ubuntu で動作することを確認します。

· 「./configure --without-libvirt」が機能することを確認します。

・ファイナライズ guestfs-release-notes.pod

・ザナタから押し引き。

実行：

ザナタプッシュ

最新の POT ファイルを Zanata にプッシュします。 次に、次を実行します。

./zanata-pull.sh

これは、最新の翻訳済みファイルをプルするためのラッパーです * .po ファイル。

· gnulib を最新のアップストリーム バージョンに更新することを検討してください。

· 新しい安定ディレクトリと開発ディレクトリを以下に作成します。 http://libguestfs.org/download.

・編集 ウェブサイト/index.html.in.

· バージョンを設定します( configure.ac) 新しいものへ 安定した バージョン、つまり。 1.XX.0、コミット
それ：

./localconfigure
distclean を作成します -k
./localconfigure
make && make dist
メンテナをコミットさせる
メンテナタグを作成する

· git で安定したブランチを作成します。

git ブランチ 安定版-1.XX
git プッシュオリジン安定版-1.XX

· 安定版ブランチを完全にリリースします。

· バージョンを次の開発バージョンに設定し、コミットします。 必要に応じて、完全な
開発ブランチのリリース。

onworks.net サービスを使用してオンラインで guestfs-hacking を使用する