نام (NAME)

glib-genmarshal - ابزار تولید مارشالرهای سیگنال C برای رویدادهای GObject

خلاصه دستور (SYNOPSIS)

glib-genmarshal [OPTION…] [FILE…]

توضیحات (DESCRIPTION)

دستور glib-genmarshal یک ابزار کوچک است که مارشالرهای کد C را برای توابع بازخوانی (callback) سازوکار GClosure در زیرکتابخانه GObject از GLib تولید می‌کند. توابع مارشالر دارای امضای استاندارد هستند؛ کلوژر فراخواننده‌شده، آرایه‌ای از ساختارهای مقادیر شامل پارامترهای تابع بازخوانی، و یک ساختار مقدار برای مقدار بازگشتی تابع بازخوانی به آن‌ها منتقل می‌شود. سپس مارشالر مسئول فراخوانی تابع کد C متناظر کلوژر با تمام پارامترها در پشته و جمع‌آوری مقدار بازگشتی آن است.

ابزار glib-genmarshal فهرستی از مارشالرها را جهت تولید به عنوان ورودی دریافت می‌کند. این فهرست مارشالرها یا از فایل‌های ارائه‌شده به عنوان آرگومان‌های اضافی در خط فرمان خوانده می‌شود، یا از ورودی استاندارد با استفاده از - به عنوان فایل ورودی دریافت می‌گردد.

# this is a comment

RTYPE:PTYPE
RTYPE:PTYPE,PTYPE
RTYPE:PTYPE,PTYPE,PTYPE
…

گزینه‌ها (OPTIONS)

--header

--body

--prefix <PREFIX>

--skip-source

--stdinc

--nostdinc

--internal

-valist-marshallers

-v, --version

--g-fatal-warnings

-h, --help

--output <FILE>

--prototypes

--pragma-once

--include-header <HEADER>

-D <SYMBOL>[=<VALUE>]

-U <SYMBOL>

--quiet

--verbose

استفاده از GLIB-GENMARSHAL با MESON

سیستم ساخت Meson از تولید مارشالرهای کلوژر با استفاده از glib-genmarshal به‌طور توکار در ماژول gnome خود پشتیبانی می‌کند.

در فایل meson.build خود معمولاً متد gnome.genmarshal() را به همراه فهرست منابع مارشالرها جهت تولید فراخوانی می‌کنید:

gnome = import('gnome')
marshal_files = gnome.genmarshal('marshal',
  sources: 'marshal.list',
  internal: true,
)

متغیر marshal_files شامل آرایه‌ای از دو عنصر با ترتیب زیر خواهد بود:

باید از شیء‌های بازگردانده‌شده برای ایجاد وابستگی در هر هدف ساخت دیگری که به فایل منبع یا سرایند ارجاع دارد استفاده کنید؛ به عنوان مثال، اگر از منبع برای ساخت یک کتابخانه استفاده می‌کنید:

mainlib = library('project',
  sources: project_sources + marshal_files,
  …
)

علاوه بر این، اگر فایل سرایند تولیدشده را درون هدف ساختی قرار می‌دهید که به کتابخانه‌ای که به تازگی ساخته‌اید وابسته است، باید مطمئن شوید که وابستگی داخلی شامل سرایند تولیدشده به عنوان یک فایل منبع الزامی است:

mainlib_dep = declare_dependency(sources: marshal_files[1], link_with: mainlib)

نباید فایل منبع تولیدشده را نیز اضافه کنید، در غیر این صورت برای هر هدفی که به آن وابسته است به‌طور جداگانه ساخته می‌شود و باعث خطای ساخت خواهد شد. برای کسب اطلاعات بیشتر در مورد علت نیاز به همه این موارد، لطفاً به مدخل متناظر در سوالات متداول Meson مراجعه کنید: https://mesonbuild.com/FAQ.html#how-do-i-tell-meson-that-my-sources-use-generated-headers.

برای اطلاعات بیشتر در مورد نحوه استفاده از این متد، مستندات Meson را برای gnome.genmarshal() در https://mesonbuild.com/Gnome-module.html#gnomegenmarshal ببینید.

استفاده از GLIB-GENMARSHAL با AUTOTOOLS

به منظور استفاده از glib-genmarshal در پروژه خود هنگام استفاده از Autotools به عنوان سیستم ساخت، ابتدا باید فایل configure.ac خود را ویرایش کنید تا اطمینان حاصل شود دستور مناسب را با استفاده از pkg-config پیدا می‌کنید، مشابه روشی که فلگ‌های کامپایلر و پیونددهنده را برای GLib پیدا می‌کنید:

PKG_PROG_PKG_CONFIG([0.28])
PKG_CHECK_VAR([GLIB_GENMARSHAL], [glib-2.0], [glib_genmarshal])

در فایل Makefile.am خود معمولاً به قواعد بسیار ساده‌ای برای تولید فایل‌های C مورد نیاز جهت ساخت احتیاج خواهید داشت:

marshal.h: marshal.list
        $(AM_V_GEN)$(GLIB_GENMARSHAL) \
                --header \
                --output=$@ \
                $<
marshal.c: marshal.list marshal.h
        $(AM_V_GEN)$(GLIB_GENMARSHAL) \
                --include-header=marshal.h \
                --body \
                --output=$@ \
                $<
BUILT_SOURCES += marshal.h marshal.c
CLEANFILES += marshal.h marshal.c
EXTRA_DIST += marshal.list

در مثال بالا، قاعده اول فایل سرایند را تولید می‌کند و به یک فایل marshal.list وابسته است تا در صورت به‌روزرسانی فهرست مارشالرها، نتیجه مجدداً تولید شود. قاعده دوم فایل منبع را برای همان marshal.list تولید می‌کند و شامل فایل تولیدشده توسط قاعده سرایند می‌شود.

مثال‌ها (EXAMPLES)

برای تولید مارشالرها برای توابع بازخوانی زیر:

void   foo (gpointer data1,
            gpointer data2);
void   bar (gpointer data1,
            gint     param1,
            gpointer data2);
gfloat baz (gpointer data1,
            gboolean param1,
            guchar   param2,
            gpointer data2);

فایل marshaller.list باید به این شکل باشد:

VOID:VOID
VOID:INT
FLOAT:BOOLEAN,UCHAR

و glib-genmarshal را به این صورت فراخوانی می‌کنید:

glib-genmarshal --header marshaller.list > marshaller.h
glib-genmarshal --body marshaller.list > marshaller.c

مارشالرهای تولیدشده آرگومان‌ها را در نام تابع خود کدگذاری کرده‌اند. برای این فهرست خاص، آن‌ها عبارتند از:

g_cclosure_user_marshal_VOID__VOID(...),
g_cclosure_user_marshal_VOID__INT(...),
g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR(...).

آن‌ها می‌توانند مستقیماً برای GClosures استفاده شوند یا به عنوان آرگومان GSignalCMarshaller c_marshaller هنگام ایجاد سیگنال‌ها ارسال گردند:

GClosure *cc_foo, *cc_bar, *cc_baz;
cc_foo = g_cclosure_new (NULL, foo, NULL);
g_closure_set_marshal (cc_foo, g_cclosure_user_marshal_VOID__VOID);
cc_bar = g_cclosure_new (NULL, bar, NULL);
g_closure_set_marshal (cc_bar, g_cclosure_user_marshal_VOID__INT);
cc_baz = g_cclosure_new (NULL, baz, NULL);
g_closure_set_marshal (cc_baz, g_cclosure_user_marshal_FLOAT__BOOLEAN_UCHAR);

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

glib-mkenums(1) <man:glib-mkenums(1)>