Configurando um ambiente de desenvolvimento do calibre

calibre é completamente open source, licenciado sob o ‘GNU GPL v3 <https://www.gnu.org/licenses/gpl.html>’_. Isso significa que você é livre para baixar e modificar o programa para o conteúdo do seu coração. Nesta seção, você aprenderá como configurar um ambiente de desenvolvimento de calibre no sistema operacional de sua escolha. calibre é escrito principalmente em ‘Python <https://www.python.org>’_ com algum código C/C++ para velocidade e interface do sistema. Note que o calibre requer pelo menos Python 3.8.

Filosofia de desenvolvimento

O Calibre tem as suas raízes no mundo Unix, o que se traduz por um design altamente modular. Os módulos interagem uns com os outros através de interfaces bem definidas. Tal torna o adicionar de novas funcionalidades e a correção de erros de programação muito fáceis no Calibre, resultando num ritmo frenético de desenvolvimento. Por causa das suas raízes, o Calibre tem uma interface de linha de comando muito completa para todas as suas funções, documentadas em generated/pt/cli-index.

O design modular do calibre é expresso através de ‘’Plugins’’. Há um :ref:’tutorial <customize>’ sobre a escrita de plugins de calibre. Por exemplo, adicionar suporte para um novo dispositivo ao calibre normalmente envolve escrever menos de 100 linhas de código na forma de um plug-in de driver de dispositivo. Você pode navegar pelo ‘built-in drivers <https://github.com/kovidgoyal/calibre/tree/master/src/calibre/devices>’_. Da mesma forma, adicionar suporte para novos formatos de conversão envolve escrever plugins de formato de entrada/saída. Outro exemplo do design modular é o sistema :ref:’recipe <news>’ para buscar notícias. Para obter mais exemplos de plug-ins projetados para adicionar recursos ao calibre, consulte o ‘Índice de plug-ins <https://www.mobileread.com/forums/showthread.php?p=1362767#post1362767>’_.

Layout do código

Todo o código Python calibre está no pacote ‘’calibre’’. Este pacote contém os seguintes subpacotes principais

  • dispositivos - Todos os drivers de dispositivo. Olhe alguns dos drivers embutidos para ter uma ideia de como eles funcionam.

    • Para obter detalhes, consulte: ‘’devices.interface’’ que define a interface suportada por drivers de dispositivo e ‘’devices.usbms’’ que define um driver genérico que se conecta a um dispositivo USBMS. Todos os drivers baseados em USBMS em calibre herdam dele.

  • e-books - Todo o código de conversão/metadados do e-book. Um bom ponto de partida é ‘’calibre.ebooks.conversion.cli’’, que é o módulo que alimenta o comando :command:’ebook-convert’. O processo de conversão é controlado através de ‘’conversion.plumber’’. O código independente de formato está todo em ‘’ebooks.oeb’’ e o código dependente de formato está em ‘’ebooks.format_name’’.

    • A leitura, escrita e download de metadados estão em ebooks.metadata

    • A conversão acontece em um pipeline, para a estrutura do pipeline, veja :ref:’conversion-introduction’. O pipeline consiste em um plugin de entrada, várias transformações e um plugin de saída. O código que constrói e conduz o pipeline está em :file:’plumber.py’. O pipeline funciona em uma representação de um e-book que é como um epub descompactado, com manifesto, coluna, toc, guia, conteúdo html, etc. A classe que gerencia essa representação é OEBBook em ‘’ebooks.oeb.base’’. As várias transformações que são aplicadas ao livro durante as conversões vivem em :file:’oeb/transforms/.py’. E os plugins de entrada e saída vivem em :file:’conversion/plugins/.py’.

    • A edição de e-book acontece usando um objeto de contêiner diferente. Está documentado em :ref:’polish_api’.

  • db - O back-end do banco de dados. Consulte :ref:’db_api’ para a interface com a biblioteca de calibre.

  • Servidor de conteúdo: ‘’srv’’ é o servidor de conteúdo de calibre.

  • gui2 - A Interface Gráfica do Usuário. A inicialização da GUI acontece em ‘’gui2.main’’ e ‘’gui2.ui’’. O e-book-viewer está em ‘’gui2.viewer’’. O editor de e-book está em ‘’gui2.tweak_book’’.

Se você quiser localizar os pontos de entrada para todos os vários executáveis de calibre, observe a estrutura ‘’entry_points’’ em ‘linux.py <https://github.com/kovidgoyal/calibre/blob/master/src/calibre/linux.py>’_.

Se você precisar de ajuda para entender o código, poste no ‘fórum de desenvolvimento <https://www.mobileread.com/forums/forumdisplay.php?f=240>’_ e você provavelmente receberá ajuda de um dos muitos desenvolvedores do calibre.

Obtendo o código

Você pode obter o código-fonte do calibre de duas maneiras, usando um sistema de controle de versão ou baixando diretamente um :website_base:’tarball <dist/src>’.

calibre usa ‘Git <https://www.git-scm.com/>’_, um sistema de controle de versão distribuído. O Git está disponível em todas as plataformas suportadas. Depois de instalar o Git, você pode obter o código-fonte do calibre com o comando:

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

No Windows, você precisará do nome completo do caminho, que será algo como :file:’C:\Arquivos de Programas\Git\git.exe’.

O calibre é um projeto muito grande com um histórico de controle de fonte muito longo, então o acima pode levar um tempo (10 minutos a uma hora, dependendo da velocidade da sua internet).

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

To update a branch to the latest code, use the command:

git pull --no-edit

Também é possível navegar pelo código no GitHub.

Enviando suas alterações para serem incluídas

If you only plan to make a few small changes, you can make your changes and create a “merge directive” which you can then attach to a ticket in the calibre bug tracker. To do this, make your changes, then run:

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

To send the last n commits, replace 1 with n, for example, for the last 3 commits:

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

Be careful to not include merges when using HEAD~n.

If you plan to do a lot of development on calibre, then the best method is to create a GitHub account. Below is a basic guide to setting up your own fork of calibre in a way that will allow you to submit pull requests for inclusion into the main calibre repository:

  • Setup git on your machine as described in this article: Setup Git

  • Setup ssh keys for authentication to GitHub, as described here: Generating SSH keys

  • Go to https://github.com/kovidgoyal/calibre and click the Fork button.

  • Em um Terminal faça:

    git clone git@github.com:<username>/calibre.git
git remote add upstream https://github.com/kovidgoyal/calibre.git

    Replace <username> above with your GitHub username. That will get your fork checked out locally.

  • You can make changes and commit them whenever you like. When you are ready to have your work merged, do a:

    git push

    and go to https://github.com/<username>/calibre and click the Pull Request button to generate a pull request that can be merged.

  • You can update your local copy with code from the main repo at any time by doing:

    git pull upstream

You should also keep an eye on the calibre development forum. Before making major changes, you should discuss them in the forum or contact Kovid directly (his email address is all over the source code).

Ambiente de Desenvolvimento Windows

Nota

You must also get the calibre source code separately as described above.

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.

Once you have set the environment variable, open a new command prompt and check that it was correctly set by using the command:

echo %CALIBRE_DEVELOP_FROM%

Setting this environment variable means that calibre will now load all its Python code from the specified location.

That’s it! You are now ready to start hacking on the calibre code. For example, open the file src\calibre\__init__.py in your favorite editor and add the line:

print("Hello, world!")

near the top of the file. Now run the command calibredb. The very first line of output should be Hello, world!.

You can also setup a calibre development environment inside the free Microsoft Visual Studio, if you like, following the instructions here.

ambiente de desenvolvimento no macOS

Nota

You must also get the calibre source code separately as described above.

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.

Crie um arquivo de texto simples:

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

Guardar este ficheiro como /usr/local/bin/calibre-develop, e depois defina as suas permissões para que possa ser executado:

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

Depois de fazer isso, execute:

calibre-develop

You should see some diagnostic information in the Terminal window as calibre starts up, and you should see an asterisk after the version number in the GUI window, indicating that you are running from source.

Ambiente de Desenvolvimento Linux

Nota

You must also get the calibre source code separately as described above.

calibre is primarily developed on Linux. You have two choices in setting up the development environment. You can install the calibre binary as normal and use that as a runtime environment to do your development. This approach is similar to that used in Windows and macOS. Alternatively, you can install calibre from source. Instructions for setting up a development environment from source are in the INSTALL file in the source tree. Here we will address using the binary as a runtime, which is the recommended method.

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.

Nota

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.

Depois de definir a variável de ambiente, abra uma nova janela de terminal e verifique se foi configurado corretamente usando o comando:

echo $CALIBRE_DEVELOP_FROM

Setting this environment variable means that calibre will now load all its Python code from the specified location.

That’s it! You are now ready to start hacking on the calibre code. For example, open the file src/calibre/__init__.py in your favorite editor and add the line:

print("Hello, world!")

near the top of the file. Now run the command calibredb. The very first line of output should be Hello, world!.

Having separate “normal” and “development” calibre installs on the same computer

The calibre source tree is very stable and rarely breaks, but if you feel the need to run from source on a separate test library and run the released calibre version with your everyday library, you can achieve this easily using .bat files or shell scripts to launch calibre. The example below shows how to do this on Windows using .bat files (the instructions for other platforms are the same, just use a shell script instead of a .bat file)

To launch the release version of calibre with your everyday library:

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"

Debugging tips

Python is a dynamically typed language with excellent facilities for introspection. Kovid wrote the core calibre code without once using a debugger. There are many strategies to debug calibre code:

Usando declarações print()

This is Kovid’s favorite way to debug. Simply insert print statements at points of interest and run your program in the terminal. For example, you can start the GUI from the terminal as:

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

Usando um interpretador Python interativo

É possível inserir as duas linhas de código a seguir para iniciar uma sessão Python interativa nesse ponto:

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.

Usando o depurador Python como depurador remoto

You can use the builtin Python debugger (pdb) as a remote debugger from the command line. First, start the remote debugger at the point in the calibre code you are interested in, like this:

from calibre.rpdb import set_trace
set_trace()

Then run calibre, either as normal, or using one of the calibre-debug commands described in the previous section. Once the above point in the code is reached, calibre will freeze, waiting for the debugger to connect.

Agora abra uma janela de terminal ou Prompt de Comando e use o seguinte comando para iniciar a sessão de depuração:

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

You can read about how to use the Python debugger in the Python stdlib docs for the pdb module.

Nota

By default, the remote debugger will try to connect on port 4444. You can change it, by passing the port parameter to both the set_trace() and the cli() functions above, like this: set_trace(port=1234) and cli(port=1234).

Nota

The Python debugger cannot handle multiple threads, so you have to call set_trace once per thread, each time with a different port number.

Usar o depurador no seu IDE Python favorito

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.

Executing arbitrary scripts in the calibre Python environment

The calibre-debug command provides a couple of handy switches to execute your own code, with access to the calibre modules:

calibre-debug -c "some Python code"

is great for testing a little snippet of code on the command line. It works in the same way as the -c switch to the Python interpreter:

calibre-debug myscript.py

can be used to execute your own Python script. It works in the same way as passing the script to the Python interpreter, except that the calibre environment is fully initialized, so you can use all the calibre code in your script. To use command line arguments with your script, use the form:

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

The -- causes all subsequent arguments to be passed to your script.

Usando o Calibre em seus projetos

É possível usar funções/código do Calibre diretamente em seu projeto Python. Existem duas maneiras de fazer isso:

Instalação binária de Calibre

If you have a binary install of calibre, you can use the Python interpreter bundled with calibre, like this:

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

Instalação de Origem no Linux

In addition to using the above technique, if you do a source install on Linux, you can also directly import calibre, as follows:

import init_calibre
import calibre

print(calibre.__version__)

It is essential that you import the init_calibre module before any other calibre modules/packages as it sets up the interpreter to run calibre code.

API documentation for various parts of calibre