Update NEWS for v0.9.4
[libquvi.git] / README
blob540378be348e2708c04284694ff0eca112b5d74c
1 General
2 =======
4 libquvi is a cross-platform library with C API for parsing
5 adobe flash media properties.
7 gitweb: <http://repo.or.cz/w/libquvi.git>
8 Home  : <http://quvi.sourceforge.net/>
11 Installation
12 ============
14 Notes
15 -----
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.
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.
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.
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.
36 Simple install procedure
37 ------------------------
39   % ./configure && make
41   [ Become root if necessary ]
42   % make install
44 The configure script supports also the following options which are
45 relevant to the installation:
47   --with-scriptsdir=DIR (default:no)
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.
54   --with(out)-manual (default:yes)
56     Install the manual page for libquvi.
59 Requirements
60 ------------
62 * libquvi-scripts 0.9
63   http://quvi.sourceforge.net/
65 * libcurl 7.21.0
66   http://curl.haxx.se/
67     $ sudo aptitude install libcurl4-gnutls-dev
68        (or libcurl4-openssl-dev)
70 * GLib 2.24.2
71   http://library.gnome.org/devel/glib/
72     $ sudo aptitude install libglib2.0-dev
74 * liblua 5.1
75   http://lua.org/
76     $ sudo aptitude install liblua5.1-0-dev
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.
83 * libproxy 0.3.1
84   http://code.google.com/p/libproxy/
85     $ sudo aptitude install libproxy-dev
87 * libgcrypt 1.4.5
88   http://directory.fsf.org/wiki/Libgcrypt
89     $ sudo aptitude install libgcrypt11-dev
91 * pkg-config for tracking the compilation flags needed for libraries
92   http://www.freedesktop.org/software/pkgconfig/
94 * GNU gettext is recommended
95   http://www.gnu.org/software/gettext/
97 * GNU make is recommended
98   http://www.gnu.org/software/make/
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)
105       See also "Documentation".
107 * asciidoc (a2x) for producing the manual pages
108   http://www.methods.co.nz/asciidoc/
110       See also "Documentation".
113 Installation directories
114 ------------------------
116 The location of the installed files is determined by the --prefix
117 and the --exec-prefix options given to the configure script.
119 The .pc file for libquvi is installed in $exec_prefix/lib/pkgconfig to provide
120 information when compiling packages that depend on libquvi.
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:
126   % pkg-config --cflags libquvi-0.9
127   % pkg-config --libs libquvi-0.9
130 Documentation
131 =============
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.
138 The libquvi documentation is split into:
140   - libquvi C API reference documentation
141     (generated by doxygen from the libquvi source code comments)
143     The dist does NOT contain the libquvi C API reference documentation.
145     Installation: The build suite does not currently install the C API
146     reference documentation. See "make doc" and "make distdoc" below.
148   - libquvi manual pages
149     (generated by asciidoc, or a2x to be precise)
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.
155 Make targets:
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
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
167   The Doxygen configuration file can be found at:
168     $top_srcdir/doc/dox/Doxygen.in -- input
169     $top_builddir/doc/dox/Doxygen -- output
171       See also "Documentation".
173   'make distdoc'  like above but produces tarballs from the documentation.
174   These tarballs are stored under the $top_builddir/ directory.
176   Alternatively, these targets may be run individually:
177     'make distdoc-html'
178     'make distdoc-pdf'
179     'make distdoc-latex' (depends on distdoc-pdf)
181   Note that it is that Doxygen produces the Makefile that will be
182   used to generate the PDF file from the LaTeX files.
185 Tests
186 =====
188 The tests use the GLib framework for testing. These tests require
189 the libquvi-scripts. The tests reside in the tests/ directory.
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'.
195   'make distcheck'  will fail if any of the tests fail.
197     NOTE: Define either
198       DISTCHECK_CONFIGURE_FLAGS=--with--scriptsdir=DIR
199     or
200       PKG_CONFIG_PATH=DIR
202     See also the --with-scriptsdir description above
203       (under "Simple install procedure").
205   'make test-mem'   requires the valgrind(1) program. These tests will
206   not automatically.
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
213 The 'test-mem' target will, additionally, produce:
214   $(top_builddir)/tests/$test_program.vgdump  # valgrind
217 Tests: Environment variables
218 ----------------------------
220 The testsuite supports the following environment variables:
222   TEST_INTERNET  will enable the tests that require an Internet connection.
224   TEST_VERBOSE  will enable verbose libcurl(3) output.
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.
230 Example:
231   % env TEST_VERBOSE=1 TEST_SKIP=test_quvi,test_resolve_  make test
234 Tests: Scripts
235 --------------
237 The tests/ directory contains:
239   'find_tests.sh'   will dump a list of available tests.
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).
245 For more info, run these scripts with the '-h' switch.
248 Tests: Notes
249 ------------
251   * The test 'test/supports' uses the HTTP proxy address
252     "http://localhost:12345" to simulate a network access error.
254     If you have something listening to that port, you may want to edit
255     test/supports.c to use some other port.
257   * Apart from the above, the testsuite does not force any specific
258     proxy address with the Internet requiring tests.
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).
263       libquvi uses libcurl to connect to the internet.
266 How to report bugs
267 ==================
269 Please see: http://quvi.sourceforge.net/#bugs
272 Patches
273 =======
275 Please see: http://quvi.sourceforge.net/contrib/
278 License
279 =======
281 libquvi is Free Software licensed under the GNU Affero GPLv3+