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 `autogen.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.sf.net/
  64
  65 * libcurl 7.21.0
  66   http://curl.haxx.se/
  67
  68 * GLib 2.24.2
  69   http://library.gnome.org/devel/glib/
  70
  71 * liblua 5.1
  72   http://lua.org/
  73
  74 * libproxy 0.3.1
  75   http://code.google.com/p/libproxy/
  76
  77 * pkg-config for tracking the compilation flags needed for libraries
  78   http://www.freedesktop.org/software/pkgconfig/
  79
  80 * GNU gettext is recommended
  81   http://www.gnu.org/software/gettext/
  82
  83 * GNU make is recommended
  84   http://www.gnu.org/software/make/
  85
  86 * Doxygen for producing the C API reference documentation
  87   http://www.stack.nl/~dimitri/doxygen/
  88     (to produce PDF: install LaTeX, e.g. TeX Live or teTeX, refer to
  89     the Doxygen documentation for more information)
  90
  91       See also "Documentation".
  92
  93 * asciidoc (a2x) for producing the manual pages
  94   http://www.methods.co.nz/asciidoc/
  95
  96       See also "Documentation".
  97
  98
  99 Installation directories
 100 ------------------------
 101
 102 The location of the installed files is determined by the --prefix
 103 and the --exec-prefix options given to the configure script.
 104
 105 The .pc file for libquvi is installed in $exec_prefix/lib/pkgconfig to provide
 106 information when compiling packages that depend on libquvi.
 107
 108 If you set PKG_CONFIG_PATH so that it points to this directory, then you
 109 can get the correct include and library flags for compiling a libquvi
 110 application with:
 111
 112   % pkg-config --cflags libquvi-0.9
 113   % pkg-config --libs libquvi-0.9
 114
 115
 116 Documentation
 117 =============
 118
 119 To build the documentation suite, you need to have the doxygen/asciidoc
 120 -toolchain.  Because not all users are inclined to install these tools,
 121 the default build target does not build the documentation. See
 122 "make doc" below for more information.
 123
 124 The libquvi documentation is split into:
 125
 126   - libquvi C API reference documentation
 127     (generated by doxygen from the libquvi source code comments)
 128
 129     The dist does NOT contain the libquvi C API reference documentation.
 130
 131     Installation: The build suite does not currently install the C API
 132     reference documentation. See "make doc" and "make distdoc" below.
 133
 134   - libquvi manual pages
 135     (generated by asciidoc, or a2x to be precise)
 136
 137     Installation: The libquvi dist tarball contains prebuilt manual
 138     pages, and are installed by default. See `--with(out)-manual' above.
 139     See also "make doc" below.
 140
 141 Make targets:
 142
 143   'make doc'  builds the C API reference documentation from the doxygen
 144   comments. This produces the 'html' and 'latex' versions of the
 145   documentation. They are stored under the directory:
 146     $top_builddir/doc/dox/libquvi-$VERSION
 147
 148   Additionally, this target generates the manual pages if a2x(1) was
 149   found by configure. The manual page files can be found at:
 150     $top_srcdir/doc/man3/ -- input
 151     $top_builddir/doc/man3/ -- output
 152
 153   The Doxygen configuration file can be found at:
 154     $top_srcdir/doc/dox/Doxygen.in -- input
 155     $top_builddir/doc/dox/Doxygen -- output
 156
 157       See also "Documentation".
 158
 159   'make distdoc'  like above but produces tarballs from the documentation.
 160   These tarballs are stored under the $top_builddir/ directory.
 161
 162   Alternatively, these targets may be run individually:
 163     'make distdoc-html'
 164     'make distdoc-pdf'
 165     'make distdoc-latex' (depends on distdoc-pdf)
 166
 167   Note that it is that Doxygen produces the Makefile that will be
 168   used to generate the PDF file from the LaTeX files.
 169
 170
 171 Tests
 172 =====
 173
 174 The tests use the GLib framework for testing. These tests require
 175 the libquvi-scripts. The tests reside in the tests/ directory.
 176
 177   'make check'  will run the test programs listed in the TEST_PROGS
 178   variable in the tests/Makefile.am . 'make check' will fail if any
 179   of the tests fail. This is identical to running 'make test'.
 180
 181   'make distcheck'  will fail if any of the tests fail.
 182
 183     NOTE: Define either
 184       DISTCHECK_CONFIGURE_FLAGS=--with--scriptsdir=DIR
 185     or
 186       PKG_CONFIG_PATH=DIR
 187
 188     See also the --with-scriptsdir description above
 189       (under "Simple install procedure").
 190
 191   'make test-mem'   requires the valgrind(1) program. These tests will
 192   not automatically.
 193
 194 The tests use the gtester(1) and gtester-report(1) commands to produce
 195 the logs. These programs are part of GLib. The test programs will produce:
 196   $(top_builddir)/tests/$test_program.html  # gtester-report
 197   $(top_builddir)/tests/$test_program.xml   # gtester
 198
 199 The 'test-mem' target will, additionally, produce:
 200   $(top_builddir)/tests/$test_program.vgdump  # valgrind
 201
 202
 203 Tests: Environment variables
 204 ----------------------------
 205
 206 The testsuite supports the following environment variables:
 207
 208   TEST_INTERNET  will enable the tests that require an Internet connection.
 209
 210   TEST_VERBOSE  will enable verbose libcurl(3) output.
 211
 212   TEST_SKIP  will disable the specified tests. This list is a comma-separated
 213   list of test names. The comma-separated values are treated as regular
 214   expression patterns.
 215
 216 Example:
 217   % env TEST_VERBOSE=1 TEST_SKIP=test_quvi,test_resolve_  make test
 218
 219
 220 Tests: Scripts
 221 --------------
 222
 223 The tests/ directory contains:
 224
 225   'find_tests.sh'   will dump a list of available tests.
 226
 227   'run_tests.sh'  is a convenience script that wraps many of the
 228   testsuite features making them available via GUI. Note that
 229   this script requires zenity(1).
 230
 231 For more info, run these scripts with the '-h' switch.
 232
 233
 234 Tests: Notes
 235 ------------
 236
 237   * The test 'test/supports' uses the HTTP proxy address
 238     "http://localhost:12345" to simulate a network access error.
 239
 240     If you have something listening to that port, you may want to edit
 241     test/supports.c to use some other port.
 242
 243   * Apart from the above, the testsuite does not force any specific
 244     proxy address with the Internet requiring tests.
 245
 246     If you need to use a proxy, refer to the curl(1) manual page for
 247     a complete list of the supported environment variables (e.g. http_proxy).
 248
 249       libquvi uses libcurl to connect to the internet.
 250
 251
 252 How to report bugs
 253 ==================
 254
 255 Please see: http://quvi.sourceforge.net/#bugs
 256
 257
 258 Patches
 259 =======
 260
 261 Please see: http://quvi.sourceforge.net/contrib/
 262
 263
 264 License
 265 =======
 266
 267 libquvi is Free Software licensed under the GNU Affero GPLv3+