Nastavenie vývojového prostredia calibre

calibre je úplne open source, licencované pod GNU GPL v3. To znamená, že môžete program slobodne stiahnuť a upravovať podľa svojich predstáv. V tejto sekcii sa naučíte, ako si nastaviť vývojové prostredie calibre vo vami zvolenom operačnom systéme. calibre je napísané primárne v jazyku Python s určitým množstvom kódu v C/C++ pre rýchlosť a systémové rozhranie. Upozorňujeme, že calibre vyžaduje aspoň Python 3.8.

Filozofia dizajnu

calibre má korene v unixovom svete, čo znamená, že jeho dizajn je vysoko modulárny. Moduly navzájom komunikujú prostredníctvom dobre definovaných rozhraní. To veľmi uľahčuje pridávanie nových funkcií a opravu chýb v calibre, čo vedie k frenetickému tempu vývoja. Vďaka svojim koreňom má calibre komplexné rozhranie príkazového riadka pre všetky svoje funkcie, zdokumentované v Rozhranie príkazového riadka.

Modulárny dizajn calibre sa prejavuje prostredníctvom zásuvných modulov. Existuje návod na písanie zásuvných modulov pre calibre. Napriklad pridanie podpory pre nové zariadenie do calibre zvyčajne znamená napísanie menej ako 100 riadkov kódu vo forme zásuvného modulu ovládača zariadenia. Môžete si prezrieť vstavané ovládače. Podobne pridanie podpory pre nové konverzné formáty znamená napísanie zásuvných modulov vstupných/výstupných formátov. Ďalším príkladom modulárneho dizajnu je systém receptov na načítavanie správ. Ďalšie príklady zásuvných modulov navrhnutých na pridanie funkcií do calibre nájdete v Indexe zásuvných modulov.

Usporiadanie kódu

Všetok kód calibre v Pythone je v balíku calibre. Tento balík obsahuje nasledujúce hlavné podbalíky

  • devices – Všetky ovládače zariadení. Stačí sa pozrieť na niektoré z vstavaných ovládačov a získate predstavu o tom, ako fungujú.

    • Podrobnosti nájdete v: devices.interface, ktorý definuje rozhranie podporované ovládačmi zariadení, a devices.usbms, ktorý definuje generický ovládač pripájajúci sa k zariadeniu USBMS. Všetky ovládače v calibre založené na USBMS z neho dedia.

  • e-books – Všetok kód na konverziu e-kníh a prácu s metadátami. Dobrým východiskovým bodom je calibre.ebooks.conversion.cli, čo je modul, ktorý poháňa príkaz ebook-convert. Proces konverzie je riadený cez conversion.plumber. Kód nezávislý od formátu je celý v ebooks.oeb a kód závislý od formátu je v ebooks.format_name.

    • Čítanie, zápis a sťahovanie metadát je celé v ebooks.metadata

    • Konverzia prebieha v rúre (pipeline); štruktúru rúry nájdete v Úvod. Rúra pozostáva zo vstupného zásuvného modulu, rôznych transformácií a výstupného zásuvného modulu. Kód, ktorý rúru zostavuje a poháňa, je v plumber.py. Rúra pracuje s reprezentáciou e-knihy, ktorá je ako rozbalené epub s manifestom, chrbtom (spine), obsahom, sprievodcom, HTML obsahom atď. Trieda, ktorá túto reprezentáciu spravuje, je OEBBook v ebooks.oeb.base. Rôzne transformácie, ktoré sa na knihu počas konverzií aplikujú, sídlia v oeb/transforms/*.py. A vstupné a výstupné zásuvné moduly sídlia v conversion/plugins/*.py.

    • Úprava e-kníh prebieha pomocou iného objektu kontajnera. Je zdokumentovaný v Dokumentácia API pre nástroje na úpravu e-kníh.

  • db – Databázový backend. Rozhranie ku knižnici calibre nájdete v Dokumentácia API pre databázové rozhranie.

  • Server obsahu: srv je server obsahu calibre.

  • gui2 – Grafické používateľské rozhranie. Inicializácia GUI prebieha v gui2.main a gui2.ui. Prehliadač e-kníh je v gui2.viewer. Editor e-kníh je v gui2.tweak_book.

Ak chcete nájsť vstupné body pre všetky rôzne spustiteľné súbory calibre, pozrite sa na štruktúru entry_points v linux.py.

Ak potrebujete pomoc s pochopením kódu, napíšte na fórum vývojárov a pravdepodobne vám pomôže jeden z mnohých vývojárov calibre.

Získanie kódu

Zdrojový kód calibre môžete získať dvoma spôsobmi: pomocou systému na správu verzií alebo priamym stiahnutím tarballu.

calibre používa Git, distribuovaný systém na správu verzií. Git je k dispozícii na všetkých platformách, ktoré calibre podporuje. Po nainštalovaní gitu môžete získať zdrojový kód calibre príkazom:

git clone https://github.com/kovidgoyal/calibre.git

Vo Windows budete potrebovať úplnú cestu, ktorá bude vyzerať nejako takto: C:\Program Files\Git\git.exe.

calibre je veľmi veľký projekt s veľmi dlhou históriou správy verzií, takže vyššie uvedené môže chvíľu trvať (10 minút až hodinu v závislosti od rýchlosti vášho internetu).

Ak chcete získať kód rýchlejšie, zdrojový kód najnovšieho vydania je vždy k dispozícii ako archív.

Ak chcete aktualizovať vetvu na najnovší kód, použite príkaz:

git pull --no-edit

Kód si môžete tiež prezrieť na GitHube.

Odoslanie vašich zmien na zahrnutie

Ak plánujete vykonať iba niekoľko malých zmien, môžete svoje zmeny vykonať a vytvoriť „merge directive“, ktorý potom môžete pripojiť k tiketu v sledovači chýb calibre. Ak to chcete urobiť, vykonajte svoje zmeny a potom spustite:

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

Týmto sa v aktuálnom priečinku vytvorí súbor my-changes; jednoducho ho pripojte k tiketu v sledovači chýb calibre. Upozorňujeme, že bude obsahovať všetky commity, ktoré ste vykonali. Ak chcete poslať iba niektoré commity, musíte zmeniť origin/master vyššie. Ak chcete poslať iba posledný commit, použite:

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

Ak chcete poslať posledných n commitov, nahraďte 1 číslom n, napríklad pre posledné 3 commity:

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

Pri používaní HEAD~n dávajte pozor, aby ste nezahrnuli merge operácie.

Ak plánujete na calibre intenzívne vyvíjať, najlepším spôsobom je vytvoriť si účet na GitHube. Nižšie je základný návod na nastavenie vlastnej forkovej kópie calibre tak, aby ste mohli odosielať pull requesty na zahrnutie do hlavného repozitára calibre:

  • Nastavte si git na svojom počítači podľa tohto článku: Setup Git

  • Nastavte si SSH kľúče na overovanie voči GitHubu, ako je opísané tu: Generating SSH keys

  • Prejdite na https://github.com/kovidgoyal/calibre a kliknite na tlačidlo Fork.

  • V termináli spustite:

    git clone git@github.com:<username>/calibre.git
git remote add upstream https://github.com/kovidgoyal/calibre.git

    Nahraďte <username> vyššie svojím používateľským menom na GitHube. Tým sa vaša fork kópia stiahne lokálne.

  • Zmeny môžete vykonávať a commitovať, kedykoľvek chcete. Keď budete pripravení nechať svoju prácu zlúčiť, spustite:

    git push

    a prejdite na https://github.com/<username>/calibre a kliknite na tlačidlo Pull Request na vygenerovanie pull requestu, ktorý možno zlúčiť.

  • Svoju lokálnu kópiu môžete kedykoľvek aktualizovať kódom z hlavného repa pomocou:

    git pull upstream

Mali by ste tiež sledovať fórum vývojárov calibre. Pred vykonaním väčších zmien by ste o nich mali diskutovať na fóre alebo kontaktovať priamo Kovida (jeho e-mailová adresa je všade v zdrojovom kóde).

Vývojové prostredie vo Windows

Poznámka

Tiež musíte samostatne získať zdrojový kód calibre, ako je opísané vyššie.

Nainštalujte calibre bežným spôsobom pomocou inštalátora pre Windows. Potom otvorte príkazový riadok a prepnite sa do predtým stiahnutého priečinka s kódom calibre. Napníklad:

cd C:\Users\kovid\work\calibre

calibre je priečinok, ktorý obsahuje podpriečinky src a resources.

Ďalším krokom je nastaviť premennú prostredia CALIBRE_DEVELOP_FROM na absolútnu cestu k priečinku src. Takže podľa vyššie uvedeného príkladu by to bolo C:\Users\kovid\work\calibre\src. Tu je krátky návod na nastavenie premenných prostredia vo Windows.

Keď ste nastavili premennú prostredia, otvorte nový príkazový riadok a skontrolujte, či bola správne nastavená, pomocou príkazu:

echo %CALIBRE_DEVELOP_FROM%

Nastavenie tejto premennej prostredia znamená, že calibre teraz bude načítavať všetok svoj kód v Pythone z určeného umiestnenia.

To je všetko! Teraz ste pripravení začať hackovať kód calibre. Napríklad otvorte súbor src\calibre\__init__.py vo svojom obľúbenom editore a pridajte riadok:

print("Hello, world!")

na začiatok súboru. Teraz spustite príkaz calibredb. Úplne prvý riadok výstupu by mal byť Hello, world!.

Ak chcete, môžete si tiež nastaviť vývojové prostredie calibre v bezplatnom Microsoft Visual Studio podľa pokynov tu.

Vývojové prostredie v macOS

Poznámka

Tiež musíte samostatne získať zdrojový kód calibre, ako je opísané vyššie.

Nainštalujte calibre bežným spôsobom pomocou poskytnutého .dmg. Potom otvorte terminál a prepnite sa do predtým stiahnutého priečinka s kódom calibre, napríklad:

cd /Users/kovid/work/calibre

calibre je priečinok, ktorý obsahuje podpriečinky src a resources. Nástroje príkazového riadka calibre sa nachádzajú vnútri balíka aplikácie calibre, v /Applications/calibre.app/Contents/MacOS. Ak chcete nástroje príkazového riadka spúšťať jednoducho, mali by ste tento priečinok pridať do premennej prostredia PATH.

Ďalším krokom je vytvoriť bash skript, ktorý pri spustení calibre v režime ladenia nastaví premennú prostredia CALIBRE_DEVELOP_FROM na absolútnu cestu k priečinku src.

Vytvorte čistý textový súbor:

#!/bin/sh
export CALIBRE_DEVELOP_FROM="/Users/kovid/work/calibre/src"
calibre-debug -g

Uložte tento súbor ako /usr/local/bin/calibre-develop a potom nastavte jeho oprávnenia, aby sa dal spustiť:

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

Keď to urobíte, spustite:

calibre-develop

Pri spustení calibre by ste v okne terminálu mali vidieť nejaké diagnostické informácie a v okne GUI by ste mali vidieť hviezdičku za číslom verzie, čo znamená, že spúšťate zo zdrojového kódu.

Vývojové prostredie v Linuxe

Poznámka

Tiež musíte samostatne získať zdrojový kód calibre, ako je opísané vyššie.

calibre sa primárne vyvíja na Linuxe. Pri nastavovaní vývojového prostredia máte dve možnosti. Môžete nainštalovať binárnu verziu calibre bežným spôsobom a použiť ju ako runtime prostredie na vývoj. Tento prístup je podobný ako vo Windows a macOS. Prípadne môžete calibre nainštalovať zo zdrojového kódu. Pokyny na nastavenie vývojového prostredia zo zdrojového kódu sú v súbore INSTALL v zdrojovom strome. Tu sa budeme zaoberať použitím binárnej verzie ako runtime, čo je odporúčaná metóda.

Nainštalujte calibre pomocou binárneho inštalátora. Potom otvorte terminál a prepnite sa do predtým stiahnutého priečinka s kódom calibre, napríklad:

cd /home/kovid/work/calibre

calibre je priečinok, ktorý obsahuje podpriečinky src a resources.

Ďalším krokom je nastaviť premennú prostredia CALIBRE_DEVELOP_FROM na absolútnu cestu k priečinku src. Takže podľa vyššie uvedeného príkladu by to bolo /home/kovid/work/calibre/src. Spôsob nastavenia premenných prostredia závisí od vašej linuxovej distribúcie a od toho, ktorý shell používate.

Poznámka

Odporúča sa použiť binárny inštalátor poskytnutý priamo od vývojárov. Ak však trváte na použití balíka poskytnutého vašou distribúciou, použite namiesto toho premenné CALIBRE_PYTHON_PATH a CALIBRE_RESOURCES_PATH. Získate ich spustením calibre-debug --paths. Upozorňujeme však, že balíky calibre z distribúcií sú často nenapraviteľne pokazené a sú úplne nepodporované.

Keď ste nastavili premennú prostredia, otvorte nový terminál a skontrolujte, či bola správne nastavená, pomocou príkazu:

echo $CALIBRE_DEVELOP_FROM

Nastavenie tejto premennej prostredia znamená, že calibre teraz bude načítavať všetok svoj kód v Pythone z určeného umiestnenia.

To je všetko! Teraz ste pripravení začať hackovať kód calibre. Napríklad otvorte súbor src/calibre/__init__.py vo svojom obľúbenom editore a pridajte riadok:

print("Hello, world!")

na začiatok súboru. Teraz spustite príkaz calibredb. Úplne prvý riadok výstupu by mal byť Hello, world!.

Mať oddelené „normálne“ a „vývojové“ inštalácie calibre na tom istom počítači

Zdrojový strom calibre je veľmi stabilný a málokedy sa pokazí, ale ak cítite potrebu spúšťať zo zdrojového kódu s oddelenou testovacou knižnicou a spúšťať vydanú verziu calibre so svojou každodennou knižnicou, môžete to ľahko dosiahnuť pomocou .bat súborov alebo shell skriptov na spustenie calibre. Nižšie uvedený príklad ukazuje, ako to urobiť vo Windows pomocou .bat súborov (pokyny pre iné platformy sú rovnaké, len namiesto .bat súboru použite shell skript)

Ak chcete spustiť vydanú verziu calibre so svojou každodennou knižnicou:

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"

Tipy na ladenie

Python je dynamicky typovaný jazyk s vynikajúcimi prostriedkami na introspekciu. Kovid napísal jadro kódu calibre bez toho, aby raz použil ladiaci nástroj. Existuje mnoho stratégií na ladenie kódu calibre:

Používanie príkazov print

Toto je Kovidov obľúbený spôsob ladenia. Jednoducho vložte príkazy print na zaujímavé miesta a spustite svoj program v termináli. Napríklad GUI môžete spustiť z terminálu takto:

calibre-debug -g

Podobne môžete spustiť prehliadač e-kníh takto:

calibre-debug -w /path/to/file/to/be/viewed

Editor e-kníh možno spustiť takto:

calibre-debug --edit-book /path/to/be/edited

Používanie interaktívneho interpreta Pythonu

Na spustenie interaktívnej relácie Pythonu na danom mieste môžete vložiť nasledujúce dva riadky kódu:

from calibre import ipython
ipython(locals())

Pri spustení z príkazového riadka sa spustí interaktívny interpret Pythonu s prístupom ku všetkým lokálne definovaným premenným (premenným v lokálnom rozsahu). Interaktívny príkazový riadok má dokonca dopĺňanie pomocou Tab pre vlastnosti objektov a môžete použiť rôzne prostriedky Pythonu na introspekciu, ako napríklad dir(), type(), repr() atď.

Používanie ladiča Pythonu ako vzdialeného ladiča

Vstavaný ladič Pythonu (pdb) môžete použiť ako vzdialený ladič z príkazového riadka. Najprv spustite vzdialený ladič na mieste v kóde calibre, ktoré vás zaujíma, takto:

from calibre.rpdb import set_trace
set_trace()

Potom spustite calibre, buď bežne, alebo pomocou jedného z príkazov calibre-debug opísaných v predchádzajúcej sekcii. Keď sa dosiahne vyššie uvedené miesto v kóde, calibre zamrzne a bude čakať na pripojenie ladiča.

Teraz otvorte terminál alebo príkazový riadok a pomocou nasledujúceho príkazu spustite ladiacu reláciu:

calibre-debug -c "from calibre.rpdb import cli; cli()"

O používaní ladiča Pythonu si môžete prečítať v dokumentácii štandardnej knižnice Pythonu pre modul pdb.

Poznámka

V predvolenom nastavení sa vzdialený ladič pokúsi pripojiť na porte 4444. Môžete to zmeniť odovzdaním parametra port do funkcií set_trace() a cli() vyššie, takto: set_trace(port=1234) a cli(port=1234).

Poznámka

Ladič Pythonu nezvládne viacero vlákien, takže musíte zavolať set_trace raz pre každé vlákno, vždy s iným číslom portu.

Používanie ladiča vo vašom obľúbenom IDE pre Python

Vstavaný ladič môžete použiť vo svojom obľúbenom IDE pre Python, ak podporuje vzdialené ladenie. Prvým krokom je pridať kópiu src calibre do PYTHONPATH vo vašom IDE. Inými slovami, priečinok, ktorý ste nastavili ako CALIBRE_DEVELOP_FROM vyššie, musí byť tiež v PYTHONPATH vášho IDE.

Potom umiestnite modul vzdialeného ladiča vášho IDE do podpriečinka src v stiahnutej kópii zdrojového kódu calibre. Pridajte do calibre na zaujímavé miesto, napríklad do hlavnej funkcie, kód potrebný na spustenie vzdialeného ladiča. Potom spustite calibre bežne. Vaše IDE by sa teraz malo dokázať pripojiť k vzdialenému ladiču bežiacemu vnútri calibre.

Spúšťanie ľubovoľných skriptov v prostredí Pythonu calibre

Príkaz calibre-debug poskytuje niekoľko praktických prepínačov na spustenie vlastného kódu s prístupom k modulom calibre:

calibre-debug -c "some Python code"

je skvelý na testovanie malého úryvku kódu v príkazovom riadku. Funguje rovnako ako prepínač -c interpreta Pythonu:

calibre-debug myscript.py

možno použiť na spustenie vlastného skriptu v Pythone. Funguje rovnako ako odovzdanie skriptu interpretovi Pythonu, okrem toho, že prostredie calibre je plne inicializované, takže vo svojom skripte môžete použiť všetok kód calibre. Ak chcete vo svojom skripte použiť argumenty príkazového riadka, použite tvar:

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

-- spôsobí, že všetky nasledujúce argumenty sa odovzdajú vášmu skriptu.

Spustenie testovacej sady calibre

Testovaciu sadu calibre možno spustiť pomocou:

calibre-debug -t all

Používanie calibre vo vašich projektoch

Je možné priamo použiť funkcie alebo kód calibre vo svojom projekte v Pythone. Existujú dva spôsoby:

Binárna inštalácia calibre

Ak máte binárnu inštaláciu calibre, môžete použiť interpret Pythonu dodávaný s calibre takto:

calibre-debug /path/to/your/python/script.py -- arguments to your script

Inštalácia zo zdrojového kódu v Linuxe

Okrem použitia vyššie uvedenej techniky, ak vykonáte inštaláciu zo zdrojového kódu v Linuxe, môžete tiež priamo importovať calibre takto:

import init_calibre
import calibre

print(calibre.__version__)

Je nevyhnutné, aby ste importovali modul init_calibre pred akýmikoľvek inými modulmi alebo balíkmi calibre, pretože nastavuje interpret na spúšťanie kódu calibre.

Dokumentácia API pre rôzne časti calibre