设置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对所有功能,都有一个完整的命令行接口,可以参考:doc:`generated/zh_CN/cli-index`进行了解。

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

代码布局

所有的口径编成语言代码都存放在callbre包里.此包包含以下所有的主要子包

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

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

  • 电子书 – 所有的电子书格式转换/元数据代码。一个好的出发点是``calibre.ebooks.conversion.cli``,这是用于支持电子书转换命令的模块。转换过程通过``conversion.plumber``进行控制。 格式无关代码全部放在``ebooks.oeb``文件夹中,(文档未更新)格式有关代码放在``ebooks.format_name``中。

    • 元数据读写下载,放在``ebooks.metadata``中

    • 格式转换发生在管道(pipeline)中。有关该结构可以参看:ref:conversion-introduction。管道包含一个输入插件(plugin),多种转换方法和一个输出插件。构建和驱动管道的代码在:file:plumber.py`中。管道利用一本电子书(未压缩的equb文件)的特征(representation)工作,这里的特征是指像一个包含目录、书脊、toc、指南、html内容等。管理这些特征的类时OEBBook在``ebooks.oeb.base`。在格式转换时所用的的转换方法位于:file:oeb/transforms/*.py。输入与输出插件位于:file:conversion/plugins/*.py

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

  • db – 数据库后端。参考:ref:`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的源码,使用版本控制系统或者直接下载源码 tarball

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

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

在Windows上,你需要完整的路径名,类似于:file:C:\Program Files\Git\git.exe

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

如果你想快速获得源码,你可以直接获得一份最新的`archive <https://calibre-ebook.com/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上`错误跟踪器 <https://bugs.launchpad.net/calibre>`_上的凭证。注意,这样会包含*所有*你所做的提交。如果你只想提交一部分,则必须更改上面的``origin/master`。只发送最后一次提交,使用:

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

上传最后n次提交,用*n*代替*1*。假如提交最后三次提交:

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

当使用``HEAD~n``时,小心不要包含合并。

如果你计划为calibre进行长时间开发,那么你最好创建一个`GitHub <https://github.com>`__账号。下面是一个基本教程,它将引导你建立一个自己的calibre分支。这样你就可以向主calibre仓库提交你的pull请求:

  • 按这篇文章在你的电脑上安装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的 development forum 。在做出重大改变之前,你应该现在论坛中进行讨论或者直接联系Kovid(他的email在源码中可见)。

Windows开发环境

注解

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

正常安装calibre,使用Windows安装器。然后打开命令行(Command Prompt),切换到之前下载的calibre源码目录。举例:

cd C:\Users\kovid\work\calibre

calibre是包含源码和资源子目录的目录。

下一步是将环境变量 CALIBRE_DEVELOP_FROM``设置为src目录的绝对路径。因此,按照上面的示例,它应该是``C:\Users\kovid\work\calibre\src。关于在Windows上设置环境变量,`这里是一个的简短指南<https://docs.python.org/using/windows.html#excursus-setting-environment-variables>`_

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

echo %CALIBRE_DEVELOP_FROM%

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

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

print ("Hello, world!")

现在运行命令 calibredb 。输出的第一行应该就是``Hello, world!`` 。

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

macOS开发环境

注解

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

使用.dmg正常安装calibre。然后打开一个终端,并切换到calibre源码所在路径,举例说明:

cd /Users/kovid/work/calibre

calibre是包含源码和资源子目录的目录。calibre的命令行工具可以在calibre应用包内部找到,在文件 /Applications/calibre.app/Contents/MacOS 中。如果你想使用命令行工具,你需要将该目录添加到PATH环境变量中。

下一个步骤是建立一个bash脚本。该脚本将设置环境变量 CALIBRE_DEVELOP_FROM (源码目录绝对路径)。当以debug模式运行calibre时,该变量会被使用。

创建一个空文件:

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

将该文件保存到 /usr/bin/calibre-develop ,然后为其设置可执行权限:

chmod +x /usr/bin/calibre-develop

一旦你完成上述步骤,然后可以运行:

calibre-develop

当calibre启动时,你最好看终端上的诊断信息。你也应该注意到GUI界面的版本后有一个*号,这表示你从源码运行程序。

Linux开发环境

注解

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

calibre主要开发环境是Linux。你有两种方法配置开发环境。你可以正常安装calibre,在运行时环境下完成开发。这个方法与Windows与macOS开发类似。或者,从源码进行安装calibre。从源码配置开发环境的命令在源码树中的INSTALL文件。接下来我们将使用第一种方法,这也是推荐的方法。

使用二进制安装程序安装calibre。然后打开终端,切换到源码目录,举例:

cd /home/kovid/work/calibre

calibre是包含源码和资源子目录的目录。

下一个步骤是设置环境变量 CALIBRE_DEVELOP_FROM 。该环境变量是源码目录的绝对路径。按上面的例子,该路径为 /home/kovid/work/calibre/src 。怎样设置环境变量取决于你的Linux发行版以及你使用的shell。

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

echo $CALIBRE_DEVELOP_FROM

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

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

print ("Hello, world!")

现在运行命令 calibredb 。输出的第一行应该就是``Hello, world!`` 。

在一台电脑上同时安装正常模式与开发模式的calibre

calibre源码树非常稳定,很少崩溃,但如果你需要从源码运行一个测试库并且你还要运行released版本的calibre作为日常使用。你能方便地通过批处理文件或者shell脚本启动calibre。下面的例子展示如何在Windows上通过批处理文件启动calibre(其他平台的命令也是一样的,只是用shell脚本代替批处理文件)。

用常用库启动release版本的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 -t /path/to/be/edited

使用交互式Python解释器

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

from calibre import ipython
ipython(locals())

从命令行运行时,这将启动一个交互式Python解释器,并可以访问所有本地定义的变量(本地作用域中的变量)。交互式提示符甚至拥有对象属性的TAB补全功能,而且你可以使用Python的内省组件,例如 dir(), type(), repr() 等。

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

你可以从命令行中使用内置的Python调试器作为远程调试器。首先,在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环境下使用调试器

如果IDE支持远程调试,那么在自己的IDE环境下使用内置调试器是可行的。第一步是在你的IDE中添加值为calibre源码的变量 PYTHONPATH。换句话说,就是环境变量 CALIBRE_DEVELOP_FROM ,也必须在你的IDE被设置为 PYTHONPATH

然后把IDE的远程调试器模块放在源码 src 子目录下。添加必要代码用于启动calibre的远程调试器。然后正常运行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模块/软件包。