设置Calibre开发环境

calibre是一个完全意义上的开源程序，它采用`GNU GPL v3<https://www.gnu.org/licenses/gpl.html>_`许可证。这意味着你可以按照自己的想法下载并修改该程序。在本节，你将学会如何在你选择的操作系统下建立calibre开发环境。calibre主要使用`Python <https://www.python.org>`_ 编程，为了兼顾系统接口与速度使用了一些C/C+代码。注意，calibre要求Python 3.8及以上版本。

设计理念

calibre源自Unix，它的设计是高度模块化的。模块间相互作用通过定义良好的接口实现。这使在calibre中添加新功能或者修改bug十分方便，这种便利性使calibre的开发很迅速。正因这种模块化设计思想，calibre对所有功能，都有一个完整的命令行接口，可以参考 `generated/zh_CN/cli-index`进行了解。

模块化设计的思想通过“插件”体现出来。关于“插件”的编写，这里有一份教程 tutorial。举个例子，如果要给calibre添加一个新的设备支持，一般只需要利用设备驱动插件范式写不到100行代码即可。你能从获取`built-in drivers <https://github.com/kovidgoyal/calibre/tree/master/src/calibre/devices>`_。类似地，为新的转换格式添加支持，也只需要改写输入/输出格式插件。模块化设计的另一个例子是抓取新闻，recipe system <news>。对于更多可加入calibre的插件，可以参考 Index of plugins。

代码布局

所有calibre的Python代码都在``calibre``包中。它包含了以下的主要子包。

  • 设备 -- 所有的设备驱动器。通过浏览部分内置驱动器来获取他们的运作方式。

    • 更多细节可以参考，:devices.interface。这其中定义了被驱动器支持的接口,。另外``devices.usbms``也值得关注，它定义了一个连接了usbms设备的通用驱动器。 在calibre中，所有的基于usbms的驱动器都继承自它.。

  • 电子书 - 所有电子书转换/元数据代码。 一个好的起点是“calibre.ebooks.conversion.cli”，它是为 ebook-convert 命令提供动力的模块。 转换过程是通过“conversion.plumber”控制的。 与格式无关的代码全部在“ebooks.oeb”中，与格式相关的代码在“ebooks.format_name”中。

    • 元数据的读取、写入和下载都在``ebooks.metadata``中

    • 转换发生在传输途径中，传输途径的结构请参见“转换简介”。 该传输途径由输入插件、各种转换和输出插件组成。 构建和驱动传输途径的代码位于“plumber.py”中。 该传输途径适用于电子书的表示，就像解压的 epub，具有清单、书脊、目录、指南、html 内容等。管理此表示的类是“ebooks.oeb.base”中的 OEBBook 。 在转换过程中应用于本书的各种转换位于“oeb/transforms/.py”中。 输入和输出插件位于“conversion/plugins/.py”中。

    • 电子书编辑使用不同的容器对象。详见 polish_api。

  • db -- 数据库后端。参考`db_api`了解calibre的接口。

  • 内容服务器: "srv"是calibre的内容服务器。

  • gui2 -- 图形用户接口。GUI初始化位于``gui2.main``与``gui2.ui``。电子书浏览器位于``gui2.viewer``。电子书编辑器位于``gui2.tweak_book``。

如果要定位所有各种Calibre可执行文件的入口点，请在“linux.py <https://github.com/kovidgoyal/calibre/blob/master/src/calibre/linux.py>”中查看``entry_points``结构_。

如果你不理解某些代码，你可以在`development forum <https://www.mobileread.com/forums/forumdisplay.php?f=240>`_中提出，你很可能会得到其他开发者的帮助。

得到代码

你可以通过两种方式获取calibre的源代码：使用版本控制系统或者直接下载:website_base:源码<dist/src>

calibre使用`Git <https://www.git-scm.com/>`_，一个分布式版本控制系统。Git在所有calibre支持的平台上均可用。安装Git后，你就可以通过下面命令获得源码:

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

在 Windows 上，您将需要完整的路径名，类似于文件“C:\Program Files\Git\git.exe”。

calibre是一个拥有很长时间版本管理历史的大项目，所以下载源码可能需要一点时间（10分钟到1小时，取决于你的网速）。

如果你想更快地获取源码，可以从:website_base:`归档 <dist/src>`页面下载最新的版本。

升级一个分支到最新版本，可以使用命令:

git pull --no-edit

你也可以从`GitHub <https://github.com/kovidgoyal/calibre>`_上获得源码。

提交要包含的修改

如果你只计划做一些小修改，你可以做出修改并创建一个"merge directive"，然后将其附加到calibre的`bug tracker <https://bugs.launchpad.net/calibre>`_中。如果需要这样做，可以使用下列命令:

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

这将在当前文件夹中创建一个文件：`my changes'文件，只需将其附加到calibre `bug tracker上的票证上即可<https://bugs.launchpad.net/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 分支的基本指南，该指南允许您提交拉取请求以包含到主 calibre 存储库中：

  • 按这篇文章在你的电脑上安装git:Setup Git

  • 设置ssh密钥以进行GitHub身份验证，参考这里: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

    用你的GitHub用户名代替<username>。这将使本地校验你的分支。

  • 无论何时你都能修改代码并提交。当你准备好待合并部分时，这样做:

    git push

    进入 https://github.com/<username>/calibre 点击 Pull Request 按钮，产生一个可被合并的pull请求。

  • 你能从主仓库中更新你的本地代码副本，使用:

    git pull upstream

您还应该关注 calibre 开发论坛。 在进行重大更改之前，您应该在论坛中讨论它们或直接联系 Kovid（他的电子邮件地址遍布源代码）。

Windows开发环境

备注

你必须想上文所述的那样先得到calibre的源码。

正常安装Calibre，使用`Windows Installer<https://calibre-ebook.com/download_windows>`__。然后打开命令提示符并切换到先前检出的口径代码文件夹。例如：

cd C:\Users\kovid\work\calibre

Calibre是包含src和resource子文件夹的文件夹。

下一步是将环境变量``CALIBRE_DEVELOP_FROM``设置为src文件夹的绝对路径。因此，按照上面的示例，它应该是``C:Userskovidworkcalibresrc`。以下是<https://docs.python.org/using/windows.html#excursus-setting-environment-variables>`_在Windows上设置环境变量的简短指南。

一旦你设置了环境变量，你可以打开一个新的命令行，通过下面的命令检查环境变量是否设置成功:

echo %CALIBRE_DEVELOP_FROM%

设置环境变量意味着calibre现在可以从指定位置载入它的所有Python代码。

就是这样！你已经可以开始为calibre编写代码了。举例。用你最喜欢的编辑器打开文件 src\calibre\__init__.py ，在文件开头添加这么一行:

print("Hello, world!")

靠近文件顶部。 现在运行命令“calibredb”。 输出的第一行应该是“Hello, world!”。

你也可以通过Microsoft Visual Studio建立calibre开发环境。如果你希望这么做，可以参考这里的教程 here 。

macOS开发环境

备注

你必须想上文所述的那样先得到calibre的源码。

使用`提供的.dmg<https://calibre-ebook.com/download_osx>`__.正常安装Calibre。然后打开终端并切换到之前检出的口径代码文件夹，例如：

cd /Users/kovid/work/calibre

Calibre是包含src和resource子文件夹的文件夹。Calibre命令行工具位于Calibre应用程序包中，在：file:`/Applications/calibre.app/Contents/MacOS`中，如果您希望轻松运行命令行工具，则应将此文件夹添加到PATH环境变量中。

下一步是创建一个bash脚本，该脚本将在调试模式下运行Calibre时将环境变量``CALIBRE_DEVELOP_FROM``设置为src文件夹的绝对路径。

创建一个空文本文件:

#!/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。你有两种方法配置开发环境。你可以正常安装calibre，在运行时环境下完成开发。这个方法与Windows与macOS开发类似。或者，从源码进行安装calibre。从源码配置开发环境的命令在源码树中的INSTALL文件。接下来我们将使用第一种方法，这也是推荐的方法。

使用`二进制安装程序<https://calibre-ebook.com/download_linux>`_.安装Calibre。然后打开终端，切换到之前检出的calibre代码文件夹，例如：

cd /home/kovid/work/calibre

Calibre是包含src和resource子文件夹的文件夹。

下一步是将环境变量``CALIBRE_DEPLE_FROM``设置为src文件夹的绝对路径。因此，按照上面的示例，它应该是``/home/kovid/work/calibre/src``。如何设置环境变量取决于您的Linux发行版以及您使用的是什么Shell。

备注

建议使用上游提供的二进制安装程序。如果您坚持使用发行版提供的包，请改用``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源码树非常稳定，很少崩溃，但如果你需要从源码运行一个测试书库并且你还要运行released版本的calibre作为日常使用。你能方便地通过批处理文件或者shell脚本启动calibre。下面的例子展示如何在Windows上通过批处理文件启动calibre(其他平台的命令也是一样的，只是用shell脚本代替批处理文件)。

用常用库启动发布版本的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"

Debug技巧

Python 是一门拥有动态类型的编程语言。它拥有着出色的内省功能。 Kovid 在没有使用调试器的情况下，完成了calibre的核心代码。这里给出一些debug的策略:

使用print语句

这是Kovid最喜欢的Debug方式。只需要在目标点插入print语句，然后在终端运行程序。举例，你能从终端打开GUI界面，像这样:

calibre-debug -g

同样，您可以通过以下方式启动电子书阅读器：

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

可以通过以下方式启动电子书编辑器：

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

使用交互式Python解释器

你可以插入下面两行代码开启一个交互式Python会话:

from calibre import ipython
ipython(locals())

当从命令行运行时，这将启动一个交互式的Python解释器，可以访问所有本地定义的变量(本地作用域中的变量)。交互提示符甚至有：按键“Tab”对象属性补全，可以使用各种Python工具进行自省，如“dir”、“type”、“repr”等。

使用Python调试器作为远程调试器

您可以从命令行使用内置 Python 调试器 (pdb) 作为远程调试器。 首先，在您感兴趣的 calibre 代码中启动远程调试器，如下所示：

from calibre.rpdb import set_trace
set_trace()

然后运行calibre，正常运行，或者使用上文提到的calibre-debug命令。一旦上述代码完成，calibre会停止，等待调试器的连接。

现在打开一个终端或者命令提示符，使用下列命令打开debug会话:

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

您可以在`关于PDB模块的Python stdlib文档<https://docs.python.org/library/pdb.html#debugger-commands>中`了解如何使用Python调试器。

备注

默认情况下，远程调试器连接到端口4444。你也可以通过设置 set_trace() 与 cli() 函数更换端口，像这样: set_trace(port=1234) and cli(port=1234)。

备注

Python调试器不能控制多线程，所以你不得不在每个线程中使用 set_trace 函数一次，每次都得用一个不同的端口号。

在自己的IDE环境下使用调试器

如果内置调试器支持远程调试，则可以在您最喜欢的Python IDE中使用它。第一步是将Calibre src检出添加到IDE中的``PYTHONPATH``中。换句话说，您在上面设置为``CALIBRE_DEVELOP_FROM``的文件夹也必须位于您的IDE的``PYTHONPATH`中。

然后将IDE的远程调试器模块放入calibre源代码检测的“src”子文件夹中。 添加启动远程调试器所需的任何代码，以在感兴趣的位置进行校准，例如在主函数中。 然后正常运行 calibre。 您的 IDE 现在应该能够连接到在 calibre 内运行的远程调试器。

在calibre的Python环境中执行任意脚本

calibre-debug 提供了一些方便的开关来执行你自己的代码，并且可以访问calibre模块:

calibre-debug -c "some Python code"

非常适合在命令行上测试一小段代码。它的工作方式与-c切换至Python解释器的方式相同：

calibre-debug myscript.py

可以用来执行自己的Python脚本。 除了完全初始化calibre环境外，它的工作方式与将脚本传递给Python解释器的方式相同，因此您可以在脚本中使用所有calibre代码。 要在脚本中使用命令行参数，请使用以下格式：

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

-- 会使后面的所有参数被传到你的脚本里。

在你的项目中使用calibre

在你的Python项目中可以直接使用calibre的功能与代码。有两种方法可以这么做:

二进制安装calibre

如果您有calibre的二进制安装，则可以使用calibre附带的Python解释器，如下所示：

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

Linux源码安装

除了使用上面的技巧，如果你在Linux中进行源码安装，你可以直接import calibre，就像下面这样:

import init_calibre
import calibre

print(calibre.__version__)

在将init_calibre模块设置为运行calibre代码的解释器之前，必须先导入init_calibre模块，然后再输入其他calibre模块/软件包。

calibre丰富的API文档