guestfs-hacking - מקוון בענן

תָכְנִית:

שֵׁם

guestfs-hacking - הרחבה ותרומה ל-libguestfs

תיאור

דף מדריך זה מיועד להאקרים שרוצים להרחיב את libguestfs עצמו.

סקירה כללית OF LA מקור CODE
המקור של Libguestfs ממוקם במאגר github
https://github.com/libguestfs/libguestfs

כמויות גדולות של קוד ה-boilerplate ב-libguestfs (RPC, כריכות, תיעוד)
נוצר. משמעות הדבר היא שקובצי מקור רבים ייראו כחסרים ב-a
צ'ק גיט פשוט. עליך להפעיל את המחולל ("./autogen.sh && make -C
מחולל") כדי ליצור קבצים אלה.

Libguestfs משתמש במערכת בנייה מבוססת כלי אוטומטי, כאשר הקבצים העיקריים הם configure.ac
ו Makefile.am. ה גנרטור ספריית המשנה מכילה את המחולל, בתוספת קבצים המתארים
ה-API. ה src ספריית המשנה מכילה מקור לספרייה. ה מכשיר ו דמון
ספריות משנה מכילות את המקור לקוד שבונה את ה-Appliance ואת הקוד
שפועל במכשיר בהתאמה. ספריות אחרות מכוסות בסעיף
"ספריות משנה של קוד המקור" למטה.

מלבד העובדה שכל נקודות הכניסה ל-API עוברות דרך איזה קוד שנוצר, הספרייה היא
פָּשׁוּט. (למעשה, אפילו הקוד שנוצר נועד להיות קריא, וצריך
להיקרא כקוד רגיל). חלק מהפעולות פועלות במלואן בספרייה, ונכתבות כ-C
פונקציות בקבצים מתחת src. אחרים מועברים לדמון שבו (אחרי כמה
יצירת RPC marshalling) הם מופיעים כפונקציות 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=python3
# דלג על המבחן הזה, הוא מקולקל.
ייצא SKIP_TEST_BTRFS_FSCK=1

שים לב כי localenv נכלל ב-Makefile העליון (אז זה קטע Makefile). אבל אם
זה גם מקורו על ידי שלך תצורה מקומית סקריפט אז הוא משמש כסקריפט מעטפת.

מוֹסִיף A NEW API פעולה
מכיוון שנוצרות כמויות גדולות של קוד boilerplate ב-libguestfs, זה מקל על זה
כדי להרחיב את ה-API של libguestfs.

כדי להוסיף פעולת API חדשה יש שני שינויים:

1. עליך להוסיף תיאור של השיחה (שם, פרמטרים, סוג החזרה, בדיקות,
תיעוד) ל generator/actions.ml.

ישנם שני סוגים של פעולות API, תלוי אם השיחה עוברת אל
דמון במכשיר, או מטופל כולו על ידי הספרייה (ראה "אדריכלות" ב
guestfs-פנימיים(3)). "guestfs_sync" ב guestfs(3) הוא דוגמה לראשון,
מכיוון שהסנכרון נעשה במכשיר. "guestfs_set_trace" ב guestfs(3) הוא an
דוגמה של האחרון, שכן דגל מעקב נשמר בידית וכל המעקב
נעשה בצד הספרייה.

רוב הפעולות החדשות הן מהסוג הראשון, ומתווספות לרשימת "פונקציות_דימון".
לכל פונקציה יש מספר פרוצדורה ייחודי המשמש בפרוטוקול RPC המוקצה
לפעולה זו כאשר אנו מפרסמים libguestfs ולא ניתן לעשות בהם שימוש חוזר. קח את האחרון
מספר ההליך והגדל אותו.

עבור פעולות לספרייה בלבד מהסוג השני, הוסף לרשימת "פונקציות_לא_דימון".
מכיוון שפונקציות אלו מטופלות על ידי הספרייה ואינן עוברות דרך ה-RPC
מנגנון לדמון, פונקציות אלו אינן זקוקות למספר פרוצדורה, וכך
מספר ההליך מוגדר ל-"-1".

2. בצע את הפעולה (ב-C):

עבור פעולות דמון, יישם את הפונקציה "do_ " בספריית "דימון/".

עבור פעולות ספרייה, יישם את הפונקציה "guestfs_impl_ " ב-"src/"
במדריך.

בכל מקרה, השתמש בפונקציה אחרת כדוגמה למה לעשות.

לאחר ביצוע שינויים אלה, השתמש ב-"make" כדי להדר.

שים לב שאינך צריך ליישם את ה-RPC, כריכות שפה, דפים ידניים או משהו
אַחֵר. הכל נוצר אוטומטית מתיאור ה-OCaml.

מוֹסִיף בדיקות עבור AN API פעולה
אתה יכול לספק אפס או כמה בדיקות שתרצה לכל קריאת API. הבדיקות יכולות להיות
נוסף כחלק מתיאור ה-API (generator/actions.ml), או במקרים נדירים יותר אתה
אולי תרצה לשחרר סקריפט לתוך "tests/*/". שים לב שהוספת סקריפט ל-"tests/*/" היא
לאט יותר, אז אם אפשר השתמש בשיטה הראשונה.

להלן מתאר את סביבת הבדיקה שבה נעשה שימוש בעת הוספת בדיקת API actions.ml.

בסביבת הבדיקה יש 4 התקני בלוק:

/ dev / sda 500MB
מכשיר חסימה כללי לבדיקה.

/ dev / sdb 500MB
/ dev / sdb1 היא מערכת קבצים ext2 המשמשת לבדיקת פעולות כתיבה של מערכת קבצים.

/ dev / sdc 10MB
משמש בכמה בדיקות שבהן יש צורך בשני התקני בלוק.

/ dev / sdd
ISO עם תוכן קבוע (ראה images/test.iso).

כדי להיות מסוגל להריץ את הבדיקות בפרק זמן סביר, התקן libguestfs ו
נעשה שימוש חוזר במכשירי חסימה בין בדיקות. אז אל תנסה לבדוק את "guestfs_kill_subprocess" ב
guestfs(3) :-x

כל בדיקה מתחילה בתרחיש ראשוני, שנבחר באמצעות אחד מביטויי "Init*",
מתואר ב generator/types.ml. אלה מאתחלים את הדיסקים שהוזכרו לעיל ב
דרך מסוימת כפי שתועד ב types.ml. אתה לא צריך להניח שום דבר לגבי
תכנים קודמים של דיסקים אחרים שאינם מאותחלים.

אתה יכול להוסיף סעיף קדם לכל מבחן בודד. זה בדיקת זמן ריצה,
שאם הוא נכשל, גורם לדילוג על המבחן. שימושי אם בודקים פקודה אשר
ייתכן שלא יעבוד על כל הווריאציות של libguestfs builds. מבחן שיש לו תנאי מוקדם של
"תמיד" פירושו לרוץ ללא תנאי.

בנוסף, מארזים יכולים לדלג על בדיקות בודדות על ידי הגדרת משתני סביבה לפני כן
הפעלת "עשה בדיקה".

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 לפרטים נוספים על אופן הפעולה של משתני סביבה אלה.

פיתרון NEW API פעולות
בדוק שפעולות חדשות פועלות לפני שליחתן.

אתה יכול להשתמש ב- guestfish כדי לנסות פקודות חדשות.

איתור באגים של הדמון הוא בעיה מכיוון שהוא פועל בתוך סביבה מינימלית. למרות זאת
אתה יכול fprintf הודעות בדמון ל-stderr, והן יופיעו אם תשתמש
"אורח דג -v".

מוֹסִיף A NEW שָׂפָה כריכה
כל כריכות השפה חייבות להיות מופקות על ידי המחולל (ראה את גנרטור ספריית משנה).

אין עדיין תיעוד לכך. אנו מציעים לך להסתכל על כריכה קיימת, למשל.
generator/ocaml.ml or generator/perl.ml.

מוֹסִיף בדיקות עבור שָׂפָה כריכות
כריכת שפה צריכה לבוא עם מבחנים. בעבר בדיקה של כריכות שפה הייתה
אלא אד-הוק, אבל ניסינו להכשיר את מערך המבחנים שבכל שפה
כריכה צריך להשתמש.

נכון לעכשיו רק הכריכות Ocaml ו-Perl מיישמות למעשה את מערך הבדיקות המלא, ו
הכריכות של OCaml הן קנוניות, אז אתה צריך לחקות את מה שבדיקות ה-OCaml עושות.

זוהי סכימת המספור המשמשת את הבדיקות:

- 000+ מבחנים בסיסיים:

010 טען את הספרייה
020 ליצור
030 ליצור-דגלים
040 ליצור מספר ידיות
050 הגדרת בדיקה וקבלת מאפייני תצורה
060 סגירה מפורשת
065 סגירה מרומזת (בשפות GC'd)
070 optargs

- 100 הפעל, צור מחיצות ו-LVs ומערכות קבצים

- 400+ אירועים:

אירוע סגור 410
420 הודעות יומן
430 הודעות התקדמות

- 800+ מבחני רגרסיה (ספציפי לשפה)

- 900+ כל מבחנים מותאמים אישית אחרים עבור השפה

כדי לחסוך זמן בעת ​​הפעלת הבדיקות, רק 100, 430, 800+, 900+ צריכים להפעיל את הידית.

עיצוב CODE
קוד המקור C שלנו בדרך כלל תואם לכמה מוסכמות בסיסיות של עיצוב קוד. ה
בסיס הקוד הקיים אינו עקבי לחלוטין בחזית זו, אך אנו מעדיפים זאת
הקוד שתרם יהיה בפורמט דומה. בקיצור, השתמש ברווחים-לא-TAB עבור הזחה,
השתמש ב-2 רווחים עבור כל רמת הזחה, וחוץ מזה, עקוב אחר סגנון K&R.

אם אתה משתמש ב-Emacs, הוסף את הדברים הבאים לאחד מקבצי ההפעלה שלך (למשל, ~/.emacs),
כדי להבטיח שתבצע הזחה נכונה:

;;; ב-libguestfs, הזחה עם רווחים בכל מקום (לא TABs).
;;; חריגים: מצבי Makefile ו-ChangeLog.
(add-hook 'find-file-hook
'(lambda () (אם (ו-buffer-file-name
(string-match "/libguestfs\\>"
(שם קובץ-buffer))
(לא (מחרוזת-שווה מצב-שם "יומן שינויים"))
(לא (שם-מצב מחרוזת שווה "Makefile")))
(setq indent-tabs-mode nil))))

;;; בעת עריכת מקורות C ב-libguestfs, השתמש בסגנון זה.
(defun libguestfs-c-mode ()
"מצב C עם ברירות מחדל מותאמות לשימוש עם libguestfs."
(אינטראקטיבי)
(ק-סט בסגנון "K&R")
(setq c-indent-level 2)
(setq c-basic-offset 2))
(add-hook 'c-mode-hook
'(lambda () (if (string-match "/libguestfs\\>"
(שם קובץ-buffer))
(libguestfs-c-mode))))

בדיקות שֶׁלְךָ שינויים
הפעל אזהרות בעת הידור (ותקן את כל הבעיות שזה מוצא):

./configure --enable-gcc-warnings

יעדים שימושיים הם:

"לעשות בדיקה"
מפעיל את חבילת הבדיקות הרגילה.

זה מיושם באמצעות היעד הרגיל של הייצור האוטומטי "בדיקות". ראה את יצרנית הרכב
תיעוד לפרטים.

"לעשות צ'ק-וואלגרינד"
מפעיל תת-קבוצה של חבילת הבדיקות תחת valgrind.

כל Makefile.am בעץ שיש לו יעד "check-valgrind:" יופעל על ידי זה
כְּלָל.

"עשה צ'ק-valgרind-מקומי-אורחים"
מפעיל קבוצת משנה של חבילת הבדיקה תחת valgrind באמצעות אורחי libvirt המותקנים מקומית
(לקריאה בלבד).

"עשה צ'ק ישיר"
מפעיל את כל הבדיקות באמצעות ברירת המחדל האחורי של התקן. יש לזה השפעה רק אם לא-
הקצה האחורי של ברירת המחדל נבחר באמצעות "./configure --with-default-backend=..."

"עשה צ'ק-valgרind-direct"
הפעל קבוצת משנה של חבילת הבדיקה תחת valgrind באמצעות ברירת המחדל האחורי של המכשיר.

"עשה צ'ק-uml"
מריץ את כל הבדיקות באמצעות ה-User-Mode Linux Backend.

מכיוון שאין מיקום סטנדרטי עבור ליבת לינוקס במצב משתמש, אתה יש כדי להגדיר
"LIBGUESTFS_HV" כדי להצביע על תמונת הליבה, למשל:

בצע check-uml LIBGUESTFS_HV=~/d/linux-um/vmlinux

"עשה צ'ק-valgrind-uml"
מריץ את כל הבדיקות באמצעות ה-User-Mode Linux Backend, תחת valgrind.

כמו לעיל, עליך להגדיר את "LIBGUESTFS_HV" כדי להצביע על הליבה.

"בצע בדיקה עם-קמו במעלה הזרם"
מריץ את כל הבדיקות באמצעות קובץ בינארי qemu מקומי. הוא מחפש את ה-qemu הבינארי ב-QEMUDIR
(ברירת מחדל ל $HOME/d/qemu), אבל אתה יכול להגדיר את זה לספרייה אחרת בפקודה
קו, למשל:

בצע צ'ק עם-upstream-qemu QEMUDIR=/usr/src/qemu

"לעשות בדיקה עם-מעלה הזרם-libvirt"
מריץ את כל הבדיקות באמצעות libvirt מקומי. זה משפיע רק אם הקצה האחורי של libvirt
נבחר באמצעות "./configure --with-default-backend=libvirt"

זה מחפש libvirt ב-LIBVIRTDIR (ברירת המחדל היא $HOME/d/libvirt), אבל אתה יכול להגדיר זאת
לספרייה אחרת בשורת הפקודה, למשל:

בצע בדיקה עם-upstream-libvirt LIBVIRTDIR=/usr/src/libvirt

"לעשות צ'ק-איטי"
מפעיל כמה בדיקות איטיות/ארוכות טווח שאינן מופעלות כברירת מחדל.

כל Makefile.am בעץ שיש לו יעד "check-slow:" יופעל על ידי כלל זה.

"לעשות סימון הכל"
שווה ערך להפעלת כל כללי ה"עשה בדיקה*".

"לעשות צ'ק-שחרור"
מפעיל קבוצת משנה של כללי "ביצוע בדיקה*" שנדרשים לעבור לפני שניתן יהיה לבצע טארבול
מְשׁוּחרָר. כרגע זה:

· חשבון

· צ'ק-וולגרינד

· צ'ק-ישיר

· check-valgrind-direct

· צ'ק-איטי

"בצע בדיקת התקנה"
הפעל את "make check" בעותק המותקן של libguestfs.

הגרסה של libguestfs המותקנת הנבדקת, והגרסה של libguestfs
עץ המקור חייב להיות זהה.

האם:

./autogen.sh
לעשות נקי ||:
לעשות
בצע בדיקת התקנה

דיימון המותאם אישית PRINTF פורמטורים
בקוד הדמון יצרנו פורמטים מותאמים אישית של printf %Q ו-%R, אשר רגילים אליהם
לעשות ציטוט פגז.

%Q מחרוזת מצוטטת קליפה פשוטה. כל הרווחים או דמויות המעטפת האחרות בורחים עבורך.

%R זהה ל-%Q למעט המחרוזת מטופלת כנתיב עם קידומת ה-sysroot.

לדוגמה:

asprintf (&cmd, "cat %R", נתיב);

ייצור "cat /sysroot/some\ path\ with\ spaces"

הערה: Do לֹא השתמש באלה כאשר אתה מעביר פרמטרים ל-"command{,r,v,rv}()"
פונקציות. אין צורך לצטט פרמטרים אלה מכיוון שהם אינם מועברים דרך ה-
מעטפת (במקום זאת, ישר ל-exec). אתה כנראה רוצה להשתמש בפונקציה "sysroot_path()".
למרות זאת.

הַגָשָׁה שֶׁלְךָ NEW API פעולות
שלח טלאים לרשימת התפוצה: http://www.redhat.com/mailman/listinfo/libguestfs ו
CC ל [מוגן בדוא"ל].

בִּנאוּם (I18N) תמיכה
אנו תומכים ב-i18n (gettext בכל מקרה) בספרייה.

עם זאת, הודעות רבות מגיעות מהדמון, ואנחנו לא מתרגמים אותן כרגע.
אחת הסיבות היא שבדרך כלל כל קבצי המקום הוסרו מהמכשיר, כי
הם תופסים הרבה מקום. אז נצטרך לקרוא כמה מהם, כמו גם להעתיק את שלנו
קבצי PO לתוך המכשיר.

הודעות איתור באגים לעולם אינן מתורגמות, מכיוון שהן מיועדות למתכנתים.

מקור CODE ספריות משנה
ליישר
virt-alignment-scan(1) פיקוד ותיעוד.

מכשיר
מכשיר ה-libguestfs, בניית סקריפטים וכן הלאה.

לחבוט
סקריפטים להשלמת כרטיסיות Bash.

build-aux
סקריפטים לבנייה שונים המשמשים את הכלים האוטומטיים.

בונה
בונה וירט(1) פיקוד ותיעוד.

חתול השמיים וירט-חתול(1), virt-filesystems(1), virt-log(1) ו virt-ls(1) פקודות ו
תיעוד.

תורם
תרומות מבחוץ, חלקים ניסיוניים.

אישית
וירט-התאמה אישית(1) פיקוד ותיעוד.

דמון
הדמון שרץ בתוך ה-libguestfs appliance ומבצע פעולות.

df virt-df(1) פיקוד ותיעוד.

טבילה וירט-דיב(1) פיקוד ותיעוד.

הבדל
virt-diff(1) פיקוד ותיעוד.

doc דפי מדריך שונים.

עריכה
virt-edit(1) פיקוד ותיעוד.

דוגמאות
קוד לדוגמה של C API.

דג
דג אורח(1), מעטפת שורת הפקודה, ותסריטי מעטפת שונים הבנויים למעלה כגון
virt-copy-in(1), virt-copy-out(1), וירט-טאר-אין(1), וירט-טאר-אאוט(1).

פוּרמָט
וירט-פורמט(1) פיקוד ותיעוד.

פתיל
mountainmount(1), FUSE (מערכת קבצים של מרחב משתמש) בנוי על גבי libguestfs.

גנרטור
המחולל החשוב ביותר, המשמש לייצור אוטומטי של כמויות גדולות של
קוד boilerplate C עבור דברים כמו RPC ו-bindings.

קבל-קרנל
virt-get-kernel(1) פיקוד ותיעוד.

גנוליב
Gnulib משמש כספריית ניידות. עותק של gnulib כלול כאן.

מפקח
וירט-מפקח(1), מפקח התמונות של המכונה הווירטואלית.

סֵמֶל
לוגו בשימוש באתר. לדג קוראים ארתור אגב.

m4 פקודות מאקרו M4 בשימוש על ידי autoconf.

לעשות-fs
virt-make-fs(1) פיקוד ותיעוד.

mllib
ספריות שונות וקוד נפוץ בשימוש על ידי וירט-שינוי גודל(1) ושאר הכלים שהם
כתוב ב-OCaml.

p2v virt-p2v(1) פקודה, תיעוד ותסריטים לבניית ה- ISO או הדיסק virt-p2v
תמונה.

po תרגומים של מחרוזות gettext פשוטות.

po-docs
תשתית הבנייה וקבצי PO עבור תרגומים של דפי man וקבצי POD.
בסופו של דבר זה ישולב עם po ספרייה, אבל זה יותר נכון
מורכב.

להציל
וירט-הצלה(1) פיקוד ותיעוד.

לשנות את הגודל
וירט-שינוי גודל(1) פיקוד ותיעוד.

לזלזל
וירט-ספייס(1) פיקוד ותיעוד.

src קוד מקור לספריית C.

sysprep
virt-sysprep(1) פיקוד ותיעוד.

בדיקות
בדיקות.

נתוני בדיקה
קבצים ונתוני בדיקה אחרים המשמשים את הבדיקות.

כלי בדיקה
כלי בדיקה למשתמשי קצה כדי לבדוק אם שילוב ה-qemu/kernel שלהם יעבוד איתו
libguestfs.

tmp משמש לקבצים זמניים בעת הפעלת הבדיקות (במקום / Tmp וכו). הסיבה היא
כך שתוכל להריץ מספר בדיקות מקבילות של libguestfs מבלי שיהיה לך קבוצה אחת של
בדיקות המחליפות את המכשיר שנוצר על ידי אחר.

כלים
כלים של שורת הפקודה שנכתבו בפרל (virt-win-reg(1) ועוד רבים אחרים).

V2v virt-v2v(1) פיקוד ותיעוד.

אתר אינטרנט
השמיים http://libguestfs.org קבצי אתר.

צארפ
erlang
גובל
גולאנג
haskell
תאווה
lua
ocaml
php
פרל
פִּיתוֹן
אודם
כריכות שפה.

הֲכָנָה A יציב שחרור
כאשר אנו עושים גרסה יציבה, ישנם מספר שלבים המתועדים כאן. ראה "LIBGUESTFS
מספרי גרסה" ב guestfs(3) למידע כללי על מדיניות הסניף היציב.

· בדוק ש"עשה && בצע בדיקה" עובד על לפחות פדורה, דביאן ואובונטו.

· בדוק "./configure --without-libvirt" עובד.

· סיום guestfs-release-notes.pod

· דחיפה ומשיכה מ-Zanata.

הפעלה:

דחיפה של zanata

לדחוף את קבצי ה-POT העדכניים ביותר ל-Zanata. לאחר מכן הרץ:

./zanata-pull.sh

שהוא עטיפה למשוך את התרגום האחרון *.po קבצים.

· שקול לעדכן את gnulib לגרסה האחרונה במעלה הזרם.

· יצירת ספריות יציבות ופיתוח חדשות תחת http://libguestfs.org/download.

· ערוך website/index.html.in.

· הגדר את הגרסה (ב configure.ac) לחדש יציב גרסה, כלומר. 1.XX.0, ומתחייב
זה:

./localconfigure
לעשות disclean -ק
./localconfigure
לעשות && לעשות dist
לעשות תחזוקה-מתחייב
לעשות תחזוקה-תג

· צור את הענף היציב ב-git:

git branch stable-1.XX
git push origin stable-1.XX

· עשה שחרור מלא של הענף היציב.

· הגדר את הגרסה לגרסת הפיתוח הבאה ועשה זאת. אופציונלי לעשות מלא
שחרור ענף הפיתוח.

השתמש בפריצת guestfs באינטרנט באמצעות שירותי onworks.net