dvda-author 10.06 (June 2010)
=================


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; in short, a full build can be
   obtained with:
        ./configure --enable-all-deps --enable-all-builds && make && make install

 - Code::Blocks workspace projects for Windows/Mingwin platforms
   (dvda-author-09.09.workspace)


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/dvda-author.conf"




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

Build system:

Prerequisites are : autoconf 2.63, automake 1.10 and libtool if you are to perform a full build,
owing to a patch agains SoX configure.ac script.
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.

A summary of the configuration features is available using ./configure --help
_____________________________________________________________________________________

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.
On Cygwin/MSYS, it is advised to build the full source package with downloaded dependencies
using --enable-all-deps --enable-all-builds
_____________________________________________________________________________________

_____________________________________________________________________________________

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. WITH MULTICORE CPUs it is advised to build
     using  `make -j4' as it speeds up both nested configure execution and source code build.

  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. If Ogg is not installed
    on system, install it manually, or FLAC will be automatically configured without Ogg support.
    If libogg is installed on system, default configuration for FLAC is with Ogg support,
    unless --disable-ogg-flac is added on command line.
  - libsox 14.3.1, a general-purpose audio format converter
  - libiberty.a if --enable-iberty-build is not used and if it is installed in a system path, and if
    there is no SoX bug (see file BUGS )
  - dvdauthor version 0.6.14, patched version.

A patched version of mkisofs is needed to create an ISO image file that is DVD-Audio compliant.

To generate the documentation, you will need help2man for the man page and man2html
for the html man page. If these applications are installed, the autotools building
system automatically creates them. The Code::Blocks project also has a script for
generating these pages. Most *nix platforms propose these tools. Currently source
code for man2html is hosted by http://savannah.nongnu.org/projects/man2html and source
code for help2man is hosted by http://ftp.gnu.org/gnu/help2man. You may need to install
Perl to run man2html.

This version will use either libiberty.a if already installed on your platform
or source code for a few GNU libc functions located in libiberty/ 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.


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 and *nix-like platforms, dependencies can be rebuilt automatically from source code.
Requested packages will be downloaded, patched if necessary and installed, some of them locally
in the local/ subdirectory created at by the main configure script.

Consequently subdirectories libFLAC and libsox of prior versions have been pruned off the current package.

Rebuilding dependencies may be useful in the event of version conflicts between what is requested by dvda-author
source code and what is already installed on your platform.

In order to rebuild dependencies, you will need the following tools: curl, patch, tar, automake, autoconf-2.63 or
(later version), libtool-2.26 (or later version), GNU make.

Please check that you have a functional internet connection before configuring as follows.

In a nutshell, to download dependency X, use ./configure --enable-X-download, and --enable-X-patch when X needs patching.

Packages will be downloaded from the dvd-audio project mirror repository, and in case of failure, from Sourceforge mirrors (first trying
kent, garr, voxel and free_fr). Alternatively, you can specify the Sourceforge mirror that you would like to download your
packages from on the configure command line, e.g:

./configure SF_MIRROR=odh

Both .gz and .bz2 formats will be successively attempted.

Then add --enable-X-build to build the X sub-package.

More specifically, from the top source directory:


- You can force rebuilding of libiberty(l) source code using configure option:

	 --enable-iberty-build

- To build the FLAC 1.2.1 library, run:

	./configure --enable-flac-download --enable-flac-build

  for a windows (mingw32/MSYS) build use:

  curl -O http://dvd-audio.sourceforge.net/utils/flac-1.2.1.cvs.tar.gz

  as (patched) CVS code is necessary owing to a bug in the standard flac package build system
  for windows builds. The patched CVS flac package can only be downloaded from the dvd-audio site repository.
  Alternatively, you can dowload it manually using:

	Note: a) add --disable-ogg-flac  if you wish to deactivate Ogg FLAC support (enabled by default).
              b) dependencies to Ogg are now managed by the full (downloaded) FLAC package.

- To build and patch the libsox library:

	./configure --enable-sox-patch  --enable-sox-build

- To build and patch dvdauthor (only necessary if you need DVD-Audio menus):

	./configure --enable-dvdauthor-patch  --enable-dvdauthor-build

- To build and patch mkisofs (and original Schily version of cdrecord in addition):

	./configure --enable-cdrtools-patch  --enable-cdrtools-build

- To build and patch mjpegtools (owing to source code bug), if you need to enable menu authoring only:

        ./configure --enable-mjpegtools-patch --enable-mjpegtools-build

- To build help2man:

	./configure --enable-help2man-download  --enable-help2man-build

- To build ImageMagick:

	./configure --enable-magick-download  --enable-magick-build


- To avoid repreating -build enable options, you may just add to command line:

        --enable-all-builds

  after the -patch and -download options. In this case, after the first stage configure script run, manually rename
  your flac and sox subdirectories as follows: libFLAC, libsox.

The "full-build" package is thus obtained with:

	./configure  --enable-flac-download --enable-sox-patch --enable-dvdauthor-patch --enable-cdrtools-patch --enable-all-builds

or equivalently with:

        ./configure --enable-all-deps --enable-all-builds

The autotools scripts 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-...
configuration option.

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=/full/path/to/libFLAC.so
to help out the linking process. You may equally
indicate the path to libsox using --with-sox=/full/path/to/libsox.so (preferably use dynamic libs).


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 with SoX module and build a statically-linked binary, first installed all SoX
  libs on your system and use --disable-sox-shared. Should this fail, try the more restrictive
  option --enable-static-sox, which will look into /usr/lib to find libsox.a and apply tested
  building options on an Ubuntu (09.04) platform.
  When patching and building SoX code with --enable-sox-patch --enable-sox-build, static linking
  is forced to the locally-built library.

- 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.
  _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 -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/bin', include files under `/usr/include', etc.  You
can specify an installation prefix other than `/usr' 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.


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).

See file BUGS for additional advice.

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.

