Opzetten van Calibre in een development omgeving¶
calibre is volledig open source, onder de GNU GPL v3 licentie <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 opzetten voor het besturingssysteem van uw keuze. calibre wordt voornamelijk geschreven in Python <https://www.python.org> _ met wat C/C++ code voor snelheid en systeeminterface. Merk op dat calibre minstens Python 3.8 nodig heeft.
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.
Voor details, bekijk:
devices.interface
wat de interface definieert ondersteund door toestel stuurprogramma’s endevices.usbms
wat een generiek stuurprogramma definieert die met een USBMS toestel verbindt. Alle USBMS gebaseerde stuurprogramma’s erven ervan.e-boeken - Alle e-boek conversie/metadata code. Een goed beginpunt is
calibre.ebooks.conversion.cli
, de module die het ebook-convert commando drijft. Het conversieproces wordt gecontroleerd viaconversion.plumber
. De formaat onafhankelijke code zit allemaal inebooks.oeb
en de formaat afhankelijke code inebooks.format_name
.
Metadata lezen, schrijven en downloaden staat allemaal in `` ebooks.metagegevans``
Conversie gebeurt in een pijplijn, voor de structuur van de pijplijn, bekijk Inleiding. De pijplijn bestaat uit een invoerplug-in, verschillende transforms en een uitvoerplug-in. De code die de pijplijn opbouwt en aandrijft zit in
plumber.py
. De pijplijn werkt op een voorstelling van een e-boek als een ontzipte EPUB, met manifest, spine, ToC, gids, HTML inhoud, enz. De class die deze voorstelling beheert is OEBBook inebooks.oeb.base
. De verschillende transformaties toegepast op het boek tijdens conversie wonen inoeb/transforms/*.py
. En de in- en uitvoerplug-in wonen inoeb/transforms/*.py
.E-boek bewerken gebeurt met een ander container object, gedocumenteerd in API documentatie voor e-book bewerking functies.
db - De database achterkant. Bekijk API documentatie voor de gegevensbank interface voor de interface naar de calibre bibliotheek.
Content server:
srv
is de calibre Content server.gui2 - De Grafische Gebruiker Interface. GUI initialisatie gebeurt in
gui2.main
engui2.ui
. De e-boek-viewer zit ingui2.viewer
. De e-book editor ingui2.tweak_book
.
Als u de ingangspunten voor alle calibre executables wilt lokaliseren, bekijk de entry_points
structuur in linux.py.
Als u hulp nodig hebt om de code te begrijpen, post iets in het ontwikkelforum en u zal heel waarschijnlijk hulp krijgen van een van de vele calibre ontwikkelaars.
De code verkrijgen¶
U kan de calibre broncode op twee manieren krijgen, via een versiecontrolesysteem of download direct een tarball.
calibre gebruikt Git, een gedistribueerd versiecontrolesysteem. Git is beschikbaar op alle platformen die calibre ondersteunt. Na installeren van Git kan u de calibre source code krijgen met het commando:
git clone https://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).
Als u de code sneller wilt krijgen, de broncode van de laatste uitgave is altijd beschikbaar als een archive.
Om een vertakking bij te werken naar de nieuwste code, gebruik de volgende opdracht:
git pull --no-edit
U kan ook de code doorbladeren op GitHub.
Uw aanpassingen insturen voor productie¶
Als u enkel een paar kleine veranderingen wilt maken, maak uw veranderingen en creëer een “merge directive” die u dan aan een ticket in de calibre bug tracker kan koppelen. Om dit te doen, maak uw veranderingen , draai dan:
git commit -am "Comment describing your changes"
git format-patch origin/master --stdout > my-changes
Dit creëert een my-changes
bestand in de huidige map, koppel dit gewoon aan een ticket op de calibre bug tracker. Merk op dat dit alle commits die gemaakt hebt meeneemt. Als u slechts enkele commits wil sturen, moet u de origin/master
boven veranderen. Om enkel de laatste commit te sturen, gebruik:
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
.
Als u veel ontwikkelwerk aan calibre wil doen, kan u best een GitHub account creëren. Onder vindt u een basisgids om uw eigen fork van calibre op te zetten die u toelaat pull requests in te dienen voor opname in calibre’s hoofdrepository:
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.gitVervang <username> boven door uw GitHub gebruikersnaam. Dat zorgt ervoor dat uw fork lokaal wordt uitgecheckt.
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
U houdt best een oogje op het calibre ontwikkelforum. Vooraleer grote veranderingen te maken, bespreek ze best in het forum of contacteer Kovid direct (de broncode krioelt van z’n e-mailadres).
Windows ontwikkel omgeving¶
Notitie
U moet ook de calibre broncode apart ophalen zoals beschreven boven.
Installeer calibre normaal met de Windows installer <https://calibre-ebook.com/download_windows>`__. Open dan een Commandoprompt en ga naar de voordien bekeken calibre codemap. Bijvoorbeeld:
cd C:\Users\kovid\work\calibre
calibre is de map die de src bevat en bronnensubmappen.
De volgende stap is de omgevingsvariabele CALIBRE_DEVELOP_FROM
instellen op het absolute pad van de src map. Dus, volgens het voorbeeld boven zou het C:\Users\kovid\work\calibre\src
zijn. Hier is een korte gids <https://docs.python.org/using/windows.html#excursus-setting-environment-variables>`_ over instellen van omgevingsvariabelen in 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%
Deze omgevingsvariabele instellen betekent dat calibre nu alle Python code vanuit de gespecificeerde locatie laadt.
Das alles! U bent nu klaar om de calibre code te beginnen hacken. Bv. open het bestand src\calibre\__init__.py
in uw favoriete editor en voeg volgende regel toe:
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! ``.
U kan ook een calibre ontwikkelomgeving opzetten in het gratis Microsoft Visual Studio, als u wilt, met volgende instructies hier.
macOS ontwikkelomgeving¶
Notitie
U moet ook de calibre broncode apart ophalen zoals beschreven boven.
Installeer calibre normaal met de provided .dmg. Open dan een Terminal en ga naar de voordien bekeken calibre codemap, bijvoorbeeld:
cd /Users/kovid/work/calibre
calibre is de map die de src bevat en bronnensubmappen. de calibre opdrachtregelgereedschappen vindt u in de calibre appbundel, in /Applications/calibre.app/Contents/MacOS
, u voegt deze map best toe aan uw PATH omgevingsvariabele als u de opdrachtregelgereedschappen vlot wilt gebruiken.
De volgende stap is het maken van een bash-script dat de omgevingsvariabele CALIBRE_DEVELOP_FROM
instelt op het absolute pad van de src map bij het uitvoeren van calibre in foutzoekmodus.
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/local/bin/calibre-develop
, stel dan de rechten in zodat het kan worden uitgevoerd:
chmod +x /usr/local/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
U moet ook de calibre broncode apart ophalen zoals beschreven boven.
calibre is voornamelijk in Linux ontwikkeld. U hebt twee keuzes bij instellen van de ontwikkelomgeving. U kan de calibre binary als gewoonlijk installeren en dat als runtime omgeving gebruiken voor uw ontwikkeling. Deze werkwijze is gelijkaardig aan die in Windows en macOS. Als alternatief kan u calibre van de bron installeren. Instructies om een ontwikkelomgeving op te zetten vanuit de bron staan in het INSTALL bestand in de bestandsboom. Hier gaat het over gebruik van de binary als een runtime, wat de aanbevolen methode is.
Installeer calibre met de binary installer. Open dan een Terminal en ga naar de voordien bekeken calibre codemap, bijvoorbeeld:
cd /home/kovid/work/calibre
calibre is de map die de src bevat en bronnensubmappen.
De volgende stap is om de omgevingsvariabele `` CALIBRE_DEVELOP_FROM`` in te stellen op het absolute pad van de src-map. 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.
Notitie
Gebruik van de binaire installer, vanaf stroomopwaarts geleverd, wordt aanbevolen. Staat u erop een pakket te gebruiken uit uw distro, gebruik dan de CALIBRE_PYTHON_PATH
and CALIBRE_RESOURCES_PATH
variabelen.
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
Deze omgevingsvariabele instellen betekent dat calibre nu alle Python code vanuit de gespecificeerde locatie laadt.
Das alles! U bent nu klaar om de calibre code te beginnen hacken. Bv. open het bestand src\calibre\__init__.py
in uw favoriete editor en voeg volgende regel toe:
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! ``.
Afzonderlijke “normale” en “ontwikkel” calibre installaties op dezelfde computer hebben¶
De calibre bronboom is heel stabiel en breekt zelden maar als u de behoefte voelt om vanuit de bron te draaien op een aparte testbibliotheek en de uitgegeven calibre versie met uw dagdagelijkse bibliotheek, kan u dat gemakkelijk met .bat bestanden of shellscripts om calibre te starten. Het voorbeeld onder toont hoe dit te doen in Windows met .bat bestanden (de instructies voor andere platformen zijn hetzelfde, gebruik gewoon een shellscript i.p.v. een .bat bestand).
De releaseversie van calibre lanceren met uw alledaagse bibliotheek
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 een dynamisch getypeerde taal met uitstekend onderdak voor introspectie. Kovid schreef de kern calibre code zonder ook maar één keer een foutzoeker te gebruiken. Er zijn veel strategieën voor foutzoeken in 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
U kan de e-boekviewer ook starten als:
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
Een interactieve Python vertaler gebruiken¶
U kan de volgende twee regels code invoegen om op dat punt een interactieve Python sessie te starten:
from calibre import ipython
ipython(locals())
Bij het uitvoeren van de opdrachtregel start hiermee een interactieve Python vertaler met toegang tot alle lokaal gedefinieerde variabelen (variabelen in de lokale scope). De interactieve prompt heeft zelfs Tab voltooiing voor objecteigenschappen en u kunt de verschillende Python faciliteiten gebruiken voor introspectie, zoals dir()
, type()
, repr()
, enz.
De Python foutzoeker als een externe foutzoeker gebruiken¶
U kan de ingebouwde Python foutzoeker gebruiken (pdb) als een externe foutzoeker vanop de opdrachtregel. Om te beginnen, start de externe foutzoeker op de plaats in de code waar u in geïnteresseerd bent, zoals dit:
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()"
U kan lezen hoe de Python foutzoeker te gebruiken in de Python stdlib docs voor de 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
De Python foutzoeker kan niet met meerdere draadjes overweg, u moet set_trace dus voor elk draadje roepen, elke keer met een ander poortnummer.
De foutzoeker gebruiken in uw favoriete Python IDE¶
Het is mogelijk om de ingebouwde foutzoeker van uw favoriete Python IDE te gebruiken, als hij extern foutzoeken ondersteunt. De eerste stap is toevoegen van de calibre scr checkout aan PYTHONPATH
in uw IDE. M.a.w. de map die u instelde als CALIBRE_DEVELOP_FROM
boven moet ook in PYTHONPATH
van uw IDE staan.
Plaats dan de IDE’s externe foutzoekmodule in de src
submap van de calibre broncode checkout. Voeg de nodige code toe om de externe foutzoeker te starten op het punt van interesse, bv. in de hoofdfunctie. Draai calibre dan als gewoonlijk. Uw IDE zou nu moeten kunnen verbinden met de externe foutzoeker die in calibre draait.
Willekeurige scripts uitvoeren in de calibre Python omgeving¶
Het calibre-debug commando voorziet enkele handige schakelaars om uw eigen code uit te voeren, met toegang tot de calibre modules:
calibre-debug -c "some Python code"
is geweldig om een klein code knipseltje te testen op de commandoregel. Werkt op dezelfde manier als de -c schakelaar naar de Python vertaler:
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¶
Het is mogelijk calibre functies/code direct te gebruiken in uw Python project. Er zijn twee manieren om dit te doen:
Binaire installatie van Calibre¶
Als u een binaire installatie van calibre hebt, kan u de Python vertaler, gebundeld met calibre, zo gebruiken:
calibre-debug /path/to/your/python/script.py -- arguments to your script
Broncode installatie op Linux¶
Bijkomend aan de techniek boven, als u een broninstallatie doet in Linux kan u calibre ook direct importeren, op deze manier:
import init_calibre
import calibre
print(calibre.__version__)
Het is essentieel dat u de init_calibre module importeert voor enige andere calibre modules/packages want het stelt de vertaler in om de calibre code te draaien.