calibre 開発環境の構築¶

calibre は完全にオープンソースであり、 GNU GPL v3 のもとにライセンスされています。これは自由にプログラムをダウンロードして、思う存分変更できることを意味します。この章では、選んだ OS 上で calibre の開発環境を構築するにはどうすればよいかを学べます。calibre は主に `Python <https://www.python.org>`_で書かれており、一部は速度とシステムインタフェースのために C/C++ のコードで書かれています。calibre には Python 3.8 以上が必要です。

設計の哲学 ¶

calibre のルーツは UNIX の世界にあります。つまり、その設計は高度にモジュール化されています。モジュールは明確に定義されたインタフェースを介して互いにコミュニケーションをとります。これによって calibre に新しい機能を追加してバグを修正することが容易になり、開発のペースが大きく向上します。このルーツのおかげで、calibre にはすべての機能に対して包括的なコマンドラインが備わっています。コマンドラインについては、コマンドライン・インタフェースを参照してください。

calibre のモジュール化された設計は、プラグイン の形で表されます。calibre のプラグイン作成に関してはチュートリアルがあります。たとえば calibre に新しいデバイスを追加するためには、通常はデバイスドライバプラグインの形で 100 行未満くらいのコードを書く必要があります。ビルトインドライバを参照できます。同様に、新しい形式への変換をサポートしたい場合にも、その形式の入力/出力プラグインを書く必要があります。モジュール化された設計のもうひとつの例は、ニュース取得のレシピシステムです。calibre に機能追加するために設計されたプラグインのその他の例については、`プラグイン目録 <https://www.mobileread.com/forums/showthread.php?p=1362767#post1362767>`_を参照してください。

コードレイアウト ¶

All the calibre Python code is in the calibre package. This package contains the following main sub-packages

devices - すべてのデバイスドライバ。ビルトインドライバのいくつかを調べて、どのように機能するかを調べてみてください。

詳しくは、デバイスドライバがサポートするインタフェースを定義する devices.interface および USBMS デバイスに接続する汎用ドライバを定義する devices.usbms を参照してください。calibre のすべての USBMS ベースのドライバは、これを継承しています。

e-books - すべての電子書籍変換/書誌のコード。ebook-convert コマンドを起動するモジュールである calibre.ebooks.conversion.cli から始めるとよいでしょう。変換処理は conversion.plumber を介して行われます。形式に依存しないコードはすべて ebooks.oeb にあり、形式依存のコードは ebooks.format_name にあります。

書誌の読み書き、およびダウンロードはすべて ebooks.metadata にあります。

変換はパイプラインで行われます。パイプラインの構造についてははじめにを参照してください。パイプラインは、入力プラグイン、種々の変換、および出力プラグインで構成されています。パイプラインを構築して動かすコードは plumber.py にあります。パイプラインは電子書籍の中身に対して機能します。中身とは、たとえばマニフェスト、スパイン、目次、ガイド、HTML コンテンツなどを含む、解凍された EPUB のことです。この中身を管理するクラスは、ebooks.oeb.base にある OEBBook です。変換中に本に対して施される種々の変形は、oeb/transforms/*.py にあります。また入力および出力プラグインは conversion/plugins/*.py にあります。

電子書籍の編集は、別のコンテナオブジェクトを用いて行われます。これは電子書籍編集ツール API 説明書に記載されています。

db - データベースのバックエンド。calibre ライブラリへのインタフェースはデータベースの API 説明書を参照してください。

コンテンツサーバ: srv は calibre コンテンツサーバです。

gui2 - グラフィカルユーザインタフェース。GUI の初期化は gui2.main と gui2.ui で行われます。電子書籍ビューアは gui2.viewer にあります。電子書籍エディタは gui2.tweak_book にあります。

calibre のさまざまな実行可能ファイルすべてのエントリポイントを探したい場合は、 linux.py の entry_points 構造体を確認してください。

コードの理解に手助けが必要な場合には、開発フォーラムに投稿してください。おそらく数多くの calibre 開発者の中から誰かが手を貸してくれるでしょう。

コードを入手 ¶

calibre のソースコードを入手する方法は 2 つあります。バージョン管理システムを利用する方法と、直接 tarball をダウンロードする方法です。

calibre は分散バージョン管理システムである Git を使用しています。Git は calibre がサポートしているすべてのプラットフォーム上で利用可能です。Git をインストールした後、次のコマンドで calibre のソースコードを入手できます:

git clone https://github.com/kovidgoyal/calibre.git

Windows では C:\Program Files\Git\git.exe のような完全なパス名が必要です。

calibre は非常に大規模なプロジェクトであり、ソース管理の履歴も長いため、上記には時間がかかる場合があります (インターネットの速度に応じて 10 分から 1 時間)。

コードの入手に時間をかけたくない場合は、最新リリースのソースコードはいつでも archive で入手可能です。

ブランチを最新のコードに更新するには、次のコマンドを使用します:

git pull --no-edit

コードを GitHub で参照することもできます。

変更を取り入れてもらうために投稿 ¶

もしいくつかのちょっとした変更を行いたいだけなら、変更を加えてマージディレクティブを作成し、それを calibre のバグトラッカーのチケットに添付することができます。それを行うには、変更を加えてから、次のように実行します:

git commit -am "Comment describing your changes"
git format-patch origin/master --stdout > my-changes

これは現在のフォルダに my-changes ファイルを作成し、calibre バグトラッカーのチケットにそれを添付します。ただしこれは、コミットしたもの すべて を含めます。一部のコミットのみを送信したい場合には、上の origin/master を変更する必要があります。最後のコミットのみを送信するには、次のようにします:

git format-patch HEAD~1 --stdout > my-changes

最後の n 個のコミットを送信するには、1 を n に変更します。たとえば最後の 3 コミットの場合には次のようにします:

git format-patch HEAD~3 --stdout > my-changes

HEAD~n を使用するときにはマージを含めないよう注意してください。

calibre で多くの開発を行うつもりであれば、最良の方法は GitHub アカウントを作成することです。下に示す基本的なガイドに従ってフォークを作成すれば、メインの calibre リポジトリにプルリクエストを送れるようになります:

次の記事に従ってマシン上に Git を準備します: Setup Git

GitHub の認証用に SSH の鍵を Generating SSH keys の説明に従って用意します

https://github.com/kovidgoyal/calibre へ行き、Fork ボタンをクリックします。
ターミナルで次を実行します:
git clone git@github.com:<username>/calibre.git
git remote add upstream https://github.com/kovidgoyal/calibre.git
上の <username> は GitHub のユーザ名で置き換えてください。これでフォークがローカルにチェックアウトされます。
いつでも好きなときに変更を加えてコミットできます。作業したものがマージできるようになったら、次のようにします:
git push
そして https://github.com/<username>/calibre に行き、Pull Request ボタンをクリックしてマージできるようプルリクエストを発行します。
次の手順を実行することで、メインのリポジトリからのコードでローカルコピーを更新できます:
git pull upstream

また、開発フォーラムにも注目しておくべきです。大きな変更を加える前に、フォーラムで話し合うか、または直接 Kovid に連絡してください。 (メールアドレスはソースコードのいたるところに埋めこまれています)

Windows 開発環境 ¶

注釈

上で説明したように calibre のソースコードを別に入手する必要があります。

Windows インストーラを使用して通常どおりにインストールします。次にコマンドプロンプトを開き、先にチェックアウトしておいた calibre のコードに移動します。例:

cd C:\Users\kovid\work\calibre

calibre は src と resources サブフォルダを含むフォルダです。

次のステップは、環境変数 CALIBRE_DEVELOP_FROM に src フォルダの絶対パスを設定することです。上の例では C:\Users\kovid\work\calibre\src になります。Windows 上での環境変数の設定方法は、こちらのガイドを参照してください。

環境変数を設定したらコマンドプロンプトを開き、正しく設定されていることを確認するために次のコマンドを実行します:

echo %CALIBRE_DEVELOP_FROM%

この環境変数を設定すると、calibre はすべての Python コードを指定された場所からロードするようになります。

これでおしまいです。calibre コードのハックを開始できるようになりました。たとえば src\calibre\__init__.py ファイルを好みのエディタで開き、次の行をファイルの先頭近くに追加します:

print("Hello, world!")

次に calibredb コマンドを実行します。最初の行の出力は Hello, world! となるでしょう。

必要に応じて calibre 開発環境を無償の Microsoft Visual Studio にセットアップすることも可能です。こちらの手順に従ってください。

macOS 開発環境 ¶

注釈

上で説明したように calibre のソースコードを別に入手する必要があります。

提供された .dmg を使用して通常どおりに calibre をインストールします。次にターミナルを開いて、先にチェックアウトしておいた calibre のコードのフォルダに移動します。例:

cd /Users/kovid/work/calibre

calibre は src と resources サブフォルダを含むフォルダです。calibre のコマンドラインツールは calibre アプリのバンドルの中の /Applications/calibre.app/Contents/MacOS にあります。コマンドラインツールを簡単に実行するには、このフォルダを環境変数 PATH に追加する必要があります。

次のステップは、calibre をデバッグモードで実行するときに環境変数 CALIBRE_DEVELOP_FROM に src フォルダの絶対パスを設定するための bash スクリプトを作成することです。

プレーンテキストファイルを作成します:

#!/bin/sh
export CALIBRE_DEVELOP_FROM="/Users/kovid/work/calibre/src"
calibre-debug -g

これを /usr/local/bin/calibre-develop という名前のファイルに保存し、実行権を付与します:

chmod +x /usr/local/bin/calibre-develop

それが終わったら、実行します:

calibre-develop

calibre が開始されるとターミナルウィンドウに診断情報が表示されます。GUI ウィンドウにはバージョン番号の後ろにアスタリスクが表示され、ソースから実行していることを示します。

Linux 開発環境 ¶

注釈

上で説明したように calibre のソースコードを別に入手する必要があります。

calibre は主に Linux 上で開発されています。開発環境の構築には、2 つの選択肢があります。calibre のバイナリを通常どおりインストールして、それを開発用のランタイム環境として使用することができます。この手法は Windows や macOS で使われるものとよく似ています。もうひとつの方法は、calibre をソースからインストールすることです。ソースから開発環境を構築する手順はソースツリーの中の INSTALL ファイルにあります。ここではバイナリをランタイムとして使用する方法を取り上げます。こちらが推奨される方法です。

バイナリインストーラを使用して calibre を通常どおりにインストールします。次にターミナルを開き、先にチェックアウトしておいた calibre のコードのフォルダに移動します。例:

cd /home/kovid/work/calibre

calibre は src と resources サブフォルダを含むフォルダです。

次のステップは、環境変数 CALIBRE_DEVELOP_FROM に src フォルダの絶対パスを設定することです。上の例では /home/kovid/work/calibre/src になります。環境変数の設定方法は、Linux のディストリビューションや使用しているシェルによって異なります。

注釈

上流で提供されたバイナリインストーラを使用することを推奨します。どうしても自分のディストリビューションで提供するパッケージを使用したい場合には、 CALIBRE_PYTHON_PATH および CALIBRE_RESOURCES_PATH を代わりに使用してください。

環境変数を設定したらターミナルを開き、正しく設定されていることを確認するために次のコマンドを実行します:

echo $CALIBRE_DEVELOP_FROM

この環境変数を設定すると、calibre はすべての Python コードを指定された場所からロードするようになります。

これでおしまいです。calibre コードのハックを開始できるようになりました。たとえば src/calibre/__init__.py ファイルを好みのエディタで開き、次の行をファイルの先頭近くに追加します:

print("Hello, world!")

次に calibredb コマンドを実行します。最初の行の出力は Hello, world! となるでしょう。

"通常" と "開発用" の calibre を同じコンピュータ上に別々にインストール ¶

calibre のソースツリーは非常に安定していて壊れることは滅多にありません。しかしソースから実行したものはテスト用のライブラリに使用し、日常的に使用するライブラリにはリリース版の calibre を使用する必要があると感じる場合には、calibre を起動する .bat ファイルやシェルスクリプトを使うことで簡単に実現できます。下の例では、Windows 上で .bat ファイルを使ってこれを行う手順を紹介します (他のプラットフォームでの手順も同じです。.bat ファイルの代わりにシェルスクリプトを使用してください)

日常的に使用するライブラリ用にリリース版の calibre を起動するには次のようにします:

calibre-normal.bat:

calibre.exe "--with-library=C:\path\to\everyday\library folder"

calibre-dev.bat:

set CALIBRE_DEVELOP_FROM=C:\path\to\calibre\checkout\src
calibre.exe "--with-library=C:\path\to\test\library folder"

デバッグのコツ ¶

Python は動的型付けの言語であり、内省のための優れた機能を備えています。Kovid は calibre の中核となるコードを一度もデバッガを使用せずに書き上げました。calibre のコードをデバッグするには多くの戦略があります:

print 文を使用 ¶

Kovid のお気に入りのデバッグ方法は、これです。気になる場所に print 文を挿入し、プログラムをターミナルから実行するだけです。たとえば GUI をターミナルから次のように開始します:

calibre-debug -g

同様にして、電子書籍ビューアは次にように開始します:

calibre-debug -w /path/to/file/to/be/viewed

The e-book editor can be started as:

calibre-debug --edit-book /path/to/be/edited

インタラクティブな Python インタプリタの利用 ¶

次に示す 2 行のコードを挿入すると、その場所でインタラクティブな Python セッションを開始できます:

from calibre import ipython
ipython(locals())

コマンドラインから実行すると、これはローカルに定義された変数 (ローカルスコープ内の変数) にアクセスできるインタラクティブな Python インタプリタを開始します。インタラクティブプロンプトはオブジェクトプロパティの タブ 補完機能も備えており、さまざまな Python 機能を dir(), type(), repr() などの内省に使用できます。

Python デバッガをリモートデバッガとして使用 ¶

ビルトインの Python デバッガ (pdb) をリモートデバッガとしてコマンドラインから使用することができます。まず、次のように calibre コードの中の気になる場所でリモートデバッガを開始します:

from calibre.rpdb import set_trace
set_trace()

次に calibre を実行します。通常どおりに実行しても、または前の章で説明したようにcalibre-debug コマンドのひとつを使用してもかまいません。コード内の上記の場所に到達したら、calibre はフリーズしてデバッガの接続を待ちます。

次にターミナルまたはコマンドプロンプトを開き、デバッグセッションを開始するために次のコマンドを使用します:

calibre-debug -c "from calibre.rpdb import cli; cli()"

Python デバッガの使い方は Python stdlib docs for the pdb module を読んでください。

注釈

デフォルトではリモートデバッガはポート 4444 に接続しようとします。ポート番号をパラメータとして set_trace() および cli() 関数の両方に渡してやると、使用するポートを変更できます。set_trace(port=1234) や cli(port=1234) のように指定します。

注釈

Python デバッガは複数スレッドを処理できないため、スレッドごとに set_trace を呼び出してそれぞれ別のポート番号を指定してやる必要があります。

好みの Python IDE でデバッガを使用 ¶

リモートデバッグをサポートしていれば、お気に入りの IDE でビルトインデバッガを使用することも可能です。最初のステップは、calibre の src を IDE の PYTHONPATH にチェックアウトすることです。別の言葉で言うと、上で CALIBRE_DEVELOP_FROM に設定したフォルダを、IDE の PYTHONPATH にする必要があります。

次に IDE のリモートデバッガモジュールを、チェックアウトした calibre ソースコードの src サブフォルダに配置します。calibre の気になる場所、たとえば main 関数でリモートデバッガを起動するのに必要なコードを追加します。通常の方法で calibre を実行します。これで IDE は calibre の内部で実行されているリモートデバッガに接続できるようになるはずです。

calibre の Python 環境で任意のスクリプトを実行 ¶

calibre-debug コマンドには calibre のモジュールにアクセスしてコードを実行するための便利なスイッチがいくつかあります:

calibre-debug -c "some Python code"

これはコマンドラインでちょっとしたスニペットをテストするのに最適です。Python インタプリタの -c スイッチと同じように機能します:

calibre-debug myscript.py

これは Python スクリプトを実行するのに使用できます。スクリプトを Python インタプリタに渡すのと同じように機能しますが、calibre 環境が完全に初期化され、スクリプト内で calibre のすべてのコードを利用できる点が異なります。スクリプトでコマンドライン引数を利用するには、次の形式を使います:

calibre-debug myscript.py -- --option1 arg1

-- を指定すると、後続のすべての引数がスクリプトに渡されます。

プロジェクトで calibre を使用 ¶

Python のプロジェクトで calibre 関数/コードを直接利用することが可能です。それには 2 つの方法があります:

calibre のバイナリインストール ¶

calibre のバイナリインストールがある場合には、calibre に付属している Python インタプリタを次のようｊにして使用できます:

calibre-debug /path/to/your/python/script.py -- arguments to your script

Linux 上のソースインストール ¶

上記の手法に加えて、Linux 上にソースインストールを行う場合は、次のようにして直接 calibre をインポートすることができます:

import init_calibre
import calibre

print(calibre.__version__)

重要なのは、他の calibre モジュール/パッケージの前に init_calibre をインポートすることです。インタプリタを calibre コードとして実行するようセットアップするためです。

Related Topics

calibre 開発環境の構築¶

設計の哲学 ¶

コードレイアウト ¶

コードを入手 ¶

変更を取り入れてもらうために投稿 ¶

Windows 開発環境 ¶

macOS 開発環境 ¶

Linux 開発環境 ¶

"通常" と "開発用" の calibre を同じコンピュータ上に別々にインストール ¶

デバッグのコツ ¶

print 文を使用 ¶

インタラクティブな Python インタプリタの利用 ¶

Python デバッガをリモートデバッガとして使用 ¶

好みの Python IDE でデバッガを使用 ¶

calibre の Python 環境で任意のスクリプトを実行 ¶

プロジェクトで calibre を使用 ¶

calibre のバイナリインストール ¶

Linux 上のソースインストール ¶

calibre のパーツの API 説明書 ¶