Opzetten van Calibre in een development omgeving

Calibre is volledig open source, gelicenseerd onder de GNU GPL v3 <https://www.gnu.org/licenses/gpl.html> _. Dit betekent dat u vrij bent om het programma naar hartenlust te downloaden en aan te passen. In dit gedeelte leert u hoe u een Calibre ontwikkelingsomgeving kunt instellen voor het besturingssysteem van uw keuze. Calibre wordt voornamelijk geschreven in Python <https://www.python.org> _ met enkele C/C++ code voor snelheid en systeeminterface. Merk op dat Calibre niet compatibel is met Python 3 en op zijn minst Python 2.7.9 vereist.

Ontwerp filosofie

Calibre heeft zijn wortels in de Unix-wereld, wat betekent dat het design bijzonder modulair is. De modules werken samen met elkaar via precies gedefinieerde interfaces. Hierdoor wordt het toevoegen van nieuwe features en het oplossen van bugs in Calibre erg eenvoudig, wat resulteert in een snel ontwikkelingstempo. Vanwege deze wortels heeft Calibre een uitgebreide command line interface voor al zijn functies, welke gedocumenteerd zijn in Opdrachtpromt.

Het modulaire ontwerp van Calibre wordt uitgedrukt via `` Plugins``. Er is een: ref :handleiding <customize> over het schrijven van Calibre plug-ins. Als u bijvoorbeeld ondersteuning toevoegt voor een nieuw Calibre apparaat, heeft dit meestal betrekking op het schrijven van minder dan 100 regels code in de vorm van een plug-in voor apparaatstuurprogramma’s. U kunt bladeren door de ingebouwde stuurprogramma’s. Op dezelfde manier houdt het toevoegen van ondersteuning voor nieuwe conversie-indelingen het schrijven van invoeg- / uitvoerformatenplug-ins in. Een ander voorbeeld van het modulaire ontwerp is de: ref: receptuursysteem <news> voor het ophalen van nieuws. Zie de Index van plug-ins <https://www.mobileread.com/forums/showthread.php?p=1362767#post1362767> _ voor meer voorbeelden van plug-ins die zijn ontworpen om functies aan Calibre toe te voegen.

Code opmaak

Alle de Calibre python code staat in het Calibre pakket. Dit pakket bevat de volgende hoofddeel pakketten

  • apparaten - Alle apparaatstuurprogramma’s. Bekijk enkele van de ingebouwde stuurprogramma’s om een ​​idee te krijgen hoe ze werken.

    • For details, see: devices.interface which defines the interface supported by device drivers and devices.usbms which defines a generic driver that connects to a USBMS device. All USBMS based drivers in calibre inherit from it.

  • e-books - All the e-book conversion/metadata code. A good starting point is calibre.ebooks.conversion.cli which is the module powering the ebook-convert command. The conversion process is controlled via conversion.plumber. The format independent code is all in ebooks.oeb and the format dependent code is in ebooks.format_name.

    • Metagegevens lezen, schrijven en downloaden staat allemaal in `` ebooks.metagegevans``
    • Conversion happens in a pipeline, for the structure of the pipeline, see Inleiding. The pipeline consists of an input plugin, various transforms and an output plugin. The code that constructs and drives the pipeline is in plumber.py. The pipeline works on a representation of an e-book that is like an unzipped epub, with manifest, spine, toc, guide, html content, etc. The class that manages this representation is OEBBook in ebooks.oeb.base. The various transformations that are applied to the book during conversions live in oeb/transforms/*.py. And the input and output plugins live in conversion/plugins/*.py.
    • E-book editing happens using a different container object. It is documented in API documentatie voor e-book bewerking functies.

  • db - The database back-end. See API documentatie voor de gegevensbank interface for the interface to the calibre library.

  • Content server: srv is the calibre Content server.

  • gui2 - The Graphical User Interface. GUI initialization happens in gui2.main and gui2.ui. The e-book-viewer is in gui2.viewer. The e-book editor is in gui2.tweak_book.

If you want to locate the entry points for all the various calibre executables, look at the entry_points structure in linux.py.

If you need help understanding the code, post in the development forum and you will most likely get help from one of calibre’s many developers.

De code verkrijgen

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

calibre uses Git, a distributed version control system. Git is available on all the platforms calibre supports. After installing Git, you can get the calibre source code with the command:

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

Op Windows heb je de volledige padnaam nodig, dat zal ongeveer zo zijn: bestand: C:\Program Files\Git\git.exe.

Calibre is een zeer groot project met een zeer lange versiebeheergeschiedenis, dus het bovenstaande kan een tijd duren (10 minuten tot een uur, afhankelijk van je internetsnelheid).

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

Om een ​​vertakking bij te werken naar de nieuwste code, gebruik de volgende opdracht:

git pull --no-edit

You can also browse the code at GitHub.

Uw aanpassingen insturen voor productie

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 directory, 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

Als u de laatste n commentaren wilt verzenden, vervangt u 1 door n, bijvoorbeeld voor de laatste 3 commentaren:

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

Zorg dat u geen samenvoegingen opneemt bij het gebruik van 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:

  • Stel git in op uw machine zoals beschreven in dit artikel: Setup Git

  • Stel ssh-sleutels in voor authenticatie naar GitHub, zoals hier beschreven: SSH-sleutels genereren <https://help.github.com/articles/generating-ssh-keys> _

  • Ga naar https://github.com/kovidgoyal/Calibre en klik op de Fork button.

  • In een terminalvenster doe:

    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.

  • U kunt wijzigingen aanbrengen en deze toewijzen wanneer u maar wilt. Wanneer je klaar bent om je werk samen te voegen, doe dan een:

    git push

    en ga naar https://github.com/<username>/Calibre en klik op Pull Request button om een pull request te generen die samengevoegd kan worden.

  • U kunt uw lokale exemplaar op elk gewenst moment bijwerken met code van de hoofdrepo door te doen:

    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).

Windows ontwikkel omgeving

Notitie

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 directory. For example:

cd C:\Users\kovid\work\calibre

Calibre is de map die de subdirectory’s src en resources bevat.

The next step is to set the environment variable CALIBRE_DEVELOP_FROM to the absolute path of the src directory. 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.

Nadat u de omgevingsvariabele hebt ingesteld, opent u een nieuwe opdrachtprompt en controleert u of deze correct is ingesteld met de opdracht:

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!")

in de buurt van de bovenkant van het bestand. Voer nu de opdracht: opdracht uit: calibredb. De allereerste regel van de uitvoer zou moeten zijn `` Hallo, wereld! ``.

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

macOS development environment

Notitie

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 directory, for example:

cd /Users/kovid/work/calibre

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

De volgende stap is het maken van een bash-script dat de omgevingsvariabele `` CALIBRE_DEVELOP_FROM`` op het absolute pad van de src-locatie plaatst bij het uitvoeren van Calibre in debug-modus.

Maak een platte-tekst bestand:

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

Sla dit bestand op als /usr/bin/Calibre-develop, stel vervolgens de rechten in zodat het kan worden uitgevoerd:

chmod +x /usr/bin/calibre-develop

Als u dit heeft gedaan, voer uit:

calibre-develop

U zou wat diagnostische informatie in het Terminal-venster moeten zien als Calibre opstart, en u zou een asterisk na het versienummer in het GUI-venster moeten zien, om aan te geven dat u vanuit de bron loopt.

Linux ontwikkel omgeving

Notitie

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 directory, for example:

cd /home/kovid/work/calibre

Calibre is de map die de subdirectory’s src en resources bevat.

De volgende stap is om de omgevingsvariabele `` CALIBRE_DEVELOP_FROM`` in te stellen op het absolute pad van de src-locatie. Dus, in navolging van het bovenstaande voorbeeld, zou het /home/kovid/work/Calibre/src zijn. Het instellen van omgevingsvariabelen is afhankelijk van je Linux-distributie en welke shell je gebruikt.

Nadat u de omgevingsvariabele hebt ingesteld, opent u een nieuwe terminal en controleert u of deze correct is ingesteld met de opdracht:

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!")

in de buurt van de bovenkant van het bestand. Voer nu de opdracht: opdracht uit: calibredb. De allereerste regel van de uitvoer zou moeten zijn `` Hallo, wereld! ``.

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"

Debug 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:

Gebruik van print statements

Dit is de favoriete manier van Kovid om te debuggen. Voeg eenvoudig afdrukinstructies in op interessante plaatsen en voer uw programma uit in de terminal. U kunt de GUI bijvoorbeeld vanuit de terminal starten als:

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 -t /path/to/be/edited

Using an interactive Python interpreter

You can insert the following two lines of code to start an interactive Python session at that point:

from calibre import ipython
ipython(locals())

Bij het uitvoeren van de opdrachtregel start hiermee een interactieve Python-interpreter met toegang tot alle lokaal gedefinieerde variabelen (variabelen in de lokale scope). De interactieve prompt heeft zelfs TAB-voltooiing voor objecteigenschappen en je kunt de verschillende Python-faciliteiten gebruiken voor introspectie, zoals: func: dir, :func:` type`, repr(), etc.

Using the Python debugger as a remote debugger

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()

Voer vervolgens Calibre uit, hetzij als normaal, of met behulp van een van de Calibre-debug-opdrachten die in de vorige sectie zijn beschreven. Zodra het bovenstaande punt in de code is bereikt, zal Calibre bevriezen, wachtend totdat de foutopsporing verbinding maakt.

Open nu een terminal of opdrachtprompt en gebruik de volgende opdracht om de foutopsporingssessie te starten:

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.

Notitie

Standaard probeert de debugger op afstand verbinding te maken op poort 4444. Je kunt dit wijzigen door de parameter port naar zowel de set_trace() als de cli() -functies hierboven door te geven, zoals deze: set_trace(port=1234)``en``cli(port = 1234).

Notitie

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

Using the debugger in your favorite Python 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 directory 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 subdirectory 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

kan worden gebruikt om je eigen Python-script uit te voeren. Het werkt op dezelfde manier als het doorgeven van het script aan de Python-interpreter, behalve dat de Calibre omgeving volledig is geïnitialiseerd, zodat u alle Calibre code in uw script kunt gebruiken. om opdrachtregelargumenten te gebruiken met uw script, gebruik de vorm:

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

De `` –`` zorgt ervoor dat alle volgende argumenten aan je script worden doorgegeven.

Calibre gebruiken in uw projecten

It is possible to directly use calibre functions/code in your Python project. Two ways exist to do this:

Binaire installatie van 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

Broncode installatie op 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.