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