Inrätta en calibre-utvecklingsmiljö¶
calibre har helt öppen källkod, licensierad under GNU GPL v3. Detta innebär att du är fri att hämtar och ändra programmet hur mycket du vill. I det här avsnittet får du lära dig hur du inrättar en calibre-utvecklingsmiljö på valfritt operativsystem. calibre är främst skriven i Python med lite C/C++-kod för hastighet och systemgränssnitt. Observera att calibre kräver minst Python 3.8.
Konstruktionsfilosofi¶
calibre har sina rötter i Unix-världen, vilket innebär att dess design är mycket modulär. Modulerna samverkar med varandra via väl definierade gränssnitt. Detta gör det mycket lätt att lägga till nya funktioner och fixa felproblem i calibre, vilket resulterar i en frenetisk utvecklingstakt. På grund av sina rötter har calibre ett omfattande kommandoradsgränssnitt för alla dess funktioner, dokumenterat i Kommandoradsgränssnitt.
Den modulära uppbyggnaden av calibre uttrycks via Insticksmoduler
. Det finns en tutorial för att skriva calibre insticksmoduler. Till exempel för att lägga till stöd för en ny enhet i calibre behövs vanligtvis att man skriver mindre än 100 rader kod i form av en drivrutininsticksmodul.
Du kan bläddra i inbyggda drivrutiner. På samma sätt lägga till stöd för nya konverteringsformat innebär att skriva inmatning/utmatning formatsinsticksmoduler. Ett annat exempel på modulär design är recipe system för att hämta nyheter. För fler exempel på insticksmoduler designade för att lägga till funktioner till calibre, se det så kallade Index of plugins.
Kodutformning¶
All calibre-pythonkod finns i paketet calibre
. Paketet innehåller följande huvudunderpaket
enheter - Alla drivrutiner. Bara titta igenom några av de inbyggda drivrutiner för att få en uppfattning om hur de fungerar.
För mer information, se:
devices.interface
som definierar gränssnitt stöds av drivrutiner ochdevices.usbms
som definierar en generisk drivrutin som ansluter till en USBMS enhet. Alla USBMS baserade drivrutiner i calibre ärver från den.e-böcker - All e-bokkonvertering/metadatakod. En bra utgångspunkt är
calibre.ebooks.conversion.cli
vilken är modulen som driver ebook-convert kommandot. Konverteringen styrs viaconversion.plumber
. Formatoberoende kod är alla iebooks.oeb
och formatberoende kod finns iebooks.format_name
.
Metadataläsning, skrivning, och hämtning finns i
ebooks.metadata
Konvertering sker i en ”rörledning”, för strukturen av rörledningen, se konversions-introduktion. Rörledningen består av en inmatningsinsticksmodul, olika omvandlingar och en utmatningsinsticksmodul. Den kod som konstruerar och driver rörledningen i
plumber.py
. Rörledningen fungerar på en representation av en e-bok som är som en uppackad EPUB, med manifest, rygg, innehållsförteckning, guide, html innehåll, o.s.v. Den klass som hanterar denna representation är OEBBook iebooks.oeb.base
. De olika omvandlingarna som tillämpas på boken under konvertering finns ioeb/transforms/*.py
. Och inmatning och utmatning insticksmodul finns iconversion/plugins/*.py
.E-bokredigering sker med hjälp av en annat kontainerobjekt. Det är dokumenterat i API-dokumentation för e-bokredigeringsverktygen.
db - Databasens backend. Se API-dokumentation för databasgränssnittet för gränssnittet till calibre-biblioteket.
Innehållsserver:
srv
är calibre Innehållsservern.gui2 - Grafiska användargränssnittet. Grafiska gränssnittet initialiseringen händer i
gui2.main``och ``gui2.ui
. E-bokvisaren finns igui2.viewer
. E-bokredigeraren finns igui2.tweak_book
.
Om du vill hitta startplatser för alla olika calibre körbara delar, titta på entry_points
struktur i linux.py.
Om du behöver hjälp med att förstå koden, skicka inlägg i det så kallade utvecklingsforum <https://www.mobileread.com/forums/forumdisplay.php?f=240>`_ och du kommer sannolikt att få hjälp från en av calibres många utvecklare .
Få koden¶
Du kan hämta calibre-källkoden på två sätt, med hjälp av ett versionshanteringssystem eller direkt hämta en - tarball.
calibre använder Git, ett distribuerat versionshanteringssystem. Git är tillgänglig på alla plattformar som calibre stöder. När du har installerat Git kan du få calibre-källkoden med kommandot:
git clone git://github.com/kovidgoyal/calibre.git
I Windows behöver du den fullständiga sökvägen, som kommer att vara något i stil med C:\Program Files\Git\git.exe
.
calibre är ett mycket stort projekt med en mycket lång källkontrollshistoria, så ovanstående kan ta ett tag (10 minuter till en timme beroende på din internet hastighet).
Om du vill få koden snabbare, är källkoden för den senaste versionen alltid finns som ett arkiv.
För att uppdatera en filial till den senaste koden använder du kommandot:
git pull --no-edit
Du kan också se koden på GitHub.
Skicka in dina ändringar som ska ingå¶
Om du bara planerar att göra några små förändringar kan du göra dina ändringar och skapa ett ”merge direktiv” som du sedan kan fästa på ett ärende i calibre-felhantering. För att göra detta, gör ändringarna, kör då:
git commit -am "Comment describing your changes"
git format-patch origin/master --stdout > my-changes
Detta kommer att skapa en file:my-changes fil i den aktuella katalogen, helt enkelt bifoga det till ett ärende i calibre-felhantering. Observera att detta kommer att omfatta alla de åtgärder du har gjort. Om du bara vill skicka några åtgärder, måste du ändra origin/master
ovan. Om du vill skicka bara den senaste bekräftelsen, använd:
git format-patch HEAD~1 --stdout > my-changes
Om du vill skicka de senaste n ändringar, ersätt 1 med n , till exempel under de senaste 3 ändringarna:
git format-patch HEAD~3 --stdout > my-changes
Var noga med att inte inkludera sammanslagningar när HEAD~n
.
Om du planerar att göra en hel del calibre utveckling, då det bästa sättet är att skapa ett GitHub-konto. Här är en grundläggande guide för att inrätta din egen förgrening av calibre på ett sätt som gör att du kan skicka in pull-förfrågningar för införande i calibre huvudförrådet:
Installering av git på maskinen som beskrivs i denna artikel: Setup Git
Installera ssh nycklar för autentisering till GitHub, som beskrivs här: Generating SSH keys
Gå till https://github.com/kovidgoyal/calibre och klicka på knappen Fork.
I en terminal utför:
git clone git@github.com:<username>/calibre.git git remote add upstream https://github.com/kovidgoyal/calibre.gitErsätt <username> ovan med ditt användarnamn på Github. Det kommer att få din förgrening kontrollerad lokalt.
Du kan göra ändringar och överlämna dem när du vill. När du är redo att ha ditt arbete ihopslaget, gör en:
git pushoch gå till
https://github.com/<username>/calibre
och klicka på knappen Pull Request för att generera en hämtningsbegäran som kan sammanfogas.Du kan uppdatera din lokala kopia med kod från huvudarkivet när som helst genom att göra:
git pull upstream
Du bör också hålla ett öga på calibres utvecklingsforum. Innan du gör stora ändringar bör du diskutera dem i forumet eller kontakta Kovid direkt (hans e-postadress är över hela källkoden).
Windows-utvecklingsmiljö¶
Observera
Du måste också hämta calibre källkod separat som beskrivet ovan.
Installera calibre normalt, med hjälp av installationsprogrammet för Windows. Öppna sedan en kommandotolk och ändra till den tidigare kontrollerade calibre kodkatalogen. Till exempel:
cd C:\Users\kovid\work\calibre
calibre är den katalog som innehåller src och resurser undermappar.
Nästa steg är att ställa in miljövariabeln CALIBRE_DEVELOP_FROM
till den absoluta sökvägen för src-katalogen. Så efter exemplet ovan skulle det vara C:\Users\kovid\work\calibre\src
. Här är en kort guide för att ställa in miljövariabler i Windows.
När du har ställt in miljövariabeln, öppna en ny kommandotolk och kontrollera att den blev rätt inställd med kommandot:
echo %CALIBRE_DEVELOP_FROM%
Ställa denna miljövariabel innebär att calibre kommer nu läsa in all sin Pythonkod från den angivna platsen.
Det är allt! Du är nu redo att börja hacka på calibre koden. Till exempel öppna filen src\calibre\__init__.py
i din favorit redigerare och lägg till raden:
print ("Hello, world!")
nära toppen av filen. Nu kör kommandot calibredb . Den allra första raden av produktionen bör vara Hej världen! .
Du kan också konfigurera en calibre-utvecklingsmiljö i den fria Microsoft Visual Studio, om man så vill, att följa instruktionerna här.
macOS-utvecklingsmiljö¶
Observera
Du måste också hämta calibre källkod separat som beskrivet ovan.
Installera calibre normalt med den medföljande .dmg. Öppna sedan en terminal och ändra till den tidigare kontrollerade calibre kodkatalogen, till exempel:
cd /Users/kovid/work/calibre
calibre är mappen som innehåller src och resources underkatalogerna. Kommandoradsverktygen för calibre finns i calibre-app-paketet, i /Applications/calibre.app/Contents/MacOS
bör du lägga till den här katalogen till din PATH-miljövariabel, om du enkelt vill kunna köra kommandoradsverktygen.
Nästa steg är att skapa ett bash skript som kommer att sätta miljövariabeln CALIBRE_DEVELOP_FROM
till den absoluta sökvägen till katalogen src när man kör calibre i felsökningsläge.
Skapa en fil med oformaterad text:
#!/bin/sh
export CALIBRE_DEVELOP_FROM="/Users/kovid/work/calibre/src"
calibre-debug -g
Spara den här filen som /usr/bin/calibre-develop
, ställ sedan in dess rättigheter så att den kan köras:
chmod +x /usr/bin/calibre-develop
När du har gjort det, kör:
calibre-develop
Du bör se en del diagnostisk information i terminalfönstret när calibre startar, och du bör se en asterisk efter versionsnumret i grafiska gränssnittsfönstret, vilket indikerar att du kör från källkod.
Linux-utvecklingsmiljö¶
Observera
Du måste också hämta calibre källkod separat som beskrivet ovan.
calibre är främst utvecklat i Linux. Du har två val i inrättandet av utvecklingsmiljön. Du kan installera calibre-binär som vanligt och använda det som en drifttidsmiljö för att göra din utveckling. Detta tillvägagångssätt liknar den som används i Windows och macOS. Alternativt kan du installera calibre från källan. Instruktioner för hur du installerar en utvecklingsmiljö från källan är i installationsfilen i källkodsträdet. Här kommer vi att ta itu med den binär som en körbar, vilket är den rekommenderade metoden.
Installera calibre att använda den binära installationsprogrammet. Öppna sedan en terminal och ändra till den tidigare kontrollerade calibre kodkatalogen, till exempel:
cd /home/kovid/work/calibre
calibre är den katalog som innehåller src och resurser undermappar.
Nästa steg är att ställa in miljövariabeln CALIBRE_DEVELOP_FROM
till den absoluta sökvägen till src katalog. Så, efter exemplet ovan skulle det vara /home/kovid/work/calibre/src
. Så ställer du in miljövariabler beror i din Linux-distribution och vad kommandoskal du använder.
När du har ställt in miljövariabeln, öppna en ny terminal och kontrollera att den blev rätt inställd med kommandot:
echo $CALIBRE_DEVELOP_FROM
Ställa denna miljövariabel innebär att calibre kommer nu läsa in all sin Pythonkod från den angivna platsen.
Det är allt! Du är nu redo att börja hacka på calibre-koden. Till exempel öppna filen src/calibre/__init__.py
i din favorit redigerare och lägg till raden:
print ("Hello, world!")
nära toppen av filen. Nu kör kommandot calibredb . Den allra första raden av produktionen bör vara Hej världen! .
Att ha separata ”normala” och ”utvecklings” calibre-installationer på samma dator¶
calibre källkodsträd är mycket stabila och sällan brytes sönder, men om du känner behov av att köras från källan på ett separat testbibliotek och kör släppt calibre version med ditt vardagliga biblioteket kan du uppnå detta enkelt med hjälp bat-filer eller skalskript för att starta calibre. Exemplet nedan visar hur man gör detta på Windows med bat-filer (instruktionerna för andra plattformar är samma, bara använda ett skalskript istället för en bat-fil)
För att starta den utgivna versionen av calibre med din vardagliga biblioteket:
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"
Felsökningstips¶
Python är ett dynamiskt typat språk med utmärkta faciliteter för introspektion. Kovid skrev kärndelar av calibrekod utan en gång med hjälp av ett avlusningsprogram. Det finns många strategier för att felsöka calibre-kod:
Använda skrivsatser¶
Det här är Kovids favorit sätt att felsöka. Sätt bara in utskrift-satser vid intressanta punkter och köra ditt program i terminalen. Till exempel kan du starta grafiska gränssnittet från terminalen som:
calibre-debug -g
På samma sätt kan du starta E-bokvisaren med:
calibre-debug -w /path/to/file/to/be/viewed
E-bokredigeraren kan startas som:
calibre-debug -t /path/to/be/edited
Med hjälp av en interaktiv Python-tolk¶
Du kan infoga följande två rader kod för att starta en interaktiv Python-session på den punkten:
from calibre import ipython
ipython(locals())
När du kör från kommandoraden, kommer detta att starta en interaktiv python-tolk med tillgång till alla lokalt definierade variabler (variabler i den lokala omfattning). Den interaktiva prompten har till och med TAB komplettering för objektegenskaper och du kan använda de olika python-finnesser för introspektion, såsom dir()
, type()
, repr()
, o.s.v.
Använda Python-felsökaren som fjärrfelsökare¶
Du kan använda den inbyggda Python-felsökaren (PDB) som fjärrfelsökare från kommandoraden. Först startar fjärrfelsökaren vid den punkt i calibre koden du är intresserad av, så här:
from calibre.rpdb import set_trace
set_trace()
Kör sedan calibre, antingen som vanligt, eller använda någon av calibre felsökningskommandon som beskrivs i föregående avsnitt. När ovanstående punkt i koden är nådd kommer calibre frysa, väntar på felsökaren för att ansluta.
Nu öppna en terminal eller kommandotolk och använd följande kommando för att starta felsökningssessionen:
calibre-debug -c "from calibre.rpdb import cli; cli()"
Du kan läsa om hur man använder Python-felsökaren i Python stdlib docs för pdb-modulen.
Observera
Som standard kommer fjärrfelsökaren försöker ansluta på port 4444. Du kan ändra det, genom att skicka portparametern till både set_trace()- och cli()-funktioner ovan, så här: set_trace(port=1234)
och cli(port=1234)
.
Observera
Python-felsökaren kan inte hantera flera trådar, så du måste anropa set_trace en gång per tråd, varje gång med ett annat portnummer.
Använda felsökaren i din favorit Python-IDE¶
Det är möjligt att använda den inbyggda felsökaren i din favorit Python-IDE, om den stöder fjärrfelsökning. Det första steget är att lägga till utcheckat calibre src till PYTHONPATH
i IDE. Med andra ord, den katalog du anger som CALIBRE_DEVELOP_FROM
måste ovan, också vara i PYTHONPATH
din IDE.
Placera sedan IDE-fjärrfelsökarmodulen i src
-underkatalogen i calibre-källkoden. Lägg allt vilken kod som behövs för att starta fjärrfelsökaren i calibre vid intressepunkten, till exempel i huvudfunktionen. Kör sedan calibre som vanligt. Din IDE bör nu kunna ansluta till fjärrfelsökaren som körs inuti calibre.
Kör godtyckliga skript i calibre-Python-miljön¶
calibre-debug-kommandot ger ett par praktiska flaggor för att köra egen kod, med tillgång till calibre moduler:
calibre-debug -c "some Python code"
är bra för att testa ett litet texturval på kommandoraden. Det fungerar på samma sätt som den -c flaggan till Python-tolken:
calibre-debug myscript.py
kan användas för att köra din egen Python-skript. Det fungerar på samma sätt som att skicka skriptet till Python-tolken, förutom att calibre miljön är helt initierad, så att du kan använda all calibre kod i skriptet. För att använda kommandoradsargument med ditt manus, använd formuläret:
calibre-debug myscript.py -- --option1 arg1
Den --
leder till att alla efterföljande argument skickas till ditt skript.
Använda calibre i dina projekt¶
Det är möjligt att direkt använda calibrefunktioner/kod i Python-projektet. Två sätt finns för att göra detta:
Binär installation av calibre¶
Om du har en binär installation av calibre, kan du använda Python-tolken som medföljer calibre, så här:
calibre-debug /path/to/your/python/script.py -- arguments to your script
Installera källkod i Linux¶
Förutom att använda ovanstående teknik, om du gör en källkodsinstallation i Linux, kan du också direkt importera calibre, enligt följande:
import init_calibre
import calibre
print calibre.__version__
Det är viktigt att du importerar init_calibre modulen innan någon annan calibre modules/packages som det sätter upp tolken att köra calibre kod.