Geekly Articles each Day

Perlモジュールの作成

真珠のモジュールを開発するとき、モジュールのタスクとコードに実質的に関係しない多くの作業をしなければなりません-ダースの典型的なファイル/ディレクトリの作成から、新しいバージョンをリリースするのに必要なダースの同一の操作を完了するまで。

退屈で怠け者であり、多くの場合エラーを引き起こすという事実に加えて（バージョン番号などのメタ情報をいくつかのファイルで更新する必要がある、またはリリース時にコマンドの一部を意図せずにスキップするため）、Perlov TIMTOWTDIによってすべてがさらに複雑になります-いくつかの異なるビルドシステムがあります、誰もが自分の長所と短所を持っています（ただし、それらをリストする単純なタブレットはありません）。公式にもコミュニティからも推奨されません。

さらに、私たちの多くは長年真珠で書いており、 perlnewmodを最後に読んだのは真珠を勉強したときでした。 その結果、新しいモジュールが作成されると、これは15年前のスタイルで行われることが多く、アセンブリシステムはほぼランダムに選択されます -古くて使い慣れた正確なEUMMまたは他の1つ（必要ではないため） 、しかし、新しい問題を作成することなく、EUMMよりも簡単で便利であることを期待して... ...

以下は、真珠モジュールの開発プロセスを促進し、モジュールをよりモダンにし、他の開発者がモジュールを簡単に改良できるようにする、2015年の初めに利用可能なツールを簡単に説明しています。 私は彼らの主な長所と短所をリストしようとしましたが、 自分では使用しませんでした。コメントに応じてこのリストを補足/修正します。


タスク


それでは、Perlモジュールのオーサリングプロセスに通常含まれるタスクのリストを作成しましょう。

新しいモジュールを作成するときのタスク：
  1. 著者名/メールアドレスを設定
  2. ライセンスを定義する
  3. 組立システムを選択
  4. 追加機能を選択します。
    • XSサポート
    • 基本的なテストスイート（ドキュメントのチェック、スペル、コード品質、依存関係、システムファイルのビルドなど）
    • モジュールのドキュメントからのREADMEの自動生成
    • vcsを使用する
    • GitHub、Travis CIとの統合
  5. モジュールのスケルトンを作成します-開発とリリースに必要な一連のファイルを含むディレクトリ：
    • モジュール自体のスケルトンとドキュメント
    • 基本的なテストスイート
    • 変更点
    • Readme
    • 免許
    • システムファイルを構築する
    • 依存関係のリスト（ビルドシステムファイルに含まれることもあります）
    • VCSを使用する場合：リポジトリとその設定

新しいバージョンのリリースのタスク：
  1. 依存関係リストを更新する
  2. モジュールを組み立てる
  3. テストを実行する
  4. 新しいバージョン番号を選択し、いくつかのファイルで変更します（いくつかのファイルで-いくつかの場所で）
  5. 変更の変更を説明する
  6. 現在の日付とリリースバージョンを変更に追加する
  7. READMEを更新
  8. VCSを使用する場合：
    1. バージョンの変更、変更、およびその他すべての変更されたファイルをコミットする
    2. 新しいバージョンのタグを追加
    3. セントラルリポジトリ（GitHub）を使用する場合-変更を送信する
  9. モジュールでアーカイブを作成
  10. CPANにアップロードする

理想的には、新しいモジュールを作成するときに必要なすべての決定（XSでの必要性を除く）を1回行い、将来的には1つのコマンドで新しいモジュールを作成する必要があります。 また、リリースでは、理想的には、1つのチームが新しいバージョン番号を選択し、変更の変更を説明する以外のすべての手順に従う必要があります。

更新：ここを読んで、「オーサリング」とは何か、Makefile.PL / Build.PLの通常の使用との違いを理解していない場合-これら2つの コメントを読んでください。

$バージョン


完璧な世界では、Perlのバージョン番号についてブログを書くことはありません。
「バージョン番号は退屈なはずです」-David Golden
質問の最後に進む前に、1つの問題を説明する必要があります。それは、モジュールバージョンの形式を選択することです。 これは記事のトピックに直接関係していませんが、この選択はオーサリングプロセス中に行う必要があり、見た目ほど簡単ではありません。

モジュールのバージョンを誤って宣言する方法はたくさんあるので 、正しいものだけをリストします-ずっと少ないです。

古い10進数/古いスタイルの10進数


安定リリース（お好みで2桁/ 3桁）：

our $VERSION = '0.08'; our $VERSION = '0.008'; package MyModule 0.08; # need perl-5.12 package MyModule 0.008; # need perl-5.12

0.09 / 0.009リリース前のCPANテスターをテストするためのアルファ版：

 our $VERSION = '0.08_01'; our $VERSION = '0.008_001';

または、とにかくユーザーにアルファ版が表示されない場合、安定リリースと不安定リリースの2つの独立したシーケンスを使用できます。

ドット付き10進数


安定リリース（バージョンでは3つ以上の数字を使用できます）：

 use version; our $VERSION = 'v0.8.0'; # need perl-5.8.1 our $VERSION = 'v0.8.0'; # need perl-5.10 package MyModule v0.8.0; # need perl-5.12

v0.8.1のリリース前にCPANテスターをテストするためのアルファ版：

 use version; our $VERSION = 'v0.8.0_1'; # need perl-5.8.1 our $VERSION = 'v0.8.0_1'; # need perl-5.10

"v0.8_1"は安定版"v0.8.0"と"v0.8.1"間のアルファ版としても使用できますが、バージョンは1つしかありません。複数のアルファ版をリリースする必要がある場合は、番号"v0.8.1"安定版をリリースして"v0.8.1"失敗します。

セマンティック


現時点では、セマンティックバージョニングの仕様に完全に準拠する方法はありません。 "1.2.3-alpha1"として定義されているプレリリースバージョンは、パールモジュールに適用できません。 最も近いオプションは上記の3要素のドットと数字のバージョンです-仕様に従って次の安定バージョンを決定するためのルールに従い、テキストのプレリリースバージョンの代わりに数値アルファバージョンをリリースできます。

トライアル


アルファ版は、外国人の同僚が言うように、「お尻が痛い」ことに気づきました。 実際、これは実際の「アルファ」に関するものではありません。実際のアルファ、ベータ、およびその他のプレリリースバージョンは、セマンティックバージョニングの仕様に記載されており、pearlではサポートされていません。 これは、 CPANにこのバージョンの「インデックスを作成しない」コマンドを与えることです。 したがって、2つのタイプのデータを1つの変数（CPANのバージョン番号とフラグ）に"v0.8.1"させると、スタイルが悪く、見苦しくなり、混乱します（リリース前に選択するもの"v0.8.1" - "v0.8_1"または"v0.8.0_1" ？）その他の問題が発生します。アルファバージョンはパッケージで指定できません。一部の古いバージョン（5.8.1まで）のperlでは正しく動作しません。

少し前に、CPANに新しい方法が追加され、コマンドにこのバージョンを「インデックスを作成しない」-モジュールのアーカイブ名に"TRIAL"という名前が含まれている場合。 したがって、「アルファ」バージョンは使用できなくなります。 一部のユーティリティ（ Dist :: Zilla 、 shipitなど）は、CPANに"-TRIAL"する前に"-TRIAL"モジュールを使用してアーカイブ名に追加するパラメーターをサポートしています。 "v1.2.3-TRIAL" （ "v1.2_3"とは異なります）は"v1.2_3"の通常バージョンであるため、次のバージョンは"v1.2.4"または"v1.2.4-TRIAL"ます。

モジュールスケルトン/ボイラープレート


これらのユーティリティは、新しいモジュールを使用してディレクトリを作成し、テンプレートの種類に応じて必要なファイルの基本セットをそのモジュールに格納します。 これは最も古いもので、これまでのところ、新しいモジュールを作成する主な方法です。 このアプローチの問題は、これらのファイルの大部分は一度作成するだけでは不十分であり、モジュールの新しいバージョンがリリースされたときに絶えず更新する必要があることです。 そのため、多くはこれらのユーティリティ（通常はDist :: Zillaに基づいています）の代わりに、より複雑なソリューションを徐々に使用し始めています。

h2xs、モジュール::スターター


これらのモジュールの使用法はperlnewmodで説明されていますが、ポイントは非常に時代遅れであり、実際にはサポートされておらず 、複雑すぎて十分な柔軟性がないことです。

CPANには、 同様の モジュールが多数ありますが、私が見たものはすべて作者のニーズに合わせたものであり、柔軟性に欠けていました。実際、テンプレートに従って新しいモジュールを使用してカタログを生成するタスクは非常に単純で、ほとんどの人が独自のバイクを作成します（私のものは~/bin/にある20行のスクリプトで、これも完全にカスタマイズ可能です）。

構築する


モジュールの95％に複数のpmファイル、テスト、および標準の小さなXSが含まれているため、どのビルドシステムでも処理できます。

5.10.1以降、configure_requiresのサポートが登場しました-つまり これでMETA.{json,yml} perl Makefile.PLまたはperl Build.PL実行する前にインストールするモジュールをMETA.{json,yml}で指定できます。 言い換えると、ユーザーが、たとえばModule :: Build :: Tinyをインストールしているかどうかは問題ではありません。これを使用してモジュールをビルドできます。 または、モジュール用のビルドシステムを作成できます。

ExtUtils :: MakeMaker（別名EUMM）


機能：
短所：
利点：

モジュール::ビルド（別名MB）


機能：
短所：
利点：

モジュール::インストール（別名MI）


機能：
短所：
利点：
EUMMとモジュール::ビルドに対するコミュニティの満場一致の嫌悪感にもかかわらず、私はモジュール::インストールが最近真剣に受け止められなくなったという印象を受けました-彼が時々作成した問題は彼のメリットを上回っていました。

モジュール::ビルド:: Tiny（別名MBT）


機能：
Build.PLは次のようになります。

 use 5.008001; # only if you need it use Module::Build::Tiny; Build_PL();

奇妙なことに、これを使用することもできます-依存関係管理にcpanfileファイルを使用し、オーサリングにmbtinyユーティリティを使用（ Build.PL 、 MANIFEST 、 META.{json,yml}生成しMETA.{json,yml} 、モジュールでアーカイブを準備します-モジュールがしたこと：ビルドおよびモジュールアセンブリプロセスに適用されないもの）。 または、 mbtiny代わりにDist :: Zillaを使用します（ちなみに、 Dist :: MillaとMinillaはMBTを使用します。ビルドシステムが機能し、「不要な」タスクを引き受けない場合、このような洗練されたシステムに非常に便利です）。

依存関係管理


cpanfile


これは、依存関係をビルドシステムとはcpanfileファイルで指定するアプローチです。 これにはいくつかの理由があります。


バージョン管理/ VCS


真珠モジュールの場合、一方では、モジュールを構築するために必要なすべてのファイルをリポジトリに保存する必要があることに留意する必要があります（ cpanmを介してリポジトリから直接インストールでき、他の開発者がフォーク後にプロジェクトの作業バージョンを取得できるようにするため）一方、不必要な自動生成ファイル（たとえば、モジュール::インストールファイルをinc/ ）で散らかさないようにするには、常にそれらをコミットする必要があり、さらにdiffなどを散らかします。 これは特にDist :: Zillaのユーザーに当てはまります-プルリクエストを受け取りたい場合は、些細なことを修正したい人にプロジェクトのビルドを開始するために150-200の追加モジュールをインストールするように強制する必要はありません。

Github


GitHubを使用する場合、ほとんどの場合、追加のモジュール記述をREADME.mdに記述するか、モジュールのPODドキュメントからこのファイルの自動生成を構成する必要があります。 2番目のケースでは、追加の要素を追加する必要がある場合があります。たとえば、Travis CIのプロジェクトのビルドステータスです。

継続的インテグレーション/ CI


CPANテスター


2013年4月まで、 CPANテスターは個別のtest_requiresをサポートしていませんでした （依存関係はテストの実行にのみ必要です）。 同時に、組立システムは長い間それらを示すことを可能にしてきました...しかし、これは機能しませんでした。 その結果、一部のモジュール開発者は非常に怒っており、スマートなtest_requiresなしで新しいバージョンをリリースし、この機能を忘れていました。 だから、 すでに可能です！ test_requiresの詳細は、ビルドシステムの異なるバージョンによるサポートを必要とします。

原則として、CPAN Testersサービスは基本的なニーズをカバーしますが、1つの欠点があります。テストはリリース後に行われます。 リリース前にCPAN Testerを介してモジュールを実行するには、特別なアルファバージョンをリリースする必要があります -それでも、これはリリースであり、CPAN Testersはそれほど速く動作しません。

GitHub + Travis CI


GitHub Travis CIのモジュールを使用してリポジトリに接続することにより、perlのいくつかのバージョンで リリースする前にモジュールの現在のバージョンのテストを自動化できます（ただし、異なるプラットフォームの点ではCPANテスターほどクールではありませんが、マシンでのみテストを実行するよりも優れています） ）

リリース


アプリ:: scan_prereqs_cpanfile


モジュールの依存関係を分析し、 cpanfileを生成するか、現在のcpanfileとの差異を表示するためのscan-prereqs-cpanfileコマンドを提供します（手動で変更し、単に再生成することはお勧めできません）。

Perl ::バージョン


（ほぼ）すべてのモジュールファイルのバージョン番号を変更するperl-reversionコマンドを提供します。

READMEをサポートしていREADME 、 README.mdサポートしていませREADME.md 。

CPAN ::アップローダー


コマンドラインからCPANにモジュールをアップロードするためのcpan-uploadコマンドを提供します。 PAUSEのログイン/パスワードを~/.pauseは、GnuPGで暗号化できます。

Github


残念ながら、GitHubは、新しいバージョンのタグを追加するときに（たとえば、プラグインでCPANがGitHubからモジュールをポンプできないと言う方がおそらく正しいかもしれませんが）、パールモジュールをCPANに自動的にアップロードできませんjQuery）。 しかし、私はまだこのアイテムをここに残します。突然、適切な人がそれを見て、機能を追加します。

サポート


CPAN RT


CPANバグトラッカーは、長年利用可能な唯一のオプションです。 その不便なインターフェースを考えると、それは非常に悲しかったです。 一方、モジュールの開発時にVCSを使用しない場合でも使用できます。

幸いなことに、 META.{json,yml}指定できるようになりましMETA.{json,yml} （もちろん、ハンドルではなく、使用されているビルドシステムを通じて） 代替バグトラッカー （GitHubなど）を指定します。 残念ながら、これによりCPANおよびMetaCPANサイトのバグトラッカーへのリンクが変更されますが、CPAN RTでモジュールのチケットを追加する機能は無効になりません（ただし、優先バグトラッカーが別の場所にあるという通知が表示されます）。 もちろん、バグトラッカーを変更した後、 現在のバグはRTに残ります。

Github


GitHubでプロジェクトをサポートすることの利点と利便性については説明しません（特にCPAN RTと比較して顕著です）。 さらに、Gitが気に入らなくても、問題なくMercurialをローカルで操作でき、プロジェクトをGitHubに保持できます（ hg-gitプラグインを使用）。

現在のチケットをCPAN RTからGitHub Issuesに移動したい場合は、 rt-to-github.plまたは古いバージョンのこの変更を試すことができます。

オーサリング


このセクションでは、モジュールのオーサリングプロセスを完全に引き継ぐユーティリティについて説明します。多くの場合、上記のユーティリティを使用して個々のオーサリングサブタスクを解決します。

2つのサーバーがあり、1つがインストールされたばかりで、27個のCPANモジュールしかありません。2番目のサーバーは、長年にわたって多くの真珠プロジェクトを開発しており、248個のCPANモジュールがインストールされています。 このセクションで説明するユーティリティのために、各サーバーにインストールする必要がある追加のCPANモジュールの数を計算しました。


距離::ジラ


これは本当のモンスターです。 彼は何でもします！ CPANでは、Dist :: Zillaの機能を拡張する480のディストリビューションに約900のモジュールが含まれています。 これらの480個のディストリビューションのうち、315個はプラグイン（Dist :: Zilla :: Plugin :: *）であり、別の100個はこれらのプラグインの異なるコレクション（Dist :: Zilla :: PluginBundle :: *）です。

問題は2つしかありません。彼があなたが個人的に必要とすることを始めるのに何日を費やす必要があるか、そしてそれを使用するためにインストールする必要があるモジュールの数です。

最初の問題については何も言えません。 私はあえて参加し、自分のためにそれをカスタマイズしようとしませんでした。 誰がこれをしたか-コメントであなたの印象を共有してください。

2番目の問題も十分に重要です。モジュールへのパッチとプルリクエストを受け取りたい場合、モジュールを変更したい人がこれを非常に簡単に行えることが必要です。 いくつかの行を修正するためにCPANの半分をインストールする必要がある場合（著者によると半分ではなく0.6％のみであると主張します）、非標準のビルドプロセスに対処する場合、パッチを待ちません。

距離::ミラ


機能：
短所（Distと比較して:: Zilla）：
利点：

ミニーラ


機能：
短所：
利点：
松野徳宏（Minillaの著者）とほぼ同じ方法でオーサリングを行う場合、またはオーサリングの正確性を気にしない場合、主なことは、すべてが箱から出してすぐに機能することです（つまり、gitとGitHubを使用）多数のモジュールをインストールする必要がありました-Minillaは最適です。 他に何かを行う必要がある場合は、代替品を探す必要があります（ほとんどの場合、Dist :: Millaです）。

Shipit


1つのコマンドでshipit、新しいバージョンをリリースするときに必要なほとんどの操作を実行できます。

モジュールディレクトリ.shipitにファイルが作成されます。次のようなものです。

 steps = FindVersion、ChangeVersion、CheckChangeLog、DistTest、Commit、Tag、MakeDist、UploadCPAN

そして今、起動すると、次の操作shipitが実行され.shipitます：

  1. 彼らはあなたに新しいバージョン番号を尋ねます
  2. 新しいバージョンはモジュールコードで記述されます
  3. のエントリの可用性を確認し、Changes追加を提案します
  4. テストを実行します（サポートMakefile.PLおよびBuild.PL）
  5. コミットします（Git / Mercurial / SVNをサポート）
  6. 新しいバージョンのタグを追加
  7. モジュールでアーカイブを準備する
  8. CPANにアーカイブをアップロード

使用可能なすべての操作はプラグインとして設計されているため、CPANには追加のモジュールがいっぱいです（READMEPODからの生成、PODでのバージョンの更新、各モジュールのコードでの新しいバージョンの作成、ソーシャルネットワークでのアナウンスなど）。

ShipItがサポートされるかどうかは明らかではありません-数年間更新されておらず、現在著者はDist :: Millaに積極的に取り組んでおり、ShipItからDist :: Millaへの移行について説明しています。私の意見では、ShipItは必要なほとんどすべてを実行し、同時に非常に小さく、シンプルで、拡張可能で、依存関係がありません。著者が彼に何を好まなかったか、そして彼がShipItのプラグインに不足している機能を追加する代わりに、Dist :: Zillaのラッパーを作成することにした理由はわかりません。によるとDist :: Zilla（Dist :: Zillaを開発する前にShipItを積極的に使用していた）ShipItの主な問題は、プラグインで拡張する際の複雑さと柔軟性の欠如です。確かに、Dist :: Zillaはこの問題を徹底的に解決しました。

アプリ:: ModuleBuildTiny


私はそれを記事に含める価値があるかどうか長い間考えていました。その機能は初歩的であり、現在のバージョンは0.005で、1年間誰も更新していません...しかし、先日、著者が積極的に取り組んでいただけでなく、Dist :: ZillaまたはMinillaではなく、Module :: Build :: Tinyを直接使用する必要があります。

少なくともその機能を上記のユーティリティと比較した場合、これはオーサリングユーティリティとは異なります。しかし、著者は「スタンドアロンオーサリングツール」と呼んでいたため、このセクションで検討します。その非常に限られた機能を考えると、Dist :: Zillaなしで完全なオーサリング機能を取得するために、他の小さなユーティリティ（次のセクションで説明）を使用してみます。

まず第一に、CPANのモジュールを作成する最も最小限の方法は次のとおりです。

 mkdir -p Example-MBtiny/lib/Example/ cd Example-MBtiny vi lib/Example/MBtiny.pm mbtiny dist

その結果、Example-MBtiny-$VERSION.tar.gzCPANにアップロードできるものを取得します。モジュールを含むディレクトリには他のファイルはありませんlib/Example/MBtiny.pm。このアーカイブのみが作成されます。

今すぐ作成（または任意のユーティリティを生成する）GitHubの上にレイアウト全てのモダンなモジュール内に通常存在するすべての標準のファイル：README.md、LICENSE、Changes、t/*、.gitignore、.travis.ymlだけでなく、リポジトリを作成すると、我々はすべてのこれらのファイルに追加し、GitHubの上で記入してください。

次の質問は、どのスタイルを使用するかですmbtiny。


GitHubを使用する場合、プロジェクトに追加する必要がありmetamerge.json、その内容は生成中に考慮されますMETA.{json,yml}：

 { "resources" : { "bugtracker" : { "web" : "https://github.com/powerman/Example-MBtiny/issues" }, "homepage" : "https://github.com/powerman/Example-MBtiny", "repository" : { "type" : "git", "url" : "git://github.com/powerman/Example-MBtiny.git", "web" : "https://github.com/powerman/Example-MBtiny" } } }

新しいバージョンをリリースするとき、追加のユーティリティが役立ちます。

 # update dependencies scan-prereqs-cpanfile >cpanfile # ... update META.* from cpanfile if you added META.* into the repo mbtiny regenerate # build & test mbtiny test # update version everywhere ver=1.2.3 perl-reversion -set $ver # don't forget to update version & date vi Changes # regenerate README.md with badges cp BADGES.md README.md pod2markdown lib/Example/MBtiny.pm >> README.md # release git commit -a -m "release $ver" git tag $ver git push mbtiny dist cpan-upload Example-MBtiny-$ver.tar.gz

ご覧のとおり、毎回これをすべて手動で行うことは良い考えではありません。何かを忘れてしまい、どこかで間違えられます。しかし、これをスクリプトにすることは難しくありません。このような単純な2つのスクリプト（このスクリプトとテンプレートによって新しいモジュールのスケルトンを作成するスクリプト）は、Dist :: Zillaなしで最新のモジュールを作成するのに十分です。

まとめ



オーサリング用のユーティリティの選択に関しては、明確な推奨事項を提示することは困難です。放棄されていないものを選択した場合：


モジュール作成者向けのさまざまなユーティリティ



______________________
AsciiDocのhabrahabrバックエンドを使用して変換されたテキスト。

Source: https://habr.com/ru/post/J249767/

More articles:


All Articles