guestfs-hacking - Интернет в облаке

ПРОГРАММА:

ИМЯ

guestfs-hacking - расширение и добавление libguestfs

ОПИСАНИЕ

Эта страница руководства предназначена для хакеров, которые хотят расширить саму libguestfs.

О проекте OF ИСТОЧНИК КОД
Исходный код Libguestfs находится в репозитории github
https://github.com/libguestfs/libguestfs

Большой объем стандартного кода в libguestfs (RPC, привязки, документация)
сгенерировано. Это означает, что многие исходные файлы будут отсутствовать в
простая проверка git. Вы должны запустить генератор ("./autogen.sh && make -C
генератор ") для создания этих файлов.

Libguestfs использует систему сборки на основе автоинструментов, при этом основные файлы настроить.ac
и Makefile.am, генератор подкаталог содержит генератор, а также файлы с описанием
API. В SRC подкаталог содержит исходный код библиотеки. В прибор и демон
подкаталоги содержат исходный код для кода, который строит устройство, и код
который работает в приборе соответственно. Остальные каталоги описаны в разделе
«ПОДКАТАЛОГИ ИСХОДНОГО КОДА» ниже.

Помимо того, что все точки входа в API проходят через некоторый сгенерированный код, библиотека
простой. (На самом деле, даже сгенерированный код предназначен для чтения и должен
можно читать как обычный код). Некоторые действия выполняются полностью в библиотеке и записываются как C
функции в файлах в SRC. Остальные перенаправляются демону, где (после некоторого
сгенерированный маршаллинг RPC) они отображаются как функции C в файлах в демон.

Чтобы собрать из исходников, сначала прочтите файл «README».

местный* FILES
Файлы в верхнем исходном каталоге, начинающиеся с префикса местный* игнорируются git.
Эти файлы могут содержать локальную конфигурацию или сценарии, необходимые для сборки libguestfs.

По соглашению у меня есть файл с именем локальная конфигурация который представляет собой простую оболочку вокруг
autogen.sh содержащие локальные настройки конфигурации, которые мне нужны:

. локаленв
./autogen.sh \
--with-default-backend = libvirt \
--enable-gcc-предупреждения \
--enable-gtk-doc \
-С \
"$ @"

Итак, я могу использовать это для создания libguestfs:

./localconfigure && make

Если в верхнем каталоге сборки есть файл с именем локаленв, то он будет получен
"делать". Этот файл может содержать любые необходимые локальные переменные среды, например. для пропуска
Тесты:

# Используйте альтернативный двоичный файл Python.
экспорт PYTHON = python3
# Пропустите этот тест, он сломан.
экспорт SKIP_TEST_BTRFS_FSCK = 1

Обратите внимание, что локаленв включен в верхний Makefile (так что это фрагмент Makefile). Но если
это также получено вашим локальная конфигурация script, то он используется как сценарий оболочки.

ДОБАВЛЕНИЕ A НОВЫЕ API ДЕЙСТВИЯ
Поскольку создается большое количество шаблонного кода в libguestfs, это упрощает
для расширения API libguestfs.

Чтобы добавить новое действие API, необходимо внести два изменения:

1. Вам необходимо добавить описание звонка (название, параметры, тип возврата, тесты,
документация) генератор / actions.ml.

Существует два типа действий API, в зависимости от того, проходит ли вызов к
демон в устройстве или полностью обслуживается библиотекой (см. «АРХИТЕКТУРА» в
guestfs-внутренние(3)). "guestfs_sync" в гость(3) является примером первого,
поскольку синхронизация выполняется в устройстве. "guestfs_set_trace" в гость(3) является
пример последнего, поскольку флаг трассировки поддерживается в дескрипторе, и все трассировки
делается на стороне библиотеки.

Большинство новых действий относятся к первому типу и добавляются в список «daemon_functions».
Каждая функция имеет уникальный номер процедуры, используемый в протоколе RPC, который назначается
на это действие, когда мы публикуем libguestfs, и его нельзя использовать повторно. Возьмите последний
номер процедуры и увеличить его.

Для библиотечных действий второго типа добавьте в список «non_daemon_functions».
Поскольку эти функции обслуживаются библиотекой и не передаются через RPC
механизму демона, эти функции не нуждаются в номере процедуры, поэтому
номер процедуры установлен на «-1».

2. Реализуйте действие (в C):

Для действий демона реализуйте функцию do_ "в каталоге" daemon / ".

Для библиотечных действий реализуйте функцию "guestfs_impl_ "в" src / "
каталог.

В любом случае используйте другую функцию как пример того, что делать.

После внесения этих изменений используйте "make" для компиляции.

Обратите внимание, что вам не нужно реализовывать RPC, языковые привязки, справочные страницы или что-то еще.
еще. Все это автоматически генерируется из описания OCaml.

ДОБАВЛЕНИЕ ИСПЫТАНИЯ Для AN API ДЕЙСТВИЯ
Вы можете предоставить ноль или столько тестов, сколько хотите для каждого вызова API. Тесты могут быть
добавлен как часть описания API (генератор / actions.ml), или в некоторых более редких случаях вы
может захотеть перетащить скрипт в "tests / * /". Обратите внимание, что добавление скрипта в "tests / * /" является
медленнее, поэтому по возможности используйте первый метод.

Ниже описывается тестовая среда, используемая при добавлении теста API в действия.мл.

В тестовой среде есть 4 блочных устройства:

/ Dev / ПДД 500MB
Генеральное блочное устройство для тестирования.

/ DEV / SDB 500MB
/ DEV / sdb1 файловая система ext2, используемая для тестирования операций записи файловой системы.

/ DEV / SDC 10MB
Используется в нескольких тестах, где необходимы два блочных устройства.

/ DEV / SDD
ISO с фиксированным содержанием (см. images / test.iso).

Чтобы иметь возможность запускать тесты в разумные сроки, устройство libguestfs и
блочные устройства повторно используются между тестами. Так что не пытайтесь тестировать "guestfs_kill_subprocess" в
гость(3): -x

Каждый тест начинается с начального сценария, выбранного с помощью одного из выражений "Init *",
описанный в генератор / types.ml. Они инициализируют диски, упомянутые выше, в
конкретным способом, как описано в типы.мл. Вы не должны ничего предполагать о
предыдущее содержимое других дисков, которые не инициализированы.

Вы можете добавить предварительное условие к любому отдельному тесту. Это проверка во время выполнения,
который в случае неудачи приводит к пропуску теста. Полезно при тестировании команды, которая
может не работать во всех вариантах сборок libguestfs. Тест, требующий выполнения
«Всегда» означает безоговорочно бежать.

Кроме того, упаковщики могут пропускать отдельные тесты, задавая переменные среды перед
работает "сделать проверку".

SKIP_TEST_ _ = 1

например: "SKIP_TEST_COMMAND_3 = 1" пропускает тест № 3 "guestfs_command" в гость(3).

или:

SKIP_TEST_ = 1

например: "SKIP_TEST_ZEROFREE = 1" пропускает все "guestfs_zerofree" в гость(3) тесты.

Упаковщики могут запускать только определенные тесты, например, установив:

TEST_ONLY = "vfs_type zerofree"

Посмотреть тесты / c-api / tests.c для получения дополнительных сведений о том, как работают эти переменные среды.

ОТЛАДКА НОВЫЕ API Действия
Перед отправкой проверьте работу новых действий.

Вы можете использовать guestfish, чтобы опробовать новые команды.

Отладка демона представляет собой проблему, потому что он работает в минимальной среде. тем не мение
вы можете отправлять сообщения fprintf в демоне на stderr, и они будут отображаться, если вы используете
"guestfish -v".

ДОБАВЛЕНИЕ A НОВЫЕ АНГЛИЙСКИЙ ЯЗЫК ОБЯЗАТЕЛЬНОЕ
Все языковые привязки должны генерироваться генератором (см. генератор подкаталог).

Для этого пока нет документации. Предлагаем вам взглянуть на существующую привязку, например.
генератор / ocaml.ml or генератор / perl.ml.

ДОБАВЛЕНИЕ ИСПЫТАНИЯ Для АНГЛИЙСКИЙ ЯЗЫК ПРИЛОЖЕНИЯ
Привязки к языку должны сопровождаться тестами. Ранее тестирование языковых привязок было
скорее ad-hoc, но мы пытались формализовать набор тестов, которые каждый язык
привязку следует использовать.

В настоящее время только привязки 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.
(добавить-крючок 'find-file-hook
'(лямбда () (если (и имя-файла-буфера
(совпадение строки "/ libguestfs \\>"
(имя-файла-буфера))
(not (строковое имя режима "Журнал изменений"))
(not (строковое имя режима "Makefile")))
(setq отступ-вкладки-режим ноль))))

;;; При редактировании исходных текстов C в libguestfs используйте этот стиль.
(defun libguestfs-c-mode()
«Режим C с измененными значениями по умолчанию для использования с libguestfs».
(интерактивный)
(в стиле c-set "K&R")
(setq c-отступ-уровень 2)
(setq c-базовое смещение 2))
(add-hook 'c-mode-hook
'(лямбда () (если (совпадение строки "/ libguestfs \\>"
(имя-файла-буфера))
(libguestfs-c-режим))))

ТЕСТИРОВАНИЕ ВАШ ШАНГИ
Включите предупреждения при компиляции (и исправьте все обнаруженные проблемы):

./configure --enable-gcc-предупреждения

Полезные цели:

"сделать чек"
Запускает обычный набор тестов.

Это реализовано с помощью штатной мишени «ТЕСТЫ» автомата. Посмотреть автопроизводитель
документация для деталей.

"сделать чек-valgrind"
Выполняет подмножество набора тестов под valgrind.

Любые Makefile.am в дереве, имеющем цель "check-valgrind:", будет запускаться этим
править.

"сделать чек-валгринд-местные-гости"
Запускает часть набора тестов под valgrind с использованием локально установленных гостей libvirt.
(только для чтения).

"сделать чек-прямой"
Выполняет все тесты с использованием серверной части устройства по умолчанию. Это имеет какой-либо эффект только в том случае, если не
бэкэнд по умолчанию был выбран с помощью "./configure --with-default-backend = ..."

"сделать чек-valgrind-direct"
Запустите подмножество набора тестов под valgrind, используя серверную часть устройства по умолчанию.

"сделать чек-умл"
Выполняет все тесты с использованием серверной части Linux в пользовательском режиме.

Поскольку стандартное расположение ядра Linux в пользовательском режиме отсутствует, вы встали на сторону установить
«LIBGUESTFS_HV» указывает на образ ядра, например:

сделать check-uml LIBGUESTFS_HV =~ / д / Linux-ум / vmlinux

"сделать чек-valgrind-uml"
Выполняет все тесты с использованием серверной части Linux в пользовательском режиме под valgrind.

Как и выше, вы должны установить «LIBGUESTFS_HV» так, чтобы он указывал на ядро.

"сделать проверку с-upstream-qemu"
Запускает все тесты с использованием локального двоичного файла qemu. Ищет двоичный файл qemu в QEMUDIR
(по умолчанию $ HOME / d / qemu), но вы можете установить это в другой каталог с помощью команды
строка, например:

сделать check-with-upstream-qemu QEMUDIR = / usr / src / qemu

"сделать проверку-с-апстрим-libvirt"
Запускает все тесты с использованием локальной библиотеки libvirt. Это имеет какой-либо эффект, только если серверная часть libvirt
был выбран с помощью "./configure --with-default-backend = libvirt"

Он ищет libvirt в LIBVIRTDIR (по умолчанию $ HOME / d / libvirt), но вы можете установить это
в другой каталог в командной строке, например:

сделать check-with-upstream-libvirt LIBVIRTDIR = / usr / src / libvirt

"сделать чек-медленный"
Выполняет некоторые медленные / длительные тесты, которые не запускаются по умолчанию.

Любые Makefile.am в дереве, имеющем цель «check-slow:», будет выполняться по этому правилу.

"проверить все"
Эквивалентно выполнению всех правил "make check *".

"сделать чек-релиз"
Выполняет подмножество правил "make check *", которые необходимо пройти перед тем, как tarball может быть
выпущенный. В настоящее время это:

· проверить

· Чек-valgrind

· Чек-прямой

· Чек-valgrind-direct

· Чек-медленный

"сделать installcheck"
Запустите "make check" на установленной копии libguestfs.

Версия установленной тестируемой библиотеки libguestfs и версия библиотеки libguestfs.
исходное дерево должно быть таким же.

Делать:

./autogen.sh
очистить ||:
сделать
сделать installcheck

ДЕЙМОН CUSTOM ПЕЧАТЬ ФОРМАТТЕРЫ
В коде демона мы создали собственные средства форматирования printf% Q и% R, которые используются для
цитировать оболочку.

% Q Простая строка, заключенная в кавычки. Любые пробелы или другие символы оболочки будут экранированы.

% R То же, что и% Q, за исключением того, что строка рассматривается как путь с префиксом sysroot.

Например:

asprintf (& cmd, "cat% R", путь);

создаст "cat / sysroot / some \ path \ with \ space"

Примечание: Do используйте их при передаче параметров в "command {, r, v, rv} ()"
функции. Эти параметры НЕ нужно указывать, потому что они не передаются через
shell (вместо этого прямо в exec). Вероятно, вы захотите использовать функцию "sysroot_path ()"
Однако.

ПОДАЧА ВАШ НОВЫЕ API Действия
Отправляйте патчи в список рассылки: http://www.redhat.com/mailman/listinfo/libguestfs и
CC в [электронная почта защищена].

ИНТЕРНАЦИОНАЛИЗАЦИЯ (И18Н) ПОДДЕРЖКA
Мы поддерживаем i18n (все равно gettext) в библиотеке.

Однако от демона приходит много сообщений, и мы их в настоящий момент не переводим.
Одна из причин заключается в том, что из устройства обычно удаляются все файлы локали, поскольку
они занимают много места. Поэтому нам пришлось бы прочитать некоторые из них, а также скопировать наши
PO файлы в устройство.

Сообщения отладки никогда не переводятся, поскольку они предназначены для программистов.

ИСТОЧНИК КОД ПОДКАТАЛОГИ
выравнивать
виртуальное выравнивание-сканирование(1) команда и документация.

прибор
Устройство libguestfs, сценарии сборки и так далее.

колотить
Скрипты завершения табуляции в Bash.

сборка-вспомогательная
Различные сценарии сборки, используемые автоинструментами.

строитель
строитель добродетели(1) команда и документация.

кошка The виртуальный кот(1) виртуальные файловые системы(1) виртуальный журнал(1) и вирт-лс(1) команды и
документация.

вно
Внешние материалы, экспериментальные части.

настроить
виртуальная настройка(1) команда и документация.

демон
Демон, который работает внутри устройства libguestfs и выполняет действия.

df вирт-дф(1) команда и документация.

dib вирт-диб(1) команда и документация.

Разница
вирт-дифф(1) команда и документация.

док Разные справочные страницы.

отредактировать
вирт-править(1) команда и документация.

Примеры реализованных проектов
Пример кода C API.

рыба
рыба-гость(1), оболочка командной строки и различные сценарии оболочки, созданные поверх, такие как
виртуальная копия(1) виртуальная копия(1) вирт-тар-ин(1) вирт-тар-аут(1).

формат
виртуальный формат(1) команда и документация.

предохранитель
гостевая гора(1), FUSE (файловая система пользовательского пространства), построенная на основе libguestfs.

генератор
Критически важный генератор, используемый для автоматического создания большого количества
шаблонный код C для таких вещей, как RPC и привязки.

получить ядро
виртуальное ядро(1) команда и документация.

гнулиб
Gnulib используется как переносимая библиотека. Копия gnulib находится здесь.

инспектор
вирт-инспектор(1), инспектор образов виртуальной машины.

логотип
Логотип, используемый на сайте. Кстати, эту рыбу зовут Артур.

m4 Макросы M4, используемые autoconf.

make-fs
вирт-мейк-фс(1) команда и документация.

мллиб
Различные библиотеки и общий код, используемый виртуальное изменение размера(1) и другие инструменты, которые
написано в OCaml.

p2v вирт-p2v(1) команда, документация и скрипты для сборки виртуального ISO-образа или диска.
изображения.

po Переводы простых строк gettext.

po-документы
Инфраструктура сборки и файлы PO для переводов страниц руководства и файлов POD.
В конечном итоге это будет объединено с po каталог, но это скорее
сложный.

спасать
спасение вирт(1) команда и документация.

изменить размер
виртуальное изменение размера(1) команда и документация.

разрежать
вирт-разреженный(1) команда и документация.

SRC Исходный код библиотеки C.

Sysprep
вирт-sysprep(1) команда и документация.

тестов
Тесты.

тестовые данные
Файлы и другие тестовые данные, используемые тестами.

тестовый инструмент
Инструмент тестирования для конечных пользователей, чтобы проверить, будет ли их комбинация qemu / kernel работать с
libguestfs.

TMP Используется для временных файлов при запуске тестов (вместо / Tmp так далее). Причина в том
так что вы можете запускать несколько параллельных тестов libguestfs без единого набора
тесты, перезаписывающие устройство, созданное другим.

инструменты
Инструменты командной строки, написанные на Perl (Вирт-победа-рег(1) и многие другие).

v2v вирт-v2v(1) команда и документация.

.
The http://libguestfs.org файлы веб-сайта.

острый
эрланг
Gobject
golang
Haskell
Ява
луна
OCaml
PHP
Perl
питон
рубин
Привязки к языку.

ИЗГОТОВЛЕНИЕ A СТАБИЛЬНЫЙ РЕЛИЗ
Когда мы делаем стабильную версию, здесь описываются несколько шагов. См. "LIBGUESTFS
НОМЕРА ВЕРСИИ "в гость(3) для получения общей информации о политике стабильного филиала.

· Убедитесь, что "make && make check" работает как минимум в Fedora, Debian и Ubuntu.

· Проверьте работу "./configure --without-libvirt".

· Завершить Guestfs-release-notes.pod

· Толкайте и вытягивайте из Занаты.

Run:

заната толчок

для загрузки последних файлов POT в Zanata. Затем запустите:

./zanata-pull.sh

который является оболочкой для получения последних переведенных * .po файлы.

· Рассмотрите возможность обновления gnulib до последней исходной версии.

· Создавайте новые каталоги стабильной работы и разработки под http://libguestfs.org/download.

· Редактировать сайт / index.html.in.

· Установить версию (в настроить.ac) к новому стабильный версия, т.е. 1.XX.0 и фиксируем
он:

./localconfigure
сделать distclean -k
./localconfigure
сделать && сделать расст
сделать коммит сопровождающего
сделать тег-сопровождающий

· Создайте стабильную ветку в git:

git ветка стабильный-1.XX
git push origin стабильный-1.XX

· Сделайте полный выпуск стабильной ветки.

· Установите следующую версию разработки и зафиксируйте ее. При желании сделать полный
выпуск развивающейся ветки.

Используйте guestfs-hacking онлайн с помощью сервисов onworks.net