guestfs-hacking - 云端在线

程序：

您的姓名

guestfs-hacking - 扩展和贡献 libguestfs

商品描述

本手册页适用于想要扩展 libguestfs 本身的黑客。

产品详情 OF “ 源 守则
Libguestfs 源码位于 github 仓库
https://github.com/libguestfs/libguestfs

libguestfs 中的大量样板代码（RPC、绑定、文档）是
生成。 这意味着许多源文件似乎从一个
简单的 git checkout。 你必须运行生成器 ("./autogen.sh && make -C
生成器”）以创建这些文件。

Libguestfs 使用基于自动工具的构建系统，主要文件为 配置文件
和 生成文件。 该 发电机 子目录包含生成器，以及描述
API。 这 SRC 子目录包含库的源代码。 这 器具 和 守护
子目录包含构建组件的代码源，以及代码
分别在设备中运行。 其他目录在本节中介绍
“源代码子目录”如下。

除了所有 API 入口点都通过一些生成的代码这一事实之外，该库是
直截了当。 （事实上​​，即使是生成的代码也被设计成可读的，并且应该
读作普通代码）。 一些动作完全在库中运行，并被编写为 C
下文件中的函数 SRC. 其他人被转发到守护进程（经过一些
生成的 RPC 编组）它们在下面的文件中显示为 C 函数 守护.

要从源代码构建，首先阅读“README”文件。

当地的* FILES
顶级源目录中以前缀开头的文件 当地的* 被 git 忽略。
这些文件可以包含构建 libguestfs 所需的本地配置或脚本。

按照惯例，我有一个名为 本地配置 这是一个简单的包装
自动生成文件 包含我需要的本地配置自定义：

. 本地环境
./autogen.sh \
--with-default-backend=libvirt \
--启用-gcc-警告\
--启用-gtk-doc \
-C \
“$@”

所以我可以用它来构建 libguestfs：

./localconfigure && make

如果顶层构建目录中有一个文件叫做 本地环境，那么它将来自
“制作”。 该文件可以包含所需的任何本地环境变量，例如。 跳过
测试：

# 使用替代的 python 二进制文件。
导出 Python=python3
# 跳过这个测试，它坏了。
导出 SKIP_TEST_BTRFS_FSCK=1

需要注意的是 本地环境 包含在顶部 Makefile 中（因此它是一个 Makefile 片段）。 但是如果
它也来自您的 本地配置 脚本然后它被用作shell脚本。

ADDING A 新品 API 活动正式启动
因为在 libguestfs 中生成了大量样板代码，这使得它很容易
扩展 libguestfs API。

要添加新的 API 操作，有两个更改：

1. 您需要添加调用的描述（名称、参数、返回类型、测试、
文件）到 生成器/actions.ml.

有两种 API 动作，取决于调用是否经过
设备中的守护进程，或者完全由库提供服务（请参阅“架构”
来宾内部(3))。 “guestfs_sync”中 来宾(3) 是前者的一个例子，
因为同步是在设备中完成的。 “guestfs_set_trace”中 来宾(3) 是一个
后者的示例，因为在句柄和所有跟踪中维护了跟踪标志
是在图书馆一侧完成的。

大多数新操作属于第一种类型，并被添加到“daemon_functions”列表中。
每个函数都有一个在 RPC 协议中使用的唯一过程号，它被分配
当我们发布 libguestfs 并且不能重用时，到那个动作。 拿最新的
程序编号并增加它。

对于第二种类型的仅限库的操作，添加到“non_daemon_functions”列表中。
由于这些函数由库提供服务并且不通过 RPC
守护进程的机制，这些函数不需要过程号，所以
程序编号设置为“-1”。

2. 执行操作（在 C 中）：

对于守护进程，实现函数“do_ “在“守护进程/”目录中。

对于库操作，实现函数“guestfs_impl_ “在“src/”
目录。

在任何一种情况下，使用另一个函数作为执行操作的示例。

进行这些更改后，使用“make”进行编译。

请注意，您不需要实现 RPC、语言绑定、手册页或任何东西
别的。 它都是从 OCaml 描述自动生成的。

ADDING 试验 用于 AN API 活动正式启动
您可以为每个 API 调用提供零个或任意多个测试。 测试可以是
作为 API 描述的一部分添加（生成器/actions.ml)，或者在一些罕见的情况下你
可能想要将脚本放入“tests/*/”。 请注意，将脚本添加到“tests/*/”是
速度较慢，因此如果可能，请使用第一种方法。

下面介绍在添加API测试时使用的测试环境 动作.ml.

测试环境有4个块设备：

/ dev / sda上的 500MB
用于测试的通用块设备。

的/ dev / sdb的 500MB
的/ dev / sdb1 是用于测试文件系统写入操作的 ext2 文件系统。

的/ dev / SDC 10MB
在一些需要两个块设备的测试中使用。

的/ dev / SDD
具有固定内容的 ISO（请参阅 图像/test.iso).

为了能够在合理的时间内运行测试，libguestfs 设备和
块设备在测试之间重用。 所以不要尝试测试“guestfs_kill_subprocess”
来宾(3):-x

每个测试都从一个初始场景开始，使用“Init*”表达式之一进行选择，
描述于 生成器/types.ml. 这些初始化上面提到的磁盘
记录在的特定方式 类型.ml. 你不应该假设任何关于
未初始化的其他磁盘的先前内容。

您可以向任何单个测试添加先决条件子句。 这是一个运行时检查，
如果失败，则会导致跳过测试。 在测试命令时很有用
可能不适用于 libguestfs 构建的所有变体。 一个有先决条件的测试
“始终”意味着无条件地运行。

此外，打包者可以通过在之前设置环境变量来跳过单个测试
运行“检查”。

跳过_测试_ _ =1

例如：“SKIP_TEST_COMMAND_3=1”跳过“guestfs_command”中的测试#3 来宾（3）。

要么：

跳过_测试_ =1

例如：“SKIP_TEST_ZEROFREE=1”跳过所有“guestfs_zerofree” 来宾(3)测试。

打包程序只能通过设置运行某些测试，例如：

TEST_ONLY="vfs_type zerofree"

参见 测试/c-api/tests.c 有关这些环境变量如何工作的更多详细信息。

调试 新品 API 行动
在提交新动作之前测试它们的效果。

您可以使用 guestfish 来尝试新命令。

调试守护进程是一个问题，因为它在最小环境中运行。 然而
您可以将守护进程中的 fprintf 消息发送到 stderr，如果您使用它们，它们将显示
“guestfish -v”。

ADDING A 新品 语言 捆绑
所有语言绑定都必须由生成器生成（请参阅 发电机 子目录）。

目前还没有这方面的文档。 我们建议您查看现有的绑定，例如。
生成器/ocaml.ml or 生成器/perl.ml.

ADDING 试验 用于 语言 绑定
语言绑定应该带有测试。 以前对语言绑定的测试是
相当临时，但我们一直试图将每种语言的测试集正式化
绑定应该使用。

目前只有 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+ 应该启动手柄。

格式化 守则
我们的 C 源代码通常遵循一些基本的代码格式约定。 这
现有的代码库在这方面并不完全一致，但我们更喜欢
贡献的代码格式类似。 简而言之，使用空格而不是制表符来缩进，
每个缩进级别使用 2 个空格，除此之外，请遵循 K&R 样式。

如果您使用 Emacs，请将以下内容添加到您的启动文件之一（例如， 〜/.emacs),
帮助确保您正确缩进：

;;; 在 libguestfs 中，到处都用空格缩进（不是制表符）。
;;; 例外：Makefile 和 ChangeLog 模式。
(添加钩子'查找文件钩子
'(lambda() (if (and buffer-file-name)
（字符串匹配“/libguestfs\\>”
（缓冲区文件名））
（不是（字符串等于模式名称“更改日志”））
（不是（字符串等于模式名称“Makefile”）））
(setq 缩进制表符模式 nil))))

;;; 在 libguestfs 中编辑 C 源代码时，请使用此样式。
(defun libguestfs-c-mode()
“具有调整默认值的 C 模式与 libguestfs 一起使用。”
（交互的）
（c-set 风格的“K&R”）
(setq c-缩进级别 2)
(setq c-基本偏移 2))
(添加钩子 'c-mode-hook
'(lambda() (if (string-match "/libguestfs\\>"
（缓冲区文件名））
(libguestfs-c-模式))))

测试 你的 变化
编译时启用警告（并修复发现的任何问题）：

./configure --enable-gcc-警告

有用的目标是：

“做检查”
运行常规测试套件。

这是使用常规 automake "TESTS" 目标实现的。 看到汽车制造商
有关详细信息的文档。

“进行检查-valgrind”
在 valgrind 下运行测试套件的子集。

任何 生成文件 在具有“check-valgrind：”目标的树中，将由此运行
规则。

“检查valgrind-local-guests”
使用本地安装的 libvirt 来宾在 valgrind 下运行测试套件的子集
（只读）。

“直接检查”
使用默认设备后端运行所有测试。 这仅在非
使用“./configure --with-default-backend=...”选择默认后端

“进行检查-valgrind-direct”
使用默认设备后端在 valgrind 下运行测试套件的子集。

“检查-uml”
使用用户模式 ​​Linux 后端运行所有测试。

由于用户模式 ​​Linux 内核没有标准位置，因此您 它们在许多情况下都能提供类似的结果。 设置
“LIBGUESTFS_HV”指向内核映像，例如：

检查 uml LIBGUESTFS_HV=〜/ d / linux-um / vmlinux

“进行检查-valgrind-uml”
在 valgrind 下使用用户模式 ​​Linux 后端运行所有测试。

如上所述，您必须将“LIBGUESTFS_HV”设置为指向内核。

“使用上游 qemu 进行检查”
使用本地 qemu 二进制文件运行所有测试。 它在 QEMUDIR 中查找 qemu 二进制文件
（默认为 $HOME/d/qemu)，但您可以在命令中将其设置为另一个目录
行，例如：

使用上游 qemu 进行检查 QEMUDIR=/usr/src/qemu

“使用上游 libvirt 进行检查”
使用本地 libvirt 运行所有测试。 这仅在 libvirt 后端有任何影响
使用“./configure --with-default-backend=libvirt”选择

它在 LIBVIRTDIR 中查找 libvirt（默认为 $HOME/d/libvirt)，但你可以设置这个
到命令行上的另一个目录，例如：

使用上游 libvirt 检查 LIBVIRTDIR=/usr/src/libvirt

“让检查变慢”
运行一些默认情况下不运行的缓慢/长时间运行的测试。

任何 生成文件 在具有“check-slow:”目标的树中，将按此规则运行。

“全部检查”
相当于运行所有“make check*”规则。

“做检查释放”
运行一个“make check*”规则的子集，这些规则在 tarball 可以被通过之前
释放。 目前这是：

· 查看

·检查valgrind

·直接检查

·检查valgrind直接

·检查缓慢

“进行安装检查”
在安装的 libguestfs 副本上运行“make check”。

正在测试的已安装 libguestfs 的版本，以及 libguestfs 的版本
源树必须相同。

这样做：

./autogen.sh
清洁||：
使
进行安装检查

达蒙 定制 打印 格式化程序
在守护程序代码中，我们创建了自定义 printf 格式化程序 %Q 和 %R，它们用于
做外壳引用。

%Q 简单的 shell 引用字符串。 任何空格或其他 shell 字符都会为您转义。

%R 与 %Q 相同，但字符串被视为以 sysroot 为前缀的路径。

例如：

asprintf (&cmd, "cat %R", 路径);

会产生“cat /sysroot/some\path\with\spaces”

请注意： Do 而不去 当您将参数传递给“command{,r,v,rv}()”时使用这些
职能。 这些参数不需要被引用，因为它们不是通过
shell（而是直接执行）。 您可能想使用“sysroot_path()”函数
然而。

提交 你的 新品 API 行动
将补丁提交到邮件列表： http://www.redhat.com/mailman/listinfo/libguestfs 和
抄送 [电子邮件保护].

国际化 （国际化） 客户服务
我们在库中支持 i18n（无论如何都是 gettext）。

然而，许多消息来自守护进程，我们目前不翻译这些消息。
原因之一是设备通常会从中删除所有区域设置文件，因为
它们占用了大量空间。 所以我们必须阅读其中一些，以及复制我们的
PO 文件导入设备。

调试消息永远不会被翻译，因为它们是为程序员准备的。

源 守则 子目录
对齐
虚拟对齐扫描(1) 命令和文档。

器具
libguestfs 组件、构建脚本等。

打坏
Bash 选项卡完成脚本。

构建辅助
autotools 使用的各种构建脚本。

建设者
虚拟建设者(1) 命令和文档。

猫 - 虚拟猫（1） 虚拟文件系统（1） 虚拟日志（1）和 虚拟机(1) 命令和
文档。

的contrib
外部贡献，实验部分。

定制
虚拟定制(1) 命令和文档。

守护
在 libguestfs 设备内运行并执行操作的守护程序。

df 虚拟机(1) 命令和文档。

迪伯 虚拟机(1) 命令和文档。

差异
虚拟差异(1) 命令和文档。

DOC 各种手册页。

编辑
虚拟编辑(1) 命令和文档。

例子
C API 示例代码。

鱼露
客鱼(1)、命令行shell，以及建立在上面的各种shell脚本如
虚拟拷贝（1） 虚拟拷贝（1） 虚拟机（1） 解压（1）。

格式
虚拟格式(1) 命令和文档。

保险丝
来宾山(1)、FUSE（用户空间文件系统）建立在libguestfs之上。

发电机
至关重要的生成器，用于自动生成大量
用于诸如 RPC 和绑定之类的样板 C 代码。

获取内核
虚拟获取内核(1) 命令和文档。

库库库
Gnulib 用作可移植性库。 此处包含 gnulib 的副本。

检查员
虚拟检查员(1)、虚拟机镜像检查器。

商标
网站上使用的标志。 顺便说一下，这条鱼叫亚瑟。

m4 autoconf 使用的 M4 宏。

制作-fs
virt-make-fs(1) 命令和文档。

毫升库
使用的各种库和通用代码 虚拟调整大小(1) 和其他工具
用 OCaml 编写。

2 虚拟-p2v(1) 用于构建 virt-p2v ISO 或磁盘的命令、文档和脚本
图片。

po 简单 gettext 字符串的翻译。

文档
用于翻译联机帮助页和 POD 文件的构建基础结构和 PO 文件。
最终这将与 po 目录，但那是
复杂。

营救
虚拟救援(1) 命令和文档。

调整
虚拟调整大小(1) 命令和文档。

稀疏化
虚拟化(1) 命令和文档。

SRC C 库的源代码。

系统预备
虚拟系统准备(1) 命令和文档。

测试
测试。

测试数据
测试使用的文件和其他测试数据。

测试工具
供最终用户测试他们的 qemu/内核组合是否适用的测试工具
libguestfs。

TMP 运行测试时用于临时文件（而不是 / tmp目录 等等）。 原因是
这样您就可以在没有一组 libguestfs 的情况下运行多个并行测试
测试覆盖另一个创建的设备。

工具
用 Perl 编写的命令行工具（虚拟双赢注册（1）和许多其他）。

v2v virt-v2v(1) 命令和文档。

官网
- http://libguestfs.org 网站文件。

尖锐的
二郎
对象
golang
哈斯克尔
java的
月亮
卡姆
PHP
perl的
蟒蛇
红宝石
语言绑定。

MAKING A 稳定 RELEASE
当我们发布稳定版本时，这里记录了几个步骤。 见“LIBGUESTFS
版本号”在 来宾(3) 有关稳定分支政策的一般信息。

· 检查“make && make check”至少适用于 Fedora、Debian 和 Ubuntu。

· 检查“./configure --without-libvirt”是否有效。

· 敲定 guestfs-release-notes.pod

·从Zanata推拉。

跑：

扎那塔推

将最新的 POT 文件推送到 Zanata。 然后运行：

./zanata-pull.sh

这是提取最新翻译的包装器 *.po 文件。

· 考虑将 gnulib 更新到最新的上游版本。

· 在下面创建新的稳定和开发目录 http://libguestfs.org/download.

· 编辑 网站/index.html.in.

· 设置版本（在 配置文件) 到新 稳定 版本，即。 1.XX.0，并提交
它：

./本地配置
使 distclean -k
./本地配置
make && make dist
使维护者提交
制作维护者标签

· 在 git 中创建稳定分支：

git 分支 stable-1.XX
git push origin stable-1.XX

· 做一个稳定分支的完整发布。

· 将版本设置为下一个开发版本并提交。 可选地做一个完整的
开发分支的发布。

使用 onworks.net 服务在线使用 guestfs-hacking