| 5 | | == Design philosophy == |
| 6 | | |
| 7 | | I come from the Unix world, which means calibre is architected in little pieces each with its own command line interface which means that each piece of functionality is reusable not just in python programs but in any software. |
| 8 | | |
| 9 | | In fact adding complete support for converting any new ebook format to calibre requires the writing of only two converters format->html and html->format as well as a metadata reading/writing tool. All the other features of calibre will work automatically with these three converters in place. Similarly, writing a device driver requires very little work. You basically have to implement a well-defined interface ([http://bazaar.launchpad.net/~kovid/calibre/trunk/annotate/kovid%40kovidgoyal.net-20080503012900-ch7vk8ob2st34dqw?file_id=303%40b0dd1a5d-880a-0410-ada5-a57097536bc1%3Alibprs500%252Ftrunk%3Asrc%252Flibprs500%252Fdevices%252Finterface.py interface.py]). Once you do that, your device will have full support in calibre. |
| 10 | | |
| 11 | | == Adding support for new Input/Output formats == |
| 12 | | |
| 13 | | calibre is written primarily in Python with a few C extension modules. So you have to contribute plugins in either Python or C/C++. Because of its modular design and support infrastructure, adding support for new formats is simple: |
| 14 | | |
| 15 | | * A new input format |
| 16 | | * A module that can read metadata from files in the input format. |
| 17 | | * A module that can convert the input format into one or more HTML files. |
| 18 | | |
| 19 | | * A new output format |
| 20 | | * A module that can write metadata to files in the output format. |
| 21 | | * A module that can convert a sequential list of HTML files into a file in the output format. |
| 22 | | |
| 23 | | If you create a plugin to do this, just let me know, and I will take care of integrating it into the calibre code base. |
| 24 | | |
| 25 | | == Adding support for new devices == |
| 26 | | |
| 27 | | You have to create a device driver that implements the !DeviceInterface defined in [http://bazaar.launchpad.net/~kovid/calibre/trunk/annotate/kovid%40kovidgoyal.net-20080503012900-ch7vk8ob2st34dqw?file_id=303%40b0dd1a5d-880a-0410-ada5-a57097536bc1%3Alibprs500%252Ftrunk%3Asrc%252Flibprs500%252Fdevices%252Finterface.py interface.py]. You should be able to lift a lot of code from the existing drivers in the `calibre.devices` package. |
| 28 | | |
| 29 | | == Browsing the source code == |
| 30 | | |
| 31 | | The source code can be browsed online in [http://bazaar.launchpad.net/~kovid/calibre/trunk/files launchpad]. If you're interested in development, you can submit patches as outlined below. Also consider joining the [https://launchpad.net/~calibre-devs calibre-devs] team and subscribing to its mailing list. |
| 32 | | |
| 33 | | == Setting up the development environment == |
| 34 | | |
| 35 | | *Read first*: If all you want to do is make changes to existing modules in the calibre source code, you don't need a full development environment, you can just use the binary install. The binary install includes the executable calibre-debug which has an --update-module option. So for example if you make changes to the calibre module calibre.devices.kindle.driver you can test your changes by running |
| 36 | | |
| 37 | | {{{ |
| 38 | | calibre-debug --update-module calibre.devices.kindle.driver /path/to/updated/driver.py |
| 39 | | }}} |
| 40 | | |
| 41 | | |
| 42 | | If you are on Linux, setting up a development environment is very simple and is outlined below. If not, there is a VMWare Appliance with a fully-setup development environment as a [https://dev.mobileread.com/dist/brendanl79/calibredevelftenxfce/Calibre-devel-Fedora10-XFCE-20090417.7z virtual machine appliance]. If the above image fails to open in VMware: (1) download the ovf image in [http://calibre.kovidgoyal.net/attachment/wiki/Development/Calibre-devel-F10-XFCE.ovf.zip this zip file,] (2) replace the ovf image in the original directory with the [http://calibre.kovidgoyal.net/attachment/wiki/Development/Calibre-devel-F10-XFCE.ovf.zip downloaded ovf file (1),] (3) run the ovftool as follows |
| 43 | | {{{ |
| 44 | | ovftool --skipManifestGeneration Calibre-devel-F10-XFCE.ovf Calibre-devel-F10-XFCE.vmx |
| 45 | | }}} |
| 46 | | This needs to be run under linux or Windows, you can then copy across to a Mac. When you open the VM in Fusion it will ask if you want to update it, you can safely say yes to this. Passwords are the same as usernames. Once you have it running, log in as kovid and start up Eclipse; it has the calibre project already setup. Update the code from bzr and run setup as shown below. Submit patches and if you want to do a lot of development you can register your own branch in Launchpad, from which I will merge your changes into trunk. |
| 47 | | |
| 48 | | == Instructions for linux == |
| 49 | | |
| 50 | | If you want to submit patches or follow development, you can check out and use calibre from bzr with the commands |
| 51 | | {{{ |
| 52 | | bzr branch lp:calibre |
| 53 | | cd calibre && python setup.py build && sudo python setup.py develop |
| 54 | | }}} |
| 55 | | |
| 56 | | If you do not need the udev support for the Sony Reader, the installed man pages, or the bash completion, you can install it inside your home directory without root privileges, e.g. by using [http://pypi.python.org/pypi/virtualenv/ virtualenv]. |
| 57 | | |
| 58 | | On windows and OSX you may get a Memory Error while trying to do the above. In which case locate the file socket.py in your python installation and change line 308 to |
| 59 | | {{{ |
| 60 | | recv_size = min(65636, max(self._rbufsize, left)) |
| 61 | | }}} |
| 62 | | |
| 63 | | To update from bzr |
| 64 | | {{{ |
| 65 | | python setup.py develop --uninstall |
| 66 | | bzr merge && make && sudo python setup.py develop; |
| 67 | | }}} |
| 68 | | |
| 69 | | To create a patch to submit for inclusion: |
| 70 | | |
| 71 | | |
| 72 | | {{{ |
| 73 | | bzr commit -m "Describe your change here" |
| 74 | | bzr merge |
| 75 | | bzr send -o my-change |
| 76 | | }}} |
| 77 | | |
| 78 | | Attach the file my-change to a [/newticket ticket] with a short description of the change and why you think it should be included. |
| 79 | | |
| 80 | | == Instructions for Windows == |
| 81 | | |
| 82 | | WindowsDevelopment page. (This is out of date, use the calibre-debug based instructions above) |
| 83 | | |
| 84 | | == Instructions for OS X == |
| 85 | | |
| 86 | | [wiki:OSXDevelopment] page. |
| 87 | | |
| 88 | | |
| 89 | | = Sony USB Protocol = |
| 90 | | |
| 91 | | The Sony USB protocol is documented via the API documentation in [http://calibre.kovidgoyal.net/apidocs/html/index.html HTML] and [http://calibre.kovidgoyal.net/apidocs/api.pdf PDF]. A good way to start understanding the protocol is to run `prs500` with the `--log-packets` option. This will give you a packet trace of communication between the device and host. Each packet is identified in the log. The packet format is documented in the API documentation of [http://calibre.kovidgoyal.net/apidocs/html/calibre.prstypes-module.html calibre.prstypes]. |
| 92 | | |
| 93 | | If you want write access to the wiki please [https://calibre.kovidgoyal.net/register register] and then contact me: calibre at kovidgoyal.net. |
| | 5 | Instructions for setting up a development environment are available at: http://calibre.kovidgoyal.net/user_manual/develop.html |
