Kullanım
h2xs [SEÇENEKLER ...] [başlıkdosyası ... [ek_kütüphaneler]]
h2xs -h|-?|--help
Açıklama
h2xs, C başlık dosyalarından bir Perl uzantısı oluşturur. Uzantı, C başlık dosyalarında bulunan herhangi bir #define ifadesinin değerini almak için kullanılabilecek işlevleri içerecektir.
Uzantının adı olarak modül_adı (module_name) kullanılacaktır. Eğer modül_adı belirtilmezse, ilk karakteri büyük harf yapılarak ilk başlık dosyasının adı kullanılır.
Uzantının ek kütüphanelere ihtiyacı olabilecekse, bunlar burada belirtilmelidir. Uzantı içindeki Makefile.PL, kütüphanelerin gerçekten var olup olmadığını ve nasıl yüklenmeleri gerektiğini kontrol etme işini üstlenecektir. Ek kütüphaneler, tıpkı cc komut satırında olduğu gibi -lm -lposix vb. şeklinde belirtilmelidir. Varsayılan olarak Makefile.PL, Configure tarafından belirlenen kütüphane yolunu arayacaktır. Bu yol, ek-kütüphaneler argümanına -L/başka/bir/kütüphane/yolu biçiminde argümanlar eklenerek genişletilebilir.
Adına rağmen h2xs, iskelet halindeki saf bir Perl modülü oluşturmak için de kullanılabilir. -X seçeneğine bakın.
Seçenekler
-A, --omit-autoload Tüm otomatik yükleme (autoload) olanaklarını devre dışı bırakır. Bu seçenek -c ile aynıdır ancak aynı zamanda .pm dosyasından "use AutoLoader" ifadesini de kaldırır.
-B, --beta-version Alpha/beta tarzı bir sürüm numarası kullanır. -v belirtilmedikçe sürüm numarasının "0.00_01" olmasına neden olur.
-C, --omit-changes Changes dosyasının oluşturulmasını atlar ve POD şablonuna bir HISTORY bölümü ekler.
-F, --cpp-flags=ek_bayraklar İşlev bildirimleri için başlık dosyası taranırken C önişlemcisine (preprocessor) belirtilecek ek bayraklar. Bu seçenekleri oluşturulan Makefile.PL dosyasına da yazar.
-M, --func-mask=düzenli_ifade İşlenecek işlevleri/makroları seçer.
-O, --overwrite-ok Önceden var olan bir uzantı dizininin üzerine yazılmasına izin verir.
-P, --omit-pod Otomatik oluşturulan taslak POD bölümünü atlar.
-X, --omit-XS XS bölümünü atlar. İskelet halinde saf bir Perl modülü oluşturmak için kullanılır. "-c" ve "-f" seçenekleri örtülü olarak etkinleştirilir.
-a, --gen-accessors Yapıların (structs) ve birliklerin (unions) her bir öğesi için bir erişimci (accessor) yöntemi oluşturur. Oluşturulan yöntemler öğe adıyla adlandırılır; ek argümanlar olmadan çağrılırsa öğenin geçerli değerini döndürür; ek bir argümanla çağrılırsa öğeyi sağlanan değere ayarlar (ve yeni değeri döndürür). İç içe geçmiş yapılar ve birlikler, zincirleme çağrıları kolaylaştırmak için tam yapı yerine bir işaretçi olarak döndürülür.
Bu yöntemlerin tümü yapının Ptr türü için geçerlidir; ek olarak yapı türünün kendisi için iki yöntem oluşturulur: aynı yapıya işaret eden bir Ptr türü döndüren "_to_ptr" ve sıfırlarla başlatılmış yeni bir yapı oluşturup döndüren bir "new" yöntemi.
-b, --compat-version=sürüm Belirtilen perl sürümüyle geriye dönük uyumlu bir .pm dosyası oluşturur.
5.6.0'dan önceki sürümler için değişiklikler şunlardır:
- 'our' kullanılmaz (bunun yerine 'use vars' kullanılır)
- 'use warnings' kullanılmaz
h2xs'i çalıştırmak için kullandığınız perl sürümünden daha yüksek bir uyumluluk sürümü belirtmenin hiçbir etkisi olmayacaktır. Belirtilmezse h2xs, varsayılan olarak h2xs'i çalıştırmak için kullandığınız perl sürümüyle uyumlu olacaktır.
-c, --omit-constant .xs dosyasından "constant()" işlevini ve .pm dosyasından buna karşılık gelen özel "AUTOLOAD" işlevini çıkarır.
-d, --debugging Hata ayıklama mesajlarını etkinleştirir.
-e, --omit-enums=[düzenli_ifade] Düzenli ifade verilmezse, bir C numaralandırmasında (enumeration) tanımlanan tüm sabitleri atlar. Aksi takdirde, yalnızca adı düzenli ifade ile eşleşen bir enum içinde tanımlanan sabitleri atlar.
Düzenli ifade isteğe bağlı olduğundan, düzenli ifadeyi atlarsanız ve başlık dosyası adları gibi bekleyen bazı argümanlarınız varsa, bu seçeneğin ardından en az bir başka seçeneğin geldiğinden emin olun. Bu kullanım uygundur:
h2xs -e -n Module::Foo foo.h
Bu kullanım uygun değildir:
h2xs -n Module::Foo -e foo.h
İkinci kullanımda foo.h, düzenli ifade olarak kabul edilir.
-f, --force Standart include dizinlerinde bulunmasa bile bir başlık dosyası için uzantı oluşturulmasına izin verir.
-g, --global Statik verileri .xs dosyasında güvenli bir şekilde depolamak için kod içerir. Statik veri kullanmayan uzantılar bu seçeneği yoksayabilir.
-h, -?, --help Bu h2xs sürümü için kullanımı, yardımı ve sürüm bilgisini yazdırır ve çıkar.
-k, --omit-const-func "const" olarak bildirilen işlev argümanları için, üretilen XS kodunda const özniteliğini atlar.
-m, --gen-tied-var Deneysel: Başlık dosyasında (dosyalarında) bildirilen her değişken için, C değişkenine sihirli bir şekilde bağlanmış aynı isimde bir perl değişkeni bildirir.
-n, --name=modül_adı Uzantı için kullanılacak adı belirtir, örneğin -n RPC::DCE
-o, --opaque-re=düzenli_ifade Düzenli ifade ile eşleşen C türleri için, bu türler typemap'lerdeki türlerle "typedef" eşdeğeri olsa bile "opaque" (opak) veri türü kullanır. -x olmadan kullanılmamalıdır.
Bu seçenek yararlı olabilir, çünkü örneğin tamsayılarla "typedef" eşdeğeri olan türler işletim sistemiyle ilgili tanıtıcıları (handles) temsil edebilir ve kişi bu tanıtıcılarla nesne yönelimli bir şekilde, "$handle->do_something()" gibi çalışmak isteyebilir. Tüm "typedef"li türleri opak türler olarak ele almak istiyorsanız "-o ." seçeneğini kullanın.
Eşleştirilecek tür temizlenir (virgüller hariç, önlerinde boşluk kalmaz ve aralarında boşluk olmayan birden fazla "*" işaretçisi hariç).
-p, --remove-prefix=önek Perl işlev adlarından kaldırılması gereken bir önek belirtir, örneğin -p sec_rgy_ Bu, XS PREFIX anahtar kelimesini ayarlar ve "constant()" mekanizması aracılığıyla otomatik yüklenen işlevlerden öneki kaldırır.
-s, --const-subs=alt_prog1,alt_prog2 constant() alt programı ile otomatik yükleme yapmak yerine, belirtilen makrolar için bir perl alt programı oluşturur. Bu makroların dönüş türünün char * olduğu varsayılır, örneğin -s sec_rgy_wildcard_name,sec_rgy_wildcard_sid.
-t, --default-type=tür constant() mekanizmasının makrolar için kullandığı dahili türü belirtir. Varsayılan değer IV'tür (işaretli tamsayı). Şu anda başlık tarama işlemi sırasında bulunan tüm makroların bu türe sahip olduğu varsayılacaktır. "h2xs"in gelecekteki sürümleri bu konuda mantıklı tahminler yapma yeteneği kazanabilir.
--use-new-tests --compat-version (-b) mevcut olduğunda, oluşturulan testler 5.6.2'den önceki sürümler için varsayılan olan "Test" yerine "Test::More" kütüphanesini kullanacaktır. "Test::More", oluşturulan "Makefile.PL" içindeki PREREQ_PM bölümüne eklenecektir.
--use-old-tests Daha eski "Test" modülünü kullanan test kodlarının oluşturulmasını zorunlu kılar.
--skip-exporter "Exporter" modülünü kullanmaz ve/veya herhangi bir sembolü dışa aktarmaz (export).
--skip-ppport "Devel::PPPort" modülünü kullanmaz: eski sürümlere taşınabilirlik sağlanmaz.
--skip-autoloader "AutoLoader" modülünü kullanmaz; ancak sabitler için constant() işlevini ve "sub AUTOLOAD" yapısını korur.
--skip-strict "strict" pragma'sını kullanmaz.
--skip-warnings "warnings" pragma'sını kullanmaz.
-v, --version=sürüm Bu uzantı için bir sürüm numarası belirtir. Bu sürüm numarası şablonlara eklenir. Varsayılan değer 0.01'dir veya "-B" belirtilmişse 0.00_01'dir. Belirtilen sürüm sayısal olmalıdır.
-x, --autogen-xsubs Başlık dosyasındaki işlev bildirimlerine dayanarak otomatik olarak XSUB'lar oluşturur. "C::Scan" paketinin kurulu olması gerekir. Bu seçenek belirtilirse, başlık dosyasının adı "AD1,AD2" gibi görünebilir. Bu durumda belirtilen dize yerine AD1 kullanılır, ancak XSUB'lar yalnızca AD2 dosyasından dahil edilen bildirimler için üretilir.
İşlevler için bazı argüman/dönüş değeri türlerinin, elle düzenleme gerektiren XSUB bildirimlerine/typemap girişlerine neden olabileceğini unutmayın. Bunlar bir işaretçiye dönüştürülemeyen nesneler (örneğin "long long"), işlev işaretçileri veya diziler olabilir. Ayrıca "-x Seçeneğinin Sınırları" bölümüne bakın.
Örnekler
# Varsayılan davranış, uzantı adı Rusers olur
h2xs rpcsvc/rusers
# Aynı işlem, ancak uzantı adı RUSERS olur
h2xs -n RUSERS rpcsvc/rusers
# Uzantı adı rpcsvc::rusers olur. Yine de <rpcsvc/rusers.h> dosyasını bulur
h2xs rpcsvc::rusers
# Uzantı adı ONC::RPC olur. Yine de <rpcsvc/rusers.h> dosyasını bulur
h2xs -n ONC::RPC rpcsvc/rusers
# constant() veya AUTOLOAD olmadan
h2xs -c rpcsvc/rusers
# RPC adında bir uzantı için şablonlar oluşturur
h2xs -cfn RPC
# Uzantı adı ONC::RPC olur.
h2xs -cfn ONC::RPC
# Uzantı, XS kodu içermeyen saf bir Perl modülüdür.
h2xs -X My::Module
# En az Perl5.005_03 ile çalışan Lib::Foo uzantısı oluşturulur.
# foo.h içinde h2xs'in bulabildiği tüm #define'lar ve enum'lar için sabitler oluşturulur.
h2xs -b 5.5.3 -n Lib::Foo foo.h
# En az Perl5.005_03 ile çalışan Lib::Foo uzantısı oluşturulur.
# Tüm #define'lar için sabitler oluşturulur, ancak yalnızca adları
# 'bar_' ile başlamayan enum'lar için sabit oluşturulur.
h2xs -b 5.5.3 -e '^bar_' -n Lib::Foo foo.h
# Makefile.PL, ek dizin olan /opt/net/lib altında
# -lrpc kütüphanesini arayacaktır
h2xs rpcsvc/rusers -L/opt/net/lib -lrpc
# Uzantı adı DCE::rgynbase olur
# "sec_rgy_" öneki perl işlev adlarından kaldırılır
h2xs -n DCE::rgynbase -p sec_rgy_ dce/rgynbase
# Uzantı adı DCE::rgynbase olur
# "sec_rgy_" öneki perl işlev adlarından kaldırılır
# sec_rgy_wildcard_name ve sec_rgy_wildcard_sid için
# alt programlar (subroutines) oluşturulur
h2xs -n DCE::rgynbase -p sec_rgy_ \
-s sec_rgy_wildcard_name,sec_rgy_wildcard_sid dce/rgynbase
# perl.h içindeki define'lar olmadan, ancak perl.h dosyasından görünen
# işlev bildirimleri ile XS oluşturur. Uzantının adı perl1'dir.
# perl.h taranırken -DEXT=extern -DdEXT= -DINIT(x)= tanımlanır.
# Dize kabuğa (shell) aktarıldığı için aşağıda ek ters eğik çizgiler vardır.
# Perl başlık dosyalarını içeren bir dizinin include yoluna otomatik olarak
# ekleneceğini unutmayın.
h2xs -xAn perl1 -F "-DEXT=extern -DdEXT= -DINIT\(x\)=" perl.h
# perl.h dosyasından göründüğü şekliyle proto.h içindeki işlev bildirimleri ile aynı işlem.
h2xs -xAn perl2 perl.h,proto.h
# Aynı işlem, ancak yalnızca /^av_/ ile eşleşen işlevleri seçer
h2xs -M '^av_' -xAn perl2 perl.h,proto.h
# Aynı işlem, ancak SV* vb. yapıları "opaque" (opak) türler olarak ele alır
h2xs -o '^[S]V \*$' -M '^av_' -xAn perl2 perl.h,proto.h
.h ve .c Dosyalarına Dayalı Uzantı
Bazı işlevleri gerçekleştiren C dosyalarınız ve bunlara karşılık gelen
başlık dosyalarınız olduğunu varsayalım. Bu işlevselliği Perl'de erişilebilir
kılan bir uzantıyı nasıl oluşturursunuz? Aşağıdaki örnek, başlık dosyalarının
interface_simple.h ve interface_hairy.h olduğunu ve perl modülünüzün adının
"Ext::Ension" olmasını istediğinizi varsayar. Bazı önişlemci yönergelerine ve/veye
harici kütüphanelerle bağlamaya (linking) ihtiyacınız varsa, "SEÇENEKLER" bölümündeki
"-F", "-L" ve "-l" bayraklarına bakın.
Dizin adını bulun
h2xs'in deneme amaçlı bir çalıştırılmasıyla başlayın:
h2xs -Afn Ext::Ension
Bu adımın tek amacı gerekli dizinleri oluşturmak ve size bu dizinlerin
adlarını bildirmektir. Çıktıdan uzantı dizininin Ext/Ension olduğunu
görebilirsiniz.
C dosyalarını kopyalayın
Başlık dosyalarınızı ve C dosyalarınızı Ext/Ension dizinine kopyalayın.
Uzantıyı oluşturun
Eski otomatik oluşturulmuş dosyaların üzerine yazarak h2xs'i çalıştırın:
h2xs -Oxan Ext::Ension interface_simple.h interface_hairy.h
h2xs, uzantı dizinine geçiş yaptıktan sonra başlık dosyalarını arar,
bu nedenle başlık dosyalarınızı sorunsuz bir şekilde bulacaktır.
Arşivleyin ve test edin
Her zamanki gibi çalıştırın:
cd Ext/Ension
perl Makefile.PL
make dist
make
make test
İpuçları
"make dist" işlemini mümkün olduğunca erken yapmak önemlidir. Bu şekilde,
".h" dosyalarınızı düzenlemeye karar verirseniz ve h2xs'i tekrar çalıştırırsanız,
otomatik oluşturulan dosyalardaki değişikliklerinizi kolayca birleştirebilirsiniz (merge(1)).
Üretilen .pm dosyasındaki belgeleri düzenlemeyi unutmayın.
Otomatik oluşturulan dosyaları yalnızca iskelet olarak görün; h2xs'in tahmin
edebileceğinden daha iyi arayüzler tasarlayabilirsiniz.
Bu bölümü yalnızca bir kılavuz olarak kabul edin; h2xs'in diğer bazı seçenekleri
ihtiyaçlarınıza daha iyi uyabilir.
Ortam
Hiçbir ortam değişkeni kullanılmaz.
Yazar
Larry Wall ve diğerleri
Ayrıca Bakınız
perl, perlxstut, ExtUtils::MakeMaker ve AutoLoader.
Teşhisler
İlgili dosyalar okunamadığında veya yazılamadığında verilen genel uyarılar.
-x Seçeneğinin Sınırları h2xs, bir C işlevine gönderilen ve örneğin "int *" biçiminde olan bir argümanın girdi (input) mi, çıktı (output) mu, yoksa girdi/çıktı (input/output) parametresi mi olduğunu ayırt edemez. Özellikle, aşağıdaki biçimdeki argüman bildirimleri:
int foo(n) int *n
eğer "n" bir girdi parametresiyse, şu şekilde yeniden yazılmalıdır:
int foo(n) int &n
Ek olarak, h2xs'in bir işlevin:
int foo(addr,l) char *addr int l
bu adresteki verinin adresini ve uzunluğunu çift olarak aldığını sezme yeteneği yoktur, bu nedenle bu işlevi şu şekilde yeniden yazmak daha iyidir:
int foo(sv) SV *addr PREINIT: STRLEN len; char *s; CODE: s = SvPV(sv,len); RETVAL = foo(s, len); OUTPUT: RETVAL
veya alternatif olarak:
static int my_foo(SV *sv) { STRLEN len; char *s = SvPV(sv,len);
return foo(s, len); }
MODULE = foo PACKAGE = foo PREFIX = my_
int foo(sv) SV *sv
Ek ayrıntılar için perlxs ve perlxstut dokümanlarına bakın.
perl v5.34.1 2026-02-21 H2XS(1)