Add a section to the User Manual explaining how to setup a development environment for calibre on all the OSes

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
 

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'

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

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

src/calibre/manual/index.rst

@@ -35,6 +35,7 @@ Sections
    xpath
    customize
    cli/cli-index
+   develop
    glossary