18.2 PECL_Gen · phpbook-PHP擴展開發及內核應用

# 18.2 PECL\_Gen # PECL\_Gen 還有一種更加完善但也更加復雜的代碼生成器: PECL\_Gen, 可以在PECL(http:// pecl.php.net)中找到它, 使用pear install PECL\_Gen命令可以安裝它. ``` ?譯者注: PECL_Gen已經遷移為CodeGen_PECL(http://pear.php.net/package/ CodeGen_PECL). 本章涉及代碼測試使用CodeGen_PECL的版本信息為: "php 1.1.3, Copyright (c) 2003-2006 Hartmut Holzgraefe", 如果您的環境使用有問題, 請參考譯序中譯者的環境配置. ``` ?旦安裝完成, 它就可以像ext\_skel一樣運行, 接受相同的輸入參數, 產生大致相同的輸出, 或者如果提供了一個完整的xml定義文件, 則產生一個更加健壯和完整可編譯版本的擴展. PECL\_Gen并不會節省你編寫擴展核心功能的時間; 而是提供?種可選的方式高效的生成擴展骨架代碼. #### specfile.xml 下面是最簡單的擴展定義文件: ``` <?xml version="1.0" encoding="utf-8" ?> <extension name="sample9"> <functions> <function name="sample9_hello_world" role="public"> <![CDATA[php_printf("Hello World!");]]> </function> </functions></extension>譯注: 請注意, 譯者使用的原著中第一行少了后面的問號, 導致不能使用, 加上就OK. ``` 通過PECL\_Gen命令運行這個文件: ``` jdoe@devbox:/home/jdoe/cvs/php-src/ext/$ pecl-gen specfile.xml ``` 則會產生一個名為sample9的擴展, 并暴露一個用戶空間函數sample9\_hello\_world(). #### 關于擴展除了你已經熟悉的功能文件, PECL\_Gen還會產生?個package.xml文件它可以用于 pear安裝. 如果你計劃發布包到PECL庫, 或者哪怕你只是想要使用pear包系統交付內容, 有這個文件都會很有用. 總之, 你可以在PECL\_Gen的specfile.xml中指定多數package.xml文件的元素. ``` <?xml version="1.0" encoding="UTF-8" ?> <extension name="sample9"> <summary>Extension 9 generated by PECL_Gen</summary> <description>Another sample of PHP Extension Writing</description> <maintainers> <maintainer> <name>John D. Bookreader</name> <email>jdb@example.com</email> <role>lead</role> </maintainer> </maintainers> <release> <version>0.1</version> <date>2006-01-01</date> <state>beta</state> <notes>Initial Release</notes> </release> ... </extension> ``` 當PECL\_Gen創建擴展時, 這些信息將被翻譯到最終的package.xml文件中. 依賴 #### 依賴如你在第17章"配置和鏈接"中所見, 依賴可以掃描出來用于config.m4和config.w32文件. PECL\_Gen可以使用定義各種類型的依賴完成掃描工作. 默認情況下, 列在標簽下的依賴會同時應用到Unix和win32構建中, 除非顯式的是否用platform屬性指定某個目標 ``` <?xml version="1.0" encoding="UTF-8" ?> <extension name="sample9"> ... <deps platform="unix"> <! UNIX specific dependencies > </deps> <deps platform="win32"> <! Win32 specific dependencies > </deps> <deps platform="all"> <! Dependencies that apply to all platforms > </deps> ... </extension> ``` #### with 通常, 擴展在配置時使用--enable-extname樣式的配置選項. 通過增加?個或多個標簽到塊中, 則不僅配置選項被修改為--with-extname, 而且同時需要掃描頭文件: ``` <deps platform="unix"> <with defaults="/usr:/usr/local:/opt" testfile="include/zlib/zlib.h">zlib headers</with> </deps> ``` #### 庫必須的庫也列在下, 使用標簽. ``` <deps platform="all"> <lib name="ssleay" platform="win32"/> <lib name="crypto" platform="unix"/> <lib name="z" platform="unix" function="inflate"/> </deps> ``` 在前面兩個例子中, 只是檢查了庫是否存在; 第三個例子中, 庫將被真實的加載并掃描以確認inflate()函數是否定義. ?盡管標簽實際已經命名了目標平臺, 但標簽也有?個platform屬性可以覆蓋標簽的platform設置. 當它們混合使用的時候要格外小心. #### 此外, 需要包含的文件也可以通過在塊中使用標簽在你的代碼中追加?個#include指令列表. 要強制某個頭先包含, 可以在標簽上增加屬性 prepend="yes". 和依賴類似, 也可以嚴格限制平臺: ``` <deps> <header name="sys/types.h" platform="unix" prepend="yes"/> <header name="zlib/zlib.h"/> </deps> 譯注: 經測試, 譯者的環境<header>標簽不支持platform屬性. ``` #### 常量用戶空間常量使用塊中的一個或多個標簽定義. 每個標簽需要一個name和?個value屬性, 以及?個值必須是int, float, string之一的type屬性. ``` <constants> <constant name="SAMPLE9_APINO" type="int" value="20060101"/> <constant name="SAMPLE9_VERSION" type="float" value="1.0"/> <constant name="SAMPLE9_AUTHOR" type="string" value="John Doe"/> </constants> ``` #### 全局變量線程安全全局變量的定義方式幾乎相同. 唯?的不同在于type參數需要使用C語言原型而不是php用戶空間描述. ?旦定義并構建, 全局變量就可以使用第12章"啟動, 終止, 以及其中的?些點"中學習的EXTNAME\_G(global\_name)的宏用法進行訪問. 在這里, value屬性表示變量在請求啟動時的默認值. 要注意在specfile.xml中這個默認值只能指定為簡單的標量數值. 字符串和其他復雜結構應該在RINIT階段手動設置. ``` ?<globals> <global name="greeting" type="char *"/> <global name="greeting_was_issued" type="zend_bool" value="1"/> </globals> ``` #### INI選項要綁定線程安全的全局變量到php.ini設置, 則需要使用標簽而不是. 這個標簽需要兩個額外的參數: onupdate="updatemethod"標識INI的修改應該怎樣處理, access="mode"和第13章"INI設置"中介紹的模式含義相同, "mode"值可以是: all, user, perdir, system. ``` ??<globals> <phpini name="mysetting" type="int" value="42" onupdate="OnUpdateLong" access="all"/> </globals> ``` #### 函數你已經看到了最基本的函數定義; 不過, 標簽在PECL\_Gen的specfile中實際上支持兩種不同類型的函數. 兩個版本都支持你已經在級別上使用過的和屬性; 兩種類型都必須的元素是`標簽, 它包含了將要被放入你的源代碼文件中的原文C語言代碼.`#### role="public" 如你所想, 所有定義為public角色的函數都將包裝恰當的PHP\_FUNCTION()頭和花括號, 對應到擴展的函數表向量中的條目. 除了其他函數支持的標簽, public類型還允許指定一個標簽. 這個標簽的格式應該匹配php在線手冊中的原型展示, 它將被文檔生成器解析. ``` <functions> <function role="public" name="sample9_greet_me"> <summary>Greet a person by name</summary> <description>Accept a name parameter as a string and say hello to that person. Returns TRUE.</description> <proto>bool sample9_greet_me(string name)</proto> <![CDATA[ char *name; int name_len; if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "s", &name, &name_len) == FAILURE) { return; } php_printf("Hello "); PHPWRITE(name, name_len); php_printf("!\n"); RETURN_TRUE; ]]> </function> </functions> ``` #### role="internal" 內部函數涉及5個zend\_module\_entry函數: MINIT, MSHUTDOWN, RINIT, RSHUTDOWN, MINFO. 如果指定的名字不是這5個之一將會產生pecl-gen無法處理的錯誤. ``` <functions> <function role="internal" name="MINFO"> <![CDATA[ php_info_print_table_start(); php_info_print_table_header(2, "Column1", "Column2"); php_info_print_table_end(); ]]> </function> </functions> ``` #### 自定義代碼所有其他需要存在于你的擴展中的代碼都可以使用`標簽包含. 要放置任意代碼到你的目標文件extname.c中, 使用role="code"; 或者說使用role="header"將代碼放到目標文件php_extname.h中. 默認情況下, 代碼將放到代碼或頭文件的底部, 除非指定了 position="top"屬性.` ``` <![CDATA[ typedef struct _php_sample9_data { long val; } php_sample9_data; ]]> <![CDATA[ static php_sample9_data *php_sample9_data_ctor(long value) { php_sample9_data *ret; ret = emalloc(sizeof(php_sample9_data)); ret->val = value; return ret; } ]]> 譯注: 譯者的環境中不支持原著中標簽的name屬性. ``` ## links - [目錄](preface.md) - 18.1 [ext\_skel](18.1.html) - 18.3 [小結](18.3.html)