Konfigurera en utvecklingsmiljö för calibre

calibre har helt öppen källkod och är licensierat under GNU GPL v3. Det innebär att du fritt kan hämta och ändra programmet så mycket du vill. I det här avsnittet får du lära dig hur du konfigurerar en utvecklingsmiljö för calibre på valfritt operativsystem. calibre är huvudsakligen skrivet i Python, med viss C/C++-kod för bättre prestanda och systemintegration. Observera att calibre kräver minst Python 3.8.

Designfilosofi

calibre har sina rötter i Unix-världen, vilket innebär att dess design är mycket modulär. Modulerna samverkar via väldefinierade gränssnitt. Det gör det mycket enkelt att lägga till nya funktioner och rätta fel i calibre, vilket ger en snabb utvecklingstakt. Tack vare sina rötter har calibre ett omfattande kommandoradsgränssnitt för samtliga funktioner, dokumenterat i Kommandoradsgränssnitt.

calibres modulära design bygger på insticksmoduler. Det finns en handledning om hur du skriver insticksmoduler för calibre. Att lägga till stöd för en ny enhet kräver till exempel vanligtvis färre än 100 rader kod i form av en insticksmodul för enhetsdrivrutinen. Du kan bläddra bland de inbyggda drivrutinerna. På motsvarande sätt lägger du till stöd för nya konverteringsformat genom att skriva insticksmoduler för in- och utmatningsformat. Ett annat exempel på den modulära designen är receptsystemet för att hämta nyheter. Fler exempel på insticksmoduler som lägger till funktioner i calibre finns i indexet över insticksmoduler.

Kodstruktur

All Python-kod i calibre finns i paketet calibre. Paketet innehåller följande huvudsakliga underpaket

  • devices – Alla enhetsdrivrutiner. Titta igenom några av de inbyggda drivrutinerna för att få en uppfattning om hur de fungerar.

    • Mer information finns i devices.interface, som definierar gränssnittet som enhetsdrivrutiner stöder, och devices.usbms, som definierar en allmän drivrutin för anslutning till en USBMS-enhet. Alla USBMS-baserade drivrutiner i calibre ärver från den.

  • e-books – All kod för e-bokskonvertering och metadata. En bra utgångspunkt är calibre.ebooks.conversion.cli, modulen som driver kommandot ebook-convert. Konverteringsprocessen styrs via conversion.plumber. All formatoberoende kod finns i ebooks.oeb och den formatberoende koden i ebooks.format_name.

    • All läsning, skrivning och hämtning av metadata finns i ebooks.metadata

    • Konverteringen sker i en bearbetningskedja. Information om kedjans struktur finns i Introduktion. Kedjan består av en insticksmodul för inmatning, olika omvandlingar och en insticksmodul för utmatning. Koden som bygger upp och driver kedjan finns i plumber.py. Kedjan arbetar med en representation av en e-bok som liknar en uppackad EPUB, med manifest, läsordning, innehållsförteckning, guide, HTML-innehåll och så vidare. Klassen som hanterar representationen är OEBBook i ebooks.oeb.base. De olika omvandlingarna som tillämpas på boken under konverteringen finns i oeb/transforms/*.py. Insticksmodulerna för in- och utmatning finns i conversion/plugins/*.py.

    • E-boksredigering använder ett annat behållarobjekt. Det dokumenteras 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 – Det grafiska användargränssnittet. Gränssnittet initieras i gui2.main och gui2.ui. E-bokvisaren finns i gui2.viewer. E-bokredigeraren finns i gui2.tweak_book.

Om du vill hitta startpunkterna för de olika körbara calibre-programmen, titta på strukturen entry_points i linux.py.

Om du behöver hjälp med att förstå koden kan du göra ett inlägg i utvecklingsforumet. Du får sannolikt hjälp av någon av calibres många utvecklare.

Hämta koden

Du kan hämta calibres källkod på två sätt: med ett versionshanteringssystem eller genom att hämta ett tar-arkiv direkt.

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 versionshanteringshistorik, så kommandot ovan kan ta en stund, från 10 minuter till en timme beroende på din internethastighet.

Om du vill hämta koden snabbare är källkoden för den senaste utgåvan alltid tillgänglig som ett arkiv.

Använd följande kommando för att uppdatera en gren till den senaste koden:

git pull --no-edit

Du kan också se koden på GitHub.

Skicka in ändringar för införande

Om du bara planerar att göra några mindre ändringar kan du genomföra dem och skapa ett ”merge directive” som du sedan bifogar till ett ärende i calibres felrapporteringssystem. Gör ändringarna och kör sedan:

git commit -am "Comment describing your changes"
git format-patch origin/master --stdout > my-changes

Det skapar filen my-changes i den aktuella mappen. Bifoga den till ett ärende i calibres felrapporteringssystem. Observera att filen innehåller alla incheckningar du har gjort. Om du bara vill skicka vissa incheckningar måste du ändra origin/master ovan. Använd följande för att endast skicka den senaste incheckningen:

git format-patch HEAD~1 --stdout > my-changes

Om du vill skicka de senaste n incheckningarna ersätter du 1 med n. För de senaste tre incheckningarna använder du till exempel:

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 utveckla mycket för calibre är den bästa metoden att skapa ett konto på GitHub. Nedan följer en grundläggande guide för hur du skapar en egen förgrening av calibre så att du kan skicka pull-begäranden för införande i calibres huvudförråd:

  • Konfigurera Git på datorn enligt artikeln Konfigurera Git

  • Konfigurera SSH-nycklar för autentisering mot GitHub enligt anvisningarna här: Skapa SSH-nycklar

  • Gå till https://github.com/kovidgoyal/calibre och klicka på knappen Fork.

  • Kör följande i en terminal:

    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. Din förgrening checkas då ut lokalt.

  • Du kan göra ändringar och checka in dem när du vill. När du är redo att få arbetet sammanslaget kör du:

    git push

    Gå sedan till https://github.com/<username>/calibre och klicka på knappen Pull Request för att skapa en pull-begäran som kan slås samman.

  • Du kan när som helst uppdatera din lokala kopia med kod från huvudförrådet genom att köra:

    git pull upstream

Du bör också hålla ett öga på calibres utvecklingsforum. Innan du gör större ändringar bör du diskutera dem i forumet eller kontakta Kovid direkt. Hans e-postadress finns på många ställen i källkoden.

Windows-utvecklingsmiljö

Anteckning

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

Installera calibre på vanligt sätt med installationsprogrammet för Windows. Öppna sedan en kommandotolk och växla till den tidigare utcheckade mappen med calibre-koden. Till exempel:

cd C:\Users\kovid\work\calibre

calibre är mappen som innehåller undermapparna src och resources.

Nästa steg är att ställa in miljövariabeln CALIBRE_DEVELOP_FROM på den absoluta sökvägen till mappen src. I exemplet ovan blir det C:\Users\kovid\work\calibre\src. Här finns en kort guide till hur du ställer in miljövariabler i Windows.

När du har ställt in miljövariabeln öppnar du en ny kommandotolk och kontrollerar med följande kommando att den är korrekt inställd:

echo %CALIBRE_DEVELOP_FROM%

När den här miljövariabeln ställs in läser calibre in all sin Python-kod från den angivna platsen.

Klart! Nu kan du börja arbeta med calibre-koden. Öppna till exempel filen src\calibre\__init__.py i din favoritredigerare och lägg till raden:

print("Hello, world!")

nära början av filen. Kör sedan kommandot calibredb. Den första utdataraden ska vara Hello, world!.

Du kan också konfigurera en utvecklingsmiljö för calibre i kostnadsfria Microsoft Visual Studio genom att följa anvisningarna här.

macOS-utvecklingsmiljö

Anteckning

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

Installera calibre på vanligt sätt med den medföljande DMG-filen. Öppna sedan Terminal och växla till den tidigare utcheckade mappen med calibre-koden, till exempel:

cd /Users/kovid/work/calibre

calibre är mappen som innehåller undermapparna src och resources. Calibres kommandoradsverktyg finns i calibre-appens paket, i /Applications/calibre.app/Contents/MacOS. Lägg till den mappen i miljövariabeln PATH om du enkelt vill kunna köra kommandoradsverktygen.

Nästa steg är att skapa ett bash-skript som ställer in miljövariabeln CALIBRE_DEVELOP_FROM på den absoluta sökvägen till mappen src när calibre körs i felsökningsläge.

Skapa en vanlig textfil:

#!/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

När calibre startar bör du se diagnostisk information i terminalfönstret och en asterisk efter versionsnumret i GUI-fönstret. Asterisken visar att du kör från källkoden.

Linux-utvecklingsmiljö

Anteckning

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

calibre utvecklas främst på Linux. Du kan konfigurera utvecklingsmiljön på två sätt. Antingen installerar du calibres binärversion på vanligt sätt och använder den som körmiljö för utvecklingen, på samma sätt som i Windows och macOS, eller så installerar du calibre från källkoden. Anvisningar för att konfigurera en utvecklingsmiljö från källkoden finns i filen INSTALL i källkodsträdet. Här beskriver vi hur binärversionen används som körmiljö, 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 undermapparna src och resources.

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.

Anteckning

Vi rekommenderar att du använder det binära installationsprogrammet från huvudprojektet. Om du ändå vill använda ett paket från din distribution ska du i stället använda variablerna CALIBRE_PYTHON_PATH och CALIBRE_RESOURCES_PATH. Du kan få fram dem genom att köra calibre-debug --paths. Observera dock att distributionernas calibre-paket ofta är allvarligt trasiga och inte stöds alls.

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

När den här miljövariabeln ställs in läser calibre in all sin Python-kod från den angivna platsen.

Klart! Nu kan du börja arbeta med calibre-koden. Öppna till exempel filen src/calibre/__init__.py i din favoritredigerare och lägg till raden:

print("Hello, world!")

nära början av filen. Kör sedan kommandot calibredb. Den första utdataraden ska vara Hello, world!.

Ha separata installationer av den vanliga versionen och utvecklingsversionen av calibre på samma dator

Calibres källkodsträd är mycket stabilt och slutar sällan fungera. Om du ändå vill köra källkodsversionen med ett separat testbibliotek och den utgivna calibre-versionen med ditt vanliga bibliotek kan du enkelt göra det genom att starta calibre med .bat-filer eller skalskript. Exemplet nedan visar hur du gör i Windows med .bat-filer. På andra plattformar är anvisningarna desamma, men du använder ett skalskript i stället för en .bat-fil.

Så här startar du den utgivna versionen av calibre med ditt vanliga 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 möjligheter till introspektion. Kovid skrev kärnan i calibre utan att någonsin använda en felsökare. Det finns många sätt att felsöka calibre-kod:

Använda utskriftssatser

Det här är Kovids favoritsätt att felsöka. Infoga helt enkelt utskriftssatser på intressanta ställen och kör programmet i terminalen. Du kan till exempel starta GUI:t 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å kodrader för att starta en interaktiv Python-session vid den aktuella punkten:

from calibre import ipython
ipython(locals())

När du kör från kommandoraden startar detta en interaktiv Python-tolk med åtkomst till alla lokalt definierade variabler, det vill säga variabler i det lokala omfånget. Den interaktiva prompten har till och med Tab-komplettering för objektegenskaper, och du kan använda Pythons olika funktioner för introspektion, till exempel dir(), type() och repr().

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 på vanligt sätt eller med något av kommandona för calibre-debug som beskrivs i föregående avsnitt. När den aktuella punkten i koden nås fryser calibre och väntar på att felsökaren ska 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 Python-felsökaren används i Pythons standardbiblioteksdokumentation för pdb-modulen.

Anteckning

Som standard försöker fjärrfelsökaren ansluta via port 4444. Du kan ändra porten genom att skicka portparametern till både funktionerna set_trace() och cli() ovan, så här: set_trace(port=1234) och cli(port=1234).

Anteckning

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-IDE för Python

Du kan använda den inbyggda felsökaren i din favorit-IDE för Python om den stöder fjärrfelsökning. Lägg först till den utcheckade src-mappen för calibre i PYTHONPATH i din IDE. Med andra ord måste mappen som du angav som CALIBRE_DEVELOP_FROM ovan även finnas i IDE:ns PYTHONPATH.

Placera sedan IDE:ns fjärrfelsökningsmodul i undermappen src i den utcheckade calibre-källkoden. Lägg till den kod som krävs för att starta fjärrfelsökaren i calibre vid den punkt du vill undersöka, till exempel i huvudfunktionen. Kör därefter 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 calibre-debug har ett par praktiska växlar för att köra egen kod med åtkomst till calibre-modulerna:

calibre-debug -c "some Python code"

är utmärkt för att testa ett kort kodavsnitt på kommandoraden. Det fungerar på samma sätt som växeln -c för Python-tolken:

calibre-debug myscript.py

kan användas för att köra ett eget Python-skript. Det fungerar på samma sätt som att skicka skriptet till Python-tolken, förutom att calibre-miljön är fullständigt initierad så att du kan använda all calibre-kod i skriptet. Om du vill använda kommandoradsargument med skriptet använder du följande form:

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

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

Köra calibres testsvit

Calibres testsvit kan köras med:

calibre-debug -t all

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 metoden ovan kan du, om du installerar från källkod på Linux, även importera calibre direkt 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