.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.60.1 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "guestfs-building 1"
.TH guestfs-building 1 2026-07-14 libguestfs-1.60.1 "Virtualization Support"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "نام (NAME)"
guestfs\-building \- نحوه ساخت libguestfs از کد منبع
.SH "توضیحات (DESCRIPTION)"
.IX Header "DESCRIPTION"
این صفحه راهنما نحوه ساخت libguestfs را از کد منبع شرح می‌دهد.
.PP
مراحل اصلی عبارتند از:
.IP \(bu 4
نصب نیازمندی‌ها و وابستگی‌ها.
.IP \(bu 4
ساخت، یا از طریق مخزن گیت و یا از یک فایل فشرده (تاربال).
.IP \(bu 4
اجرای آزمون‌ها.
.IP \(bu 4
اجرای ابزارها از دایرکتوری سورس، یا نصب آن‌ها.
.SH "نیازمندی‌ها (REQUIREMENTS)"
.IX Header "REQUIREMENTS"
.SS "میان‌بر برای کاربران Fedora یا Red Hat Enterprise Linux (RHEL)"
.IX Subsection "Short cut for Fedora or Red Hat Enterprise Linux (RHEL) users"
در فدورا، از دستور \fBdnf\fR\|(8) برای نصب تمام نیازمندی‌ها استفاده کنید:
.PP
.Vb 2
\& dnf builddep libguestfs
\& dnf install autoconf automake libtool gettext\-devel
.Ve
.PP
در سیستم‌هایی که هنوز از \fByum\fR\|(8) استفاده می‌کنند، دستور زیر را اجرا کنید:
.PP
.Vb 2
\& yum\-builddep libguestfs
\& yum install autoconf automake libtool gettext\-devel
.Ve
.SS "میان‌بر برای کاربران دبیان یا اوبونتو (Debian or Ubuntu)"
.IX Subsection "Short cut for Debian or Ubuntu users"
برای نصب تمام نیازمندی‌ها از APT استفاده کنید:
.PP
.Vb 2
\& apt\-get build\-dep libguestfs
\& apt\-get install autoconf automake libtool\-bin gettext
.Ve
.PP
اگر آن دستور کار نکرد، نگاهی به بسته سورس دبیان در
http://packages.debian.org/source/libguestfs
بیندازید، به ویژه لیست \f(CW\*(C`build\-depends\*(C'\fR و \f(CW\*(C`build\-depends\-indep\*(C'\fR، و هر آنچه در آنجا فهرست شده را نصب کنید.
.SS "فهرست کامل نیازمندی‌ها (Full list of requirements)"
.IX Subsection "Full list of requirements"
.IP \fIappliance/packagelist.in\fR 4
.IX Item "appliance/packagelist.in"
تا حد امکان نام بسته‌های موجود در این فایل را نصب کنید. (نصب همه آن‌ها اکیداً الزامی نیست).
.Sp
\&\fIنکته\fR: اگر libguestfs را بسازید و سپس بسته‌های اپلاینس را نصب کنید، فرآیند ساخت آن‌ها را به‌طور خودکار شناسایی نخواهد کرد، حتی اگر \f(CW\*(C`make\ clean\*(C'\fR را اجرا کنید. برای پاک‌سازی اپلاینس قدیمی supermin و اجبار به آماده‌سازی یک اپلاینس جدید، باید این دستور را اجرا کنید:
.Sp
.Vb 1
\& make \-C appliance clean\-supermin\-appliance
.Ve
.IP "qemu ≥ 7.2.0" 4
.IX Item "qemu ≥ 7.2.0"
\&\fIالزامی\fR.
.IP "qemu\-img ≥ 7.2.0" 4
.IX Item "qemu-img ≥ 7.2.0"
\&\fIالزامی\fR.
.IP "kernel ≥ 2.6.34" 4
.IX Item "kernel ≥ 2.6.34"
\&\fIالزامی\fR. قابلیت‌های زیر باید فعال باشند:
\&\f(CW\*(C`virtio\-pci\*(C'\fR, \f(CW\*(C`virtio\-serial\*(C'\fR, \f(CW\*(C`virtio\-block\*(C'\fR, \f(CW\*(C`virtio\-net\*(C'\fR.
.IP "supermin ≥ 5.1.18" 4
.IX Item "supermin ≥ 5.1.18"
\&\fIالزامی\fR. برای گزینه‌های جایگزین، بخش "استفاده از اپلاینس دودویی از پیش ساخته شده" را در زیر ببینید.
.IP "XDR (tirpc, glibc or other)" 4
.IX Item "XDR (tirpc, glibc or other)"
\&\fIالزامی\fR. ما از پیاده‌سازی XDR موجود در
\&\f(CW\*(C`<rpc/xdr.h>\*(C'\fR استفاده می‌کنیم که ممکن است از glibc، tirpc یا کتابخانه دیگری ارائه شود.
.Sp
ابزار \f(CW\*(C`rpcgen\*(C'\fR اختیاری است، مگر اینکه بخواهید از گیت کامپایل کنید و/یا وصله‌هایی با APIهای جدید به libguestfs اعمال نمایید.
.IP "Gcc or Clang" 4
.IX Item "Gcc or Clang"
\&\fIالزامی\fR. ما از قابلیت افزونه‌ای \f(CW\*(C`_\|_attribute_\|_((cleanup))\*(C'\fR در GCC استفاده می‌کنیم که توسط Clang نیز پشتیبانی می‌شود.
.IP Perl 4
.IX Item "Perl"
\&\fIالزامی\fR. مراحل مختلف ساخت و آزمون با پرل نوشته شده‌اند. پرل در زمان اجرا مورد نیاز نیست، مگر اینکه بخواهید تعداد محدودی از ابزارهای virt را که هنوز با پرل نوشته شده‌اند اجرا کنید.
.ie n .IP "Perl ""Pod::Man""" 4
.el .IP "Perl \f(CWPod::Man\fR" 4
.IX Item "Perl Pod::Man"
.PD 0
.ie n .IP "Perl ""Pod::Simple""" 4
.el .IP "Perl \f(CWPod::Simple\fR" 4
.IX Item "Perl Pod::Simple"
.PD
\&\fIالزامی\fR. بخشی از هسته اصلی Perl.
.IP "OCaml ≥ 4.08" 4
.IX Item "OCaml ≥ 4.08"
.PD 0
.IP "OCaml findlib" 4
.IX Item "OCaml findlib"
.PD
\&\fIالزامی\fR.
.IP autoconf 4
.IX Item "autoconf"
.PD 0
.IP automake 4
.IX Item "automake"
.IP gettext 4
.IX Item "gettext"
.PD
در صورت کامپایل از گیت \fIالزامی\fR است.
در صورت کامپایل از تاربال اختیاری است.
.IP cpio 4
.IX Item "cpio"
\&\fIالزامی\fR.
.IP gperf 4
.IX Item "gperf"
\&\fIالزامی\fR.
.IP realpath 4
.IX Item "realpath"
\&\fIالزامی\fR.
.IP "کتابخانه PCRE2 (عبارات باقاعده سازگار با پرل)" 4
.IX Item "Perl-compatible Regular Expressions (PCRE2) library"
\&\fIالزامی\fR.
.IP "xorriso, genisoimage or mkisofs" 4
.IX Item "xorriso, genisoimage or mkisofs"
یکی از این موارد \fIالزامی\fR است.
.IP libxml2 4
.IX Item "libxml2"
\&\fIالزامی\fR.
.IP ncurses 4
.IX Item "ncurses"
\&\fIالزامی\fR.
.IP "augeas ≥ 1.2.0" 4
.IX Item "augeas ≥ 1.2.0"
\&\fIالزامی\fR.
.IP ocaml\-augeas 4
.IX Item "ocaml-augeas"
\&\fIالزامی\fR. این‌ها بایندینگ‌های OCaml برای Augeas هستند که در نشانی زیر یافت می‌شوند:
http://people.redhat.com/~rjones/augeas
.IP xz 4
.IX Item "xz"
\&\fIالزامی\fR.
.IP zstd 4
.IX Item "zstd"
\&\fIالزامی\fR.
.IP "json\-c ≥ 0.14" 4
.IX Item "json-c ≥ 0.14"
\&\fIالزامی\fR.
.IP po4a 4
.IX Item "po4a"
در صورت کامپایل از گیت \fIالزامی\fR است.
در صورت کامپایل از تاربال اختیاری است.
.IP "hivex ≥ 1.2.7" 4
.IX Item "hivex ≥ 1.2.7"
.PD 0
.IP ocaml\-hivex 4
.IX Item "ocaml-hivex"
.PD
\&\fIالزامی\fR. بسته ocaml\-hivex بایندینگ OCaml برای hivex است که هنگام ساخت دیمن مورد نیاز می‌باشد.
.IP "libvirt ≥ 11.10.0" 4
.IX Item "libvirt ≥ 11.10.0"
اختیاری. همواره از جدیدترین نسخه ممکن libvirt استفاده کنید.
.IP xmllint 4
.IX Item "xmllint"
اختیاری. فقط برای تست‌ها استفاده می‌شود.
.IP libconfig 4
.IX Item "libconfig"
اختیاری. برای تجزیه فایل‌های پیکربندی خود libguestfs استفاده می‌شود،
مانند \fI/etc/libguestfs\-tools.conf\fR.
.IP libselinux 4
.IX Item "libselinux"
اختیاری. توسط بک‌اند libvirt برای محصورسازی امن اپلاینس (sVirt) استفاده می‌شود.
.IP readline 4
.IX Item "readline"
اختیاری. برای ویرایش بهتر خط فرمان در \fBguestfish\fR\|(1).
.IP acl 4
.IX Item "acl"
اختیاری. کتابخانه و برنامه‌ها برای مدیریت ACLهای استاندارد POSIX.
.IP libcap 4
.IX Item "libcap"
اختیاری. کتابخانه و برنامه‌ها برای مدیریت قابلیت‌های (capabilities) لینوکس.
.IP libldm 4
.IX Item "libldm"
اختیاری. کتابخانه و \fBldmtool\fR\|(1) برای مدیریت دیسک‌های پویای ویندوز (Windows Dynamic Disks).
.IP sd\-journal 4
.IX Item "sd-journal"
اختیاری. کتابخانه برای دسترسی به ژورنال‌های systemd.
.IP gdisk 4
.IX Item "gdisk"
اختیاری. پشتیبانی از دیسک‌های با جدول پارتیشن GPT.
.IP netpbm 4
.IX Item "netpbm"
اختیاری. رندر کردن آیکون‌ها از ماشین‌های مهمان.
.IP icoutils 4
.IX Item "icoutils"
اختیاری. رندر کردن آیکون‌ها از مهمان‌های ویندوزی.
.IP librpm 4
.IX Item "librpm"
اختیاری. برای پردازش و استخراج لیست برنامه‌ها از مهمان‌های مبتنی بر RPM.
.ie n .IP "Perl ""Expect""" 4
.el .IP "Perl \f(CWExpect\fR" 4
.IX Item "Perl Expect"
اختیاری. ماژول پرل که برای آزمایش \fBvirt\-rescue\fR\|(1) استفاده می‌شود.
.IP FUSE 4
.IX Item "FUSE"
اختیاری. اگر به \fBguestmount\fR\|(1) و/یا پشتیبانی mount\-local نیاز دارید، \fBfusermount\fR\|(1)، libfuse و ماژول هسته همگی مورد نیاز هستند.
.IP "static glibc" 4
.IX Item "static glibc"
اختیاری. فقط برای آزمون و تست استفاده می‌شود.
.IP qemu\-nbd 4
.IX Item "qemu-nbd"
اختیاری. ابزار qemu\-nbd برای آزمون‌ها استفاده می‌شود.
.ie n .IP "Perl ""Module::Build"" ≥ 0.19" 4
.el .IP "Perl \f(CWModule::Build\fR ≥ 0.19" 4
.IX Item "Perl Module::Build ≥ 0.19"
.PD 0
.ie n .IP "Perl ""Test::More""" 4
.el .IP "Perl \f(CWTest::More\fR" 4
.IX Item "Perl Test::More"
.PD
اختیاری. برای ساخت و تست بایندینگ‌های Perl استفاده می‌شود.
.IP "Python ≥ 3.6" 4
.IX Item "Python ≥ 3.6"
اختیاری. برای ساخت بایندینگ‌های پایتون استفاده می‌شود.
پشتیبانی از پایتون ۲ در libguestfs\ 1.42.1 حذف شد.
.ie n .IP "Python ""unittest""" 4
.el .IP "Python \f(CWunittest\fR" 4
.IX Item "Python unittest"
اختیاری. برای اجرای مجموعه تست‌های پایتون استفاده می‌شود.
.IP Ruby 4
.IX Item "Ruby"
.PD 0
.IP rake 4
.IX Item "rake"
.IP rubygem\-minitest 4
.IX Item "rubygem-minitest"
.IP rubygem\-rdoc 4
.IX Item "rubygem-rdoc"
.PD
اختیاری. برای ساخت بایندینگ‌های Ruby استفاده می‌شود.
.IP "Java ≥ 1.6" 4
.IX Item "Java ≥ 1.6"
اختیاری. ابزارهای Java، JNI و jpackage\-utils برای ساخت بایندینگ‌های جاوا مورد نیاز هستند.
.IP GHC 4
.IX Item "GHC"
اختیاری. برای ساخت بایندینگ‌های هاسکل استفاده می‌شود.
.IP PHP 4
.IX Item "PHP"
.PD 0
.IP phpize 4
.IX Item "phpize"
.PD
اختیاری. برای ساخت بایندینگ‌های PHP استفاده می‌شود.
.IP LUA 4
.IX Item "LUA"
اختیاری. برای ساخت بایندینگ‌های LUA استفاده می‌شود.
.IP "Erlang ≥ 23" 4
.IX Item "Erlang ≥ 23"
.PD 0
.IP ei 4
.IX Item "ei"
.PD
اختیاری. برای ساخت بایندینگ‌های Erlang استفاده می‌شود. توجه داشته باشید که Erlang ≤
22 کار نخواهد کرد مگر اینکه از libguestfs ≤ 1.42 استفاده کنید.
.IP "golang ≥ 1.1.1" 4
.IX Item "golang ≥ 1.1.1"
اختیاری. برای ساخت بایندینگ‌های Go استفاده می‌شود.
.IP valgrind 4
.IX Item "valgrind"
اختیاری. برای بررسی و اشکال‌زدایی مشکلات حافظه.
.IP libvirt\-python 4
.IX Item "libvirt-python"
اختیاری. برای آزمایش تعاملات میان پایتون با libvirt و libguestfs.
.ie n .IP "Perl ""libintl""" 4
.el .IP "Perl \f(CWlibintl\fR" 4
.IX Item "Perl libintl"
اختیاری.
.IP bash\-completion 4
.IX Item "bash-completion"
اختیاری. برای تکمیل خودکار دستورات با کلید تب در bash.
.IP libtsk 4
.IX Item "libtsk"
اختیاری. کتابخانه برای تحلیل و جرم‌شناسی (forensics) فایل‌سیستم.
.IP "yara ≥ 4.0.0" 4
.IX Item "yara ≥ 4.0.0"
اختیاری. ابزاری برای دسته‌بندی فایل‌ها بر اساس محتوای آن‌ها.
.SH "ساخت از گیت (BUILDING FROM GIT)"
.IX Header "BUILDING FROM GIT"
هنگام ساخت از مخزن گیت باید وابستگی‌های اضافی \f(CW\*(C`autoconf\*(C'\fR،
\&\f(CW\*(C`automake\*(C'\fR، \f(CW\*(C`gettext\*(C'\fR، OCaml findlib و po4a را نصب کنید.
.PP
.Vb 6
\& git clone https://github.com/libguestfs/libguestfs
\& cd libguestfs
\& git submodule update \-\-init
\& autoreconf \-i
\& ./configure
\& make
.Ve
.SH "ساخت از تاربال (BUILDING FROM TARBALLS)"
.IX Header "BUILDING FROM TARBALLS"
فایل‌های فشرده سورس (تاربال) از نشانی http://download.libguestfs.org دانلود می‌شوند.
تاربال‌های نسخه پایدار با کلید GnuPG برای \f(CW\*(C`rich@annexia.org\*(C'\fR امضا شده‌اند؛ ببینید:
https://pgp.mit.edu/pks/lookup?op=vindex&search=0x91738F73E1B768A0
اثرانگشت کلید عبارت است از: \f(CW\*(C`F777 4FB1 AD07 4A7E 8C87 67EA 9173 8F73 E1B7 68A0\*(C'\fR.
.PP
تاربال را دانلود کرده و از حالت فشرده استخراج کنید:
.PP
.Vb 3
\& cd libguestfs\-1.xx.yy
\& ./configure
\& make
.Ve
.SH "اجرای آزمون‌ها (RUNNING THE TESTS)"
.IX Header "RUNNING THE TESTS"
\&\fBتست‌ها را با دسترسی root اجرا نکنید!\fR  ابزار Libguestfs را می‌توان به عنوان کاربر عادی و غیر ریشه ساخت و آزمایش کرد. اجرای تست‌ها با کاربر روت حتی می‌تواند خطرناک باشد؛ این کار را انجام ندهید.
.PP
برای بررسی سلامت اولیه ساخت، دستور زیر را اجرا کنید:
.PP
.Vb 1
\& make quickcheck
.Ve
.PP
برای اجرای تست‌های پایه، دستور زیر را اجرا کنید:
.PP
.Vb 1
\& make check
.Ve
.PP
تست‌های بسیار بیشتری وجود دارند که می‌توانید اجرا کنید. برای جزئیات به \fBguestfs\-hacking\fR\|(1) مراجعه فرمایید.
.SH "نصب (INSTALLING)"
.IX Header "INSTALLING"
\&\fBاز دستور \fR\f(CB\*(C`make install\*(C'\fR\fB استفاده نکنید!\fR  این کار منجر به نصب نسخه‌های متداخل و ناسازگار از libguestfs شده و برای کاربران سردردهای مداوم ایجاد می‌کند. برای نحوه استفاده از اسکریپت \fI./run\fR به عنوان راهکار مناسب، بخش بعدی را مشاهده نمایید.
.PP
بسته‌سازهای توزیع‌ها می‌توانند از دستور زیر استفاده کنند:
.PP
.Vb 1
\& make INSTALLDIRS=vendor DESTDIR=[temp\-build\-dir] install
.Ve
.SH "اسکریپت ./run (THE ./run SCRIPT)"
.IX Header "THE ./run SCRIPT"
با استفاده از اسکریپت \fI./run\fR در بالاترین سطح دایرکتوری سورس، می‌توانید برنامه‌های \fBguestfish\fR\|(1)، \fBguestmount\fR\|(1) و سایر ابزارهای virt را بدون نیاز به نصب سراسری آن‌ها اجرا نمایید. این اسکریپت با تنظیم چندین متغیر محیطی عمل می‌کند.
.PP
برای مثال:
.PP
.Vb 1
\& ./run guestfish [usual guestfish args ...]
\&
\& ./run virt\-inspector [usual virt\-inspector args ...]
.Ve
.PP
اسکریپت \fI./run\fR تمام باینری‌های libguestfs را به \f(CW$PATH\fR اضافه می‌کند، بنابراین مثال‌های بالا guestfish و virt\-inspector را از دایرکتوری ساخت اجرا می‌کنند (نه نسخه نصب‌شده سراسری guestfish، در صورتی که وجود داشته باشد).
.PP
می‌توانید از این اسکریپت در هر دایرکتوری استفاده کنید. اگر می‌خواهید برنامه خودتان را که از libguestfs استفاده می‌کند اجرا کنید، دستور زیر نیز کار خواهد کرد:
.PP
.Vb 1
\& /path/to/libguestfs/run ./my_program [...]
.Ve
.PP
همچنین می‌توانید برنامه‌های C را تحت valgrind به این صورت اجرا کنید:
.PP
.Vb 1
\& ./run valgrind [valgrind opts...] virt\-cat [virt\-cat opts...]
.Ve
.PP
یا تحت gdb:
.PP
.Vb 1
\& ./run gdb \-\-args virt\-cat [virt\-cat opts...]
.Ve
.PP
این روش با sudo نیز کار می‌کند (مثلاً اگر برای libvirt یا دسترسی به یک دستگاه بلوکی به دسترسی ریشه نیاز دارید):
.PP
.Vb 1
\& sudo ./run virt\-cat \-d LinuxGuest /etc/passwd
.Ve
.PP
برای تنظیم متغیرهای محیطی، می‌توانید یکی از دو روش زیر را انجام دهید:
.PP
.Vb 1
\& LIBGUESTFS_HV=/my/qemu ./run guestfish
.Ve
.PP
یا:
.PP
.Vb 1
\& ./run env LIBGUESTFS_HV=/my/qemu guestfish
.Ve
.SH "فایل‌های \fIlocal*\fP (\fIlocal*\fP FILES)"
.IX Header "local* FILES"
فایل‌های موجود در دایرکتوری اصلی سورس که با پیشوند \fIlocal*\fR آغاز می‌شوند توسط git نادیده گرفته می‌شوند. این فایل‌ها می‌توانند حاوی پیکربندی‌های محلی یا اسکریپت‌هایی باشند که برای ساخت libguestfs به آن‌ها نیاز دارید.
.PP
من فایلی به نام \fIlocalconfigure\fR دارم که یک پوشش‌دهنده ساده حول \fIconfigure\fR است و سفارشی‌سازی‌های محلی مورد نیازم را در بر دارد. ساختار آن شبیه به این است:
.PP
.Vb 5
\& . localenv
\& ./configure.sh \e
\&     \-C \e
\&     \-\-enable\-werror \e
\&     "$@"
.Ve
.PP
بنابراین می‌توانم از آن برای ساخت libguestfs استفاده کنم:
.PP
.Vb 1
\& ./localconfigure && make
.Ve
.PP
اگر فایلی در دایرکتوری اصلی ساخت به نام \fIlocalenv\fR وجود داشته باشد، توسط \f(CW\*(C`make\*(C'\fR فراخوانی (source) خواهد شد. این فایل می‌تواند شامل هر متغیر محیطی محلی مورد نیاز باشد، مثلاً برای نادیده گرفتن آزمون‌ها:
.PP
.Vb 2
\& # Skip this test, it is broken.
\& export SKIP_TEST_BTRFS_FSCK=1
.Ve
.PP
توجه داشته باشید که \fIlocalenv\fR توسط Makefile اصلی ضمیمه می‌شود (بنابراین قطعه‌کدی از Makefile است). اما اگر توسط اسکریپت \fIlocalconfigure\fR شما نیز source شود، به عنوان یک شل‌اسکریپت استفاده می‌شود.
.SH "تنظیمات برگزیده ./configure (SELECTED ./configure SETTINGS)"
.IX Header "SELECTED ./configure SETTINGS"
گزینه‌های متعددی برای \f(CW\*(C`./configure\*(C'\fR وجود دارند. برای مشاهده لیست کامل آن‌ها از دستور زیر استفاده کنید:
.PP
.Vb 1
\& ./configure \-\-help
.Ve
.PP
این بخش برخی از مهم‌ترین گزینه‌ها را پوشش می‌دهد.
.IP "\fB\-\-disable\-appliance \-\-disable\-daemon\fR" 4
.IX Item "--disable-appliance --disable-daemon"
بخش "استفاده از اپلاینس دودویی از پیش ساخته شده" را در زیر ببینید.
.IP \fB\-\-disable\-erlang\fR 4
.IX Item "--disable-erlang"
.PD 0
.IP \fB\-\-disable\-golang\fR 4
.IX Item "--disable-golang"
.IP \fB\-\-disable\-haskell\fR 4
.IX Item "--disable-haskell"
.IP \fB\-\-disable\-lua\fR 4
.IX Item "--disable-lua"
.IP \fB\-\-disable\-ocaml\fR 4
.IX Item "--disable-ocaml"
.IP \fB\-\-disable\-perl\fR 4
.IX Item "--disable-perl"
.IP \fB\-\-disable\-php\fR 4
.IX Item "--disable-php"
.IP \fB\-\-disable\-python\fR 4
.IX Item "--disable-python"
.IP \fB\-\-disable\-ruby\fR 4
.IX Item "--disable-ruby"
.PD
غیرفعال کردن بایندینگ‌های زبان‌های خاص، حتی اگر \f(CW\*(C`./configure\*(C'\fR تشخیص دهد که تمام کتابخانه‌های لازم برای کامپایل آن‌ها نصب شده است.
.Sp
توجه داشته باشید که غیرفعال کردن OCaml (بایندینگ‌ها) یا Perl تأثیر زنجیره‌ای بر غیرفعال شدن بخش‌هایی از مجموعه آزمون‌ها و برخی ابزارها خواهد داشت.
.Sp
زبان OCaml برای ساخت libguestfs الزامی است و این نیازمندی قابل حذف نیست. استفاده از \fI\-\-disable\-ocaml\fR صرفاً بایندینگ‌ها را غیرفعال می‌کند.
.IP \fB\-\-disable\-fuse\fR 4
.IX Item "--disable-fuse"
غیرفعال کردن پشتیبانی از FUSE در API و در ابزار \fBguestmount\fR\|(1).
.IP \fB\-\-disable\-static\fR 4
.IX Item "--disable-static"
نسخه لینک‌شده استاتیک کتابخانه libguestfs ساخته نمی‌شود.
.IP \fB\-\-enable\-install\-daemon\fR 4
.IX Item "--enable-install-daemon"
به‌طور معمول \fBguestfsd\fR\|(8) توسط \f(CW\*(C`make install\*(C'\fR نصب نمی‌شود، زیرا مفید نخواهد بود (در عوض در داخل اپلاینس supermin "نصب" می‌شود). با این حال اگر بسته‌سازها اقدام به ساخت "libguestfs live" می‌کنند باید از این گزینه استفاده کنند.
.IP \fB\-\-enable\-werror\fR 4
.IX Item "--enable-werror"
این گزینه هشدارهای کامپایلر را به خطا تبدیل می‌کند (یعنی \f(CW\*(C`\-Werror\*(C'\fR). از این گزینه در زمان توسعه، به خصوص هنگام ارسال وصله‌ها (patches) استفاده کنید. معمولاً نباید برای ساخت‌های نهایی یا توزیع استفاده شود.
.IP \fB\-\-with\-default\-backend=libvirt\fR 4
.IX Item "--with-default-backend=libvirt"
این گزینه روش پیش‌فرضی را کنترل می‌کند که libguestfs برای اجرای qemu استفاده می‌نماید (ببینید "BACKEND" در \fBguestfs\fR\|(3)). اگر مشخص نشود، بک‌اند پیش‌فرض \f(CW\*(C`direct\*(C'\fR است، به این معنی که libguestfs مستقیماً qemu را اجرا می‌کند.
.Sp
توزیع‌های Fedora و Red Hat Enterprise Linux (RHEL) نسخه ۷ به بعد از این فلگ برای تغییر بک‌اند پیش‌فرض به \f(CW\*(C`libvirt\*(C'\fR استفاده می‌کنند، زیرا (به‌ویژه در RHEL) خط‌مشی سیستمی این است که هیچ برنامه‌ای اجازه اجرای مستقیم qemu را جز از طریق libvirt ندارد.
.Sp
توجه داشته باشید که علیرغم این تنظیم، تمام بک‌اندها درون libguestfs کامپایل می‌شوند و شما می‌توانید در زمان اجرا با تنظیم متغیر محیطی \f(CW$LIBGUESTFS_BACKEND\fR (یا با روش‌های API) بک‌اند را لغو و بازنویسی کنید.
.IP \fB\-\-with\-distro=REDHAT|DEBIAN|...\fR 4
.IX Item "--with-distro=REDHAT|DEBIAN|..."
ابزار Libguestfs باید بداند کدام توزیع لینوکس در حال استفاده است تا بتواند نام بسته‌ها را برای اپلاینس به‌درستی انتخاب کند (برای مثال به \fIappliance/packagelist.in\fR مراجعه کنید). این کار به‌طور معمول به صورت خودکار انجام می‌شود.
.Sp
با این حال اگر در حال ساخت یا بسته‌بندی libguestfs روی توزیع جدیدی هستید، می‌توانید از \fI\-\-with\-distro\fR برای تعیین شباهت آن با توزیع موجود استفاده کنید (مثلاً \fI\-\-with\-distro=REDHAT\fR در صورتی که توزیع یک مشتق جدید از Red Hat یا CentOS باشد).
.Sp
توجه داشته باشید اگر توزیع شما کاملاً جدید باشد ممکن است همچنان نیازمند اعمال اصلاحاتی در بالادست (upstream) باشد.
.IP "\fB\-\-with\-extra=""\fR\fIdistroname\fR=\fIversion\fR,libvirt,...\fB""\fR" 4
.IX Item "--with-extra=""distroname=version,libvirt,..."""
.PD 0
.IP "\fB\-\-with\-extra=""local""\fR" 4
.IX Item "--with-extra=""local"""
.PD
این گزینه فیلد "extra" بازگردانده شده توسط "guestfs_version" در \fBguestfs\fR\|(3) را کنترل می‌کند که توسط گزینه \fI\-\-version\fR ابزارهای virt نیز چاپ می‌شود. این یک فیلد متنی آزاد است، اما ایده خوب این است که فهرستی از فکت‌های جداشده با کاما مانند نام و نسخه توزیع، اینکه آیا libvirt بک‌اند پیش‌فرض است یا خیر، و هر چیز دیگری را که ممکن است به رفع اشکال مشکلات مطرح‌شده توسط کاربران کمک کند، در آن رمزگذاری کنید.
.Sp
برای ساخت‌های سفارشی و/یا محلی، می‌توان این فیلد را روی \f(CW\*(C`local\*(C'\fR تنظیم کرد تا نشان دهد این یک ساخت رسمی توزیع نیست.
.IP \fB\-\-without\-libvirt\fR 4
.IX Item "--without-libvirt"
کامپایل libguestfs بدون پشتیبانی libvirt، حتی اگر کتابخانه‌های توسعه libvirt نصب باشند.
.IP "\fB\-\-with\-qemu=""\fRbin1 bin2 ...\fB""\fR" 4
.IX Item "--with-qemu=""bin1 bin2 ..."""
ارائه یک باینری جایگزین qemu (یا فهرستی از باینری‌ها). این گزینه را می‌توان در زمان اجرا با تنظیم متغیر محیطی \f(CW\*(C`LIBGUESTFS_HV\*(C'\fR لغو و بازنویسی کرد.
.IP \fB\-\-with\-supermin\-packager\-config=\fR\fIyum.conf\fR 4
.IX Item "--with-supermin-packager-config=yum.conf"
این گزینه \fI\-\-packager\-config\fR را به \fBsupermin\fR\|(1) ارسال می‌کند.
.Sp
رایج‌ترین کاربرد این گزینه ساخت اپلاینس با استفاده از مخزن جایگزین است (به جای استفاده از پیکربندی نصب‌شده yum/dnf/apt و غیره برای یافتن و دانلود بسته‌ها). اگر می‌خواهید libguestfs را بدون اتصال به اینترنت بسازید ممکن است به این گزینه نیاز داشته باشید. مثال‌هایی از این مورد در فایل \f(CW\*(C`libguestfs.spec\*(C'\fR فدورا یافت می‌شود (منابع را در "ساخت بسته برای فدورا" در زیر ببینید).
.IP "\fB\-\-with\-supermin\-extra\-options=""\fR\-\-opt1 \-\-opt2 ...\fB""\fR" 4
.IX Item "--with-supermin-extra-options=""--opt1 --opt2 ..."""
ارسال گزینه‌های اضافی به \fBsupermin\fR\|(1). برای درک دقیق عملکرد این گزینه به \fIappliance/make.sh.in\fR مراجعه کنید.
.IP \fBPYTHON\fR 4
.IX Item "PYTHON"
این متغیر محیطی را می‌توان طوری تنظیم کرد که به یک باینری پایتون اشاره کند (مثلاً \f(CW\*(C`python3\*(C'\fR). هنگامی که \f(CW\*(C`./configure\*(C'\fR اجرا می‌شود، این باینری پایتون را بررسی می‌کند تا نسخه پایتون، محل کتابخانه‌های پایتون و موارد مشابه را بیابد.
.IP \fBSUPERMIN\fR 4
.IX Item "SUPERMIN"
این متغیر محیطی می‌تواند برای انتخاب یک باینری جایگزین \fBsupermin\fR\|(1) تنظیم شود. به عنوان مثال اگر بخواهید از نسخه بالادستی جدیدتر supermin نسبت به نسخه بسته‌بندی‌شده برای توزیع خود استفاده کنید، یا اگر supermin اصلاً در توزیع شما بسته‌بندی نشده باشد، می‌توان از این متغیر استفاده کرد. در RHEL 7، هنگام کامپایل libguestfs باید متغیر \f(CW\*(C`SUPERMIN=/usr/bin/supermin5\*(C'\fR را تنظیم کنید.
.SH "نکاتی درباره QEMU و KVM (NOTES ABOUT QEMU AND KVM)"
.IX Header "NOTES ABOUT QEMU AND KVM"
یک مشکل رایج مربوط به انتشار نسخه‌های خراب یا ناسازگار qemu است.
.PP
نسخه‌های مختلف qemu به دلایل متفاوتی در بوت کردن اپلاینس با مشکل مواجه می‌شوند. این مسئله بین نسخه‌های مختلف qemu و توزیع‌های لینوکس که وصله‌های اختصاصی خود را اعمال می‌کنند متفاوت است.
.PP
اگر با مشکلی مواجه شدید، می‌توانید ساخت qemu از سورس را با یک "پوشش‌دهنده qemu" امتحان کنید (ساخت qemu از کد منبع بسیار ساده است). بخش "QEMU WRAPPERS" در \fBguestfs\fR\|(3) را ببینید.
.PP
به‌طور پیش‌فرض اسکریپت پیکربندی به دنبال qemu\-kvm (پشتیبانی KVM) خواهد گشت. شتاب‌دهنده KVM بسیار سریع‌تر از استفاده از qemu خام است.
.PP
همچنین ممکن است لازم باشد پشتیبانی KVM را برای کاربران غیر ریشه فعال کنید؛ با دنبال کردن این دستورالعمل‌ها:
http://www.linux\-kvm.org/page/FAQ#How_can_I_use_kvm_with_a_non\-privileged_user.3F
.PP
در برخی سیستم‌ها دستور زیر نیز کار خواهد کرد:
.PP
.Vb 1
\& chmod 0666 /dev/kvm
.Ve
.PP
در برخی سیستم‌ها دستور chmod پس از راه‌اندازی مجدد باقی نمی‌ماند و باید در پیکربندی udev تغییراتی ایجاد نمایید.
.SH "استفاده از CLANG (LLVM) به جای GCC (USING CLANG (LLVM) INSTEAD OF GCC)"
.IX Header "USING CLANG (LLVM) INSTEAD OF GCC"
.Vb 3
\& export CC=clang
\& ./configure
\& make
.Ve
.SH "استفاده از اپلاینس دودویی از پیش ساخته شده (USING A PREBUILT BINARY APPLIANCE)"
.IX Header "USING A PREBUILT BINARY APPLIANCE"
برای درک مفهوم اپلاینس در libguestfs، صفحه راهنمای \fBguestfs\-internals\fR\|(1) را مطالعه کنید.
.PP
اگر از سیستمی غیرلینوکسی استفاده می‌کنید، یا توزیع لینوکسی دارید که فاقد پشتیبانی از \fBsupermin\fR\|(1) است، یا صرفاً نمی‌خواهید اپلاینس libguestfs اختصاصی خود را بسازید، می‌توانید از یکی از اپلاینس‌های باینری از پیش ساخته‌شده‌ای که ما ارائه می‌دهیم استفاده کنید:
http://libguestfs.org/download/binaries/appliance
.PP
ابزار libguestfs را به این صورت بسازید:
.PP
.Vb 2
\& ./configure \-\-disable\-appliance \-\-disable\-daemon
\& make
.Ve
.PP
متغیر \f(CW$LIBGUESTFS_PATH\fR را روی مسیری که تاربال اپلاینس را در آن استخراج کرده‌اید تنظیم کنید؛ مانند:
.PP
.Vb 1
\& export LIBGUESTFS_PATH=/usr/local/lib/guestfs/appliance
.Ve
.PP
و برنامه‌های libguestfs و ابزارهای virt را به روش معمول، به عنوان مثال با استفاده از اسکریپت \fI./run\fR اجرا کنید (به بالا مراجعه فرمایید).
.SH "ساخت بسته برای فدورا (BUILDING A PACKAGE FOR FEDORA)"
.IX Header "BUILDING A PACKAGE FOR FEDORA"
فایل spec فدورا در نشانی زیر نگهداری می‌شود:
http://pkgs.fedoraproject.org/cgit/rpms/libguestfs.git
.PP
ابزار Libguestfs در فدورا با استفاده از سیستم ساخت استاندارد فدورا (Koji) ساخته می‌شود.
.SH "ساخت بسته برای RED HAT ENTERPRISE LINUX"
.IX Header "BUILDING A PACKAGE FOR RED HAT ENTERPRISE LINUX"
نسخه‌های Red Hat Enterprise Linux (RHEL) از libguestfs به شدت پچ شده‌اند. به طور کلی دو نوع وصله (پچ) اعمال می‌کنیم:
.IP \(bu 4
ما بسیاری از قابلیت‌هایی را که مایل به پشتیبانی از آن‌ها برای مشتریان RHEL نیستیم غیرفعال می‌کنیم. برای مثال، ویژگی "libguestfs live" غیرفعال شده است.
.IP \(bu 4
ما قابلیت‌های بالادست (upstream) را به این نسخه‌ها بک‌پورت (backport) می‌کنیم.
.PP
وصله‌هایی که به نسخه‌های انتشار RHEL اعمال می‌کنیم به صورت عمومی در مخزن گیت بالادست در شاخه‌ای به نام \f(CW\*(C`rhel\-x.y\*(C'\fR در دسترس هستند.
.PP
به عنوان مثال وصله‌های RHEL 7.3 در اینجا در دسترس هستند:
https://github.com/libguestfs/libguestfs/commits/rhel\-7.3
.PP
کدهای منبع و فایل‌های spec برای نسخه‌های RHEL از libguestfs در نشانی https://git.centos.org/project/rpms و همچنین https://wiki.centos.org/Sources در دسترس هستند.
.SH "همچنین ببینید (SEE ALSO)"
.IX Header "SEE ALSO"
\&\fBguestfs\fR\|(3),
\&\fBguestfs\-examples\fR\|(3),
\&\fBguestfs\-hacking\fR\|(1),
\&\fBguestfs\-internals\fR\|(1),
\&\fBguestfs\-performance\fR\|(1),
\&\fBguestfs\-release\-notes\fR\|(1),
\&\fBguestfs\-testing\fR\|(1),
\&\fBlibguestfs\-test\-tool\fR\|(1),
\&\fBlibguestfs\-make\-fixed\-appliance\fR\|(1),
http://libguestfs.org
.SH "نویسندگان (AUTHORS)"
.IX Header "AUTHORS"
Richard W.M. Jones (\f(CW\*(C`rjones at redhat dot com\*(C'\fR)
.SH "حق نشر (COPYRIGHT)"
.IX Header "COPYRIGHT"
Copyright (C) 2009\-2025 Red Hat Inc.
.SH "مجوز (LICENSE)"
.IX Header "LICENSE"
این کتابخانه نرم‌افزار آزاد است؛ شما می‌توانید آن را تحت شرایط مجوز عمومی کمتر گنو (LGPL) که توسط بنیاد نرم‌افزارهای آزاد منتشر شده است، چه نسخه 2 مجوز و چه (به دلخواه خود) هر نسخه بالاتر، بازتوزیع کرده و/یا تغییر دهید.
.PP
این کتابخانه به این امید توزیع شده است که مفید واقع شود، اما بدون هیچ‌گونه ضمانت؛ حتی بدون ضمانت ضمنی قابل فروش بودن یا مناسب بودن برای یک هدف خاص. برای جزئیات بیشتر به مجوز عمومی کمتر گنو مراجعه کنید.
.PP
شما باید یک نسخه از مجوز عمومی کمتر گنو را به همراه این کتابخانه دریافت کرده باشید؛ در غیر این صورت، به بنیاد نرم‌افزارهای آزاد به نشانی زیر نامه بنویسید:
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110\-1301 USA
.SH "اشکالات (BUGS)"
.IX Header "BUGS"
برای دریافت فهرست باگ‌های گزارش‌شده در رابطه با libguestfs، از این پیوند استفاده کنید:
https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
.PP
برای ارسال گزارش باگ جدید علیه libguestfs، از این پیوند استفاده کنید:
https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
.PP
هنگام گزارش باگ، لطفاً اطلاعات زیر را درج نمایید:
.IP \(bu 4
نسخه libguestfs.
.IP \(bu 4
محل دریافت libguestfs (برای مثال کدام توزیع لینوکس، کامپایل‌شده از کد منبع و غیره).
.IP \(bu 4
توصیف دقیق باگ و ارائه راهکاری برای بازتولید آن.
.IP \(bu 4
اجرای دستور \fBlibguestfs\-test\-tool\fR\|(1) و قرار دادن خروجی \fBکامل و دست‌نخورده\fR آن در گزارش باگ.