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 Index of plugins.

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-books - All the e-book conversion/metadata code. A good starting point is calibre.ebooks.conversion.cli which is the module powering the ebook-convert command. The conversion process is controlled via conversion.plumber. The format independent code is all in ebooks.oeb and the format dependent code is in ebooks.format_name.

    • Metadata okuma, yazma ve indirme tamamen ebooks.metadata içindedir
    • Conversion happens in a pipeline, for the structure of the pipeline, see Giriş. The pipeline consists of an input plugin, various transforms and an output plugin. The code that constructs and drives the pipeline is in plumber.py. The pipeline works on a representation of an e-book that is like an unzipped epub, with manifest, spine, toc, guide, html content, etc. The class that manages this representation is OEBBook in ebooks.oeb.base. The various transformations that are applied to the book during conversions live in oeb/transforms/*.py. And the input and output plugins live in conversion/plugins/*.py.
    • E-book editing happens using a different container object. It is documented in API documentation for the e-book editing tools.
  • 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.

  • Content server: srv is the calibre Content server.

  • gui2 - The Graphical User Interface. GUI initialization happens in gui2.main and gui2.ui. The e-book-viewer is in gui2.viewer. The e-book editor is in gui2.tweak_book.

Ç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

You can also browse the code at GitHub.

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.

If you plan to do a lot of development on calibre, then the best method is to create a GitHub account. Below is a basic guide to setting up your own fork of calibre in a way that will allow you to submit pull requests for inclusion into the main calibre repository:

  • 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.

macOS development environment

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 is primarily developed on Linux. You have two choices in setting up the development environment. You can install the calibre binary as normal and use that as a runtime environment to do your development. This approach is similar to that used in Windows and macOS. Alternatively, you can install calibre from source. Instructions for setting up a development environment from source are in the INSTALL file in the source tree. Here we will address using the binary as a runtime, which is the recommended method.

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

Similarly, you can start the e-book-viewer as:

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

The e-book-editor can be started as:

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

Using an interactive Python interpreter

You can insert the following two lines of code to start an interactive Python session at that point:

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.

Using the Python debugger as a remote debugger

You can use the builtin Python debugger (pdb) as a remote debugger from the command line. First, start the remote debugger at the point in the calibre code you are interested in, like this:

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()"

You can read about how to use the Python debugger in the Python stdlib docs for the pdb module.

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

The Python debugger cannot handle multiple threads, so you have to call set_trace once per thread, each time with a different port number.

Using the debugger in your favorite Python IDE

It is possible to use the builtin debugger in your favorite Python IDE, if it supports remote debugging. The first step is to add the calibre src checkout to the PYTHONPATH in your IDE. In other words, the directory you set as CALIBRE_DEVELOP_FROM above, must also be in the PYTHONPATH of your IDE.

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ı.

Executing arbitrary scripts in the calibre Python environment

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"

is great for testing a little snippet of code on the command line. It works in the same way as the -c switch to the Python interpreter:

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.