設定 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 has its roots in the Unix world, which means that its design is highly modular. The modules interact with each other via well defined interfaces. This makes adding new features and fixing bugs in calibre very easy, resulting in a frenetic pace of development. Because of its roots, calibre has a comprehensive command line interface for all its functions, documented in generated/en/cli-index.

模組化設計的思想通過「外掛」體現出來。關於「外掛」的編寫，這裡有一份教程 tutorial。舉個例子，如果要給calibre新增一個新的裝置支援，一般只需要利用裝置驅動外掛範式寫不到100行程式碼即可。你能從獲取`built-in drivers <https://github.com/kovidgoyal/calibre/tree/master/src/calibre/devices>`_。類似地，為新的轉換格式新增支援，也只需要改寫輸入/輸出格式外掛。模組化設計的另一個例子是抓取新聞，recipe system。對於更多可加入calibre的外掛，可以參考 Index of plugins。

代码布局

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

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

    • 更多细节可以参考，: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>`_中提出，你很可能会得到其他开发者的帮助。

得到代码

You can get the calibre source code in two ways, using a version control system or directly downloading a tarball.

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

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

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

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

If you want to get the code faster, the source code for the latest release is always available as an archive.

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

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

This will create a my-changes file in the current folder, simply attach that to a ticket on the calibre bug tracker. Note that this will include all the commits you have made. If you only want to send some commits, you have to change origin/master above. To send only the last commit, use:

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的源码。

Install calibre normally, using the Windows installer. Then open a Command Prompt and change to the previously checked out calibre code folder. For example:

cd C:\Users\kovid\work\calibre

calibre is the folder that contains the src and resources sub-folders.

The next step is to set the environment variable CALIBRE_DEVELOP_FROM to the absolute path of the src folder. So, following the example above, it would be C:\Users\kovid\work\calibre\src. Here is a short guide to setting environment variables on Windows.

一旦您設定了環境變數，您可以開啟一個新的命令行，透過下面的命令檢查環境變數是否設定成功:

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的源码。

Install calibre normally using the provided .dmg. Then open a Terminal and change to the previously checked out calibre code folder, for example:

cd /Users/kovid/work/calibre

calibre is the folder that contains the src and resources sub-folders. The calibre command line tools are found inside the calibre app bundle, in /Applications/calibre.app/Contents/MacOS you should add this folder to your PATH environment variable, if you want to run the command line tools easily.

The next step is to create a bash script that will set the environment variable CALIBRE_DEVELOP_FROM to the absolute path of the src folder when running calibre in debug mode.

创建一个空文件:

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

Save this file as /usr/local/bin/calibre-develop, then set its permissions so that it can be executed:

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

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

calibre-develop

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

Linux开发环境

備註

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

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

Install calibre using the binary installer. Then open a terminal and change to the previously checked out calibre code folder, for example:

cd /home/kovid/work/calibre

calibre is the folder that contains the src and resources sub-folders.

The next step is to set the environment variable CALIBRE_DEVELOP_FROM to the absolute path of the src folder. So, following the example above, it would be /home/kovid/work/calibre/src. How to set environment variables depends on your Linux distribution and what shell you are using.

備註

It is recommended to use the binary installer provided from upstream. Should you insist on using a package provided by your distribution, use the CALIBRE_PYTHON_PATH and CALIBRE_RESOURCES_PATH variables instead.

一旦您設定了環境變數，開啟一個新終端，檢查環境變數是否設定正確，使用命令:

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

Similarly, you can start the E-book viewer as:

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解释器

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

from calibre import ipython
ipython(locals())

When running from the command line, this will start an interactive Python interpreter with access to all locally defined variables (variables in the local scope). The interactive prompt even has Tab completion for object properties and you can use the various Python facilities for introspection, such as dir(), type(), repr(), etc.

使用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环境下使用调试器

It is possible to use the builtin debugger in your favorite Python IDE, if it supports remote debugging. The first step is to add the calibre src checkout to the PYTHONPATH in your IDE. In other words, the folder you set as CALIBRE_DEVELOP_FROM above, must also be in the PYTHONPATH of your IDE.

Then place the IDE's remote debugger module into the src sub-folder of the calibre source code checkout. Add whatever code is needed to launch the remote debugger to calibre at the point of interest, for example in the main function. Then run calibre as normal. Your IDE should now be able to connect to the remote debugger running inside 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文档