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 en devices.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 via conversion.plumber. De formaat onafhankelijke code zit allemaal in ebooks.oeb en de formaat afhankelijke code in ebooks.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 in ebooks.oeb.base. De verschillende transformaties toegepast op het boek tijdens conversie wonen in oeb/transforms/*.py. En de in- en uitvoerplug-in wonen in oeb/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 en gui2.ui. De e-boek-viewer zit in gui2.viewer. De e-book editor in gui2.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.git

    Vervang <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 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

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

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. You can get these by running calibre-debug --paths. But note that distribution calibre packages are often terminally broken and are completely unsupported.

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.

API installatie voor diverse onderdelen van Calibre