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 och devices.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 via conversion.plumber. Formatoberoende kod är alla i ebooks.oeb och formatberoende kod finns i ebooks.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 i ebooks.oeb.base . De olika omvandlingarna som tillämpas på boken under konvertering finns i oeb/transforms/*.py. Och inmatning och utmatning insticksmodul finns i conversion/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’s Innehållsserver.

  • gui2 - Grafiska användargränssnittet. Grafiska gränssnittet initialiseringen händer i gui2.main``och ``gui2.ui. E-bokvisaren finns i gui2.viewer. E-bokredigeraren finns i gui2.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ämtar en ”tarboll” - 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.git

    Ersä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 push

    och 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 på 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.