Opzetten van Calibre in een development omgeving¶
calibre is completely open source, licensed under the GNU GPL v3. This means that you are free to download and modify the program to your heart’s content. In this section, you will learn how to get a calibre development environment set up on the operating system of your choice. calibre is written primarily in Python with some C/C++ code for speed and system interfacing. Note that calibre requires at least Python 3.8.
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 anddevices.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 viaconversion.plumber
. The format independent code is all inebooks.oeb
and the format dependent code is inebooks.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 inebooks.oeb.base
. The various transformations that are applied to the book during conversions live inoeb/transforms/*.py
. And the input and output plugins live inconversion/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
andgui2.ui
. The e-book-viewer is ingui2.viewer
. The e-book editor is ingui2.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.gitReplace <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 pushen 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.