README

   1
   2                           ___         _    _           ____
   3                      __ _| _ \___  __| |__| |___ _ _  |__ /
   4                     / _` |  _/ _ \/ _` / _` / -_) '_|  |_ \
   5                     \__, |_| \___/\__,_\__,_\___|_|   |___/
   6                     |___/
   7                           Media aggregator and podcast client
   8
   9   ............................................................................
  10
  11              Copyright  2005-2012 Thomas Perl and the gPodder Team
  12
  13
  14  [ LICENSE ]
  15
  16     gPodder is free software; you can redistribute it and/or modify
  17     it under the terms of the GNU General Public License as published by
  18     the Free Software Foundation; either version 3 of the License, or
  19     (at your option) any later version.
  20
  21     gPodder is distributed in the hope that it will be useful,
  22     but WITHOUT ANY WARRANTY; without even the implied warranty of
  23     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  24     GNU General Public License for more details.
  25
  26     You should have received a copy of the GNU General Public License
  27     along with this program. If not, see <http://www.gnu.org/licenses/>.
  28
  29
  30
  31  [ DEPENDENCIES ]
  32
  33     - Python 2.6 or newer              http://python.org/
  34     - "sqlite3" Python module          (usually included with Python)
  35     - Feedparser 5.1.2 or newer        http://code.google.com/p/feedparser/
  36     - mygpoclient 1.4 or newer         http://thp.io/2010/mygpoclient/
  37     - Python D-Bus bindings
  38
  39     gPodder might still work with Python 2.5, but you may need to
  40     install the json module ("simplejson") manually. We reserve the
  41     right to drop support for Python 2.5 in future point releases.
  42
  43     As an alternative to python-dbus on Mac OS X and Windows, you can use
  44     the dummy (no-op) D-Bus module provided in "tools/fake-dbus-module/".
  45
  46     For quick testing, you can use the script tools/localdepends.py to
  47     install local copies of feedparser and mygpoclient into "src/" from
  48     PyPI. With this, you get a self-contained gPodder CLI/WebUI codebase.
  49
  50
  51  [ GTK UI - ADDITIONAL DEPENDENCIES ]
  52
  53     - PyGTK 2.12 or newer              http://pygtk.org/
  54
  55
  56  [ QML UI - ADDITIONAL DEPENDENCIES ]
  57
  58     - Qt 4.7.1 or newer                http://qt.nokia.com/
  59     - PySide 1.0.8 or newer            http://www.pyside.org/
  60     - Qt Mobility 1.2 or newer         http://qt.gitorious.org/qt-mobility
  61     - Qt Quick Components              http://qt.gitorious.org/qt-components
  62
  63     The QML UI depends on the QtMultimediaKit QML bindings for playing
  64     back audio (libdeclarative-multimedia in Debian) and on the WebKit QML
  65     bindings for Flattr integration (libqtwebkit-qmlwebkitplugin in Debian).
  66
  67     The QML UI now also depends on Qt Quick Components. On MeeGo 1.2 Harmattan,
  68     these components are pre-installed. You can install them on your Desktop by
  69     checking out the code from the qt-components Git repository and running the
  70     "./configure" script with the "-meego" parameter (+ the usual make install).
  71
  72     You might also need to copy the theme from /usr/share/themes/blanco/ on a
  73     MeeGo 1.2 Harmattan device to your development machine in order for all UI
  74     elements to be displayed correctly. Alternatively, you can use the free
  75     "darko" theme from: https://github.com/jpavelek/meego-handset-theme-darko
  76
  77
  78  [ OPTIONAL DEPENDENCIES ]
  79
  80     - Bluetooth file sending: gnome-obex-send or bluetooth-sendto
  81     - HTML shownotes: python-webkit
  82     - Flattr integration: python-webkit
  83     - Size detection on Windows: PyWin32
  84     - Native OS X support: ige-mac-integration
  85
  86
  87  [ BUILD DEPENDENCIES ]
  88
  89     - help2man
  90     - intltool
  91
  92
  93  [ TEST DEPENDENCIES ]
  94
  95     - python-minimock
  96     - python-coverage
  97
  98  [ TESTING ]
  99
 100     To run tests, use...
 101         make unittest
 102
 103     To set a specific python binary set PYTHON:
 104         PYTHON=python2 make unittest
 105
 106
 107  [ RUNNING AND INSTALLATION ]
 108
 109     To run gPodder from source, use..
 110
 111         bin/gpodder              for the Gtk+ UI
 112         bin/gpodder --qml        for the QML UI
 113         bin/gpo                  for the command-line interface
 114
 115     To install gPodder system-wide, use "make install". By default, this
 116     will install *all* UIs and all translations. The following environment
 117     variables are processed by setup.py:
 118
 119         LINGUAS                  space-separated list of languages to install
 120         GPODDER_INSTALL_UIS      space-separated list of UIs to install
 121         GPODDER_MANPATH_NO_SHARE if set, install manpages to $PREFIX/man/man1
 122
 123     See setup.py for a list of recognized UIs.
 124
 125     Example: Install the CLI and Gtk UI with German and Dutch translations:
 126
 127         export LINGUAS="de nl"
 128         export GPODDER_INSTALL_UIS="cli gtk"
 129         make install
 130
 131     The "make install" target also supports DESTDIR and PREFIX for installing
 132     into an alternative root (default /) and prefix (default /usr):
 133
 134         make install DESTDIR=tmp/ PREFIX=/usr/local/
 135
 136
 137  [ PYTHON 3 SUPPORT ]
 138
 139     The CLI version of gPodder (bin/gpo) and the QML UI are compatible with
 140     Python 3 after converting the codebase with the 2to3 utility:
 141
 142       2to3 -w bin/* src share/gpodder/extensions
 143
 144     You will also need a copy of "mygpoclient" converted using 2to3 and
 145     a copy of "feedparser" converted using 2to3 (see the feedparser README
 146     for details on how to get it set up on Python 3, including sgmllib).
 147
 148     Please note that the Gtk UI is not compatible with Python 3 (it will
 149     be once we migrate the codebase to Gtk3/GObject Introspection).
 150
 151     The QML UI has been tested with PySide (Git revision a90f3bc) and
 152     Python 3.2.2 - you can use the PySide buildscripts to build PySide:
 153
 154         http://github.com/PySide/BuildScripts
 155
 156     As of February 2012, Python 3 support is still experimental. Please
 157     report any bugs that you find to the gPodder bug tracker (see below).
 158
 159
 160  [ PORTABLE MODE / ROAMING PROFILES ]
 161
 162     The run-time environment variable GPODDER_HOME is used to set
 163     the location for storing the database and downloaded files.
 164
 165     This can be used for multiple configurations or to store the
 166     download directory directly on a MP3 player or USB disk:
 167
 168         export GPODDER_HOME=/media/usbdisk/gpodder-data/
 169
 170
 171  [ CHANGING THE DOWNLOAD DIRECTORY ]
 172
 173     The run-time environment variable GPODDER_DOWNLOAD_DIR is used to
 174     set the location for storing the downloads only (independent of the
 175     data directory GPODDER_HOME):
 176
 177         export GPODDER_DOWNLOAD_DIR=/media/BigDisk/Podcasts/
 178
 179     In this case, the database and settings will be stored in the default
 180     location, with the downloads stored in /media/BigDisk/Podcasts/.
 181
 182     Another example would be to set both environment variables:
 183
 184         export GPODDER_HOME=~/.config/gpodder/
 185         export GPODDER_DOWNLOAD_DIR=~/Podcasts/
 186
 187     This will store the database and settings files in ~/.config/gpodder/
 188     and the downloads in ~/Podcasts/. If GPODDER_DOWNLOAD_DIR is not set,
 189     $GPODDER_HOME/Downloads/ will be used if it is set.
 190
 191
 192  [ LOGGING ]
 193
 194     By default, gPodder writes log files to $GPODDER_HOME/Logs/ and removes
 195     them after a certain amount of times. To avoid this behavior, you can set
 196     the environment variable GPODDER_WRITE_LOGS to "no", e.g:
 197
 198         export GPODDER_WRITE_LOGS=no
 199
 200
 201  [ EXTENSIONS ]
 202
 203     Extensions are normally loaded from gPodder's "extensions/" folder (in
 204     share/gpodder/extensions/) and from $GPODDER_HOME/Extensions/ - you can
 205     override this by setting an environment variable:
 206
 207         export GPODDER_EXTENSIONS="/path/to/extension1.py extension2.py"
 208
 209     In addition to that, if you want to disable loading of all extensions,
 210     you can do this by setting the following environment variable to a non-
 211     empty value:
 212
 213         export GPODDER_DISABLE_EXTENSIONS=yes
 214
 215     If you want to report a bug, please try to disable all extensions and
 216     check if the bug still appears to see if an extension causes the bug.
 217
 218
 219  [ TRANSLATIONS ]
 220
 221     These instructions are mostly useful for the maintainer, but they are
 222     documented here in case you want to update translations yourself:
 223
 224     To upload a changed translation template:
 225
 226         make messages       # update translations from source
 227         make clean          # remove temporary files after "make messages"
 228         tx push --source    # upload po/messages.pot to transifex.net
 229
 230     To download a translation that has been updated:
 231
 232         tx pull -l XX -f    # download po/XX.po from transifex.net
 233
 234     To generate Git commit commands for the translation updates:
 235
 236         python tools/i18n/generate_commits.py
 237
 238     The "tx" command is provided by the Transifex client (transifex-client
 239     in Debian/Ubuntu) which can be obtained from:
 240
 241         http://help.transifex.com/features/client/
 242
 243
 244
 245  [ MORE INFORMATION ]
 246
 247     - Homepage                         http://gpodder.org/
 248     - Bug tracker                      http://bugs.gpodder.org/
 249     - Mailing list                     http://freelists.org/list/gpodder
 250     - IRC channel                      #gpodder on irc.freenode.net
 251
 252   ............................................................................
 253              Last updated: 2012-02-24 by Thomas Perl <thp.io/about>
 254