设置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`进行了解。

The modular design of calibre is expressed via Plugins. There is a tutorial on writing calibre plugins. For example, adding support for a new device to calibre typically involves writing fewer than 100 lines of code in the form of a device driver plugin. You can browse the built-in drivers. Similarly, adding support for new conversion formats involves writing input/output format plugins. Another example of the modular design is the recipe system for fetching news. For more examples of plugins designed to add features to calibre, see the 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”变量。您可以通过运行“calibre-debug --paths”获取这些变量。但请注意，发行版中的 calibre 软件包通常存在问题，并且完全不受支持。

一旦你设置了环境变量，打开一个新终端，检查环境变量是否设置正确，使用命令:

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文档