Calibre geliştirme ortamı ayarlamak

calibre is completely open source, licensed under the GNU GPL v3. This means that you are free to download and modify the program to your heart’s content. In this section, you will learn how to get a calibre development environment set up on the operating system of your choice. calibre is written primarily in Python with some C/C++ code for speed and system interfacing. Note that calibre is not compatible with Python 3 and requires at least Python 2.7.9.

Tasarım felsefesi

calibre’nin kökleri Unix dünyasına uzanır, yani tasarımı oldukça modülerdir. Modüller birbirleriyle iyi tanımlanmış arayüzlerle iletişim kurarlar. Bu da calibre’ye yeni özellikler ekleme ve hata ayıklamayı çok kolay kılarak hızlı geliştirme temposu oluşturur. Kökleri sebebiyle, calibre’nin tüm fonksiyonları için Komut Satırı Arayüzü de belgelenmiş kapsamlı bir komut satırı arayüzü vardır.

The modular design of calibre is expressed via Plugins. There is a tutorial on writing calibre plugins. For example, adding support for a new device to calibre typically involves writing less than a 100 lines of code in the form of a device driver plugin. You can browse the built-in drivers. Similarly, adding support for new conversion formats involves writing input/output format plugins. Another example of the modular design is the recipe system for fetching news. For more examples of plugins designed to add features to calibre, see the plugin index.

Kod düzeni

Tüm calibre python kodu calibre paketindedir. Bu paket aşağıdaki alt paketleri içerir

  • devices - Tüm aygıt sürücüleri. Bazı yerleşik sürücülere bakmanız nasıl çalıştıkları konusunda fikir edinmeniz için yeterli olacaktır.

    • Detaylar için: aygıt sürücüleri tarafından desteklenen arayüzü tanımlayan devices.interface ve bir USBMS aygıtına bağlanan genel bir sürücü tanımlayan devices.usbms e göz atın. Calibre’deki tüm USBMS temelli sürücüler ondan türemiştir.

  • e-kitaplar - Tüm e-kitap dönüştürme/metadata kodu. İyi bir başlangıç noktası ebook-convert komutuna gücünü veren calibre.ebooks.conversion.cli modülüdür. Dönüştürme süreci conversion.plumber ile kontrol edilir. Biçim bağımsız tüm kod ebooks.oeb içindedir ve biçim bağımlı kodlar ebooks.format_name içindedir.

    • Metadata okuma, yazma ve indirme tamamen ebooks.metadata içindedir

    • Dönüştürme bir boru hattı içinde olur, bu hattın yapısı için şuraya göz atın Giriş. Hat bir girdi eklentisi, çeşitli dönüştürmeler ve bir çıktı eklentisinden oluşur. Boru hattını oluşturan ve yürüten kod plumber.py içerisindedir. Hat bir e-kitabın manifesto, omurga, toc, kılavuz, html içerik, vs. içeren sıkıştırılmamış epub gibi bir temsili üstünde çalışır. Bu sunumu yöneten sınıf ebooks.oeb.base içindeki OEBBook sınıfıdır. Dönüştürme sırasında e-kitaba uygulanan çeşitli dönüştürmeler oeb/transforms/*.py içindedir. Girdi ve çıktı eklentileri ise conversion/plugins/*.py içinde.

    • E-kitap düzenleme için değişik bir kapsayıcı nesne kullanılır. E-kitap düzenleme araçları için API Belgelendirmesi içinde belgelenmiştir.

  • db - Veri tabanı arka ucu. Calibre kitaplığına arayüz için Veri tabanı arayüzü için API Belgelendirmesi ye göz atın.

  • içerik sunucu: library.server calibre İçerik Sunucusudur.

  • gui2 - Grafik Kullanıcı Arayüzü. GUI ilklendirmesi gui2.main ve gui2.ui içinde gerçekleşir. E-kitap okuyucu gui2.viewer içindedir. E-kitap düzenleyici de gui2.tweak_book içinde.

Çeşitli calibre çalıştırılabilirleri için giriş noktalarını bulmak isterseniz, linux.py içindeki ``entry_points``e bakın.

If you need help understanding the code, post in the development forum and you will most likely get help from one of calibre’s many developers.

Kodun alınması

Calibre kaynak kodunu iki şekilde edinebilirsiniz, ya sürüm denetim sistemiyle ya da direkt olarak https://calibre-ebook.com/dist/src. tar arşivinden indirerek

calibre uses Git, a distributed version control system. Git is available on all the platforms calibre supports. After installing Git, you can get the calibre source code with the command:

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

Windows üstünde tam yol ismine ihtiyacınız olacaktır, şuna benzer bir şey olmalı C:\Program Files\Git\git.exe.

calibre çok geniş ve çok uzun kaynak kontrol geçmişine sahip bir projedir, yani yukarıdaki işlem bir miktar sürebilir (internet hızınıza bağlı olarak 10 dakikadan bir saate kadar).

Eğer koda daha hızlı şekilde sahip olmak istiyorsanız, en son sürüm kaynak kodu her daim arşiv olarak <https://calibre-ebook.com/dist/src>`_ adresinde mevcuttur.

Bir dalı son koda güncellemek için, şu komutu kullanın:

git pull --no-edit

Değişikliklerinizin içerilmesi için gönderilmesi

Yalnızca bir kaç küçük değişiklik yapmak istiyorsanız, değişikliklerinizi yapıp calibre hata takibinde bir bilete ekleyebileceğiniz bir “merge talimatı” oluşturun. Bu işlem için değişikliklerinizi yapıp şunu çalıştırın:

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

Bu işlem mevcut dizinde bir my-changes dosyası oluşturur, bunu basitçe calibre hata takibindeki bir bilete ekleyin. Bu işlemin yaptığınız tüm gönderimleri içereceğini unutmayın. Sadece bazı gönderimleri yollamak isterseniz, yukardaki origin/master kısmını değiştirmelisiniz. Sadece son gönderiyi yollamak için:

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

Son n gönderiyi yollamak için, 1 i n ile değiştirin, örneğin, son 3 gönderi için:

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

Be careful to not include merges when using HEAD~n.

calibre üstünde yoğun geliştirme yapmayı planlıyorsanız, en iyi yöntem bir GitHub hesabı açmak olacaktır. Aşağıda ana calibre deposuna çekme istekleri yapabileceğiniz şekilde kendi calibre çatalınızı nasıl oluşturacağınızı gösteren basit bir kılavuz bulabilirsiniz:

  • Makalede gösterildiği gibi makinenize git kurun: Git Kurulumu

  • Şurada anlatıldığı gibi, GitHub’a kimlik doğrulama için ssh anahtarları kurun: SSH anahtarları üretme

  • https://github.com/kovidgoyal/calibre adresine gidin ve Fork düğmesine tıklayın.

  • Bir Terminal açın ve:

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

    <username> kısmını github kullanıcı adınızla değiştirin. Bu işlem sizin çatalınızı yerel olarak getirmeye yarar.

  • İstediğiniz gibi değişiklikler yapabilir ve istediğiniz zaman gönderebilirsiniz. Yaptığınız işler birleştirmeye hazır olduğunda:

    git push
    

    sonra da https://github.com/<username>/calibre adresine gidin ve Pull Request düğmesine tıklayıp birleştirme işlemi için bir çekme isteği üretin.

  • Herhangi bir anda yerel kopyanızı ana depo ile şu şekilde güncel tutabilirsiniz:

    git pull upstream
    

You should also keep an eye on the calibre development forum. Before making major changes, you should discuss them in the forum or contact Kovid directly (his email address is all over the source code).

Windows geliştirme ortamı

Not

Yukarda anlatıldığı gibi calibre kaynak kodunu almalısınız.

Calibre’yi Windows yükleyici kullanarak normalce kurun. Sonra bir Komut Satırı açın ve önceden getirilmiş olan calibre kod dizinine gidin. Örneğin:

cd C:\Users\kovid\work\calibre

calibre src ve kaynak alt dizinlerini içeren dizindir.

Sonraki adım çevre değişkeni CALIBRE_DEVELOP_FROM değerinin src dizininin mutlak yoluna ayarlanmasıdır. Yani, yukardaki örneği takip edersek, C:\Users\kovid\work\calibre\src dizini olurdu. Windows üstünde çevre değişkeni ayarlamakla ilgili kısa bir kılavuz.

Çevre değişkenini ayarladıktan sonra, yeni bir komut satırı açın ve şu komutu kullanarak düzgün ayarlandığını doğrulayın:

echo %CALIBRE_DEVELOP_FROM%

Bu çevre değişkenini ayarlamak calibre’nin belirtilen konumdan tüm Python kodunu yükleyeceği anlamına gelir.

Bu kadar! Şimdi calibre kodu üstünde çalışmaya başlayabilirsiniz. Örneğin favori düzenleyicinizle src\calibre\__init__.py dosyasını açın ve şu satırı ekleyin:

print ("Hello, world!")

dosyanın üst kısmına doğru. Şimdi calibredb komutunu çalıştırın. Çıktının ilk satırı Hello, world! olmalı.

You can also setup a calibre development environment inside the free Microsoft Visual Studio, if you like, following the instructions here.

OS X geliştirme ortamı

Not

Yukarda anlatıldığı gibi calibre kaynak kodunu almalısınız.

Calibre’yi sağlanan .dmg dosyası ile normal olarak kurun. Sonra bir Terminal açın ve daha önceden getirilmiş calibre kod dizinine gidin, örneğin:

cd /Users/kovid/work/calibre

calibre src ve kaynak alt dizinlerini içeren dizindir. calibre GUI’sindeki Seçenekler->Gelişmiş->Diğer menüsünden calibre komut satırı araçlarını yüklediğinize emin olun.

Sonraki adım calibre’yi hata ayıklama kipinde çalıştırırken CALIBRE_DEVELOP_FROM çevre değişkenini src dizininin mutlak yoluna ayarlayacak bir bash betiği oluşturmaktır.

Bir düz metin dosyası oluşturun:

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

Bu dosyayı /usr/bin/calibre-develop altına kaydedin, ve çalıştırılabilir olması için izinlerini ayarlayın:

chmod +x /usr/bin/calibre-develop

Bu işlemden sonra şunu çalıştırın:

calibre-develop

Calibre başlarken Uç birim penceresinde bazı tanılama bilgileri görüyor olmalısınız, ve GUI penceresinde sürüm numarasından sonra kaynaktan çalıştırdığınızı belirten bir yıldız işareti görmelisiniz.

Linux geliştirme ortamı

Not

Yukarda anlatıldığı gibi calibre kaynak kodunu almalısınız.

calibre öncelikle Linux üzerinde geliştirilmiştir. Geliştirme ortamını seçmede iki seçeneğiniz vardır. Calibre ikiliğini normal olarak yükleyebilir ve bunu geliştirme ortamınız için çalışma zamanı ortamı olarak kullanabilirsiniz. Bu yaklaşım Windows ve OS X’de kullanılana benzer. Alternatif olarak, calibre’yi kaynaktan yükleyebilirsiniz. Kaynaktan geliştirme ortamı ayarlamakla ilgili yönergeler kaynak ağacındaki INSTALL dosyasındadır. Burada ikiliği çalışma zamanında kullanacakmış gibi anlatacağız, bu önerilen yöntemdir.

Calibre’yi ikilik yükleyici ile yükleyin. Sonra bir uç birim açın ve daha önceden getirilmiş calibre kod dizinine gidin, örneğin:

cd /home/kovid/work/calibre

calibre src ve kaynak alt dizinlerini içeren dizindir.

Sonraki adım CALIBRE_DEVELOP_FROM çevre değişkenini src dizininin mutlak yoluna ayarlamaktır. Yukardaki örnek göz önüne alınırsa bu /home/kovid/work/calibre/src olur. Çevre değişkenlerinin nasıl ayarlanacağı kullandığınız Linux dağıtımına ve kabuğa bağlıdır.

Çevre değişkenini ayarladıktan sonra, bir uç birim açın şu komutu kullanarak düzgün ayarlanıp ayarlanmadığını kontrol edin:

echo $CALIBRE_DEVELOP_FROM

Bu çevre değişkenini ayarlamak calibre’nin belirtilen konumdan tüm Python kodunu yükleyeceği anlamına gelir.

Bu kadar! Şimdi calibre kodu üstünde çalışmaya başlayabilirsiniz. Örneğin favori düzenleyicinizle src/calibre/__init__.py dosyasını açın ve şu satırı ekleyin:

print ("Hello, world!")

dosyanın üst kısmına doğru. Şimdi calibredb komutunu çalıştırın. Çıktının ilk satırı Hello, world! olmalı.

Aynı bilgisayarda ayrı “normal” ve “geliştirme” calibre yüklemelerini bulundurmak

Calibre kaynak ağacı oldukça kararlıdır ve çok nadiren kırılır, ama ayrı bir test kitaplığından kaynaktan çalıştırma ve yayınlanan calibre sürümünü gündelik kitaplığınızla çalıştırma gibi bir ihtiyaç duyarsanız, .bat dosyaları veya kabuk betikleri kullanarak calibre’yi başlatabilirsiniz. Aşağıdaki örnek Windows üzerinde .bat dosyaları (diğer platformlar için de yönergeler aynıdır, .bat dosyası yerine kabuk betiği kullanmanız yeterli) ile bu işin nasıl yapılacağını gösteriyor

Günlük kitaplığınızla calibre’nin yayınlanan sürümünü başlatmak için:

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"

Hata ayıklama ipuçları

Python iç gözlem için mükemmel imkanları olan dinamik yazılan bir dildir. Kovid calibre çekirdek kodunu hata ayıklayıcı kullanmadan yazdı. Calibre kodunda hata ayıklama için bir çok taktik vardır:

Print ifadeleri kullanarak

Kovid’in favori hata ayıklama yöntemi. İlgilendiğiniz noktalara print ifadeleri koyun ve programı uç birimde çalıştırın. Örneğin GUI’yi uç birimden şu şekilde başlatabilirsiniz:

calibre-debug -g

Benzer şekilde, e-kitap görüntüleyiciyi şu şekilde başlatabilirsiniz:

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

E-kitap düzenleyici şöyle başlatılabilir:

calibre-debug -t /path/to/be/edited

Etkileşimli python yorumcusu kullanarak

Aşağıdaki iki satır kodu ekleyerek o noktada etkileşimli bir python oturumu başlatabilirsiniz:

from calibre import ipython
ipython(locals())

Komut satırından çalıştırırken, tüm yerel tanımlı değişkenlere (yerek kapsamdaki değişkenler) erişimi olan etkileşimli bir Python yorumlayıcı başlatacaktır. Etkileşimli yorumlayıcının nesne özellikleri için TAB ile tamamlama özelliği bile vardır ayrıca dir(), type(), repr(), vs. gibi çeşitli Python olanaklarını da kullanabilirsiniz.

Python hata ayıklayıcıyı uzak hata ayıklayıcı olarak kullanmak

Yerleşik python hata ayıklayıcısını (pdb) komut satırından uzak hata ayıklayıcı olarak kullanabilirsiniz. Önce, şu şekilde, uzak hata ayıklayıcıyı calibre kodunda ilgilendiğiniz noktada başlatın:

from calibre.rpdb import set_trace
set_trace()

Ardından calibre’yi normal ya da önceki kısımda açıklanan calibre hata ayıklama komutlarından birini kullanarak çalıştırın. Kodda yukardaki noktaya erişildiğinde calibre donacak ve hata ayıklayıcının bağlanmasını bekleyecektir.

Şimdi bir uç birim açın ve hata ayıklama oturumunu başlatmak için aşağıdaki komutu kullanın:

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

Python hata ayıklayıcıyı nasıl kullanacağınız hakkında bilgiyi pdb modülü için python stdlib belgelerinde bulabilirsiniz.

Not

Varsayılan olarak, uzak hata ayıklayıcı port 4444’den bağlanmaya çalışacaktır. Yukardaki set_trace() ve cli() fonksiyonlarına port parametresini set_trace(port=1234) ve cli(port=1234) şeklinde geçirerek değiştirebilirsiniz.

Not

Python hata ayıklayıcı birden çok iş ipini desteklemez, yani her iş ipi için set_trace’i her seferinde değişik bir port numarasıyla bir kere çağırmalısınız.

Hata ayıklayıcının favori python IDE’nizde kullanımı

Eğer uzak hata ayıklamayı destekliyorsa, yerleşik hata ayıklayıcı favori python IDE’niz tarafından kullanılabilir. İlk adım calibre nin indirilmiş src yolunu IDE’nizde PYTHONPATH``e eklemek. Başka bir deyişle, yukarda ``CALIBRE_DEVELOP_FROM olarak ayarladığınız dizin IDE’nizin ``PYTHONPATH``inde de yer almalıdır.

Sonra IDE’nin uzak hata ayıklayıcı modülünü calibre kaynak kodunuzun src alt dizinine yerleştirin. Uzak hata ayıklayıcı çalıştırmak için ne gerekiyorsa calibre’de ilgilendiğiniz noktaya ekleyin. Sonra calibre’yi normal şekilde çalıştırın. IDE’niz artık calibre içinde gelen uzak hata ayıklayıcıya bağlanabiliyor olmalı.

Calibre python ortamında keyfi betik çalıştırma

calibre-debug komutu calibre modüllerine erişimi olan kodunuzun çalışmasını sağlayan bir kaç pratik anahtar içerir:

calibre-debug -c "some python code"

komut satırında küçük bir kod parçasını test etmek için çok iyidir. Python yorumlayıcısındaki -c anahtarıyla aynı şekilde çalışır:

calibre-debug myscript.py

kendi Python betiğinizi çalıştırmak için kullanılabilir. Betiğin Python yorumlayıcısına verilmesiyle aynı şekilde çalışır, tek fark calibre ortamının tamamen başlatılmış olması, yani betiğinizde tüm calibre kodunu kullanabilecek olmanızdır. Betiğinizle komut satırı bağımsız değişkenlerini kullanmak için şu biçimi kullanın:

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

-- takip eden tüm değişkenlerin betiğinize geçirilmesine sebep olur.

Projelerinizde calibre kullanmak

Python projenizde calibre fonksiyonlarını/kodunu doğrudan kullanmak mümkündür. Bunu yapmanın iki yolu vardır:

Calibre’nin ikilik kurulumu

Eğer calibre’nin ikilik kurulumuna sahipseniz, calibre ile gelen Python yorumlayıcısını şu şekilde kullanabilirsiniz:

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

Linux üstünde kaynak kurulum

Yukardaki yöntemin yanında, Linux üstünde kaynaktan kurulum yaparsanız, calibre’yi doğrudan şu şekilde içe aktarabilirsiniz:

import init_calibre
import calibre

print calibre.__version__

Calibre kodunu çalıştırmak için yorumlayıcıyı ayarladığından, herhangi başka calibre modülünden/paketinden önce init_calibre modülünü içe aktarmanız önemlidir.