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 rätta problem 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 handledning om 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 enhetsdrivrutininsticksmodul. Du kan bläddra bland de inbyggda drivrutinerna. På samma sätt, för att lägga till stöd för nya konverteringsformat innebär det att skriva inmatnings-/utmatningsformatsinsticksmoduler. Ett annat exempel på den modulära designen är receptsystemet för att hämta nyheter. För fler exempel på insticksmoduler som är utformade för att lägga till funktioner i calibre, se Index of plugins.

Kodutformning

All calibre-Pythonkod finns i paketet calibre. Paketet innehåller följande huvudunderpaket

  • enheter - Alla enhetsdrivrutiner. Titta bara igenom några av de inbyggda drivrutinerna 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 process, för strukturen av processen, se Introduktion. Processen består av en inmatningsinsticksmodul, olika omvandlingar och en utmatningsinsticksmodul. Koden som konstruerar och driver processen i plumber.py. Processen fungerar på en representation av en e-bok som är som en uppackad EPUB, med manifest, bokrygg, innehållsförteckning, guide, html-innehåll, etc. Klassen som hanterar den här representationen är OEBBook i ebooks.oeb.base . De olika omvandlingarna som tillämpas på boken under konvertering finns i oeb/transforms/*.py. Och in- och utmatningsinsticksmodulerna 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-innehållsservern.

  • 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-strukturen i linux.py.

Om du behöver hjälp med att förstå koden, skicka inlägg i det så kallade utvecklingsforumet <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 https://github.com/kovidgoyal/calibre.git

I Windows behöver du det fullständiga sökvägsnamnet 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ällkontrollshistorik, så ovanstående kan ta ett tag (10 minuter till en timme beroende på din internet hastighet).

Om du vill hämta koden snabbare är källkoden för den senaste utgåvan alltid tillgänglig 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å ändringar kan du göra dina ändringar och skapa ett ”sammanslagningsdirektiv” som du sedan kan fästa till ett ärende i calibre-felhanteringssystemet. För att göra detta, gör dina ändringar, kör sedan:

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 mappen, helt enkelt bifoga det till ett ärende i calibre-felhanteringssystemet. 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 du använder HEAD~n.

Om du planerar att göra en hel del utveckling på calibre, är den bästa metoden att skapa ett GitHub-konto. Nedan följer en grundläggande guide för att ställa in din egen förgrening av calibre på ett sätt som gör att du kan skicka förfrågningar för inkludering i calibre-huvudförrådet:

  • Installering av git på din maskin som beskrivs i denna artikel: Setup Git

  • Ställ in 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 skicka in dem när du vill. När du är redo att slå samman ditt arbete, gör en:

    git push

    och gå till https://github.com/<username>/calibre och klicka på knappen Pull Request för att skapa en hämtningsbegäran som kan slås samman.

  • Du kan när som helst uppdatera din lokala kopia med kod från huvudarkivet genom att göra:

    git pull upstream

Du bör också hålla ett öga på calibre-utvecklingsforumet. 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ällkoden separat enligt beskrivningen ovan.

Installera calibre normalt med hjälp av installationsprogrammet för Windows. Öppna sedan en kommandotolk och ändra till den tidigare kontrollerade calibre-kodmappen. Till exempel:

cd C:\Users\kovid\work\calibre

calibre är mappen som innehåller src och undermappar för resurser.

Nästa steg är att ställa in miljövariabeln CALIBRE_DEVELOP_FROM till den absoluta sökvägen för mappen src. 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 korrekt inställd genom att använda kommandot:

echo %CALIBRE_DEVELOP_FROM%

Ställa denna miljövariabel innebär att calibre kommer nu läsa in all sin Python-kod från den angivna platsen.

Det är allt! Du är nu redo att börja hacka 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. Kör nu kommandot calibredb . Den allra första raden av utmatningen bör vara Hej världen!.

Du kan också ställa in en calibre-utvecklingsmiljö i gratis Microsoft Visual Studio, om du vill, genom att följa instruktionerna här.

macOS-utvecklingsmiljö

Observera

Du måste också hämta calibre-källkoden separat enligt beskrivningen ovan.

Installera calibre normalt med hjälp av den tillhandahållna .dmg. Öppna sedan en terminal och ändra till den tidigare kontrollerade calibre-kodmappen, till exempel:

cd /Users/kovid/work/calibre

calibre är mappen som innehåller src och undermapparna för resurser. Kommandoradsverktygen för calibre finns i calibre-appaketet, i /Applications/calibre.app/Contents/MacOS bör du lägga till den här mappen 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 ställa in miljövariabeln CALIBRE_DEVELOP_FROM till den absoluta sökvägen till mappen src när calibre körs 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/local/bin/calibre-develop och ställ sedan in dess behörigheter så att den kan köras:

chmod +x /usr/local/bin/calibre-develop

När du har gjort detta, 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ällkoden separat enligt beskrivningen 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 driftstidsmiljö 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 med hjälp av det binära installationsprogrammet. Öppna sedan en terminal och ändra till den tidigare kontrollerade calibre-kodmappen, till exempel:

cd /home/kovid/work/calibre

calibre är mappen som innehåller src och undermappar för resurser.

Nästa steg är att ställa in miljövariabeln CALIBRE_DEVELOP_FROM till den absoluta sökvägen till mappen src. Så, efter exemplet ovan, skulle det vara /home/kovid/work/calibre/src. Hur man ställer in miljövariabler beror på din Linux-distribution och vilket skal du använder.

Observera

Det rekommenderas att använda det binära installationsprogrammet som tillhandahålls uppströms. Om du insisterar på att använda ett paket som tillhandahålls av din distribution, använd variablerna CALIBRE_PYTHON_PATH och CALIBRE_RESOURCES_PATH istället. Du kan få dessa genom att köra calibre-debug --paths. Observera dock att calibre-paket i distributioner ofta är terminalt trasiga och helt ounderstödda.

När du har ställt in miljövariabeln, öppna en ny terminal och kontrollera att den blev korrekt inställd genom att använda kommandot:

echo $CALIBRE_DEVELOP_FROM

Ställa denna miljövariabel innebär att calibre kommer nu läsa in all sin Python-kod från den angivna platsen.

Det är allt! Du är nu redo att börja hacka 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. Kör nu kommandot calibredb . Den allra första raden av utmatningen bör vara Hej världen!.

Att ha separata ”normala”- och ”utvecklings”-installationer av calibre på samma dator

calibre-källkodsträdet är mycket stabilt och går sällan sönder, men om du känner behov av att köra från källan i ett separat testbibliotek och köra den släppta calibre-versionen med ditt vardagliga bibliotek kan du enkelt uppnå detta med hjälp av .bat-filer eller skalskript för att starta calibre. Exemplet nedan visar hur man gör detta i Windows med .bat-filer (instruktionerna för andra plattformar är desamma, använd bara ett skalskript istället för en .bat-fil)

För att starta den utgivna versionen av calibre med ditt vardagliga bibliotek:

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 utskriftssatser

Det här är Kovids favoritsätt att felsöka. Infoga helt enkelt utskriftssatser vid intressanta platser och kör ditt program i terminalen. Till exempel kan du starta det grafiska gränssnittet från terminalen med:

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 --edit-book /path/to/be/edited

Använda 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 startar detta en interaktiv Python-tolk med tillgång till alla lokalt definierade variabler (variabler i den lokala omfånget). Den interaktiva prompten har till och med Tab-komplettering för objektegenskaper och du kan använda de olika Python-faciliteterna för introspektion, såsom dir(), type(), repr() etc.

Använda Python-felsökaren som fjärrfelsökare

Du kan använda den inbyggda Python-felsökaren (pdb) som en fjärrfelsökare från kommandoraden. Starta först 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 normalt, 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.

Öppna nu 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 att försöka ansluta på port 4444. Du kan ändra det genom att skicka portparametern till både set_trace()- och cli()-funktionerna 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, mappen du anger som CALIBRE_DEVELOP_FROM måste ovan, också vara i PYTHONPATH av din IDE.

Placera sedan IDE-fjärrfelsökarmodulen i undermappen :file:`src`för 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öra godtyckliga skript i Python-miljön för calibre

Kommandot :command:`calibre-debug`ger ett par praktiska flaggor för att köra din egen kod, med tillgång till calibre-modulerna:

calibre-debug -c "some Python code"

är bra för att testa ett litet kodavsnitt 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 ditt eget 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 skript, använd formuläret:

calibre-debug myscript.py -- --option1 arg1

-- gör att alla efterföljande argument skickas till ditt skript.

Använda calibre i dina projekt

Det är möjligt att direkt använda calibre-funktioner/-kod i ditt Python-projekt. Det finns två sätt 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

Källkodsinstallation på 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 modulen init_calibre före andra calibre-moduler/-paket eftersom den ställer in tolken för att köra calibre-kod.

API-dokumentation för olika delar av calibre