diff --git a/setup/installer/linux/freeze.py b/setup/installer/linux/freeze.py index f33452fc94..179c001f16 100644 --- a/setup/installer/linux/freeze.py +++ b/setup/installer/linux/freeze.py @@ -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 diff --git a/setup/installer/osx/freeze.py b/setup/installer/osx/freeze.py index c3e0a8d245..4f9a6c62f9 100644 --- a/setup/installer/osx/freeze.py +++ b/setup/installer/osx/freeze.py @@ -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' diff --git a/src/calibre/manual/custom.py b/src/calibre/manual/custom.py index 0df8ea4fa8..1af97bf349 100644 --- a/src/calibre/manual/custom.py +++ b/src/calibre/manual/custom.py @@ -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 diff --git a/src/calibre/manual/develop.rst b/src/calibre/manual/develop.rst new file mode 100644 index 0000000000..27865f2d9a --- /dev/null +++ b/src/calibre/manual/develop.rst @@ -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 `_. +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 `_ 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 ` 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 `_. Similarly, adding support +for new conversion formats involves writing input/output format plugins. Another example of the modular design is the :ref:`recipe system ` 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 `_ 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 `_ 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 + +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 `_ 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. + + diff --git a/src/calibre/manual/index.rst b/src/calibre/manual/index.rst index a8281ef57f..83ff7b0bfe 100644 --- a/src/calibre/manual/index.rst +++ b/src/calibre/manual/index.rst @@ -35,6 +35,7 @@ Sections xpath customize cli/cli-index + develop glossary