Podešavanje razvojnog okruženja za calibre

calibre je program otvorenog koda objavljen pod licencom GNU GPL v3. Možete ga slobodno preuzimati i menjati. U ovom odeljku saznaćete kako da podesite razvojno okruženje za calibre na operativnom sistemu koji koristite. calibre je napisan prvenstveno u jeziku Python, uz nešto C/C++ koda radi brzine i povezivanja sa sistemom. Potreban je najmanje Python 3.8.

Filozofija dizajna

calibre potiče iz sveta Unixa, pa ima veoma modularnu strukturu. Moduli međusobno komuniciraju preko jasno definisanih interfejsa. Zahvaljujući tome, nove funkcije se lako dodaju, a greške ispravljaju, što omogućava brz razvoj. calibre ima i sveobuhvatan interfejs komandne linije za sve funkcije, opisan u Interfejs komandne linije.

Modularna struktura programa calibre zasniva se na Plugins. O pisanju dodataka postoji uputstvo. Na primer, za podršku novom uređaju često je potrebno manje od 100 redova koda u dodatku koji služi kao upravljački program uređaja. Možete pogledati ugrađene upravljačke programe. Podrška novom formatu za konverziju takođe se dodaje ulaznim ili izlaznim dodatkom. Još jedan primer modularnosti je sistem recepata za preuzimanje vesti. Dodatne primere pogledajte u spisku dodataka.

Raspored koda

Sav Python kod programa calibre nalazi se u paketu calibre. Njegovi glavni potpaketi su:

  • devices - Svi drajveri uređaja. Samo pregledajte neke od ugrađenih drajvera da biste dobili ideju kako oni funkcionišu.

    • Detalje potražite u devices.interface, gde je definisan interfejs upravljačkih programa, i u devices.usbms, gde je definisan opšti upravljački program za USBMS uređaje. Svi calibre upravljački programi zasnovani na USBMS-u nasleđuju ga.

  • e-books - Sav kod za konverziju/metapodatke e-knjiga. Dobra početna tačka je calibre.ebooks.conversion.cli koji je modul koji pokreće komandu ebook-convert. Proces konverzije se kontroliše preko conversion.plumber. Kod nezavisan od formata je sav u ebooks.oeb, a kod zavisan od formata je u ebooks.format_name.

    • Čitanje, pisanje i preuzimanje metapodataka se nalazi u ebooks.metadata

    • Konverzija se odvija kroz niz koraka, opisan u Uvod. U njemu učestvuju ulazni dodatak, razne transformacije i izlazni dodatak. Kod koji sastavlja i pokreće taj niz nalazi se u plumber.py. Obrada koristi prikaz e-knjige sličan raspakovanom EPUB-u, s manifestom, redosledom sadržaja, sadržajem knjige, vodičem, HTML sadržajem itd. Tim prikazom upravlja klasa OEBBook u ebooks.oeb.base. Transformacije su u oeb/transforms/*.py, a ulazni i izlazni dodaci u conversion/plugins/*.py.

    • Uređivanje e-knjiga se odvija pomoću drugog kontejnerskog objekta. Dokumentovano je u API dokumentacija za alate za uređivanje e-knjiga.

  • db - Pozadinski sloj baze podataka. Interfejs calibre biblioteke opisan je u API dokumentacija za interfejs baze podataka.

  • Server sadržaja: srv je calibre server sadržaja.

  • gui2 - Grafički korisnički interfejs. Inicijalizacija GUI-ja se dešava u gui2.main i gui2.ui. Pregledač e-knjiga je u gui2.viewer. Uređivač e-knjiga je u gui2.tweak_book.

Ako želite da locirate ulazne tačke za sve različite calibre izvršne datoteke, pogledajte strukturu entry_points u linux.py.

Ako vam je potrebna pomoć u razumevanju koda, objavite na razvojnom forumu i najverovatnije ćete dobiti pomoć od jednog od mnogih programera calibre-a.

Preuzimanje koda

Izvorni kod calibre-a možete dobiti na dva načina, koristeći sistem za kontrolu verzija ili direktnim preuzimanjem tarball-a.

calibre koristi Git, distribuirani sistem za kontrolu verzija. Git je dostupan na svim platformama koje calibre podržava. Nakon instalacije Git-a, možete preuzeti izvorni kod calibre-a pomoću komande:

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

Na Windows-u će vam biti potrebna puna putanja, što će biti nešto poput C:\Program Files\Git\git.exe.

calibre je veoma veliki projekat sa veoma dugom istorijom kontrole izvornog koda, tako da gorenavedeno može potrajati (od 10 minuta do sat vremena u zavisnosti od brzine vašeg interneta).

Ako želite da brže preuzmete kod, izvorni kod za najnovije izdanje je uvek dostupan kao arhiva.

Da biste ažurirali granu na najnoviji kod, koristite komandu:

git pull --no-edit

Takođe možete pregledati kod na GitHub-u.

Slanje izmena za uključivanje u projekat

Ako planirate da napravite samo nekoliko malih izmena, možete napraviti svoje izmene i kreirati "merge directive" koju zatim možete priložiti uz tiket u calibre sistemu za praćenje grešaka. Da biste to uradili, napravite svoje izmene, a zatim pokrenite:

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

Ovo će kreirati datoteku my-changes u trenutnom folderu, jednostavno je priložite uz tiket na calibre sistemu za praćenje grešaka. Imajte na umu da će ovo uključiti sve komitove koje ste napravili. Ako želite da pošaljete samo neke komitove, morate promeniti origin/master iznad. Da biste poslali samo poslednji komit, koristite:

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

Da biste poslali poslednjih n komitova, zamenite 1 sa n, na primer, za poslednja 3 komita:

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

Pazite da ne uključite spajanja kada koristite HEAD~n.

Ako planirate opsežniji rad na programu calibre, najbolje je da otvorite nalog na GitHubu. U nastavku je kratko uputstvo za pravljenje sopstvene kopije projekta iz koje možete slati zahteve za spajanje izmena s glavnim calibre repozitorijumom:

  • Podesite git na vašoj mašini kao što je opisano u ovom članku: Setup Git

  • Podesite ssh ključeve za autentifikaciju na GitHub, kao što je opisano ovde: Generating SSH keys

  • Idite na https://github.com/kovidgoyal/calibre i kliknite na dugme Fork.

  • U Terminalu uradite:

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

    Zamenite <username> iznad sa vašim GitHub korisničkim imenom. To će preuzeti vaš fork lokalno.

  • Možete praviti izmene i komitovati ih kad god želite. Kada ste spremni da vaš rad bude spojen, uradite:

    git push

    i idite na https://github.com/<username>/calibre i kliknite na dugme Pull Request da generišete pull request koji može biti spojen.

  • Možete ažurirati vašu lokalnu kopiju sa kodom iz glavnog repozitorijuma u bilo kom trenutku radeći:

    git pull upstream

Takođe bi trebalo da pratite calibre razvojni forum. Pre nego što napravite velike promene, trebalo bi da ih prodiskutujete na forumu ili direktno kontaktirate Kovida (njegova email adresa je svuda u izvornom kodu).

Razvojno okruženje na Windowsu

Белешка

Takođe morate odvojeno preuzeti izvorni kod za calibre kao što je gore opisano.

Instalirajte calibre normalno, koristeći Windows instalater. Zatim otvorite komandnu liniju i pređite u prethodno preuzetu fasciklu sa kodom za calibre. Na primer:

cd C:\Users\kovid\work\calibre

calibre je fascikla koja sadrži src i resources podfascikle.

Sledeći korak je postavljanje promenljive okruženja CALIBRE_DEVELOP_FROM na apsolutnu putanju src fascikle. Dakle, prateći gornji primer, to bi bilo C:\Users\kovid\work\calibre\src. Evo kratkog vodiča za postavljanje promenljivih okruženja na Windows-u.

Kada postavite promenljivu okruženja, otvorite novu komandnu liniju i proverite da li je ispravno postavljena koristeći komandu:

echo %CALIBRE_DEVELOP_FROM%

Postavljanje ove promenljive okruženja znači da će calibre sada učitavati sav svoj Python kod sa navedene lokacije.

To je sve! Sada možete da menjate calibre kod. Na primer, otvorite fajl src\calibre\__init__.py u svom omiljenom uređivaču i dodajte red:

print("Hello, world!")

blizu vrha datoteke. Sada pokrenite komandu calibredb. Prva linija izlaza bi trebalo da bude Hello, world!.

Takođe možete postaviti calibre razvojno okruženje unutar besplatnog Microsoft Visual Studio-a, ako želite, prateći uputstva ovde.

macOS razvojno okruženje

Белешка

Takođe morate odvojeno preuzeti izvorni kod za calibre kao što je gore opisano.

Instalirajte calibre normalno koristeći priloženi .dmg. Zatim otvorite Terminal i pređite u prethodno preuzeti folder sa calibre kodom, na primer:

cd /Users/kovid/work/calibre

calibre je folder koji sadrži podfoldere src i resources. Alati komandne linije nalaze se u paketu aplikacije calibre, u folderu /Applications/calibre.app/Contents/MacOS. Dodajte taj folder u promenljivu okruženja PATH ako želite da te alate lako pokrećete.

Sledeći korak je kreiranje bash skripte koja će postaviti promenljivu okruženja CALIBRE_DEVELOP_FROM na apsolutnu putanju src foldera kada se calibre pokreće u debug modu.

Kreirajte običan tekstualni fajl:

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

Sačuvajte ovaj fajl kao /usr/local/bin/calibre-develop, a zatim postavite njegove dozvole tako da može da se izvršava:

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

Kada to uradite, pokrenite:

calibre-develop

Trebalo bi da vidite neke dijagnostičke informacije u Terminal prozoru dok se calibre pokreće, i trebalo bi da vidite zvezdicu posle broja verzije u GUI prozoru, što ukazuje da pokrećete iz izvornog koda.

Linux razvojno okruženje

Белешка

Takođe morate odvojeno preuzeti izvorni kod za calibre kao što je gore opisano.

calibre se prvenstveno razvija na Linuxu. Razvojno okruženje možete postaviti na dva načina: instalirati izvršnu verziju programa i koristiti je kao okruženje za razvoj, kao na Windowsu i macOS-u, ili instalirati calibre iz izvornog koda. Uputstva za drugi način nalaze se u fajlu INSTALL u stablu izvornog koda. Ovde je opisan preporučeni način, s izvršnom verzijom programa.

Instalirajte calibre koristeći binarni instaler. Zatim otvorite terminal i pređite u prethodno preuzeti folder sa calibre kodom, na primer:

cd /home/kovid/work/calibre

calibre je fascikla koja sadrži src i resources podfascikle.

Sledeći korak je postavljanje promenljive okruženja CALIBRE_DEVELOP_FROM na apsolutnu putanju src foldera. Dakle, prateći gornji primer, to bi bilo /home/kovid/work/calibre/src. Kako postaviti promenljive okruženja zavisi od vaše Linux distribucije i shell-a koji koristite.

Белешка

Preporučuje se zvanični instalacioni paket izvršne verzije programa. Ako ipak koristite paket svoje distribucije, umesto toga podesite promenljive CALIBRE_PYTHON_PATH i CALIBRE_RESOURCES_PATH. Njihove vrednosti možete dobiti naredbom calibre-debug --paths. Imajte u vidu da paketi iz distribucija često imaju ozbiljne probleme i da za njih nije obezbeđena podrška.

Kada postavite promenljivu okruženja, otvorite novi terminal i proverite da li je ispravno postavljena koristeći komandu:

echo $CALIBRE_DEVELOP_FROM

Postavljanje ove promenljive okruženja znači da će calibre sada učitavati sav svoj Python kod sa navedene lokacije.

To je to! Sada ste spremni da počnete sa hakovanjem calibre koda. Na primer, otvorite fajl src/calibre/__init__.py u vašem omiljenom editoru i dodajte liniju:

print("Hello, world!")

blizu vrha datoteke. Sada pokrenite komandu calibredb. Prva linija izlaza bi trebalo da bude Hello, world!.

Odvojene „uobičajena” i „razvojna” instalacija programa calibre na istom računaru

Stablo izvornog koda calibre-a je veoma stabilno i retko se kvari, ali ako osećate potrebu da pokrećete iz izvornog koda na odvojenoj test biblioteci i pokrećete izdatu verziju calibre-a sa vašom svakodnevnom bibliotekom, to možete lako postići koristeći .bat fajlove ili shell skripte za pokretanje calibre-a. Primer ispod pokazuje kako to uraditi na Windows-u koristeći .bat fajlove (uputstva za druge platforme su ista, samo koristite shell skriptu umesto .bat fajla)

Za pokretanje izdate verzije calibre-a sa vašom svakodnevnom bibliotekom:

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"

Saveti za otklanjanje grešaka

Python je jezik sa dinamičkim tipovima i odličnom podrškom za ispitivanje objekata. Kovid je napisao osnovni kod programa calibre ne koristeći debager nijednom. Greške u kodu možete otklanjati na više načina:

Korišćenje print naredbi

Ovo je Kovidov omiljeni način za otklanjanje grešaka. Umetnite naredbe print na mesta koja vas zanimaju i pokrenite program u terminalu. Grafički interfejs, na primer, možete pokrenuti ovako:

calibre-debug -g

Slično tome, pregledač e-knjiga možete pokrenuti ovako:

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

Uređivač e-knjiga se može pokrenuti kao:

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

Korišćenje interaktivnog Python interpretera

Možete ubaciti sledeće dve linije koda da biste pokrenuli interaktivnu Python sesiju na tom mestu:

from calibre import ipython
ipython(locals())

Kada se pokreće iz komandne linije, ovo će pokrenuti interaktivni Python interpreter sa pristupom svim lokalno definisanim promenljivama (promenljivama u lokalnom opsegu). Interaktivni odzivnik čak ima i Tab dovršavanje za svojstva objekata i možete koristiti razne Python mogućnosti za introspekciju, kao što su dir(), type(), repr(), itd.

Korišćenje Python debagera za udaljeno otklanjanje grešaka

Ugrađeni Python debager (pdb) možete koristiti za udaljeno otklanjanje grešaka iz komandne linije. Najpre pokrenite debager na mestu u calibre kodu koje vas zanima:

from calibre.rpdb import set_trace
set_trace()

Zatim pokrenite calibre, bilo normalno, ili koristeći jednu od calibre-debug komandi opisanih u prethodnom odeljku. Kada se dostigne gore navedena tačka u kodu, calibre će se zamrznuti, čekajući da se debager poveže.

Sada otvorite terminal ili komandnu liniju i koristite sledeću komandu da započnete sesiju debagovanja:

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

Možete pročitati o tome kako da koristite Python debager u Python stdlib dokumentaciji za pdb modul.

Белешка

Udaljeni debager podrazumevano pokušava da se poveže preko porta 4444. Drugi port možete zadati parametrom port u obe funkcije, set_trace() i cli(), na primer: set_trace(port=1234) i cli(port=1234).

Белешка

Python debager ne može da rukuje višestrukim nitima, tako da morate pozvati set_trace jednom po niti, svaki put sa različitim brojem porta.

Korišćenje debagera u vašem omiljenom Python IDE-u

Moguće je koristiti ugrađeni debager u vašem omiljenom Python IDE-u, ako podržava udaljeno debagovanje. Prvi korak je da dodate calibre src checkout u PYTHONPATH u vašem IDE-u. Drugim rečima, fascikla koju ste postavili kao CALIBRE_DEVELOP_FROM iznad, mora takođe biti u PYTHONPATH vašeg IDE-a.

Zatim postavite modul udaljenog debagera IDE-a u src podfasciklu calibre izvornog koda. Dodajte bilo koji kod koji je potreban za pokretanje udaljenog debagera u calibre na mestu od interesa, na primer u glavnoj funkciji. Zatim pokrenite calibre normalno. Vaš IDE bi sada trebalo da bude u mogućnosti da se poveže sa udaljenim debagerom koji radi unutar calibre-a.

Izvršavanje proizvoljnih skripti u calibre Python okruženju

Komanda calibre-debug pruža nekoliko korisnih prekidača za izvršavanje vašeg sopstvenog koda, sa pristupom calibre modulima:

calibre-debug -c "some Python code"

je odlično za testiranje malog dela koda u komandnoj liniji. Radi na isti način kao i -c prekidač za Python interpreter:

calibre-debug myscript.py

može se koristiti za izvršavanje vaše sopstvene Python skripte. Radi na isti način kao i prosleđivanje skripte Python interpreteru, osim što je calibre okruženje potpuno inicijalizovano, tako da možete koristiti sav calibre kod u vašoj skripti. Da biste koristili argumente komandne linije sa vašom skriptom, koristite oblik:

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

-- uzrokuje da se svi naredni argumenti proslede vašoj skripti.

Pokretanje testova programa calibre

Testove programa calibre možete pokrenuti ovako:

calibre-debug -t all

Korišćenje calibre u vašim projektima

Moguće je direktno koristiti calibre funkcije/kod u vašem Python projektu. Postoje dva načina da se to uradi:

Binarna instalacija calibre

Ako imate binarnu instalaciju calibre-a, možete koristiti Python interpreter koji dolazi uz calibre, ovako:

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

Instalacija iz izvornog koda na Linux-u

Pored korišćenja gore navedene tehnike, ako radite instalaciju iz izvornog koda na Linux-u, možete takođe direktno uvesti calibre, na sledeći način:

import init_calibre
import calibre

print(calibre.__version__)

Od suštinskog je značaja da uvezete init_calibre modul pre bilo kojih drugih calibre modula/paketa jer on podešava interpreter za pokretanje calibre koda.

API dokumentacija za različite delove calibre-a