minor testing update
[melted] / README
1 README
2 ------
3
4         This document provides a description of the MLT project organisation.
5
6         It provides *CRITICAL* architecture information, so please read carefully
7         if you plan to extend or use the MLT code base.
8
9 Directories
10 -----------
11
12         The directory heirarchy is defined as follows:
13
14         + docs                                  - Location of all text and source format 
15                                                           documentation
16         + src                                   - All project source is provided here
17                 + framework                     - The media framework
18                 + modules                       - All components are defined here
19                         + core                  - Non-dependent MLT service
20                         + dv                    - libdv services
21                         + ffmpeg                - ffmpeg dependent modules and test code
22                         + sdl                   - SDL dependent modules and test code
23                         + bluefish              - Bluefish dependent modules and test code (*)
24                         + mainconcept   - mainconcept dependent modules and test code (*)
25                 + inigo                         - A media playing test application
26                 + valerie                       - Client API to access the server
27                 + miracle                       - The server implementation
28                 + tests                         - Reserved for regression and unit tests
29
30         Additional subdirectories may be nested below those shown and should be
31         documented in their parent or here.
32
33         (*) Not posted to CVS due to licensing issues.
34
35 Configuration
36 -------------
37
38         Configuration is triggered from the top level directory via a 
39         ./configure script.
40
41         Each source bearing subdirectory shown above have their own configure
42         script which are called automatically from the top level.
43
44         Typically, new modules can be introduced without modification to the 
45         configure script and arguments are accepted and passed through to all 
46         subdirectories.
47
48         Top level usage is:
49
50         ./configure --help                      - report all configure options
51         ./configure --prefix=[dir]      - target install directory (default: /usr/local)
52         ./configure --disable-[mod] - do not compile specified module(s)
53         ./configure --[other]           - pass through to children
54
55         NB: This script must be run to register new services after a CVS checkout
56         or subsequent update.
57         
58 Compilation
59 -----------
60
61         Makefiles are generated during configuration and these are based on
62         a per directory template which must be provided by the developer.
63
64 Installation
65 ------------
66
67         The install is triggered by running make install or make install-strip
68         from the top level directory.
69         
70         The framework produces a single shared object which is installed in 
71         $prefix/lib/ and public header files which are installed in
72         $prefix/include/mlt/framework.
73
74         The client produces a single shared object which is installed in 
75         $prefix/lib/ and public header which are installed in 
76         $prefix/include/mlt/client.
77
78         The server produces a single exectuable which is installed in
79         $prefix/bin/. This is linked against the framework shared object and
80         posix libs but not against any of the modules.
81
82         The modules produce a shared object per module and update text files
83         containing a list of modules provided by this build. These are installed 
84         in $prefix/share/mlt/. It is at the discretion of the module to install
85         additional support files. 
86         
87         To allow the development of external components, mlt-client-config and
88         mlt-framework-config scripts are generated and installed in $prefix/bin.
89
90         After install, only those modules listed are usable by the server. No
91         module is loaded unless explicitly requested via server configuration
92         or usage.
93
94         External modules are also placed in this $prefix/share/mlt, and the 
95         installation of those must modify the text file accordingly before they
96         will be considered at runtime.
97
98 Development
99 -----------
100
101         All compilation in the project has {top-level-dir}/src on the include path. 
102         All headers are included as:
103
104                 #include <framework/file.h>
105         
106         All external modules have {prefix}/include/mlt on the include path. All 
107         headers should also be included as:
108
109                 #include <framework/file.h>
110
111         This allows migration of source between external and internal modules. 
112         The configuration and Makefile template requirements will require
113         attention though.
114
115 Summary
116 -------
117
118         1.      The server will interact with public interfaces from the framework only;
119         2.      The modules must expose public framework interfaces only;
120         3.      All modules are dynamically loaded at runtime.
121