Incorrectly specifying multiple package-files in Cask?

[akirak]

Hello,

I've seen your Cask file, and it contains multiple package-file entries:

(package-file "php.el")
(package-file "php-face.el")
(package-file "php-mode.el")
(package-file "php-project.el")
(package-file "php-mode-debug.el")

I personally don't use Cask, so I don't exactly understand its DSL, but according to its document, package-file is defined as:

Define this package and its runtime dependencies from the package headers of a file (used only for package development).

I guess there should be only one package-file entry per package, and the file (I call this a main file) should define all of the dependencies in its Package-Requires header. This is how package-lint works now.

The other files should be listed in files entry along with the main file of the package. For example, see the following example from nix-mode. It has only one package-file, but all the *.el files are listed in one files clause:

(package-file "nix-mode.el")

(files
 "nix-mode.el"
 "nix-company.el"
 "nix-format.el"
 "nix-repl.el"
 "nix-shell.el"
 "nix-mode-mmm.el"
 "nix-prettify-mode.el"
 "nix-store.el"
 "nix-instantiate.el"
 "nix-drv-mode.el"
 "nix-search.el"
 "nix-shebang.el"
 "nix.el"
 "nix-shell-haskell.el"
 )

I am currently developing a tool to parse Cask files, and I noticed this difference while I was looking at your package as input. I would like to know if my understanding is correct. Thanks.

[zonuexe]

Hi @akirak

I reply in Japanese to avoid interpretation mismatch. Feel free to claim me if you want to communicate in English.

---

結論から言うと、Caskにおいて複数の package-file を記述することは合法であり、期待通りに動作します。
ただしMELPAにおいては一つのパッケージを構成する複数のLispファイルに別の依存関係を記述することは想定されていません。

I guess there should be only one package-file entry per package, and the file (I call this a main file) should define all of the dependencies in its Package-Requires header. This is how package-lint works now.

はじめに、 package.el が「パッケージ」と呼ぶ単位は「必要なヘッダを備えた単一のLispファイル(バッファ)」「メタデータが記述された(NAME)-pkg.elを持つtarファイル(あるいはディレクトリ)」のどちらかです。つまり複数ファイルを持つLispリポジトリは、明示的に -pkg.el を配置しているものを除けば、そのままではパッケージと呼べるものではありません。

そのギャップを埋めるのがmelpa/package-build: Tools for assembling a package archiveです。これは-pkg.elファイルを欠いたパッケージに対して適切なメタデータを生成し、package.elが期待するパッケージとして完成させるものです。

MELPAとCaskはどちらもpackage-buildを利用してLispファイルのパッケージ化を行いますが、そのアプローチが多少異なります。

MELPAは依存関係を含むメタデータを (NAME)-pkg.el, (NAME).el.in, (NAME).el の順で読み取ります(package-build.el#L816-L835)。パッケージ名と共通するファイル名を持つこれらのファイルを「メインファイル」と呼ぶことができます。package-lintがpackage-lint--main-file-pでthe package's main fileと説明するのは、このファイルのことです。

次にCaskですが、これは package-file に指定されたファイルをすべて依存関係に加えます(cask.el#L409-L420, cask.el#L598。この両者の違いは何に基くものでしょうか。

---

ここでMELPA/README.md#Recipe Formatを参照してみましょう。ここで説明されているリポジトリ構成は「リポジトリに1ファイルが含まれる場合」「リポジトリに複数パッケージが含まれる場合」「リポジトリに複数ディレクトリのファイルが含まれる場合」の3種類です。ここでは「リポジトリに複数パッケージが含まれる場合」と「リポジトリに1パッケージだけが含まれる場合」の2パターンで考えることができるでしょう。

php-modeは「リポジトリに1パッケージだけが含まれる」構成です。かつては php-mode.el の1ファイルだったリポジトリが複数ファイル構成になった理由は「独立性の高い(独立したパッケージとしても存在できる)が、小規模のため同梱した方がユーザーの利便性に供すると思われるフィーチャ」「リファクタリングの過程で個別のファイルとして分割されたフィーチャ」があります。 (過去のメンテナによって別パッケージを統合したが、利便性が著しく低いため再分離したものもあります)

一方で、emacs-php/phpstan.elはphpstan, flymake-phpstan, flycheck-phpstanの3種類のパッケージを一つのリポジトリで管理しています。これは共通のコアロジックを持っていますが、flymakeとflycheckのような具体的なユーザーインターフェイスへの依存部分を別パッケージとして分割して公開しています。このような場合は同じリポジトリで開発するのが合理的だと判断されます。

---

さて、package-lintはどのようなファイルをmain-fileとして扱っているのでしょうか。

;; https://github.com/purcell/package-lint/blob/ff88d39dc47b4dd86e9d35614d8b5e227220339c/package-lint.el#L172-L177
(defun package-lint--main-file-p ()
  "Return non-nil if the current buffer corresponds to the package's main file."
  (or (null package-lint-main-file)
      (null (buffer-file-name))
      (string= (file-truename (expand-file-name package-lint-main-file))
               (file-truename (buffer-file-name)))))

• package-lint-main-file が未設定のとき
• 編集中のバッファが buffer-file-name を持たない (ファイルに未保存)のとき
• package-lint-main-file と buffer-file-name の正規化したファイルパスが同じとき

これらの条件を上からチェックしどれかに該当する場合、package-lintは編集中のバッファがmain-fileだと判断します。

この package-lint-main-file ですが、これはpackage-lintで自動でセットされる変数ではなく (put 'package-lint-main-file 'safe-local-variable #'stringp) として定義されているため、これはFile VariablesまたはDirectory Variablesとしてセットされることを期待した変数だと解釈できます。

複数ファイルからなる場合には .dir-locals.el または .dir-locals-2.el で設定するのが効率的でしょう。ファイル変数として記述してしまっても構いませんが、package-lintを導入していない貢献者が編集しようとしたときに安全ではないファイルローカル変数の警告が出ることを覚悟しなければなりません。一方で、「1リポジトリに3フィーチャ、3パッケージが含まれる場合」は全てのLispファイルがmain fileだと見做せますので、package-lint-main-file には何も設定されないのが自然です。

しかしphp-modeに属するファイルは、あくまでパッケージ名と同じ php-mode.el がmain fileですので、このファイルに依存を集約しpackage-lint-main-file に "php-mode.el" を設定するか、main file以外からも依存を収集して php-mode-pkg.el に出力して package-lint-main-file に "php-mode-pkg.el" を記述するかの、どちらかを選ばなければいけません。

つまり Cask ファイルの構成としては、いまのところphp-modeは外部パッケージへの依存を持っていないため表面的な問題は起こっていないものの、ご指摘の通りnix-mode方式に従うのが妥当だと言えます。一方で多くのLispパッケージではpackage-lintでチェックされていることはあっても明示的にpackage-lint-main-fileが指定されることは多くない(package-lint/README.mdでも設定の必要性について言及されていない)ため複数ファイル構成のパッケージでも package-lint-main-fileを設定しない状態で package-lint の指摘に従って Package-Requires: ((emacs "25.1")) のように設定している例が少なからず見つけられると思われる(例: smart-jump)ので、Package-Requiresヘッダ設定の有無だけでmain fileかどうかを判定するのはいささか確実性に欠けるようにも思われます。

issueの表題の件についてまとめると

• Caskファイルにpackage-fileを複数記述するのは動作するし、正当化できそうなユースケースも存在する
  • ただし cask pkg-file の出力結果は怪しく、これは想定外の可能性が高い
• リポジトリ内の複数フィーチャで1パッケージを構成する場合、package-fileの複数指定は妥当ではない
  • php-modeに関してもnix-modeと同様の設定が適切

となります。

なお現在のところ構成管理はまだCaskを利用していますが、conao3/keg.elの導入を検討しています。(ただし #637 の構成では keg build に失敗することが確認されていることも本日確認できました)

package.el, package-build, package-lint, Caskの実装を読み直す良い機会にもなったので感謝します。

[akirak]

(I can read and comprehend your comment, but I cannot write Japanese on my Linux computer. Sorry for replying to you in English.)

Thank you for the greatest explanation I've ever read about the Emacs package ecosystem. It's worth a separate post on Qiita.

I know of keg.el. It currently seems to fail on Emacs < 24.4, but otherwise it would work for typical situations. Actually, I'm trying to develop yet another CI solution for Emacs packages, and parsing Cask files is one of its planned features. The Cask parser is already available here, but it failed to handle your Cask file, so I asked you the question here. Your information is much more helpful than I expected.

(ただし #637 の構成では keg build に失敗することが確認されていることも本日確認できました)

@conao3 is a dedicating developer, so he will fix it soon.

[zonuexe]

@akirak
I can't make him work for me because @conao3 is not you or my slave. We cannot overlook an unrequited mention to him.

[akirak]

I can't make him work for me because @conao3 is not you or my slave. We cannot overlook an unrequited mention to him.

I know, but I think he is a man of (at least trying to make) perfection, and keg.el is meant to be a replacement for Cask. Yes, you are right in that we cannot tell when he will achieve that. I don't mind your giving -1 for that.