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 requires at least Python 3.8.

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

All the calibre Python code is in the calibre package. This package contains the following main sub-packages

  • 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 E-kitap düzenleme araçları için API belgeleri.

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

You can get the calibre source code in two ways, using a version control system or directly downloading a tarball.

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 https://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).

If you want to get the code faster, the source code for the latest release is always available as an archive.

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

This will create a my-changes file in the current folder, simply attach that to a ticket on the calibre bug tracker. Note that this will include all the commits you have made. If you only want to send some commits, you have to change origin/master above. To send only the last commit, use:

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

    Replace <username> above with your GitHub username. That will get your fork checked out locally.

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

Install calibre normally, using the Windows installer. Then open a Command Prompt and change to the previously checked out calibre code folder. For example:

cd C:\Users\kovid\work\calibre

calibre is the folder that contains the src and resources sub-folders.

The next step is to set the environment variable CALIBRE_DEVELOP_FROM to the absolute path of the src folder. So, following the example above, it would be C:\Users\kovid\work\calibre\src. Here is a short guide to setting environment variables on Windows.

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

Install calibre normally using the provided .dmg. Then open a Terminal and change to the previously checked out calibre code folder, for example:

cd /Users/kovid/work/calibre

calibre is the folder that contains the src and resources sub-folders. The calibre command line tools are found inside the calibre app bundle, in /Applications/calibre.app/Contents/MacOS you should add this folder to your PATH environment variable, if you want to run the command line tools easily.

The next step is to create a bash script that will set the environment variable CALIBRE_DEVELOP_FROM to the absolute path of the src folder when running calibre in debug mode.

Bir düz metin dosyası oluşturun:

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

Save this file as /usr/local/bin/calibre-develop, then set its permissions so that it can be executed:

chmod +x /usr/local/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.

Install calibre using the binary installer. Then open a terminal and change to the previously checked out calibre code folder, for example:

cd /home/kovid/work/calibre

calibre is the folder that contains the src and resources sub-folders.

The next step is to set the environment variable CALIBRE_DEVELOP_FROM to the absolute path of the src folder. So, following the example above, it would be /home/kovid/work/calibre/src. How to set environment variables depends on your Linux distribution and what shell you are using.

Not

It is recommended to use the binary installer provided from upstream. Should you insist on using a package provided by your distribution, use the CALIBRE_PYTHON_PATH and CALIBRE_RESOURCES_PATH variables instead.

Ç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 --edit-book /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())

When running from the command line, this will start an interactive Python interpreter with access to all locally defined variables (variables in the local scope). The interactive prompt even has Tab completion for object properties and you can use the various Python facilities for introspection, such as dir(), type(), repr(), etc.

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 folder you set as CALIBRE_DEVELOP_FROM above, must also be in the PYTHONPATH of your IDE.

Then place the IDE’s remote debugger module into the src sub-folder of the calibre source code checkout. Add whatever code is needed to launch the remote debugger to calibre at the point of interest, for example in the main function. Then run calibre as normal. Your IDE should now be able to connect to the remote debugger running inside calibre.

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.

Calibre’nin çeşitli kısımları için API belgelendirmesi