dvda-author 09.03 (March 2009)
=================


Installation Instructions
*************************

Builds have been successful under Linux, Windows XP/Cygwin and FreeBSD 7.0
Two building options are shipped:

 - GNU installation scripts as explained below;
 - Code::Blocks workspace projects for Windows/Mingwin platforms 
   (dvda-author-09.03.workspace)

Two executable binaries will be installed: dvda-author (main application) and fixwav
(wav header repair tool), see fixwav/INSTALL for details.


Code::Blocks install
====================


  1. Open the adequate workspace file
  2. Build workspace
  3. Binaries are to be found in the CB_project sub-directories
  4. If you later install the main executable in CB_project/dvda-author
     in another directory, please copy file dvda-author.conf in the same directory,
     unless you have added a define constant in commonvars.h:
     
     SETTINGSFILE="full//path/to/directory of /dvda-author.conf" 
     
 


GNU Basic Installation
======================

Build system:

Prerequisites are : autoconf 2.63, automake 1.10, libtool 2.26
Please update you *nix autotools system as checks for version will fail if your version
of any one of the tools is older than the above.

Users who wish to regenerate the GNU build system should use the autogen script.
Directory config contains GNU build system configuration files.
Directory m4 contains m4 macros used to by the main configure.ac script.

It is advised to build with administrative rights.

_____________________________________________________________________________________

Under Windows/Cygwin/MSYS
-------------------------

The building/installation procedure unrolls as for Unix platforms as follows.
However, users are advised to build under a buiding tree entirely devoid of
whitespace in file paths. Crashes have arisen repeatedly in such contexts owing
to a libtool port issue.
_____________________________________________________________________________________

_____________________________________________________________________________________

With Apple and Darwin-based systems (e.g Mac) 
---------------------------------------------

The building/installation procedure unrolls as for Unix platforms.
However, you may have to use --with-config=.  for a successful build (see below 
"Installation directories for auxilliary files")
_____________________________________________________________________________________


Briefly, the shell commands `./configure; make; make install' should
configure, build, and install this package. 
By default, binaries (fixwav and dvda-author) will install under /usr/bin.

The simplest way to compile this package is:

  1. `cd' to the directory containing the package's source code and type
     `./configure' to configure the package for your system.

     Running `configure' might take a while.  While running, it prints
     some messages telling which features it is checking for.
	 On Windows platforms (MSYS build), you should specify the path to 
	 the configuration file as follows:
	 
	 ./configure --prefix=/mingw --with-conf='/path to directory of dvda-author.conf'

  2. Type `make' to compile the package.

  3. Optionally, type `make check' to run any self-tests that come with
     the package.

  4. Type `make install' to install the programs and any data files and
     documentation as root user (sudo make install on K/Ubuntu)

  5. You can remove the program binaries and object files from the
     source code directory by typing `make clean'.  To also remove the
     files that `configure' created (so you can compile the package for
     a different kind of computer), type `make distclean'.  There is
     also a `make maintainer-clean' target, but that is intended mainly
     for the package's developers. If you use it, you should regenerate the
     build system by running ./autogen in the package root directory 
     (See Build system regeneration).

  6. You can also type `make uninstall' to remove the installed
     files again.


KDE/GNOME Platforms
===================

A desktop file will be installed under:

  /usr/share/applications/dvda-author.desktop 

thereby providing a menu link to the application in the audio media section.

An icon will be available under /usr/share/pixmaps/dvda-author.png
which should be in the OS VPATH to be visible in the menu. 
The link will open an x-terinal with the application help. It will later be used
to launch a graphical interface.

A man page is installed under /usr/local/share/man/man1/dvda-author.1

Check that /usr/local/share/man/man1 is in your PATH for man for otherwise copy 
to /usr/share/man/man1

An html version is shipped with this package.

Dependencies
============

Dependencies for the building process are the following libraries:

  - libc_utils, a general-purpose library used for security enhancement
  - libfixwav, a special library designed for repairing WAV headers.
  - libats2wav a DVD-Audio titleset extracter.
  - libFLAC version 1.2.1, which itself depends on:
  - libogg version 1.1.3
  - libsox and libsoxconvert, based on SoX 14.1, a general-purpose audio format converter 
    (see readmes in libsoxconvert directory).
  - on some platforms, libiberty.a or source code for a few C replacement functions

libc_utils.a, libfixwav.a and libats2wav.a will automatically build and link.

Building dependencies without the GNU build system
--------------------------------------------------

If you do not use the GNU build system (e.g. building with Code::Blocks project),
all dependencies will be rebuilt from source code. Further, check that the configuration
file dvda-author.conf is in the same directory as the main executable (see INSTALL for
other options).


Building with GNU autoconf
--------------------------

On *nix platforms, the GNU build system will automatically link to existing libFLAC
and libogg libraries, checking for the appropriate version (1.2.1 and later).
If your installed library is not compatible, or on Windows platforms, libFLAC/libogg
will be rebuilt automatically from source code in directory libFLAC/

In this case, with the GNU build system, configure with option
--disable-ogg-flac  if you wish to deactivate Ogg FLAC support.

If your libFLAC library is installed in a non-standard directory (i.e. not /usr/lib
or /usr/local/lib) you may have to use configure options --with-flac=/path/to/libFLAC.so
and --with-ogg=/path/to/libogg.so to help out the linking process. You may equally 
indicate the path to libsox using --with-sox=/path/to/libsox

This version will use either libiberty.a if already installed on your platform
or source code for a few GNU libc functions located in glibc/ The list of functions
used depends on platforms. The GNU build system will give a priority to -liberty linking,
building GNU libc source code as a fallback option.

libFLAC and libogg can be independently rebuilt from source by running `./configure` and
`make` in their respective root directories (libfixwav, libFLAC and 
libFLAC/include/libogg). 

Binaries will be located respectively in libfixwav/src, libFLAC, and 
libFLAC/include/libogg/src/.libs.

You can force new builds of dependencies from the top source directory:

- to build the FLAC 1.2.1 library, run:

	./configure --enable-flac-build  

- to build the libogg 1.1.3 library, run

	./configure --enable-ogg-build 
	
-to build the libsox and libsoxconvert libraries:

	./configure --enable-sox-build 

- You can force rebuilding of glibc source code using configure option --enable-glibc
  In this case, libiberty.a will not be used.

- to build all libraries (including glibc replacement objects), run:

   ./configure --enable-all-builds

The autotools stripts are configured to only build from source the libraries that 
cannot be found in /usr/lib, /usr/local/lib or in the path indicated by the --with-...
configuratin option.



Compilers and Options
=====================

You can give `configure' initial values for configuration parameters
by setting variables in the command line or in the environment.  Here
is an example:

     ./configure CC=c99 CFLAGS="-g SHORT_OPTIONS_ONLY"


   You can also use the "--with-debug" options as follows:

- to configure with GCC debugging options, run:

    ./configure --with-debug=full

- to configure with no GCC debugging options and full O3 optimization, run:

    ./configure --with-debug=no

- to configure with user-specific options, run:

    ./configure --with-debug-flags='your specific options'

You may conditionally compile dvda-author to exclude code associated with some modules,
depending on you requirements. The resulting executable will be smaller, which may or may not
have a positive effect on running times, depending on modules and hardware:

- to compile without the SoX module configure with:
    
    --without-sox
 
- to compile without the fixwav module configure with:
    
    --without-fixwav

- to compile without FLAC/Ogg FLAC:
    
    --without-flac
 
 Alternatively, you may add, repectively:
 
 #define WITHOUT_SOX
 #define WITHOUT_FIXWAV
 #define WITHOUT_FLAC
 
 to src/commonvars.h code.

Users who would like to build this package with other tools should at least define
the symbolic constants _GNU_SOURCE and __CB__ at compile time.

Optional Symbolic constants can be defined at compile time to specify some features:
  
  LONG_OPTIONS for command-line long options (starting with --).
  SHORT_OPTIONS_ONLY to block all such long options.
  LOCALE=locale to recompile for another locale than the default "C".
  SETTINGSFILE=filepath to specify default filepath of the configuration file.
  FLAC__HAS_OGG to enable Ogg FLAC support.
  _LARGEFILE_SOURCE,_LARGE_FILES,_FILE_OFFSET_BITS=64 enable large file support.
  ALWAYS_INLINE forces code inlining.
  WITHOUT_SOX to compile without SoX code
  WITHOUT_FLAC to compile without FLAC/OggFLAC code
  WITHOUT_FIXWAV to compile without fixwav code
  
  
Required compile-time constants:

  _GNU_SOURCE, __CB__ if compiling with Code::Blocks or similar IDE.


Default values are configured as follows:

  a) Unless SHORT_OPTIONS_ONLY is defined, LONG_OPTIONS will be enforced by default;
  b) LOCALE="C"
  c) ogg FLAC is enabled
  d) Symbolic constants _GNU_SOURCE and __CB__ (if compiling with Code::Blocks or similar IDE)
     are defined by the scripts included in this package
    (top configure.ac file for GNU builds  and CB_projects/dvda-author/dvda-author.cbp for Code::Blocks).
  e) Large file support (constants _LARGE_FILES and  _FILE_OFFSET_BITS=64 are defined)


These constants should be set using the CPPFLAGS variable at configure-time for GNU packages:
Example:

  ./configure "CPPFLAGS=-D_GNU_SOURCE -DFLAC__HAS_OGG -DLOCALE=fr_FR -DSETTINGSFILE=home/my settings/dvda/dvda.conf"

and with the Code::Blocks, ad the selected constants and values in the Projetc/Build options/#defines tab window.


Installation Names
==================

By default, `make install' installs the package's commands under
`/usr/local/bin', include files under `/usr/local/include', etc.  You
can specify an installation prefix other than `/usr/local' by giving
`configure' the option `--prefix=PREFIX'.

You can cause programs to be installed with an extra prefix or suffix 
on their names by giving `configure' the
option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.

RPM and DEB packages will install under /usr/bin and /usr/include by default.


Specifying the System Type
==========================

There may be some features `configure' cannot figure out automatically,
but needs to determine by the type of machine the package will run on.
Usually, assuming the package is built to be run on the _same_
architectures, `configure' can figure that out, but if it prints a
message saying it cannot guess the machine type, give it the
`--build=TYPE' option.  TYPE can either be a short name for the system
type, such as `sun4', or a canonical name which has the form:

     CPU-COMPANY-SYSTEM

where SYSTEM can have one of these forms:

     OS KERNEL-OS

   See the file `config.sub' for the possible values of each field.  If
`config.sub' isn't included in this package, then this package doesn't
need to know the machine type.

If you are _building_ compiler tools for cross-compiling, you should
use the option `--target=TYPE' to select the type of system they will
produce code for.

If you want to _use_ a cross compiler, that generates code for a
platform different from the build platform, you should specify the
"host" platform (i.e., that on which the generated programs will
eventually be run) with `--host=TYPE'.

Sharing Defaults
================

If you want to set default values for `configure' scripts to share, you
can create a site shell script called `config.site' that gives default
values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists.  Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: not all `configure' scripts look for a site script.

Defining Variables
==================

Variables not defined in a site shell script can be set in the
environment passed to `configure'.  However, some packages may run
configure again during the build, and the customized values of these
variables may be lost.  In order to avoid this problem, you should set
them in the `configure' command line, using `VAR=value'.  For example:

     ./configure CC=/usr/local2/bin/gcc

causes the specified `gcc' to be used as the C compiler (unless it is
overridden in the site shell script).

Unfortunately, this technique does not work for `CONFIG_SHELL' due to
an Autoconf bug.  Until the bug is fixed you can use this workaround:

     CONFIG_SHELL=/bin/bash /bin/bash ./configure CONFIG_SHELL=/bin/bash

`configure' Invocation
======================

`configure' recognizes the following options to control how it operates.

`--help'
`-h'
     Print a summary of the options to `configure', and exit.

`--version'
`-V'
     Print the version of Autoconf used to generate the `configure'
     script, and exit.

`--cache-file=FILE'
     Enable the cache: use and save the results of the tests in FILE,
     traditionally `config.cache'.  FILE defaults to `/dev/null' to
     disable caching.

`--config-cache'
`-C'
     Alias for `--cache-file=config.cache'.

`--quiet'
`--silent'
`-q'
     Do not print messages saying which checks are being made.  To
     suppress all normal output, redirect it to `/dev/null' (any error
     messages will still be shown).

`--srcdir=DIR'
     Look for the package's source code in directory DIR.  Usually
     `configure' can determine that directory automatically.

`configure' also accepts some other, not widely useful, options.  Run
`configure --help' for more details.



Build system regeneration
=========================

Users who are conversant with Autoconf scripts should not use `autoreconf` 
to regenerate the build system after modifications of configure.ac or Makefile.am
files included within this package.

They should run ./autogen from the top package directory instead. This special
regeneration script is made necessary by an autoreconf bug, which requests including
acinclude.m4 in all nested Autoconf packages (i.e. libfixwav, libFLAC and libogg)
while this m4 script is only necessary (and shipped) in the top m4 directory. 
To circumvent this issue, autogen invokes aclocal, autoconf, autoheader and automake 
from top to bottom in the package tree.


Installation directories for auxilliary files
=============================================

For *nix compatible platforms (including Cygwin and MSYS), if --prefix=directory is not 
used as indicated above, the following installation directories are used:

 for binaries: /usr/bin
 for installed libraries: /usr/lib
 for dvda-author.conf and dvd-author.desktop: /usr/share/applications
 for README and HTML help: /usr/share/doc/dvda-author
 for images/icons: /usr/share/pixmaps

Also see fixwav man page and README in fixwav/

If --prefix is used, the above directories are replaced with $prefix/<dir> instead of /usr/<dir>
The KDE/gnome .desktop file is adjusted by configure to integrate a link to the .png image (icon) 
in $prefix/pixmaps.

Configure option --with-config='full path to directory containing dvda-author.conf'
makes it possible to change the default path to the directory containing 
dvda-author.conf (mainly uselful on non *nix platforms).



Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004, 2005,
2006, 2007 Free Software Foundation, Inc.

This file is free documentation; the Free Software Foundation gives
unlimited permission to copy, distribute and modify it.

Adapted by Fabrice Nicol for dvda-author, 2008-2009.

