2. PECL_Gen · PHP擴展開發及內核應用

# PECL_Gen 還有一種更加完善但也更加復雜的代碼生成器: PECL_Gen, 可以在PECL(http:// pecl.php.net)中找到它, 使用pear install PECL_Gen命令可以安裝它. ````c ?譯者注: 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 下面是最簡單的擴展定義文件: ````c <?xml version="1.0" encoding="utf-8" ?> <extension name="sample9"> <functions> <function name="sample9_hello_world" role="public"> <code><![CDATA[php_printf("Hello World!");]]> </code> </function> </functions></extension>譯注: 請注意, 譯者使用的原著中第一行少了后面的問號, 導致不能使用, 加上就OK. ```` 通過PECL_Gen命令運行這個文件: ````c 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文件的元素. ````c <?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可以使用<deps>定義各種類型的依賴完成掃描工作. 默認情況下, 列在 <deps>標簽下的依賴會同時應用到Unix和win32構建中, 除非顯式的是否用platform屬性指定某個目標 ````c <?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>標簽到<deps>塊中, 則不僅配置選項被修改為--with-extname, 而且同時需要掃描頭文件: ````c <deps platform="unix"> <with defaults="/usr:/usr/local:/opt" testfile="include/zlib/zlib.h">zlib headers</with> </deps> ```` #### 庫必須的庫也列在<deps>下, 使用<lib>標簽. ````c <deps platform="all"> <lib name="ssleay" platform="win32"/> <lib name="crypto" platform="unix"/> <lib name="z" platform="unix" function="inflate"/> </deps> ```` 在前面兩個例子中, 只是檢查了庫是否存在; 第三個例子中, 庫將被真實的加載并掃描以確認inflate()函數是否定義. ?盡管<deps>標簽實際已經命名了目標平臺, 但<lib>標簽也有?個platform屬性可以覆蓋 <deps>標簽的platform設置. 當它們混合使用的時候要格外小心. #### <header> 此外, 需要包含的文件也可以通過在<deps>塊中使用<header>標簽在你的代碼中追加?個#include指令列表. 要強制某個頭先包含, 可以在<header>標簽上增加屬性 prepend="yes". 和<lib>依賴類似, <header>也可以嚴格限制平臺: ````c <deps> <header name="sys/types.h" platform="unix" prepend="yes"/> <header name="zlib/zlib.h"/> </deps> 譯注: 經測試, 譯者的環境<header>標簽不支持platform屬性. ```` #### 常量用戶空間常量使用<constants>塊中的一個或多個<constant>標簽定義. 每個標簽需要一個name和?個value屬性, 以及?個值必須是int, float, string之一的type屬性. ````c <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階段手動設置. ````c ?<globals> <global name="greeting" type="char *"/> <global name="greeting_was_issued" type="zend_bool" value="1"/> </globals> ```` #### INI選項要綁定線程安全的全局變量到php.ini設置, 則需要使用<phpini>標簽而不是<globa>. 這個標簽需要兩個額外的參數: onupdate="updatemethod"標識INI的修改應該怎樣處理, access="mode"和第13章"INI設置"中介紹的模式含義相同, "mode"值可以是: all, user, perdir, system. ````c ??<globals> <phpini name="mysetting" type="int" value="42" onupdate="OnUpdateLong" access="all"/> </globals> ```` #### 函數你已經看到了最基本的函數定義; 不過, <function>標簽在PECL_Gen的specfile中實際上支持兩種不同類型的函數. 兩個版本都支持你已經在<extension>級別上使用過的<summary>和<description>屬性; 兩種類型都必須的元素是<code>標簽, 它包含了將要被放入你的源代碼文件中的原文C語言代碼. #### role="public" 如你所想, 所有定義為public角色的函數都將包裝恰當的PHP_FUNCTION()頭和花括號, 對應到擴展的函數表向量中的條目. 除了其他函數支持的標簽, public類型還允許指定一個<proto>標簽. 這個標簽的格式應該匹配php在線手冊中的原型展示, 它將被文檔生成器解析. ````c <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> <code> <![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; ]]> </code> </function> </functions> ```` #### role="internal" 內部函數涉及5個zend_module_entry函數: MINIT, MSHUTDOWN, RINIT, RSHUTDOWN, MINFO. 如果指定的名字不是這5個之一將會產生pecl-gen無法處理的錯誤. ````c <functions> <function role="internal" name="MINFO"> <code> <![CDATA[ php_info_print_table_start(); php_info_print_table_header(2, "Column1", "Column2"); php_info_print_table_end(); ]]> </code> </function> </functions> ```` #### 自定義代碼所有其他需要存在于你的擴展中的代碼都可以使用<code>標簽包含. 要放置任意代碼到你的目標文件extname.c中, 使用role="code"; 或者說使用role="header"將代碼放到目標文件php_extname.h中. 默認情況下, 代碼將放到代碼或頭文件的底部, 除非指定了 position="top"屬性. ````c <code role="header" position="bottom"> <![CDATA[ typedef struct _php_sample9_data { long val; } php_sample9_data; ]]> </code> <code role="code" position="top"> <![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; } ]]> </code> 譯注: 譯者的環境中不支持原著中<code>標簽的name屬性. ```` ## links * [目錄](<preface.md>) * 18.1 [ext_skel](<18.1.md>) * 18.3 [小結](<18.3.md>)