mirror of
https://github.com/kovidgoyal/calibre.git
synced 2025-07-09 03:04:10 -04:00
Add a section to the User Manual explaining how to setup a development environment for calibre on all the OSes
This commit is contained in:
Kovid Goyal
parent
c9aeb3fd09
commit
98c00083b1
@ -147,6 +147,9 @@ class LinuxFreeze(Command):
|
||||
sys.frozen_path = DIR_NAME
|
||||
sys.extensions_location = os.path.join(DIR_NAME, 'plugins')
|
||||
sys.resources_location = os.path.join(DIR_NAME, 'resources')
|
||||
dfv = os.environ.get('CALIBRE_DEVELOP_FROM', None)
|
||||
if dfv and os.path.exists(dfv):
|
||||
sys.path.insert(0, dfv)
|
||||
|
||||
executables = %(executables)s
|
||||
|
||||
|
||||
@ -46,10 +46,16 @@ qt_plugins = os.path.join(os.path.realpath(base_dir), 'MacOS')
|
||||
loader_path = os.path.join(dirpath, base_name+'.py')
|
||||
loader = open(loader_path, 'w')
|
||||
site_packages = glob.glob(resources_dir+'/lib/python*/site-packages.zip')[0]
|
||||
devf = os.environ.get('CALIBRE_DEVELOP_FROM', None)
|
||||
do_devf = devf and os.path.exists(devf)
|
||||
if do_devf:
|
||||
devf = os.path.abspath(devf)
|
||||
print >>loader, 'import sys'
|
||||
print >>loader, 'sys.argv[0] =', repr(os.path.basename(path))
|
||||
print >>loader, 'if', repr(dirpath), 'in sys.path: sys.path.remove(', repr(dirpath), ')'
|
||||
print >>loader, 'sys.path.append(', repr(site_packages), ')'
|
||||
if do_devf:
|
||||
print >>loader, 'sys.path.insert(0, %r)'%devf
|
||||
print >>loader, 'sys.frozen = "macosx_app"'
|
||||
print >>loader, 'sys.frameworks_dir =', repr(frameworks_dir)
|
||||
print >>loader, 'sys.extensions_location =', repr(extensions_dir)
|
||||
@ -319,6 +325,11 @@ os.execv(python, args)
|
||||
sys.frameworks_dir = os.path.join(os.path.dirname(os.environ['RESOURCEPATH']), 'Frameworks')
|
||||
sys.resources_location = os.path.join(os.environ['RESOURCEPATH'], 'resources')
|
||||
sys.extensions_location = os.path.join(sys.frameworks_dir, 'plugins')
|
||||
devf = os.environ.get('CALIBRE_DEVELOP_FROM', None)
|
||||
do_devf = devf and os.path.exists(devf)
|
||||
if do_devf:
|
||||
devf = os.path.abspath(devf)
|
||||
sys.path.insert(0, devf)
|
||||
''') + r'\n\1', src)
|
||||
f = open(launcher_path, 'w')
|
||||
print >>f, 'import sys, os'
|
||||
|
||||
@ -9,7 +9,7 @@ sys.path.insert(0, os.path.abspath('../../'))
|
||||
sys.extensions_location = '../plugins'
|
||||
sys.resources_location = '../../../resources'
|
||||
|
||||
from sphinx.builder import StandaloneHTMLBuilder
|
||||
from sphinx.builders.html import StandaloneHTMLBuilder
|
||||
from qthelp import QtHelpBuilder
|
||||
from epub import EPUBHelpBuilder
|
||||
from sphinx.util import rpartition
|
||||
|
||||
192
src/calibre/manual/develop.rst
Normal file
192
src/calibre/manual/develop.rst
Normal file
@ -0,0 +1,192 @@
|
||||
.. include:: global.rst
|
||||
|
||||
.. _develop:
|
||||
|
||||
Setting up a |app| development environment
|
||||
===========================================
|
||||
|
||||
|app| is completely open source, licensed under the `GNU GPL v3 <http://www.gnu.org/copyleft/gpl.html>`_.
|
||||
This means that you are free to download and modify the program to your hearts content. In this section,
|
||||
you will learn how to get a |app| development environment setup on the operating system of your choice.
|
||||
|app| is written primarily in `Python <http://www.python.org>`_ with some C/C++ code for speed and system interfacing.
|
||||
|
||||
.. contents:: Contents
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
Design philosophy
|
||||
-------------------
|
||||
|
||||
|app| has its roots in the Unix world, which means that it's design is highly modular.
|
||||
The modules interact with each other via well defined interfaces. This makes adding new features and fixing
|
||||
bugs in |app| very easy, resulting in a frenetic pace of development. Because of its roots, |app| has a
|
||||
comprehensive command line interface for all its functions, documented in :ref:`cli`.
|
||||
|
||||
The modular design of |app| is expressed via ``Plugins``. There is a :ref:`tutorial <customize>` on writing |app| plugins.
|
||||
For example, adding support for a new device to |app| 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 <http://bazaar.launchpad.net/%7Ekovid/calibre/trunk/files/head%3A/src/calibre/devices/>`_. Similarly, adding support
|
||||
for new conversion formats involves writing input/output format plugins. Another example of the modular design is the :ref:`recipe system <news>` for
|
||||
fetching news.
|
||||
|
||||
Code layout
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
All the |app| python code is in the ``calibre`` package. This package contains the following main sub-packages
|
||||
|
||||
* devices - All the device drivers. Just look through some of the built-in drivers to get an idea for how they work.
|
||||
* ebooks - All the ebook conversion code. A good starting point is ``calibre.ebooks.conversion.cli`` which is the
|
||||
module powering the :command:`ebook-convert` command.
|
||||
* library - The database backed and the content server.
|
||||
* gui2 - The Graphical User Interface.
|
||||
|
||||
Getting the code
|
||||
------------------
|
||||
|
||||
|app| uses `Bazaar <http://bazaar-vcs.org/>`_ a distributed version control system. Bazaar is available on all the platforms |app| supports.
|
||||
After installing Bazaar, you can get the calibre source code with the command::
|
||||
|
||||
bzr branch lp:calibre
|
||||
|
||||
On Windows you will need the complete path name, that will be something like :file:`C:\\Program Files\\Bazaar\\bzr.exe`. To update a branch
|
||||
to the latest code, use the command::
|
||||
|
||||
bzr merge
|
||||
|
||||
Submitting your changes to be included
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you only plan to only make a few small changes, you can make your changes and create a
|
||||
"merge directive" which you can then attach to a ticket in the |app| bug tracker for consideration. To do
|
||||
this, make your changes, then run::
|
||||
|
||||
bzr commit -m "Comment describing your changes"
|
||||
bzr send -o my-changes
|
||||
|
||||
This will create a my-changes file in the current directory, simply attach that to a ticket on the |app| bug tracker at
|
||||
`http://calibre.kovidgoyal.net`_.
|
||||
|
||||
If you plan to do a lot of development on |app|, then the best method is to create a
|
||||
`Launchpad <http://launchpad.net>`_ account. Once you have the account, you can create your own
|
||||
branch in which you do |app| development. To do that go to `https://code.launchpad.net`_ and click
|
||||
"Register a branch" (choose a branch type of "Hosted"). Once the branch is setup you can associate it
|
||||
with the code you checked out in the previous step running the following command in any directory
|
||||
in the |app| code you checked out::
|
||||
|
||||
bzr push <URL of your launchpad branch>
|
||||
|
||||
This will host your branch on launchpad. Now go to `http://code.launchpad.net/calibre`_ and register
|
||||
your branch with the |app| project. Now whenever you commit changes to your branch with the command::
|
||||
|
||||
bzr commit -m "Comment describing your change"
|
||||
|
||||
I can merge it directly from you branch into the main |app| source tree. You should also subscribe to the |app|
|
||||
developers mailing list at `https://launchpad.net/~calibre-devs`_. Before making major changes, you should
|
||||
discuss them on the mailing list to ensure that the changes will be accepted once you're done.
|
||||
|
||||
|
||||
Windows development environment
|
||||
---------------------------------
|
||||
|
||||
Install |app| normally, using the windows installer. Then, open a Command Prompt and change to
|
||||
the previously checked out calibre code directory, for example::
|
||||
|
||||
cd C:\Users\kovid\work\calibre
|
||||
|
||||
calibre is the directory that contains the src and resources sub directories. Then, run the following command::
|
||||
|
||||
calibre-debug --develop-from src
|
||||
|
||||
This assumes that the location of the calibre install (typically ``C:\Program Files\calibre``) is in your PATH.
|
||||
The next step is to set the environment variable ``CALIBRE_DEVELOP_FROM`` to the absolute path to the src directory.
|
||||
So, following the example above, it would be ``C:\Users\kovid\work\calibre\src``. A short
|
||||
`guide <http://docs.python.org/using/windows.html#excursus-setting-environment-variables>`_ to setting environment
|
||||
variables on windows.
|
||||
|
||||
Once you have set the environment variable, open a new Command Prompt and check that it was correctly set by using
|
||||
the command::
|
||||
|
||||
echo %CALIBRE_DEVELOP_FROM%
|
||||
|
||||
Setting this environment variable means that |app| will now load all its Python code from the specified location.
|
||||
|
||||
That's it! You are now ready to start hacking on the |app| code. For example, open the file :file:`src\\calibre\\__init__.py`
|
||||
in your favorite editor and add the line::
|
||||
|
||||
print "Hello, world!"
|
||||
|
||||
near the top of the file. Now run the command :command:`calibredb`. The very first line of output should be ``Hello, world!``.
|
||||
Note that if you make changes to any .ui files (these files define the |app| Graphical User Interface), you have to re-run the
|
||||
``calibre-debug --develop-from src`` command, which will compile the .ui files, so that your changes show up.
|
||||
|
||||
OS X development environment
|
||||
------------------------------
|
||||
|
||||
Install |app| normally, using the provided .dmg. Then, open a Terminal and change to
|
||||
the previously checked out calibre code directory, for example::
|
||||
|
||||
cd /Users/kovid/work/calibre
|
||||
|
||||
calibre is the directory that contains the src and resources sub directories. Then, run the following command::
|
||||
|
||||
calibre-debug --develop-from src
|
||||
|
||||
This assumes that you have installed the |app| command line tools. This can be done via Preferences->Advanced in the |app| GUI.
|
||||
The next step is to set the environment variable ``CALIBRE_DEVELOP_FROM`` to the absolute path to the src directory.
|
||||
So, following the example above, it would be ``/Users/kovid/work/calibre/src``. Apple
|
||||
`documentation http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPRuntimeConfig/Articles/EnvironmentVars.html#//apple_ref/doc/uid/20002093-BCIJIJBH`_
|
||||
on how to set environment variables.
|
||||
|
||||
Once you have set the environment variable, open a new Terminal and check that it was correctly set by using
|
||||
the command::
|
||||
|
||||
echo $CALIBRE_DEVELOP_FROM
|
||||
|
||||
Setting this environment variable means that |app| will now load all its Python code from the specified location.
|
||||
|
||||
That's it! You are now ready to start hacking on the |app| code. For example, open the file :file:`src/calibre/__init__.py`
|
||||
in your favorite editor and add the line::
|
||||
|
||||
print "Hello, world!"
|
||||
|
||||
near the top of the file. Now run the command :command:`calibredb`. The very first line of output should be ``Hello, world!``.
|
||||
Note that if you make changes to any .ui files (these files define the |app| Graphical User Interface), you have to re-run the
|
||||
``calibre-debug --develop-from src`` command, which will compile the .ui files, so that your changes show up.
|
||||
|
||||
Linux development environment
|
||||
------------------------------
|
||||
|
||||
|app| is primarily developed on linux. You have two choices in setting up the development environment. You can install the
|
||||
|app| binary as normal and use that as a runtime environment to do your development. This approach is similar to that
|
||||
used in windows and linux. Alternatively, you can install |app| 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 a runtime.
|
||||
|
||||
Install the |app| using the binary installer. The opena terminal and change to the previously checked out |app| code directory, for example::
|
||||
|
||||
cd /home/kovid/work/calibre
|
||||
|
||||
calibre is the directory that contains the src and resources sub directories. Then, run the following command::
|
||||
|
||||
calibre-debug --develop-from src
|
||||
|
||||
The next step is to set the environment variable ``CALIBRE_DEVELOP_FROM`` to the absolute path to the src directory.
|
||||
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.
|
||||
|
||||
Once you have set the environment variable, open a new terminal and check that it was correctly set by using
|
||||
the command::
|
||||
|
||||
echo $CALIBRE_DEVELOP_FROM
|
||||
|
||||
Setting this environment variable means that |app| will now load all its Python code from the specified location.
|
||||
|
||||
That's it! You are now ready to start hacking on the |app| code. For example, open the file :file:`src/calibre/__init__.py`
|
||||
in your favorite editor and add the line::
|
||||
|
||||
print "Hello, world!"
|
||||
|
||||
near the top of the file. Now run the command :command:`calibredb`. The very first line of output should be ``Hello, world!``.
|
||||
Note that if you make changes to any .ui files (these files define the |app| Graphical User Interface), you have to re-run the
|
||||
``calibre-debug --develop-from src`` command, which will compile the .ui files, so that your changes show up.
|
||||
|
||||
|
||||
@ -35,6 +35,7 @@ Sections
|
||||
xpath
|
||||
customize
|
||||
cli/cli-index
|
||||
develop
|
||||
glossary
|
||||
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user