نام (NAME)

glib-mkenums - ابزار استخراج توضیحات شمارشی C و تولید تعاریف GType

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

glib-mkenums [OPTION…] [FILE…]

توضیحات (DESCRIPTION)

دستور glib-mkenums ابزار کوچکی است که کدهای C را برای استخراج تعاریف enum تجزیه کرده و بر اساس الگوهای متنی مشخص‌شده توسط کاربر، توصیف‌های enum را تولید می‌کند. به طور معمول، می‌توانید از این ابزار برای تولید انواع شمارشی برای سیستم نوع GType، ویژگی‌های GObject و مرتب‌سازی سیگنال‌ها (signal marshalling) استفاده کنید؛ علاوه بر این، می‌توانید از آن برای تولید مقادیر شمارشی طرح‌واره‌های GSettings بهره ببرید.

دستور glib-mkenums فهرستی از پرونده‌های معتبر کد C را به عنوان ورودی دریافت می‌کند. گزینه‌های مشخص‌شده متن تولیدشده را کنترل کرده و کلیدواژه‌های گوناگون محصور در نویسه‌های @ را در الگوها جایگزین می‌نمایند.

از نسخهٔ 2.74، کتابخانهٔ GLib ماکروهای پیش‌پردازندهٔ C با نام‌های G_DEFINE_ENUM_TYPE و G_DEFINE_FLAGS_TYPE را ارائه می‌دهد. این ماکروها می‌توانند برای تعریف یک GType در پروژه‌هایی که دارای تعداد اندکی از انواع شمارشی کوچک هستند، بدون نیاز به درگیر شدن با پیچیدگی‌های تولید کد در زمان ساخت (build time)، به کار روند.

typedef enum
{
  PREFIX_THE_XVALUE    = 1 << 3,
  PREFIX_ANOTHER_VALUE = 1 << 4
} PrefixTheXEnum;

typedef enum /*< skip >*/
{
  PREFIX_FOO
} PrefixThisEnumWillBeSkipped;
typedef enum /*< flags,prefix=PREFIX,since=1.0 >*/
{
  PREFIX_THE_ZEROTH_VALUE,   /*< skip >*/
  PREFIX_THE_FIRST_VALUE,
  PREFIX_THE_SECOND_VALUE,
  PREFIX_THE_THIRD_VALUE,    /*< nick=the-last-value >*/
} PrefixTheFlagsEnum;

گزینه‌ها (OPTIONS)

--fhead <TEXT>

--fprod <TEXT>

--ftail <TEXT>

--eprod <TEXT>

--vhead <TEXT>

--vprod <TEXT>

--vtail <TEXT>

--comments <TEXT>

--template <FILE>

/*** BEGIN section ***/
/*** END section ***/

--identifier-prefix <PREFIX>

--symbol-prefix <PREFIX>

--help

--version

--output <FILE>

@RSPFILE

استفاده از قالب‌ها (USING TEMPLATES)

به جای ارسال بخش‌های گوناگون پروندهٔ تولیدشده به خط فرمان glib-mkenums، قویاً توصیه می‌شود که از یک پروندهٔ قالب استفاده کنید، به‌ویژه برای تولید کدهای منبع C.

یک پروندهٔ قالب سرایند (header) C معمولاً به این صورت خواهد بود:

/*** BEGIN file-header ***/
#pragma once
/* Include the main project header */
#include "project.h"
G_BEGIN_DECLS
/*** END file-header ***/
/*** BEGIN file-production ***/
/* enumerations from "@basename@" */
/*** END file-production ***/
/*** BEGIN value-header ***/
GType @enum_name@_get_type (void);
#define @ENUMPREFIX@_TYPE_@ENUMSHORT@ (@enum_name@_get_type ())
/*** END value-header ***/
/*** BEGIN file-tail ***/
G_END_DECLS
/*** END file-tail ***/

یک پروندهٔ قالب منبع C معمولاً به این صورت خواهد بود:

/*** BEGIN file-header ***/
#include "config.h"
#include "enum-types.h"
/*** END file-header ***/
/*** BEGIN file-production ***/
/* enumerations from "@basename@" */
/*** END file-production ***/
/*** BEGIN value-header ***/
GType
@enum_name@_get_type (void)
{
  static GType static_g_@type@_type_id = 0;
  if (g_once_init_enter_pointer (&static_g_@type@_type_id))
    {
      static const G@Type@Value values[] = {
/*** END value-header ***/
/*** BEGIN value-production ***/
        { @VALUENAME@, "@VALUENAME@", "@valuenick@" },
/*** END value-production ***/
/*** BEGIN value-tail ***/
        { 0, NULL, NULL }
      };
      GType g_@type@_type_id =
        g_@type@_register_static (g_intern_static_string ("@EnumName@"), values);
      g_once_init_leave_pointer (&static_g_@type@_type_id, g_@type@_type_id);
    }
  return static_g_@type@_type_id;
}
/*** END value-tail ***/

پرونده‌های قالب برای ویرایش و به‌روزرسانی آسان‌تر هستند، و می‌توان از آن‌ها برای تولید انواع مختلف خروجی با استفاده از همان خط فرمان یا ابزارها در طول فرایند ساخت استفاده کرد.

استفاده از GLIB-MKENUMS همراه با MESON (USING GLIB-MKENUMS WITH MESON)

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

در پروندهٔ meson.build خود، معمولاً متد gnome.mkenums_simple() را برای تولید انواع شمارشی استاندارد از فهرستی از هدرهای مورد بررسی فراخوانی خواهید کرد:

project_headers = [
  'project-foo.h',
  'project-bar.h',
  'project-baz.h',
]
gnome = import('gnome')
enum_files = gnome.mkenums_simple('enum-types',
  sources: project_headers,
)

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

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

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

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

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

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

اگر در حال تولید پرونده‌های هدر و منبع C هستید که به الگوهای خاصی نیاز دارند، می‌توانید از gnome.mkenums() برای ارائهٔ آن هدرها استفاده کنید؛ برای نمونه:

enum_files = gnome.mkenums('enum-types',
  sources: project_headers,
  h_template: 'enum-types.h.in',
  c_template: 'enum-types.c.in',
  install_header: true,
)

برای اطلاعات بیشتر، به مستندات Meson در https://mesonbuild.com/Gnome-module.html#gnomegenmarshal برای gnome.mkenums() مراجعه کنید.

استفاده از GLIB-MKENUMS همراه با AUTOTOOLS (USING GLIB-MKENUMS WITH AUTOTOOLS)

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

PKG_PROG_PKG_CONFIG([0.28])
PKG_CHECK_VAR([GLIB_MKENUMS], [glib-2.0], [glib_mkenums])

در پروندهٔ Makefile.am خود، معمولاً از قواعدی مانند این استفاده خواهید کرد:

# A list of headers to inspect
project_headers = \
        project-foo.h \
        project-bar.h \
        project-baz.h
enum-types.h: $(project_headers) enum-types.h.in
        $(AM_V_GEN)$(GLIB_MKENUMS) \
                --template=enum-types.h.in \
                --output=$@ \
               $(project_headers)
enum-types.c: $(project_headers) enum-types.c.in enum-types.h
        $(AM_V_GEN)$(GLIB_MKENUMS) \
                --template=enum-types.c.in \
                --output=$@ \
                $(project_headers)
# Build the enum types files before every other target
BUILT_SOURCES += enum-types.h enum-types.c
CLEANFILES += enum-types.h enum-types.c
EXTRA_DIST += enum-types.h.in enum-types.c.in

در مثال بالا، متغیری به نام project_headers داریم که در آن به تمام پرونده‌های هدری که می‌خواهیم برای تولید GTypeهای شمارشی بررسی شوند ارجاع می‌دهیم. در قاعدهٔ enum-types.h از glib-mkenums با الگویی به نام enum-types.h.in برای تولید پروندهٔ هدر استفاده می‌کنیم؛ به طور مشابه، در قاعدهٔ enum-types.c از الگویی به نام enum-types.c.in استفاده می‌کنیم.

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

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