guestfs-hacking - онлайн в хмарі

ПРОГРАМА:

ІМ'Я

guestfs-hacking - розширення та внесок у libguestfs

ОПИС

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

ОГЛЯД OF THE ДЖЕРЕЛО КОД
Джерело Libguestfs знаходиться в репозиторії github
https://github.com/libguestfs/libguestfs

Велика кількість шаблонного коду в libguestfs (RPC, прив’язки, документація)
згенеровано. Це означає, що багато вихідних файлів будуть відсутні в a
проста перевірка git. Вам потрібно запустити генератор (./autogen.sh && make -C
генератор"), щоб створити ці файли.

Libguestfs використовує систему збірки на основі автоінструментів, з основними файлами configure.ac
та Makefile.am, generator підкаталог містить генератор, а також файли з описом
API. The SRC підкаталог містить джерело для бібліотеки. The прилад та демон
підкаталоги містять джерело коду, який створює пристрій, і код
який працює в приладі відповідно. Інші каталоги описані в цьому розділі
"ПІДКАТАЛОГИ ВИХОДНИХ КОДІВ" нижче.

Крім того, що всі точки входу API проходять через деякий згенерований код, бібліотека є
прямолінійний. (Насправді, навіть згенерований код призначений для читання і повинен
читати як звичайний код). Деякі дії повністю виконуються в бібліотеці і записуються як C
функції у файлах під SRC. Інші пересилаються до демона, де (після деяких
згенерований маршалінг RPC) вони відображаються як функції C у файлах під демон.

Щоб створити з джерела, спочатку прочитайте файл "README".

місцевий* ФАЙЛИ
Файли у верхньому вихідному каталозі, які починаються з префікса місцевий* ігноруються git.
Ці файли можуть містити локальну конфігурацію або сценарії, які потрібні для створення libguestfs.

За умовою, у мене є файл під назвою локальна конфігурація яка є простою обгорткою
autogen.sh містить необхідні мені налаштування локальної конфігурації:

. localenv
./autogen.sh \
--with-default-backend=libvirt \
--enable-gcc-warnings \
--enable-gtk-doc \
-C \
"$@"

Тому я можу використовувати це для створення libguestfs:

./localconfigure && make

Якщо у верхньому каталозі збірки є файл з викликом localenv, то він буде отриманий з
«зробити». Цей файл може містити будь-які необхідні змінні локального середовища, напр. для пропуску
тести:

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

Зверніть увагу, що localenv включено верхнім Makefile (тому це фрагмент Makefile). Але якщо
він також отриманий вашим локальна конфігурація script, то він використовується як сценарій оболонки.

ДОДАВАННЯ A Нове API ДІЇ
Оскільки в libguestfs генерується велика кількість шаблонного коду, це полегшує роботу
щоб розширити API libguestfs.

Щоб додати нову дію API, є дві зміни:

1. Необхідно додати опис виклику (ім'я, параметри, тип повернення, тести,
документація) до генератор/дій.мл.

Існує два види дій API, залежно від того, чи проходить виклик до
daemon в приладі або повністю обслуговується бібліотекою (див. «АРХІТЕКТУРА» в
guestfs-internals(3)). "guestfs_sync" в guestfs(3) є прикладом першого,
оскільки синхронізація виконується в пристрої. "guestfs_set_trace" в guestfs(3) є
приклад останнього, оскільки прапор трасування підтримується в дескрипторах і всьому трасуванні
виконується на стороні бібліотеки.

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

Для дій другого типу лише для бібліотеки додайте до списку "non_daemon_functions".
Оскільки ці функції обслуговуються бібліотекою і не переміщуються по RPC
механізму демона, ці функції не потребують номера процедури, і тому
номер процедури встановлено на "-1".

2. Виконайте дію (в C):

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

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

У будь-якому випадку використовуйте іншу функцію як приклад того, що потрібно зробити.

Після внесення цих змін використовуйте «make» для компіляції.

Зауважте, що вам не потрібно впроваджувати RPC, мовні прив’язки, сторінки посібника чи щось інше
інше. Все це автоматично генерується з опису OCaml.

ДОДАВАННЯ ВИПРОБУВАННЯ ДЛЯ AN API ДІЇ
Ви можете надати нуль або скільки завгодно тестів для кожного виклику API. Тести можуть бути як
додано як частину опису API (генератор/дій.мл), або в деяких рідкісних випадках ви
можливо, захочеться перекинути скрипт до "tests/*/". Зауважте, що додавання сценарію до "tests/*/" є
повільніше, тому по можливості використовуйте перший спосіб.

Нижче описано тестове середовище, яке використовується, коли ви додаєте тест API дії.мл.

Тестове середовище має 4 блокові пристрої:

/ dev / sda 500MB
Загальний блок-пристрій для тестування.

/ dev / sdb 500MB
/ dev / sdb1 є файловою системою ext2, яка використовується для тестування операцій запису файлової системи.

/ dev / sdc 10MB
Використовується в кількох тестах, де потрібні два блокові пристрої.

/ dev / sdd
ISO із фіксованим вмістом (див зображення/test.iso).

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

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

До будь-якого окремого тесту можна додати положення про передумову. Це перевірка часу виконання,
що, якщо це не вдається, спричиняє пропуск тесту. Корисно під час тестування команди, яка
може не працювати на всіх варіантах збірок libguestfs. Тест, який має передумову
«Завжди» означає бігати беззастережно.

Крім того, розробники пакетів можуть пропускати окремі тести, попередньо встановивши змінні середовища
запуск «зробити перевірку».

SKIP_TEST_ _ =1

наприклад: "SKIP_TEST_COMMAND_3=1" пропускає тест №3 "guestfs_command" у guestfs(3).

або:

SKIP_TEST_ =1

наприклад: "SKIP_TEST_ZEROFREE=1" пропускає всі "guestfs_zerofree" у guestfs(3) тести.

Пакувачі можуть виконувати лише певні тести, встановивши, наприклад:

TEST_ONLY="vfs_type zerofree"

Читати tests/c-api/tests.c щоб дізнатися більше про те, як працюють ці змінні середовища.

ВІДМОВЛЕННЯ Нове API ДІЇ
Перевірте роботу нових дій перед їх поданням.

Ви можете використовувати guestfish, щоб випробувати нові команди.

Налагодження демона є проблемою, оскільки він працює в мінімальному середовищі. Однак
ви можете fprintf повідомлення в демон до stderr, і вони відображатимуться, якщо ви використовуєте
«риба гостя -в».

ДОДАВАННЯ A Нове МОВА ОБ'ЄДНАННЯ
Усі мовні прив’язки повинні бути згенеровані генератором (див generator підкаталог).

Документації на це поки немає. Ми пропонуємо вам ознайомитися з наявним прив’язкою, напр.
генератор/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 зазвичай дотримується деяких основних умов форматування коду. The
існуюча база коду не повністю узгоджена в цьому плані, але ми віддаємо перевагу цьому
внесений код бути відформатований аналогічним чином. Коротше кажучи, використовуйте пробіли, а не TAB для відступів,
використовуйте 2 пробіли для кожного рівня відступу, а крім цього, дотримуйтесь стилю K&R.

Якщо ви використовуєте Emacs, додайте наступне до одного зі своїх файлів запуску (наприклад, ~/.emacs),
щоб забезпечити правильний відступ:

;;; У libguestfs скрізь відступ із пробілами (не TAB).
;;; Винятки: режими Makefile і ChangeLog.
(add-hook 'find-file-hook
'(lambda () (якщо (і ім'я-файлу буфера
(відповідність рядка "/libguestfs\\>"
(ім'я файлу буфера))
(не (назва режиму рівного рядку "Журнал змін"))
(не (назва режиму рівного рядку "Makefile")))
(setq indent-tabs-mode нуль))))

;;; Під час редагування джерел C у libguestfs використовуйте цей стиль.
(defun libguestfs-c-mode ()
"Режим C зі зміненими параметрами за замовчуванням для використання з libguestfs."
(інтерактивний)
(C-set у стилі "K&R")
(setq c-indent-level 2)
(setq c-basic-offset 2))
(add-hook 'c-mode-hook
'(лямбда () (якщо (відповідність рядка "/libguestfs\\>"
(ім'я файлу буфера))
(libguestfs-c-mode))))

ВИПРОБУВАННЯ ПЕЖО ЗМІНИ
Увімкніть попередження під час компіляції (і виправте будь-які проблеми, які це знайде):

./configure --enable-gcc-warnings

Корисними цілями є:

"зробити перевірку"
Запускає звичайний набір тестів.

Це реалізовано за допомогою звичайної цілі автоматичного виготовлення "TESTS". Дивіться автовиробник
документація для деталей.

"зробити check-valgrind"
Запускає підмножину набору тестів під valgrind.

будь-який Makefile.am у дереві, яке має мету "check-valgrind:", буде запускатися цим
правити

"make check-valgrind-local-guests"
Запускає підмножину тестового набору під valgrind за допомогою локально встановлених гостей libvirt
(лише для читання).

"зробити перевірку-прямий"
Виконує всі тести з використанням серверної частини пристрою за замовчуванням. Це має будь-який ефект, лише якщо не-
бекенд за замовчуванням вибрано за допомогою "./configure --with-default-backend=..."

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

"зробити check-uml"
Виконує всі тести за допомогою серверної частини Linux режиму користувача.

Оскільки для ядра Linux у режимі користувача немає стандартного розташування, ви мати встановити
"LIBGUESTFS_HV", щоб вказувати на образ ядра, наприклад:

зробити check-uml LIBGUESTFS_HV=~/d/linux-um/vmlinux

"зробити check-valgrind-uml"
Виконує всі тести за допомогою серверної частини Linux режиму користувача під valgrind.

Як і вище, ви повинні встановити "LIBGUESTFS_HV", щоб вказувати на ядро.

"здійснити перевірку за допомогою-upstream-qemu"
Виконує всі тести, використовуючи локальний двійковий файл qemu. Він шукає двійковий файл qemu в QEMUDIR
(за замовчуванням $HOME/d/qemu), але ви можете встановити це в інший каталог за допомогою команди
рядок, наприклад:

зробити перевірку за допомогою-upstream-qemu QEMUDIR=/usr/src/qemu

"здійснити перевірку за допомогою-upstream-libvirt"
Виконує всі тести за допомогою локального libvirt. Це має будь-який ефект, лише якщо сервер libvirt
було обрано за допомогою "./configure --with-default-backend=libvirt"

Він шукає libvirt у LIBVIRTDIR (за замовчуванням $HOME/d/libvirt), але ви можете встановити це
в інший каталог у командному рядку, наприклад:

здійснити перевірку за допомогою-upstream-libvirt LIBVIRTDIR=/usr/src/libvirt

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

будь-який Makefile.am у дереві, яке має цільову функцію "check-slow:", буде виконуватися за цим правилом.

"зробити перевірку всіх"
Еквівалентно запуску всіх правил "зробити перевірку*".

"зробити чек-звільнення"
Виконує підмножину правил "зробити перевірку*", які необхідно пройти, перш ніж можна буде створити tar-архів
звільнений. Наразі це:

· перевірити

· чек-валграйнд

· перевірка-пряма

· check-valgrind-direct

· перевірка-повільна

"зробити перевірку встановлення"
Запустіть "make check" на встановленій копії libguestfs.

Версія встановленого libguestfs, що перевіряється, і версія libguestfs
вихідне дерево має бути однаковим.

У:

./autogen.sh
очистити ||:
зробити
зробити перевірку встановлення

ДЕМОН ПОСЛУГИ PRINTF ФОРМАТРИ
У коді демона ми створили спеціальні форматери printf %Q і %R, до яких звикли
робити цитування оболонки.

%Q Простий рядок оболонки в лапках. Будь-які пробіли або інші символи оболонки екрануються.

%R Те ж саме, що й %Q, за винятком того, що рядок розглядається як шлях, який має префікс sysroot.

Наприклад:

asprintf (&cmd, "кот %R", шлях);

створить "cat /sysroot/some\ path\ with\ пробіли"

Примітка: Do НЕ використовуйте їх, коли ви передаєте параметри в "command{,r,v,rv}()"
функції. Ці параметри НЕ потрібно вводити в лапки, оскільки вони не передаються через
оболонка (замість цього прямо до exec). Можливо, ви захочете використовувати функцію "sysroot_path()".
однак.

ПОДАННЯ ПЕЖО Нове API ДІЇ
Надсилайте патчі до списку розсилки: http://www.redhat.com/mailman/listinfo/libguestfs та
CC до [захищено електронною поштою].

ІНТЕРНАЦІОНАЛІЗАЦІЯ (I18N) ПІДТРИМКА
Ми підтримуємо i18n (в будь-якому випадку gettext) у бібліотеці.

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

Повідомлення про налагодження ніколи не перекладаються, оскільки вони призначені для програмістів.

ДЖЕРЕЛО КОД ПІДДИРЕКТОРІЇ
вирівнювати
virt-alignment-scan(1) команда та документація.

прилад
Пристрій libguestfs, сценарії збірки тощо.

бити
Скрипти завершення вкладок Bash.

буд.-доп
Різні сценарії збірки, які використовуються автоінструментами.

будівельник
virt-builder(1) команда та документація.

як Команда вірт-кіт(1) virt-файлові системи(1) virt-log(1) і virt-ls(1) команди та
документація.

внесок
Зовнішні внески, експериментальні частини.

налаштувати
virt-налаштувати(1) команда та документація.

демон
Демон, який працює всередині пристрою libguestfs і виконує дії.

df virt-df(1) команда та документація.

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

різниця
virt-diff(1) команда та документація.

doc Різні сторінки посібника.

редагувати
virt-edit(1) команда та документація.

Приклади
Приклад коду C API.

риба
риба-гость(1), оболонку командного рядка та різні сценарії оболонки, створені поверх, наприклад
virt-copy-in(1) virt-copy-out(1) вірт-тар-ін(1) virt-tar-out(1).

формат
virt-формат(1) команда та документація.

запобіжник
guestmount(1), FUSE (файлова система простору користувача), побудована на основі libguestfs.

generator
Вирішально важливий генератор, який використовується для автоматичного генерування великої кількості
шаблонний код C для таких речей, як RPC та прив'язки.

get-ядро
virt-get-kernel(1) команда та документація.

гнуліб
Gnulib використовується як бібліотека переносимості. Копія gnulib включена тут.

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

логотип
Логотип, використаний на сайті. Рибу, до речі, звуть Артур.

m4 Макроси M4, які використовуються autoconf.

make-fs
virt-make-fs(1) команда та документація.

mllib
Різні бібліотеки та звичайний код, який використовується virt-зміна розміру(1) та інші інструменти, які є
написаний на OCaml.

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

po Переклад простих рядків gettext.

по-документи
Інфраструктура побудови та файли PO для перекладів сторінок керівництва та файлів POD.
Згодом це буде поєднуватися з po каталог, але це швидше
складний.

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

змінити розмір
virt-зміна розміру(1) команда та документація.

розріджувати
virt-sparsify(1) команда та документація.

SRC Вихідний код бібліотеки C.

Sysprep
virt-sysprep(1) команда та документація.

Тести
Тести.

тест-дані
Файли та інші дані тесту, які використовуються в тестах.

тест-інструмент
Інструмент тестування для кінцевих користувачів, щоб перевірити, чи працюватиме їх комбінація qemu/ядро
libguestfs.

tmp Використовується для тимчасових файлів під час виконання тестів (замість / Tmp тощо). Причина в тому
так що ви можете запускати кілька паралельних тестів libguestf, не маючи одного набору
тести, які перезаписують пристрій, створений іншим.

інструменти
Інструменти командного рядка, написані на Perl (virt-win-reg(1) та багато інших).

v2v virt-v2v(1) команда та документація.

сайт
Команда http://libguestfs.org файли веб-сайту.

csharp
ерланг
гооб'єкт
голанг
haskell
Ява
місяць
ocaml
PHP
Perl
пітон
рубін
Мовні прив’язки.

РОБОТА A СТАБІЛЬНА РЕЛІЗ
Коли ми створюємо стабільний випуск, тут задокументовано кілька кроків. Дивіться «LIBGUESTFS
НОМЕР ВЕРСІЙ" в guestfs(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.

· Редагувати website/index.html.in.

· Встановіть версію (в configure.ac) до нового стабільний версія, тобто. 1.XX.0 і зафіксуйте
він:

./localconfigure
зробити distclean -k
./localconfigure
зробити && зробити dist
зробити супроводжувач-фіксувати
зробити тег супроводжувача

· Створіть стабільну гілку в git:

git гілка stable-1.XX
git push origin stable-1.XX

· Виконайте повний випуск стабільної гілки.

· Установіть наступну версію для розробки та зафіксуйте її. За бажанням зробіть повну
випуск гілки розробки.

Використовуйте guestfs-hacking онлайн за допомогою служб onworks.net