نام (NAME)

guestfs-building - نحوه ساخت libguestfs از کد منبع

توضیحات (DESCRIPTION)

این صفحه راهنما نحوه ساخت libguestfs را از کد منبع شرح می‌دهد.

مراحل اصلی عبارتند از:

• نصب نیازمندی‌ها و وابستگی‌ها.
• ساخت، یا از طریق مخزن گیت و یا از یک فایل فشرده (تاربال).
• اجرای آزمون‌ها.
• اجرای ابزارها از دایرکتوری سورس، یا نصب آن‌ها.

نیازمندی‌ها (REQUIREMENTS)

dnf builddep libguestfs
dnf install autoconf automake libtool gettext-devel

yum-builddep libguestfs
yum install autoconf automake libtool gettext-devel

apt-get build-dep libguestfs
apt-get install autoconf automake libtool-bin gettext

ساخت از گیت (BUILDING FROM GIT)

هنگام ساخت از مخزن گیت باید وابستگی‌های اضافی "autoconf"، "automake"، "gettext"، OCaml findlib و po4a را نصب کنید.

git clone https://github.com/libguestfs/libguestfs
cd libguestfs
git submodule update --init
autoreconf -i
./configure
make

ساخت از تاربال (BUILDING FROM TARBALLS)

فایل‌های فشرده سورس (تاربال) از نشانی http://download.libguestfs.org دانلود می‌شوند. تاربال‌های نسخه پایدار با کلید GnuPG برای "rich@annexia.org" امضا شده‌اند؛ ببینید: https://pgp.mit.edu/pks/lookup?op=vindex&search=0x91738F73E1B768A0 اثرانگشت کلید عبارت است از: "F777 4FB1 AD07 4A7E 8C87 67EA 9173 8F73 E1B7 68A0".

تاربال را دانلود کرده و از حالت فشرده استخراج کنید:

cd libguestfs-1.xx.yy
./configure
make

اجرای آزمون‌ها (RUNNING THE TESTS)

تست‌ها را با دسترسی root اجرا نکنید! ابزار Libguestfs را می‌توان به عنوان کاربر عادی و غیر ریشه ساخت و آزمایش کرد. اجرای تست‌ها با کاربر روت حتی می‌تواند خطرناک باشد؛ این کار را انجام ندهید.

برای بررسی سلامت اولیه ساخت، دستور زیر را اجرا کنید:

make quickcheck

برای اجرای تست‌های پایه، دستور زیر را اجرا کنید:

make check

تست‌های بسیار بیشتری وجود دارند که می‌توانید اجرا کنید. برای جزئیات به guestfs-hacking(1) مراجعه فرمایید.

نصب (INSTALLING)

از دستور "make install" استفاده نکنید! این کار منجر به نصب نسخه‌های متداخل و ناسازگار از libguestfs شده و برای کاربران سردردهای مداوم ایجاد می‌کند. برای نحوه استفاده از اسکریپت ./run به عنوان راهکار مناسب، بخش بعدی را مشاهده نمایید.

بسته‌سازهای توزیع‌ها می‌توانند از دستور زیر استفاده کنند:

make INSTALLDIRS=vendor DESTDIR=[temp-build-dir] install

اسکریپت ./run (THE ./run SCRIPT)

با استفاده از اسکریپت ./run در بالاترین سطح دایرکتوری سورس، می‌توانید برنامه‌های guestfish(1)، guestmount(1) و سایر ابزارهای virt را بدون نیاز به نصب سراسری آن‌ها اجرا نمایید. این اسکریپت با تنظیم چندین متغیر محیطی عمل می‌کند.

برای مثال:

./run guestfish [usual guestfish args ...]
./run virt-inspector [usual virt-inspector args ...]

اسکریپت ./run تمام باینری‌های libguestfs را به $PATH اضافه می‌کند، بنابراین مثال‌های بالا guestfish و virt-inspector را از دایرکتوری ساخت اجرا می‌کنند (نه نسخه نصب‌شده سراسری guestfish، در صورتی که وجود داشته باشد).

می‌توانید از این اسکریپت در هر دایرکتوری استفاده کنید. اگر می‌خواهید برنامه خودتان را که از libguestfs استفاده می‌کند اجرا کنید، دستور زیر نیز کار خواهد کرد:

/path/to/libguestfs/run ./my_program [...]

همچنین می‌توانید برنامه‌های C را تحت valgrind به این صورت اجرا کنید:

./run valgrind [valgrind opts...] virt-cat [virt-cat opts...]

یا تحت gdb:

./run gdb --args virt-cat [virt-cat opts...]

این روش با sudo نیز کار می‌کند (مثلاً اگر برای libvirt یا دسترسی به یک دستگاه بلوکی به دسترسی ریشه نیاز دارید):

sudo ./run virt-cat -d LinuxGuest /etc/passwd

برای تنظیم متغیرهای محیطی، می‌توانید یکی از دو روش زیر را انجام دهید:

LIBGUESTFS_HV=/my/qemu ./run guestfish

یا:

./run env LIBGUESTFS_HV=/my/qemu guestfish

فایل‌های local* (local* FILES)

فایل‌های موجود در دایرکتوری اصلی سورس که با پیشوند local* آغاز می‌شوند توسط git نادیده گرفته می‌شوند. این فایل‌ها می‌توانند حاوی پیکربندی‌های محلی یا اسکریپت‌هایی باشند که برای ساخت libguestfs به آن‌ها نیاز دارید.

من فایلی به نام localconfigure دارم که یک پوشش‌دهنده ساده حول configure است و سفارشی‌سازی‌های محلی مورد نیازم را در بر دارد. ساختار آن شبیه به این است:

. localenv
./configure.sh \
    -C \
    --enable-werror \
    "$@"

بنابراین می‌توانم از آن برای ساخت libguestfs استفاده کنم:

./localconfigure && make

اگر فایلی در دایرکتوری اصلی ساخت به نام localenv وجود داشته باشد، توسط "make" فراخوانی (source) خواهد شد. این فایل می‌تواند شامل هر متغیر محیطی محلی مورد نیاز باشد، مثلاً برای نادیده گرفتن آزمون‌ها:

# Skip this test, it is broken.
export SKIP_TEST_BTRFS_FSCK=1

توجه داشته باشید که localenv توسط Makefile اصلی ضمیمه می‌شود (بنابراین قطعه‌کدی از Makefile است). اما اگر توسط اسکریپت localconfigure شما نیز source شود، به عنوان یک شل‌اسکریپت استفاده می‌شود.

تنظیمات برگزیده ./configure (SELECTED ./configure SETTINGS)

گزینه‌های متعددی برای "./configure" وجود دارند. برای مشاهده لیست کامل آن‌ها از دستور زیر استفاده کنید:

./configure --help

این بخش برخی از مهم‌ترین گزینه‌ها را پوشش می‌دهد.

--disable-appliance --disable-daemon

بخش "استفاده از اپلاینس دودویی از پیش ساخته شده" را در زیر ببینید.

--disable-erlang

--disable-golang

--disable-haskell

--disable-lua

--disable-ocaml

--disable-perl

--disable-php

--disable-python

--disable-ruby

غیرفعال کردن بایندینگ‌های زبان‌های خاص، حتی اگر "./configure" تشخیص دهد که تمام کتابخانه‌های لازم برای کامپایل آن‌ها نصب شده است.

توجه داشته باشید که غیرفعال کردن OCaml (بایندینگ‌ها) یا Perl تأثیر زنجیره‌ای بر غیرفعال شدن بخش‌هایی از مجموعه آزمون‌ها و برخی ابزارها خواهد داشت.

زبان OCaml برای ساخت libguestfs الزامی است و این نیازمندی قابل حذف نیست. استفاده از --disable-ocaml صرفاً بایندینگ‌ها را غیرفعال می‌کند.

--disable-fuse

غیرفعال کردن پشتیبانی از FUSE در API و در ابزار guestmount(1).

--disable-static

نسخه لینک‌شده استاتیک کتابخانه libguestfs ساخته نمی‌شود.

--enable-install-daemon

به‌طور معمول guestfsd(8) توسط "make install" نصب نمی‌شود، زیرا مفید نخواهد بود (در عوض در داخل اپلاینس supermin "نصب" می‌شود). با این حال اگر بسته‌سازها اقدام به ساخت "libguestfs live" می‌کنند باید از این گزینه استفاده کنند.

--enable-werror

این گزینه هشدارهای کامپایلر را به خطا تبدیل می‌کند (یعنی "-Werror"). از این گزینه در زمان توسعه، به خصوص هنگام ارسال وصله‌ها (patches) استفاده کنید. معمولاً نباید برای ساخت‌های نهایی یا توزیع استفاده شود.

--with-default-backend=libvirt

این گزینه روش پیش‌فرضی را کنترل می‌کند که libguestfs برای اجرای qemu استفاده می‌نماید (ببینید "BACKEND" در guestfs(3)). اگر مشخص نشود، بک‌اند پیش‌فرض "direct" است، به این معنی که libguestfs مستقیماً qemu را اجرا می‌کند.

توزیع‌های Fedora و Red Hat Enterprise Linux (RHEL) نسخه ۷ به بعد از این فلگ برای تغییر بک‌اند پیش‌فرض به "libvirt" استفاده می‌کنند، زیرا (به‌ویژه در RHEL) خط‌مشی سیستمی این است که هیچ برنامه‌ای اجازه اجرای مستقیم qemu را جز از طریق libvirt ندارد.

توجه داشته باشید که علیرغم این تنظیم، تمام بک‌اندها درون libguestfs کامپایل می‌شوند و شما می‌توانید در زمان اجرا با تنظیم متغیر محیطی $LIBGUESTFS_BACKEND (یا با روش‌های API) بک‌اند را لغو و بازنویسی کنید.

--with-distro=REDHAT|DEBIAN|...

ابزار Libguestfs باید بداند کدام توزیع لینوکس در حال استفاده است تا بتواند نام بسته‌ها را برای اپلاینس به‌درستی انتخاب کند (برای مثال به appliance/packagelist.in مراجعه کنید). این کار به‌طور معمول به صورت خودکار انجام می‌شود.

با این حال اگر در حال ساخت یا بسته‌بندی libguestfs روی توزیع جدیدی هستید، می‌توانید از --with-distro برای تعیین شباهت آن با توزیع موجود استفاده کنید (مثلاً --with-distro=REDHAT در صورتی که توزیع یک مشتق جدید از Red Hat یا CentOS باشد).

توجه داشته باشید اگر توزیع شما کاملاً جدید باشد ممکن است همچنان نیازمند اعمال اصلاحاتی در بالادست (upstream) باشد.

--with-extra="distroname=version,libvirt,..."

--with-extra="local"

این گزینه فیلد "extra" بازگردانده شده توسط "guestfs_version" در guestfs(3) را کنترل می‌کند که توسط گزینه --version ابزارهای virt نیز چاپ می‌شود. این یک فیلد متنی آزاد است، اما ایده خوب این است که فهرستی از فکت‌های جداشده با کاما مانند نام و نسخه توزیع، اینکه آیا libvirt بک‌اند پیش‌فرض است یا خیر، و هر چیز دیگری را که ممکن است به رفع اشکال مشکلات مطرح‌شده توسط کاربران کمک کند، در آن رمزگذاری کنید.

برای ساخت‌های سفارشی و/یا محلی، می‌توان این فیلد را روی "local" تنظیم کرد تا نشان دهد این یک ساخت رسمی توزیع نیست.

--without-libvirt

کامپایل libguestfs بدون پشتیبانی libvirt، حتی اگر کتابخانه‌های توسعه libvirt نصب باشند.

--with-qemu="bin1 bin2 ..."

ارائه یک باینری جایگزین qemu (یا فهرستی از باینری‌ها). این گزینه را می‌توان در زمان اجرا با تنظیم متغیر محیطی "LIBGUESTFS_HV" لغو و بازنویسی کرد.

--with-supermin-packager-config=yum.conf

این گزینه --packager-config را به supermin(1) ارسال می‌کند.

رایج‌ترین کاربرد این گزینه ساخت اپلاینس با استفاده از مخزن جایگزین است (به جای استفاده از پیکربندی نصب‌شده yum/dnf/apt و غیره برای یافتن و دانلود بسته‌ها). اگر می‌خواهید libguestfs را بدون اتصال به اینترنت بسازید ممکن است به این گزینه نیاز داشته باشید. مثال‌هایی از این مورد در فایل "libguestfs.spec" فدورا یافت می‌شود (منابع را در "ساخت بسته برای فدورا" در زیر ببینید).

--with-supermin-extra-options="--opt1 --opt2 ..."

ارسال گزینه‌های اضافی به supermin(1). برای درک دقیق عملکرد این گزینه به appliance/make.sh.in مراجعه کنید.

PYTHON

این متغیر محیطی را می‌توان طوری تنظیم کرد که به یک باینری پایتون اشاره کند (مثلاً "python3"). هنگامی که "./configure" اجرا می‌شود، این باینری پایتون را بررسی می‌کند تا نسخه پایتون، محل کتابخانه‌های پایتون و موارد مشابه را بیابد.

SUPERMIN

این متغیر محیطی می‌تواند برای انتخاب یک باینری جایگزین supermin(1) تنظیم شود. به عنوان مثال اگر بخواهید از نسخه بالادستی جدیدتر supermin نسبت به نسخه بسته‌بندی‌شده برای توزیع خود استفاده کنید، یا اگر supermin اصلاً در توزیع شما بسته‌بندی نشده باشد، می‌توان از این متغیر استفاده کرد. در RHEL 7، هنگام کامپایل libguestfs باید متغیر "SUPERMIN=/usr/bin/supermin5" را تنظیم کنید.

نکاتی درباره QEMU و KVM (NOTES ABOUT QEMU AND KVM)

یک مشکل رایج مربوط به انتشار نسخه‌های خراب یا ناسازگار qemu است.

نسخه‌های مختلف qemu به دلایل متفاوتی در بوت کردن اپلاینس با مشکل مواجه می‌شوند. این مسئله بین نسخه‌های مختلف qemu و توزیع‌های لینوکس که وصله‌های اختصاصی خود را اعمال می‌کنند متفاوت است.

اگر با مشکلی مواجه شدید، می‌توانید ساخت qemu از سورس را با یک "پوشش‌دهنده qemu" امتحان کنید (ساخت qemu از کد منبع بسیار ساده است). بخش "QEMU WRAPPERS" در guestfs(3) را ببینید.

به‌طور پیش‌فرض اسکریپت پیکربندی به دنبال qemu-kvm (پشتیبانی KVM) خواهد گشت. شتاب‌دهنده KVM بسیار سریع‌تر از استفاده از qemu خام است.

همچنین ممکن است لازم باشد پشتیبانی KVM را برای کاربران غیر ریشه فعال کنید؛ با دنبال کردن این دستورالعمل‌ها: http://www.linux-kvm.org/page/FAQ#How_can_I_use_kvm_with_a_non-privileged_user.3F

در برخی سیستم‌ها دستور زیر نیز کار خواهد کرد:

chmod 0666 /dev/kvm

در برخی سیستم‌ها دستور chmod پس از راه‌اندازی مجدد باقی نمی‌ماند و باید در پیکربندی udev تغییراتی ایجاد نمایید.

استفاده از CLANG (LLVM) به جای GCC (USING CLANG (LLVM) INSTEAD OF GCC)

export CC=clang
./configure
make

استفاده از اپلاینس دودویی از پیش ساخته شده (USING A PREBUILT BINARY APPLIANCE)

برای درک مفهوم اپلاینس در libguestfs، صفحه راهنمای guestfs-internals(1) را مطالعه کنید.

اگر از سیستمی غیرلینوکسی استفاده می‌کنید، یا توزیع لینوکسی دارید که فاقد پشتیبانی از supermin(1) است، یا صرفاً نمی‌خواهید اپلاینس libguestfs اختصاصی خود را بسازید، می‌توانید از یکی از اپلاینس‌های باینری از پیش ساخته‌شده‌ای که ما ارائه می‌دهیم استفاده کنید: http://libguestfs.org/download/binaries/appliance

ابزار libguestfs را به این صورت بسازید:

./configure --disable-appliance --disable-daemon
make

متغیر $LIBGUESTFS_PATH را روی مسیری که تاربال اپلاینس را در آن استخراج کرده‌اید تنظیم کنید؛ مانند:

export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance

و برنامه‌های libguestfs و ابزارهای virt را به روش معمول، به عنوان مثال با استفاده از اسکریپت ./run اجرا کنید (به بالا مراجعه فرمایید).

ساخت بسته برای فدورا (BUILDING A PACKAGE FOR FEDORA)

فایل spec فدورا در نشانی زیر نگهداری می‌شود: http://pkgs.fedoraproject.org/cgit/rpms/libguestfs.git

ابزار Libguestfs در فدورا با استفاده از سیستم ساخت استاندارد فدورا (Koji) ساخته می‌شود.

ساخت بسته برای RED HAT ENTERPRISE LINUX

نسخه‌های Red Hat Enterprise Linux (RHEL) از libguestfs به شدت پچ شده‌اند. به طور کلی دو نوع وصله (پچ) اعمال می‌کنیم:

• ما بسیاری از قابلیت‌هایی را که مایل به پشتیبانی از آن‌ها برای مشتریان RHEL نیستیم غیرفعال می‌کنیم. برای مثال، ویژگی "libguestfs live" غیرفعال شده است.
• ما قابلیت‌های بالادست (upstream) را به این نسخه‌ها بک‌پورت (backport) می‌کنیم.

وصله‌هایی که به نسخه‌های انتشار RHEL اعمال می‌کنیم به صورت عمومی در مخزن گیت بالادست در شاخه‌ای به نام "rhel-x.y" در دسترس هستند.

به عنوان مثال وصله‌های RHEL 7.3 در اینجا در دسترس هستند: https://github.com/libguestfs/libguestfs/commits/rhel-7.3

کدهای منبع و فایل‌های spec برای نسخه‌های RHEL از libguestfs در نشانی https://git.centos.org/project/rpms و همچنین https://wiki.centos.org/Sources در دسترس هستند.

همچنین ببینید (SEE ALSO)

guestfs(3), guestfs-examples(3), guestfs-hacking(1), guestfs-internals(1), guestfs-performance(1), guestfs-release-notes(1), guestfs-testing(1), libguestfs-test-tool(1), libguestfs-make-fixed-appliance(1), http://libguestfs.org

نویسندگان (AUTHORS)

Richard W.M. Jones ("rjones at redhat dot com")

حق نشر (COPYRIGHT)

Copyright (C) 2009-2025 Red Hat Inc.

مجوز (LICENSE)

این کتابخانه نرم‌افزار آزاد است؛ شما می‌توانید آن را تحت شرایط مجوز عمومی کمتر گنو (LGPL) که توسط بنیاد نرم‌افزارهای آزاد منتشر شده است، چه نسخه 2 مجوز و چه (به دلخواه خود) هر نسخه بالاتر، بازتوزیع کرده و/یا تغییر دهید.

این کتابخانه به این امید توزیع شده است که مفید واقع شود، اما بدون هیچ‌گونه ضمانت؛ حتی بدون ضمانت ضمنی قابل فروش بودن یا مناسب بودن برای یک هدف خاص. برای جزئیات بیشتر به مجوز عمومی کمتر گنو مراجعه کنید.

شما باید یک نسخه از مجوز عمومی کمتر گنو را به همراه این کتابخانه دریافت کرده باشید؛ در غیر این صورت، به بنیاد نرم‌افزارهای آزاد به نشانی زیر نامه بنویسید: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

اشکالات (BUGS)

برای دریافت فهرست باگ‌های گزارش‌شده در رابطه با libguestfs، از این پیوند استفاده کنید: https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools

برای ارسال گزارش باگ جدید علیه libguestfs، از این پیوند استفاده کنید: https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

هنگام گزارش باگ، لطفاً اطلاعات زیر را درج نمایید:

• نسخه libguestfs.
• محل دریافت libguestfs (برای مثال کدام توزیع لینوکس، کامپایل‌شده از کد منبع و غیره).
• توصیف دقیق باگ و ارائه راهکاری برای بازتولید آن.
• اجرای دستور libguestfs-test-tool(1) و قرار دادن خروجی کامل و دست‌نخورده آن در گزارش باگ.