언어 변경캘리버 개발 환경 설정¶
캘리버는 `GNU GPL v3 <https://www.gnu.org/licenses/gpl.html>`_에 따라 완전히 오픈 소스로 라이선스되어 있습니다. 이는 프로그램을 자유롭게 다운로드하고 원하는 대로 수정할 수 있다는 의미입니다. 이 섹션에서는 선택한 운영 체제에 캘리버 개발 환경을 설정하는 방법을 배웁니다. 캘리버는 주로 `Python <https://www.python.org>`_으로 작성되었으며, 속도와 시스템 인터페이스를 위해 일부 C/C++ 코드가 포함되어 있습니다. 캘리버에는 최소 Python 3.8이 필요합니다.
설계 철학¶
캘리버는 Unix 세계에 뿌리를 두고 있어 설계가 매우 모듈화되어 있습니다. 모듈들은 잘 정의된 인터페이스를 통해 서로 상호작용합니다. 이로 인해 캘리버에 새로운 기능을 추가하고 버그를 수정하기가 매우 쉬워 빠른 개발 속도를 유지할 수 있습니다. 이러한 뿌리 덕분에 캘리버는 모든 기능에 대한 포괄적인 명령줄 인터페이스를 갖추고 있으며, 이는 :doc:`generated/ko/cli-index`에 문서화되어 있습니다.
캘리버의 모듈식 설계는 ``플러그인``을 통해 표현됩니다. 캘리버 플러그인 작성에 대한 :ref:`튜토리얼 <customize>`이 있습니다. 예를 들어, 캘리버에 새로운 장치 지원을 추가하는 것은 일반적으로 장치 드라이버 플러그인 형태로 100줄 미만의 코드를 작성하는 것과 관련됩니다. `내장 드라이버 <https://github.com/kovidgoyal/calibre/tree/master/src/calibre/devices>`_를 둘러볼 수 있습니다. 마찬가지로, 새로운 변환 형식 지원을 추가하는 것은 입출력 형식 플러그인을 작성하는 것을 포함합니다. 모듈식 설계의 또 다른 예는 뉴스를 가져오기 위한 :ref:`레시피 시스템 <news>`입니다. 캘리버에 기능을 추가하기 위해 설계된 플러그인의 더 많은 예는 `플러그인 색인 <https://www.mobileread.com/forums/showthread.php?p=1362767#post1362767>`_을 참조하십시오.
코드 구성¶
모든 캘리버 Python 코드는 calibre 패키지에 있습니다. 이 패키지는 다음과 같은 주요 하위 패키지를 포함합니다
devices - 모든 장치 드라이버. 일부 내장 드라이버를 살펴보면 작동 방식을 이해할 수 있습니다.
e-books - 모든 전자책 변환/메타데이터 코드. 좋은 출발점은 ebook-convert 명령을 구동하는 모듈인 ``calibre.ebooks.conversion.cli``입니다. 변환 과정은 ``conversion.plumber``를 통해 제어됩니다. 형식 독립적 코드는 모두 ``ebooks.oeb``에 있고, 형식 종속적 코드는 ``ebooks.format_name``에 있습니다.
메타데이터 읽기, 쓰기, 다운로드는 모두 ``ebooks.metadata``에 있습니다
변환은 파이프라인에서 이루어지며, 파이프라인의 구조는 :ref:`conversion-introduction`을 참조하십시오. 파이프라인은 입력 플러그인, 다양한 변환, 출력 플러그인으로 구성됩니다. 파이프라인을 구성하고 구동하는 코드는 :file:`plumber.py`에 있습니다. 파이프라인은 압축 해제된 epub과 类似的 전자책 표현에서 작동하며, 매니페스트, 스파인, 목차, 가이드, html 콘텐츠 등이 포함됩니다. 이 표현을 관리하는 클래스는 ``ebooks.oeb.base``의 OEBBook입니다. 변환 중 책에 적용되는 다양한 변환은 :file:`oeb/transforms/.py`에 있습니다. 그리고 입력 및 출력 플러그인은 :file:`conversion/plugins/.py`에 있습니다.
전자책 편집은 다른 컨테이너 객체를 사용하여 이루어집니다. 이는 :ref:`polish_api`에 문서화되어 있습니다.
db - 데이터베이스 백엔드. 캘리버 라이브러리에 대한 인터페이스는 :ref:`db_api`를 참조하십시오.
콘텐츠 서버: ``srv``는 캘리버 콘텐츠 서버입니다.
gui2 - 그래픽 사용자 인터페이스. GUI 초기화는 ``gui2.main``과 ``gui2.ui``에서 이루어집니다. 전자책 뷰어는 ``gui2.viewer``에 있습니다. 전자책 편집기는 ``gui2.tweak_book``에 있습니다.
모든 다양한 캘리버 실행 파일의 진입점을 찾으려면 linux.py <https://github.com/kovidgoyal/calibre/blob/master/src/calibre/linux.py>`_에서 ``entry_points` 구조를 확인하십시오.
코드 이해에 도움이 필요하다면 `개발 포럼 <https://www.mobileread.com/forums/forumdisplay.php?f=240>`_에 게시하면 캘리버의 많은 개발자 중 한 명에게 도움을 받을 수 있을 것입니다.
코드 가져오기¶
캘리버 소스 코드를 두 가지 방법으로 얻을 수 있습니다: 버전 제어 시스템을 사용하거나 :website_base:`tarball <dist/src>`을 직접 다운로드하는 것입니다.
캘리버는 분산 버전 제어 시스템인 `Git <https://www.git-scm.com/>`_을 사용합니다. Git은 캘리버가 지원하는 모든 플랫폼에서 사용할 수 있습니다. Git을 설치한 후 다음 명령으로 캘리버 소스 코드를 얻을 수 있습니다:
git clone https://github.com/kovidgoyal/calibre.git
Windows에서는 전체 경로 이름이 필요하며, :file:`C:\Program Files\Git\git.exe`와 같은 형태가 됩니다.
캘리버는 매우 긴 소스 제어 기록을 가진 매우 큰 프로젝트이므로, 위 명령은 시간이 걸릴 수 있습니다 (인터넷 속도에 따라 10분에서 1시간).
코드를 더 빠르게 얻고 싶다면, 최신 릴리스의 소스 코드는 항상 :website_base:`아카이브 <dist/src>`로 사용할 수 있습니다.
브랜치를 최신 코드로 업데이트하려면 다음 명령을 사용하십시오:
git pull --no-edit
`GitHub <https://github.com/kovidgoyal/calibre>`_에서도 코드를 둘러볼 수 있습니다.
변경 사항 제출하여 포함시키기¶
작은 변경 사항만 만들 계획이라면, 변경 사항을 만들고 “병합 지시문”을 생성한 후 캘리버 `버그 트래커 <https://bugs.launchpad.net/calibre>`_의 티켓에 첨부할 수 있습니다. 이렇게 하려면 변경 사항을 만든 후 다음을 실행하십시오:
git commit -am "Comment describing your changes"
git format-patch origin/master --stdout > my-changes
이렇게 하면 현재 폴더에 my-changes 파일이 생성되며, 캘리버 `버그 트래커 <https://bugs.launchpad.net/calibre>`_의 티켓에 첨부하기만 하면 됩니다. 여기에는 수행한 모든 커밋이 포함됩니다. 일부 커밋만 보내려면 위의 ``origin/master``를 변경해야 합니다. 마지막 커밋만 보내려면 다음을 사용하십시오:
git format-patch HEAD~1 --stdout > my-changes
마지막 *n*개의 커밋을 보내려면 *1*을 *n*으로 바꾸십시오. 예를 들어, 마지막 3개 커밋의 경우:
git format-patch HEAD~3 --stdout > my-changes
``HEAD~n``을 사용할 때 병합을 포함하지 않도록 주의하십시오.
캘리버에 많은 개발을 할 계획이라면 GitHub 계정을 만드는 것이 가장 좋은 방법입니다. 아래는 기본 캘리버 저장소에 포함되도록 풀 요청을 제출할 수 있는 방식으로 캘리버의 자체 포크를 설정하는 기본 안내입니다:
이 문서의 설명에 따라 컴퓨터에서 git 설정: Git 설정
여기에 설명된 대로 GitHub 인증을 위한 ssh 키 설정: SSH 키 생성
https://github.com/kovidgoyal/calibre로 이동하여 포크 버튼을 클릭하십시오.
터미널에서 다음을 수행:
git clone git@github.com:<username>/calibre.git git remote add upstream https://github.com/kovidgoyal/calibre.git위의 <username>을 GitHub 사용자 이름으로 바꾸십시오. 이렇게 하면 포크가 로컬에 체크아웃됩니다.
원할 때마다 변경하고 커밋할 수 있습니다. 작업을 병합할 준비가 되면 다음을 수행합니다:
git push그리고 ``https://github.com/<username>/calibre``로 이동하여 풀 요청 버튼을 클릭하면 병합 가능한 풀 요청이 생성됩니다.
다음을 수행하여 언제든지 기본 저장소의 코드로 로컬 복사본을 업데이트할 수 있습니다:
git pull upstream
캘리버 `개발 포럼 <https://www.mobileread.com/forums/forumdisplay.php?f=240>`_도 주시해야 합니다. 주요 변경을 하기 전에 포럼에서 논의하거나 Kovid에게 직접 연락해야 합니다 (그의 이메일 주소는 소스 코드 전체에 있습니다).
Windows 개발 환경¶
참고
위에서 설명한 대로 캘리버 소스 코드도 별도로 가져와야 합니다.
`Windows 설치 프로그램 <https://calibre-ebook.com/download_windows>`__을 사용하여 캘리버를 정상적으로 설치하십시오. 그런 다음 명령 프롬프트를 열고 이전에 체크아웃한 캘리버 코드 폴더로 이동하십시오. 예를 들어:
cd C:\Users\kovid\work\calibre
calibre는 src 및 resources 하위 폴더를 포함하는 폴더입니다.
다음 단계는 환경 변수 ``CALIBRE_DEVELOP_FROM``을 src 폴더의 절대 경로로 설정하는 것입니다. 따라서 위 예시를 따르면 ``C:Userskovidworkcalibresrc``가 됩니다. Windows에서 환경 변수를 설정하는 방법에 대한 `간단한 안내 <https://docs.python.org/using/windows.html#excursus-setting-environment-variables>`_가 있습니다.
환경 변수를 설정한 후 새 명령 프롬프트를 열고 다음 명령을 사용하여 올바르게 설정되었는지 확인하십시오:
echo %CALIBRE_DEVELOP_FROM%
이 환경 변수를 설정하면 캘리버가 이제 지정된 위치에서 모든 Python 코드를 불러옵니다.
이제 됐습니다! 이제 캘리버 코드 수정을 시작할 준비가 되었습니다. 예를 들어, 즐겨 사용하는 편집기에서 src\calibre\__init__.py 파일을 열고 다음 줄을 추가하십시오:
print("Hello, world!")
파일 상단 근처에. 이제 calibredb 명령을 실행하십시오. 출력의 첫 번째 줄이 ``Hello, world!``여야 합니다.
원한다면 무료 Microsoft Visual Studio 안에서도 캘리버 개발 환경을 설정할 수 있습니다. `여기 <https://www.mobileread.com/forums/showthread.php?t=251201>`_의 안내를 따르십시오.
macOS 개발 환경¶
참고
위에서 설명한 대로 캘리버 소스 코드도 별도로 가져와야 합니다.
제공된 `.dmg <https://calibre-ebook.com/download_osx>`__를 사용하여 캘리버를 정상적으로 설치하십시오. 그런 다음 터미널을 열고 이전에 체크아웃한 캘리버 코드 폴더로 이동하십시오. 예를 들어:
cd /Users/kovid/work/calibre
calibre는 src 및 resources 하위 폴더를 포함하는 폴더입니다. 캘리버 명령줄 도구는 캘리버 앱 번들 안에 있으며, :file:`/Applications/calibre.app/Contents/MacOS`에 있습니다. 명령줄 도구를 쉽게 실행하려면 이 폴더를 PATH 환경 변수에 추가해야 합니다.
다음 단계는 디버그 모드에서 캘리버를 실행할 때 환경 변수 ``CALIBRE_DEVELOP_FROM``을 src 폴더의 절대 경로로 설정하는 bash 스크립트를 만드는 것입니다.
일반 텍스트 파일 만들기:
#!/bin/sh
export CALIBRE_DEVELOP_FROM="/Users/kovid/work/calibre/src"
calibre-debug -g
이 파일을 :file:`/usr/local/bin/calibre-develop`로 저장한 다음 실행할 수 있도록 권한을 설정하십시오:
chmod +x /usr/local/bin/calibre-develop
이 작업을 완료한 후, 실행:
calibre-develop
캘리버가 시작될 때 터미널 창에 일부 진단 정보가 표시되어야 하며, GUI 창에서 버전 번호 뒤에 별표가 표시되어 소스에서 실행 중임을 나타내야 합니다.
Linux 개발 환경¶
참고
위에서 설명한 대로 캘리버 소스 코드도 별도로 가져와야 합니다.
캘리버는 주로 Linux에서 개발됩니다. 개발 환경을 설정하는 데 두 가지 선택지가 있습니다. 캘리버 바이너리를 정상적으로 설치하고 런타임 환경으로 사용하여 개발할 수 있습니다. 이 접근 방식은 Windows와 macOS에서 사용하는 것과 유사합니다. 또는 소스에서 캘리버를 설치할 수도 있습니다. 소스에서 개발 환경을 설정하는 방법은 소스 트리의 INSTALL 파일에 있습니다. 여기서는 권장 방법으로 바이너리를 런타임으로 사용하는 방법을 다루겠습니다.
`바이너리 설치 프로그램 <https://calibre-ebook.com/download_linux>`_을 사용하여 캘리버를 설치하십시오. 그런 다음 터미널을 열고 이전에 체크아웃한 캘리버 코드 폴더로 이동하십시오. 예를 들어:
cd /home/kovid/work/calibre
calibre는 src 및 resources 하위 폴더를 포함하는 폴더입니다.
다음 단계는 환경 변수 ``CALIBRE_DEVELOP_FROM``을 src 폴더의 절대 경로로 설정하는 것입니다. 따라서 위 예시를 따르면 ``/home/kovid/work/calibre/src``가 됩니다. 환경 변수를 설정하는 방법은 Linux 배포판과 사용 중인 셸에 따라 다릅니다.
참고
상류에서 제공하는 바이너리 설치 프로그램을 사용하는 것이 좋습니다. 배포판에서 제공하는 패키지를 사용하려는 경우, 대신 CALIBRE_PYTHON_PATH 및 CALIBRE_RESOURCES_PATH 변수를 사용하십시오. ``calibre-debug –paths``를 실행하여 이를 얻을 수 있습니다. 하지만 배포판 캘리버 패키지는 종종 완전히 깨져 있으며 완전히 지원되지 않는다는 점에 유의하십시오.
환경 변수를 설정한 후 새 터미널을 열고 다음 명령을 사용하여 올바르게 설정되었는지 확인하십시오:
echo $CALIBRE_DEVELOP_FROM
이 환경 변수를 설정하면 캘리버가 이제 지정된 위치에서 모든 Python 코드를 불러옵니다.
이제 됐습니다! 이제 캘리버 코드 수정을 시작할 준비가 되었습니다. 예를 들어, 즐겨 사용하는 편집기에서 src/calibre/__init__.py 파일을 열고 다음 줄을 추가하십시오:
print("Hello, world!")
파일 상단 근처에. 이제 calibredb 명령을 실행하십시오. 출력의 첫 번째 줄이 ``Hello, world!``여야 합니다.
동일한 컴퓨터에 별도의 “일반” 및 “개발” 캘리버 설치 갖기¶
캘리버 소스 트리는 매우 안정적이며 거의 깨지지 않지만, 별도의 테스트 라이브러리에서 소스로 실행하고 일상 라이브러리에서는 릴리스된 캘리버 버전을 실행해야 한다고 느끼면, .bat 파일이나 셸 스크립트를 사용하여 캘리버를 시작하면 쉽게 이를 달성할 수 있습니다. 아래 예시는 .bat 파일을 사용하여 Windows에서 이 작업을 수행하는 방법을 보여줍니다 (다른 플랫폼에 대한 안내는 동일하며, .bat 파일 대신 셸 스크립트를 사용하십시오)
일상 라이브러리로 캘리버 릴리스 버전을 시작하려면:
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"
디버깅 팁¶
Python은 훌륭한 내성(introspection) 기능을 가진 동적 타입 언어입니다. Kovid는 디버거를 한 번도 사용하지 않고 캘리버 핵심 코드를 작성했습니다. 캘리버 코드를 디버깅하는 여러 전략이 있습니다:
print 문 사용하기¶
이것은 Kovid가 가장 좋아하는 디버깅 방법입니다. 관심 지점에 print 문을 삽입하고 터미널에서 프로그램을 실행하기만 하면 됩니다. 예를 들어, 터미널에서 GUI를 시작할 수 있습니다:
calibre-debug -g
마찬가지로, 전자책 뷰어를 시작할 수 있습니다:
calibre-debug -w /path/to/file/to/be/viewed
전자책 편집기는 다음과 같이 시작할 수 있습니다:
calibre-debug --edit-book /path/to/be/edited
대화형 Python 인터프리터 사용하기¶
다음 두 줄의 코드를 삽입하여 해당 지점에서 대화형 Python 세션을 시작할 수 있습니다:
from calibre import ipython
ipython(locals())
명령줄에서 실행하면 로컬로 정의된 변수(로컬 범위의 변수)에 접근할 수 있는 대화형 Python 인터프리터가 시작됩니다. 대화형 프롬프트는 객체 속성에 대한 Tab 완성 기능도 갖추고 있으며, dir(), type(), repr() 등과 같은 다양한 Python 내성 기능을 사용할 수 있습니다.
Python 디버거를 원격 디버거로 사용하기¶
내장 Python 디버거(pdb)를 명령줄에서 원격 디버거로 사용할 수 있습니다. 먼저 관심 있는 캘리버 코드 지점에서 원격 디버거를 시작하십시오. 예를 들어:
from calibre.rpdb import set_trace
set_trace()
그런 다음 캘리버를 정상적으로 실행하거나 이전 섹션에서 설명한 calibre-debug 명령 중 하나를 사용하여 실행하십시오. 코드의 위 지점에 도달하면 캘리버가 중단되어 디버거가 연결되기를 기다립니다.
이제 터미널이나 명령 프롬프트를 열고 다음 명령을 사용하여 디버깅 세션을 시작하십시오:
calibre-debug -c "from calibre.rpdb import cli; cli()"
`Python 표준 라이브러리 문서의 pdb 모듈 <https://docs.python.org/library/pdb.html#debugger-commands>`_에서 Python 디버거 사용 방법에 대해 읽을 수 있습니다.
참고
기본적으로 원격 디버거는 포트 4444에 연결을 시도합니다. 위의 set_trace()와 cli() 함수 모두에 port 매개변수를 전달하여 이를 변경할 수 있습니다: set_trace(port=1234) 및 cli(port=1234).
참고
Python 디버거는 여러 스레드를 처리할 수 없으므로, 각 스레드마다 한 번씩 set_trace를 호출해야 하며, 매번 다른 포트 번호를 사용해야 합니다.
즐겨 사용하는 Python IDE에서 디버거 사용하기¶
즐겨 사용하는 Python IDE에서 내장 디버거를 사용할 수 있습니다 (원격 디버깅을 지원하는 경우). 첫 번째 단계는 캘리버 src 체크아웃을 IDE의 ``PYTHONPATH``에 추가하는 것입니다. 즉, 위에서 ``CALIBRE_DEVELOP_FROM``으로 설정한 폴더가 IDE의 ``PYTHONPATH``에도 있어야 합니다.
그런 다음 IDE의 원격 디버거 모듈을 캘리버 소스 코드 체크아웃의 src 하위 폴더에 넣으십시오. 관심 지점에서 (예: 기본 함수에서) 캘리버에 원격 디버거를 시작하는 데 필요한 코드를 추가하십시오. 그런 다음 캘리버를 정상적으로 실행하십시오. 이제 IDE가 캘리버 내부에서 실행 중인 원격 디버거에 연결할 수 있어야 합니다.
캘리버 Python 환경에서 임의 스크립트 실행하기¶
calibre-debug 명령은 캘리버 모듈에 접근할 수 있는 자체 코드를 실행하기 위한 몇 가지 편리한 스위치를 제공합니다:
calibre-debug -c "some Python code"
명령줄에서 약간의 코드 조각을 테스트하는 데 유용합니다. Python 인터프리터에 대한 -c 스위치와 동일한 방식으로 작동합니다:
calibre-debug myscript.py
자신의 Python 스크립트를 실행하는 데 사용할 수 있습니다. 캘리버 환경이 완전히 초기화되어 스크립트의 모든 캘리버 코드를 사용할 수 있다는 점을 제외하고는 Python 인터프리터에 스크립트를 전달하는 것과 같은 방식으로 작동합니다. 스크립트와 함께 명령줄 인수를 사용하려면 다음 형식을 사용합니다:
calibre-debug myscript.py -- --option1 arg1
프로젝트에서 캘리버 사용하기¶
Python 프로젝트에서 직접 캘리버 함수/코드를 사용할 수 있습니다. 두 가지 방법이 있습니다:
캘리버 바이너리 설치¶
캘리버의 바이너리 설치가 있는 경우, 다음과 같이 캘리버와 함께 번들로 제공되는 Python 인터프리터를 사용할 수 있습니다:
calibre-debug /path/to/your/python/script.py -- arguments to your script
Linux에서 소스 설치¶
위의 기술을 사용하는 것 외에도, Linux에서 소스 설치를 수행하면 다음과 같이 직접 캘리버를 가져올 수도 있습니다:
import init_calibre
import calibre
print(calibre.__version__)
다른 캘리버 모듈/패키지보다 먼저 init_calibre 모듈을 가져오는 것이 필수적입니다. 이 모듈이 인터프리터를 캘리버 코드를 실행하도록 설정하기 때문입니다.