mlt/docs/install.txt

Installation Documentation

Copyright (C) 2004 Ushodaya Enterprises Limited
Author: Charles Yates <charles.yates@pandora.be>
Last Revision: 2004-04-13


INSTALL
-------

	This document provides a description of the MLT project installation and
	organisation.


Directories
-----------

	The directory heirarchy is defined as follows:

	+ demo                  - A selection of samples to show off capabilities.
	+ docs                  - Location of all documentation
	+ src                   - All project source is provided here
	    + framework         - The mlt media framework
	    + modules           - All services are defined here
	        + avformat      - libavformat dependent services
	        + bluefish      - Bluefish dependent services (*)
	        + core          - Independent MLT services
	        + dv            - libdv dependent services
	        + fezzik        - A giant (meta) service to load and normalise media
	        + gtk2          - pango and pixbuf dependent services
	        + mainconcept   - mainconcept dependent services (*)
	        + normalize     - audio normalisation functions (**)
	        + plus          - throwaway silliness
	        + resample      - libresample dependent services (**)
	        + sdl           - SDL dependent services
	        + vorbis        - vorbis dependenent services
	        + westley       - Nice and clever XML services
	        + xine          - Xine-derived sources (**)
	    + albino            - A simple console (protocol level) example (**)
	    + inigo             - A media playing test application (**)
	    + humperdink        - A terminal-based example client
	    + miracle           - The server implementation (**)
	    + tests             - Reserved for regression and unit tests
	    + valerie           - Client API to access the server (**)

	Additional subdirectories may be nested below those shown and should be
	documented in their parent.

	(*)  Not posted to CVS due to licensing issues.
	(**) Contains GPL dependencies or code.


Dependencies
------------

	The MLT core is dependent on:

	* a C99 compliant C compiler
	* posix threading
	* standard posix libraries

	The MLT applications and libraries provided are all dependent on the core.

	The modules have the following dependencies:

	----------- ----------------------------------------------------------
	MODULE      DESCRIPTION
	----------- ----------------------------------------------------------
	avformat    Provided from ffmpeg CVS and compiled as a shared library.
	            URL: http://ffmpeg.sf.net
	----------- ----------------------------------------------------------
	bluefish    Bluefish hardware and software development kit
	            URL: http://www.bluefish444.com
	----------- ----------------------------------------------------------
	dv          libdv 0.102 or later.
	            URL: http://libdv.sf.net
	----------- ----------------------------------------------------------
	gtk2        GTK2 and associated dependencies.
	            URL: http://www.gtk.org
	----------- ----------------------------------------------------------
	mainconcept Mainconcept MPEG and DVCPRO Release SDKs.
	            URL: http://www.mainconcept.com
	----------- ----------------------------------------------------------
	resample    libsamplerate 0.15 or later 
	            URL: http://www.mega-nerd.com/SRC/ (GPL)
	----------- ----------------------------------------------------------
	sdl         SDL 1.2 or later.
	            URL: http://www.libsdl.org
	----------- ----------------------------------------------------------
	vorbis      libvorbis 1.0.1 or later.
	            URL: http://www.vorbis.com/
	----------- ----------------------------------------------------------
	westley     libxml2 2.5 or later.
	            URL: http://www.xmlsoft.org/
	----------- ----------------------------------------------------------


Configuration
-------------

	Configuration is triggered from the top level directory via a 
	./configure script.

	Each source bearing subdirectory shown above have their own configure
	script which are called automatically from the top level.

	Typically, new modules can be introduced without modification to the 
	configure script and arguments are accepted and passed through to all 
	subdirectories.

	More information on usage is found by running:

	    ./configure --help

	NB: This script must be run to register new services after a CVS checkout
	or subsequent update.

	
Compilation
-----------

	Makefiles are generated during configuration and these are based on
	a per directory template which must be provided by the developer.


Testing
-------

	To execute the mlt tools without installation, or to test a new version
	on a system with an already installed mlt version, you should run:

	. setenv

	NB: This applies to your current shell only and it assumes sh or bash.


Installation
------------

	The install is triggered by running make install from the top level
	directory.
	
	The framework produces a single shared object which is installed in 
	$prefix/lib/ and public header files which are installed in
	$prefix/include/mlt/framework.

	Valerie produces a single shared object which is installed in 
	$prefix/lib/ and public header which are installed in 
	$prefix/include/mlt/valerie.

	Miracle produces a single exectuable which is installed in
	$prefix/bin/, a library in $prefix/lib and associated header files in
	$prefix/include.

	The modules produce a shared object per module and update text files
	containing a list of modules provided by this build. These are installed 
	in $prefix/share/mlt/modules. It is at the discretion of the module to 
	install additional support files. 
	
	To allow the development of external components, mlt-config and scripts 
	are generated and installed in $prefix/bin.

	After install, only those modules listed are usable by the server. No
	module is loaded unless explicitly requested via server configuration
	or usage.

	External modules are also placed in this $prefix/share/mlt/modules, and the
	installation of those must modify the text file accordingly before they
	will be considered at runtime.


Development
-----------

	All compilation in the project has {top-level-dir}/src on the include path. 
	All headers are included as:

	    #include <framework/file.h>
	
	All external modules have {prefix}/include/mlt on the include path. All 
	headers should also be included as:

	    #include <framework/file.h>

	This allows migration of source between external and internal modules. 
	The configuration and Makefile template requirements will require
	attention though.