README

   1 General
   2 =======
   3
   4 libquvi is a cross-platform library with C API for parsing
   5 adobe flash media properties.
   6
   7 gitweb: <http://repo.or.cz/w/libquvi.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 using a binary
  23 package, instead. You can find libquvi packaged for many distros already.
  24
  25   * If you have previously installed libquvi from the source code to your
  26 system, the recommended practice is to uninstall the previous installation
  27 first, before you continue with the new one. You would, typically, run
  28 "make uninstall" (as root if necessary) from the same directory you ran
  29 "make install" from.
  30
  31   * If you are building libquvi from the git repository code, run the
  32 `bootstrap.sh' first. This generates the configuration files. See also
  33 the -h output for any additional info.
  34
  35
  36 Simple install procedure
  37 ------------------------
  38
  39   % ./configure && make
  40
  41   [ Become root if necessary ]
  42   % make install
  43
  44 The configure script supports also the following options which are
  45 relevant to the installation:
  46
  47   --with-scriptsdir=DIR (default:no)
  48
  49     Look in DIR for libquvi-scripts. This negates the default check for
  50     the libquvi-scripts package.  DIR is presumed to contain similar
  51     directory structure to the $prefix/share/libquvi-scripts/ directory
  52     which is normally created by a typical libquvi-scripts installation.
  53
  54   --with(out)-manual (default:yes)
  55
  56     Install the manual page for libquvi.
  57
  58
  59 Requirements
  60 ------------
  61
  62 * libquvi-scripts 0.9
  63   http://quvi.sourceforge.net/
  64
  65 * libcurl 7.21.0
  66   http://curl.haxx.se/
  67     $ sudo aptitude install libcurl4-gnutls-dev
  68        (or libcurl4-openssl-dev)
  69
  70 * GLib 2.24.2
  71   http://library.gnome.org/devel/glib/
  72     $ sudo aptitude install libglib2.0-dev
  73
  74 * liblua 5.1
  75   http://lua.org/
  76     $ sudo aptitude install liblua5.1-0-dev
  77
  78       2013-06-04: (Debian, Wheezy)
  79         At the time of writing this, the lua-socket (listed among the
  80         libquvi-scripts prerequisites) package does not contain the
  81         files for Lua 5.2, forcing the installation of liblua 5.1.
  82
  83 * libproxy 0.3.1
  84   http://code.google.com/p/libproxy/
  85     $ sudo aptitude install libproxy-dev
  86
  87 * libgcrypt 1.4.5
  88   http://directory.fsf.org/wiki/Libgcrypt
  89     $ sudo aptitude install libgcrypt11-dev
  90
  91 * pkg-config for tracking the compilation flags needed for libraries
  92   http://www.freedesktop.org/software/pkgconfig/
  93
  94 * GNU gettext is recommended
  95   http://www.gnu.org/software/gettext/
  96
  97 * GNU make is recommended
  98   http://www.gnu.org/software/make/
  99
 100 * Doxygen for producing the C API reference documentation
 101   http://www.stack.nl/~dimitri/doxygen/
 102     (to produce PDF: install LaTeX, e.g. TeX Live or teTeX, refer to
 103     the Doxygen documentation for more information)
 104
 105       See also "Documentation".
 106
 107 * asciidoc (a2x) for producing the manual pages
 108   http://www.methods.co.nz/asciidoc/
 109
 110       See also "Documentation".
 111
 112
 113 Installation directories
 114 ------------------------
 115
 116 The location of the installed files is determined by the --prefix
 117 and the --exec-prefix options given to the configure script.
 118
 119 The .pc file for libquvi is installed in $exec_prefix/lib/pkgconfig to provide
 120 information when compiling packages that depend on libquvi.
 121
 122 If you set PKG_CONFIG_PATH so that it points to this directory, then you
 123 can get the correct include and library flags for compiling a libquvi
 124 application with:
 125
 126   % pkg-config --cflags libquvi-0.9
 127   % pkg-config --libs libquvi-0.9
 128
 129
 130 Documentation
 131 =============
 132
 133 To build the documentation suite, you need to have the doxygen/asciidoc
 134 -toolchain.  Because not all users are inclined to install these tools,
 135 the default build target does not build the documentation. See
 136 "make doc" below for more information.
 137
 138 The libquvi documentation is split into:
 139
 140   - libquvi C API reference documentation
 141     (generated by doxygen from the libquvi source code comments)
 142
 143     The dist does NOT contain the libquvi C API reference documentation.
 144
 145     Installation: The build suite does not currently install the C API
 146     reference documentation. See "make doc" and "make distdoc" below.
 147
 148   - libquvi manual pages
 149     (generated by asciidoc, or a2x to be precise)
 150
 151     Installation: The libquvi dist tarball contains prebuilt manual
 152     pages, and are installed by default. See `--with(out)-manual' above.
 153     See also "make doc" below.
 154
 155 Make targets:
 156
 157   'make doc'  builds the C API reference documentation from the doxygen
 158   comments. This produces the 'html' and 'latex' versions of the
 159   documentation. They are stored under the directory:
 160     $top_builddir/doc/dox/libquvi-$VERSION
 161
 162   Additionally, this target generates the manual pages if a2x(1) was
 163   found by configure. The manual page files can be found at:
 164     $top_srcdir/doc/man3/ -- input
 165     $top_builddir/doc/man3/ -- output
 166
 167   The Doxygen configuration file can be found at:
 168     $top_srcdir/doc/dox/Doxygen.in -- input
 169     $top_builddir/doc/dox/Doxygen -- output
 170
 171       See also "Documentation".
 172
 173   'make distdoc'  like above but produces tarballs from the documentation.
 174   These tarballs are stored under the $top_builddir/ directory.
 175
 176   Alternatively, these targets may be run individually:
 177     'make distdoc-html'
 178     'make distdoc-pdf'
 179     'make distdoc-latex' (depends on distdoc-pdf)
 180
 181   Note that it is that Doxygen produces the Makefile that will be
 182   used to generate the PDF file from the LaTeX files.
 183
 184
 185 Tests
 186 =====
 187
 188 The tests use the GLib framework for testing. These tests require
 189 the libquvi-scripts. The tests reside in the tests/ directory.
 190
 191   'make check'  will run the test programs listed in the TEST_PROGS
 192   variable in the tests/Makefile.am . 'make check' will fail if any
 193   of the tests fail. This is identical to running 'make test'.
 194
 195   'make distcheck'  will fail if any of the tests fail.
 196
 197     NOTE: Define either
 198       DISTCHECK_CONFIGURE_FLAGS=--with--scriptsdir=DIR
 199     or
 200       PKG_CONFIG_PATH=DIR
 201
 202     See also the --with-scriptsdir description above
 203       (under "Simple install procedure").
 204
 205   'make test-mem'   requires the valgrind(1) program. These tests will
 206   not automatically.
 207
 208 The tests use the gtester(1) and gtester-report(1) commands to produce
 209 the logs. These programs are part of GLib. The test programs will produce:
 210   $(top_builddir)/tests/$test_program.html  # gtester-report
 211   $(top_builddir)/tests/$test_program.xml   # gtester
 212
 213 The 'test-mem' target will, additionally, produce:
 214   $(top_builddir)/tests/$test_program.vgdump  # valgrind
 215
 216
 217 Tests: Environment variables
 218 ----------------------------
 219
 220 The testsuite supports the following environment variables:
 221
 222   TEST_INTERNET  will enable the tests that require an Internet connection.
 223
 224   TEST_VERBOSE  will enable verbose libcurl(3) output.
 225
 226   TEST_SKIP  will disable the specified tests. This list is a comma-separated
 227   list of test names. The comma-separated values are treated as regular
 228   expression patterns.
 229
 230 Example:
 231   % env TEST_VERBOSE=1 TEST_SKIP=test_quvi,test_resolve_  make test
 232
 233
 234 Tests: Scripts
 235 --------------
 236
 237 The tests/ directory contains:
 238
 239   'find_tests.sh'   will dump a list of available tests.
 240
 241   'run_tests.sh'  is a convenience script that wraps many of the
 242   testsuite features making them available via GUI. Note that
 243   this script requires zenity(1).
 244
 245 For more info, run these scripts with the '-h' switch.
 246
 247
 248 Tests: Notes
 249 ------------
 250
 251   * The test 'test/supports' uses the HTTP proxy address
 252     "http://localhost:12345" to simulate a network access error.
 253
 254     If you have something listening to that port, you may want to edit
 255     test/supports.c to use some other port.
 256
 257   * Apart from the above, the testsuite does not force any specific
 258     proxy address with the Internet requiring tests.
 259
 260     If you need to use a proxy, refer to the curl(1) manual page for
 261     a complete list of the supported environment variables (e.g. http_proxy).
 262
 263       libquvi uses libcurl to connect to the internet.
 264
 265
 266 How to report bugs
 267 ==================
 268
 269 Please see: http://quvi.sourceforge.net/#bugs
 270
 271
 272 Patches
 273 =======
 274
 275 Please see: http://quvi.sourceforge.net/contrib/
 276
 277
 278 License
 279 =======
 280
 281 libquvi is Free Software licensed under the GNU Affero GPLv3+