README

   1 General
   2 =======
   3
   4 libquvi-scripts contains the Lua scripts for libquvi that it uses to parse
   5 the media properties.
   6
   7 gitweb: <http://repo.or.cz/w/libquvi-scripts.git>
   8 Home  : <http://quvi.sourceforge.net/>
   9
  10
  11 Installation
  12 ============
  13
  14 Notes
  15 -----
  16
  17   * This document does not cover how to use GNU Autotools for building
  18 and installing software, instead, refer to the GNU Autotools documentation,
  19 the INSTALL file and the "configure --help" output for more information.
  20
  21   * If you're not familiar with GNU Autotools and/or installing software
  22 from the source code, you may prefer to install libquvi-scripts using a
  23 binary package, instead. You can find libquvi-scripts packaged for many
  24 distros already.
  25
  26   * If you have previously installed libquvi-scripts from the source code
  27 to your system, the recommended practice is to uninstall the previous
  28 installation first, before you continue with the new one. You would,
  29 typically, run "make uninstall" (as root if necessary) from the same
  30 directory you ran "make install" from.
  31
  32   * If you are building libquvi-scripts from the git repository code, run
  33 the `bootstrap.sh' first. This generates the configuration files. See also
  34 the -h output for any additional info.
  35
  36
  37 Simple install procedure
  38 ------------------------
  39
  40   % ./configure && make
  41
  42   [ Become root if necessary ]
  43   % make install
  44
  45 The configure script supports also the following options which are
  46 relevant to the installation:
  47
  48   --with(out)-geoblocked (default: yes)
  49
  50     Install the scripts written for websites that are known to geoblock
  51     IP addresses outside of their definition of the accepted IP ranges.
  52
  53     These are usually websites that block IPs from countries, sometimes
  54     even cities, based on the registered geological location of the IP
  55     address.
  56
  57   --with(out)-fixme (default: no)
  58
  59     Install the scripts that have been marked as "FIXME". These are
  60     known to be broken and need to be fixed. Patches welcome.
  61
  62   --with(out)-nsfw (default: no)
  63
  64     Install the scripts written for websites that host NSFW media.
  65
  66   --with(out)-manual (default:yes)
  67
  68     Install the manual page for libquvi-scripts.
  69
  70   --with(out)-tests (default: no)
  71
  72     Install with the tests. This enables the testsuite, see "Tests"
  73     for more information.
  74
  75     Note that the --with(out)-* options are ignored by the testsuite.
  76     If you need more control over which of the tests should be run,
  77     see the "Tests: Environment variables" for more information.
  78
  79
  80 Requirements
  81 ------------
  82
  83 * Lua BitOp 1.0.1
  84   http://bitop.luajit.org/
  85     $ sudo aptitude install lua-bitop
  86
  87 * LuaExpat 1.2.0
  88   http://matthewwild.co.uk/projects/luaexpat/
  89     $ sudo aptitude install lua-expat
  90
  91 * LuaJSON 1.1.1
  92   http://www.eharning.us/wiki/luajson/
  93     $ sudo aptitude install lua-json
  94
  95 * LuaSocket 2.0.2
  96   http://w3.impa.br/~diego/software/luasocket/
  97     $ sudo aptitude install lua-socket
  98
  99 * pkg-config for tracking the compilation flags needed for libraries
 100   http://www.freedesktop.org/software/pkgconfig/
 101
 102 * GNU make is recommended
 103   http://www.gnu.org/software/make
 104
 105 * asciidoc (a2x) for producing the manual pages
 106   http://www.methods.co.nz/asciidoc/
 107
 108       See also "Documentation".
 109
 110 When the configure script is run with the `--with-tests':
 111
 112   * libquvi 0.9
 113     http://quvi.sf.net/
 114
 115   * GLib 2.24.2
 116     http://library.gnome.org/devel/glib/
 117
 118   * libcurl 7.21.0
 119     http://curl.haxx.se/
 120
 121
 122 Installation directories
 123 ------------------------
 124
 125 The location of the installed files is determined by the --prefix
 126 and the --exec-prefix options given to the configure script.
 127
 128 The .pc file for libquvi-scripts is installed in $exec_prefix/lib/pkgconfig
 129 to provide information when compiling packages that depend on libquvi-scripts.
 130
 131
 132 Documentation
 133 =============
 134
 135 To build the documentation suite, you need to have asciidoc. Because
 136 not all users are inclined to install this tool, the default build
 137 target does not build the documentation. See "make doc" below for
 138 more information.
 139
 140     Installation: The libquvi-scripts dist tarball contains prebuilt
 141     manual pages, and are installed by default. See `--with(out)-manual'
 142     above. See also "make doc" below.
 143
 144 Make targets:
 145
 146   'make doc'  builds the manual pages for libquvi-scripts if a2x(1) was
 147   found by configure.  The manual page files can be found at:
 148     $top_srcdir/doc/man7/ -- input
 149     $top_builddir/doc/man7/ -- output
 150
 151
 152 Tests
 153 =====
 154
 155 The tests use the GLib framework for testing. All of these tests require
 156 the presence of the libquvi and a working internet connection. The tests
 157 reside in the tests/ directory.
 158
 159   'make check'  will run the test programs listed in the TEST_PROGS
 160   variable in the tests/Makefile.am . It will fail if any of the
 161   tests fail. This is identical to running 'make test'.
 162
 163     NOTE: You must run `configure --with-tests' to enable the tests,
 164           they are not enabled by default.
 165
 166   'make distcheck'  will fail if any of the tests fail. Note that this
 167   would, typically, require:
 168     env DISTCHECK_CONFIGURE_FLAGS=--with-tests  make distcheck
 169
 170 The tests use the gtester(1) and gtester-report(1) commands to produce
 171 the logs. These programs are part of GLib. The test programs produce:
 172   $(top_builddir)/tests/$test_program.html  # gtester-report
 173   $(top_builddir)/tests/$test_program.xml   # gtester
 174
 175
 176 Tests: Environment variables
 177 ----------------------------
 178
 179 The testsuite supports the following environment variables:
 180
 181   TEST_VERBOSE  will enable verbose libcurl(3) output.
 182
 183   TEST_SKIP  will disable the specified tests. This list is a comma-separated
 184   list of test names. The comma-separated values are treated as regular
 185   expression patterns.
 186
 187   TEST_GEOBLOCKED  will enable the tests for the scripts that have been
 188   marked as "geoblocked". These are skipped by default.
 189
 190   TEST_FIXME  will enable the tests for the scripts that have been marked
 191   as "FIXME". These are skipped by default.
 192
 193   TEST_NSFW  will enable the tests for the scripts that have been marked
 194   as "NSFW". These are skipped by default.
 195
 196   TEST_LEVEL  will set the level ('basic', 'complete') of the tests.
 197     'complete'  - additional and mandatory script tests
 198     'basic'     - mandatory script tests only (default)
 199
 200 Example:
 201
 202   % env TEST_SKIP=test_media_,test_scan_  make test
 203
 204   % env TEST_VERBOSE=1 TEST_FIXME=1 TEST_GEOBLOCKED=1 TEST_LEVEL=complete \
 205       TEST_SKIP=test_media_vimeo,test_playlist_youtube  make test
 206
 207
 208 Tests: Scripts
 209 --------------
 210
 211 The tests/ directory contains:
 212
 213   'find_tests.sh'   will dump a list of available tests.
 214
 215   'run_tests.sh'  is a convenience script that wraps many of the
 216   testsuite features making them available via GUI. Note that
 217   this script requires zenity(1).
 218
 219 For more info, run these scripts with the '-h' switch.
 220
 221
 222 Tests: Proxy
 223 ------------
 224
 225 If you need to use a proxy, refer to the curl(1) manual page for a
 226 complete list of the supported environment variables (e.g. http_proxy).
 227
 228   libquvi (and libquvi-scripts) uses libcurl to connect to the internet.
 229
 230
 231 How to report bugs
 232 ==================
 233
 234 Please see: http://quvi.sourceforge.net/#bugs
 235
 236
 237 Patches
 238 =======
 239
 240 Please see: http://quvi.sourceforge.net/contrib/
 241
 242
 243 License
 244 =======
 245
 246 libquvi-scripts is Free Software licensed under the GNU Affero GPLV3+