perlnewmod - 準備新的模組以供散發
本文件提供一些建議，說明如何撰寫 Perl 模組、準備散發，以及透過 CPAN 提供模組。
讓 Perl 真正強大的原因之一，在於 Perl 駭客傾向於分享他們所面對問題的解決方案，因此您和我就不必再為相同的問題奮戰。
他們這樣做的主要方式，是將解決方案抽象化成 Perl 模組。如果您不知道其中一項是什麼，本文件的其餘部分對您來說不會有太大幫助。您也錯失了許多有用的程式碼；請考慮在回到這裡之前先看看 perlmod、perlmodlib 和 perlmodinstall。
當您發現沒有模組可用於您嘗試執行的作業，而且您必須自己撰寫程式碼時，請考慮將解決方案封裝成模組並上傳到 CPAN，以便其他人受惠。
您也應該看看 perlmodstyle，了解製作模組的最佳實務。
我們將主要集中在純 Perl 模組，而不是 XS 模組。XS 模組有相當不同的用途，在散發它們之前，您應該考慮不同的事項 - 正在黏合的函式庫的普及性、可移植性到其他作業系統等等。然而，準備模組的 Perl 端和封裝及散發它的注意事項，將同樣適用於 XS 模組和純 Perl 模組。
你應該將任何你認為對他人有用的程式碼製成模組。任何可能填補共用程式庫中空缺的程式碼，以及其他人可以將其直接插入程式中的程式碼。程式碼中任何你可以隔離、萃取並插入其他程式的部分都是可能的候選程式碼。
我們舉個例子。假設你正在將資料從本機格式讀入 Perl 中的雜湊雜湊中，將其轉換成樹狀結構，遍歷樹狀結構，然後將每個節點傳遞到 Acme Transmogrifier Server。
現在，很多人都有 Acme Transmogrifier，而且你必須從頭開始撰寫一些程式碼來討論協定 - 你幾乎肯定會想要將其製成模組。你可以自行決定要將其設定在什麼層級：你可能想要類比於 Net::SMTP 的協定層級模組，然後再與類比於 Mail::Send 的更高級模組進行對話。選擇權在你，但你確實想要為該伺服器協定取得一個模組。
地球上沒有其他人會討論你的本機資料格式，所以我們可以忽略它。但是中間的東西呢？從 Perl 變數建立樹狀結構，然後遍歷它們是一個很好的一般性問題，如果還沒有人撰寫一個執行此操作的模組，你可能也想要將該程式碼模組化。
所以希望你現在對什麼是好的模組化有一些想法。現在讓我們看看它是如何完成的。
甚至在我們開始刮除程式碼之前，我們會希望事先做一些事情。
深入研究一堆模組，看看它們是如何編寫的。我建議從 Text::Tabs 開始，因為它在標準程式庫中，而且很簡單，然後再看看一些更複雜的東西，例如 File::Copy。對於物件導向程式碼，WWW::Mechanize 或 Email::* 模組提供了一些很好的範例。
這些應該讓你對模組的佈局和撰寫方式有一個整體的了解。
CPAN 上有很多模組，很容易錯過一個與你計畫貢獻的模組類似的模組。仔細瀏覽 https://metacpan.org，並確保你不是在重新發明輪子！
你可能會很喜歡它。你可能會覺得其他人需要它。但實際上可能沒有任何真正的需求。如果你不確定你的模組會有什麼需求，請考慮詢問 module-authors@perl.org 郵件清單（寄送電子郵件到 module-authors-subscribe@perl.org 訂閱；請參閱 https://lists.perl.org/list/module-authors.html 以取得更多資訊和檔案連結）。
包含在 CPAN 中的 Perl 模組有命名階層，你應該嘗試配合。請參閱 perlmodlib 以取得更多關於如何運作的詳細資訊，並瀏覽 CPAN 和模組清單以了解它。至少，請記住：模組應以標題大小寫寫成，（This::Thing）符合類別，並簡潔地說明其目的。
在你這樣做的同時，請確實確認你沒有錯過與你即將撰寫的模組類似的模組。
在你整理好名稱，並確定你的模組是需要的且目前不可用時，就是開始編碼的時候了。
module-starter 程式作為 Module::Starter CPAN 套件的一部分進行分發。它會根據模組開發的最新「最佳實務」建立一個目錄，其中包含啟動新模組所需所有檔案的程式碼片段，並從命令列呼叫，如下所示
module-starter --module=Foo::Bar \
--author="Your Name" --email=yourname@cpan.org如果你不希望從 CPAN 安裝 Module::Starter 套件，h2xs 是較舊的工具，最初用於開發 XS 模組，隨 Perl 發行版附帶。
對於純 Perl 模組，h2xs 的典型呼叫如下
h2xs -AX --skip-exporter --use-new-tests -n Foo::Bar -A 省略自動載入器程式碼，-X 省略 XS 元素，--skip-exporter 省略 Exporter 程式碼，--use-new-tests 設定現代測試環境，而 -n 指定模組的名稱。
模組的程式碼必須是警告和 strict 清除的，因為你無法保證它將在什麼條件下使用。此外，你也不想分發不是警告或 strict 清除的程式碼，對吧？
「Carp」模組可讓您從呼叫者的角度顯示錯誤訊息；這提供了一種方式，讓您可以指出呼叫者而非模組的問題。例如，如果您這麼說
warn "No hostname given";使用者會看到類似這樣的訊息
No hostname given at
/usr/local/lib/perl5/site_perl/5.6.0/Net/Acme.pm line 123.看起來像是模組出了問題。相反地，您想要將責任歸咎於使用者，並這麼說
No hostname given at bad_code, line 10.您可以使用「Carp」並將「warn」替換為「carp」來這麼做。如果您需要「die」，請改用「croak」。不過，請將「warn」和「die」保留在健全性檢查中，因為那真的是模組的錯。
「Exporter」提供了一種標準方式，可將符號和子常式從模組匯出到呼叫者的命名空間。例如，說「use Net::Acme qw(&frob)」會匯入「frob」子常式。
封裝變數「@EXPORT」將決定當呼叫者只說「use Net::Acme」時會匯出哪些符號，您幾乎不會想在那裡放任何東西。另一方面，「@EXPORT_OK」指定您願意匯出的符號。如果您確實想匯出一堆符號，請使用「%EXPORT_TAGS」並定義標準匯出集，請查看「Exporter」以取得更多詳細資訊。
在文件完成之前，工作尚未結束，您需要花一些時間為模組撰寫一些文件。module-starter 或 h2xs 會提供一個存根供您填寫；如果您不確定格式，請查看「perlpod」以取得簡介。提供模組在程式碼中如何使用的良好摘要、說明，然後說明個別子常式或方法的語法和功能。對開發人員備註使用 Perl 註解，對最終使用者備註使用 POD。
建議您為模組建立自測，以確保它在 Perl 支援的眾多平台上都能正常運作；如果您將模組上傳到 CPAN，一群測試人員將建立您的模組並傳送測試結果給您。同樣地，module-starter 和 h2xs 提供了一個測試架構，您可以加以延伸，您應該做的事情不只是檢查模組是否會編譯。撰寫測試套件時，「Test::Simple」和「Test::More」是良好的起點。
如果您要上傳到 CPAN，自動化小精靈會擷取 README 檔案並將其放在您的 CPAN 目錄中。如果您進入模組清單，它也會出現在主「按模組」和「按類別」目錄中。最好在這裡詳細說明模組實際執行的功能。
將自上次版本發布後任何使用者可見的變更新增至你的 變更 檔案。
每個在 CPAN 上發布模組的開發人員都需要一個 CPAN ID。請前往 https://pause.perl.org/，選擇「申請 PAUSE 帳戶」，並等待 PAUSE 管理員核准你的申請。
再次強調，module-starter 或 h2xs 已為你完成所有工作。它們會產生你在下載並安裝模組時會看到的標準 Makefile.PL，而這會產生一個具有 dist 目標的 Makefile。
perl Makefile.PL && make test && make distcheck && make dist一旦你確定你的模組通過其本身的測試（確保這點永遠是件好事），你可以 make distcheck 以確保一切看起來正常，接著 make dist，然後 Makefile 希望能產生一個漂亮的模組 tarball，準備上傳。
當你收到 CPAN ID 時收到的電子郵件會告訴你如何登入 PAUSE，即 Perl 作者上傳伺服器。從那裡的選單，你可以將你的模組上傳至 CPAN。
或者，你可以使用 cpan-upload 指令碼，它是 CPAN 上 CPAN::Uploader 套件的一部分。
一旦你開始累積使用者，他們會傳送錯誤報告給你。如果你幸運的話，他們甚至會傳送修補程式給你。歡迎來到維護軟體專案的樂趣...
Simon Cozens，simon@cpan.org
由 Kirrily "Skud" Robert 更新，skud@cpan.org
perlmod、perlmodlib、perlmodinstall、h2xs、strict、Carp、Exporter、perlpod、Test::Simple、Test::More ExtUtils::MakeMaker、Module::Build、Module::Starter https://www.cpan.org/