added J Cut demos
[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 documentation
15         + src                                   - All project source is provided here
16                 + framework                     - The mlt media framework
17                 + modules                       - All services are defined here
18                         + core                  - Independent MLT services
19                         + dv                    - libdv dependent services
20                         + ffmpeg                - ffmpeg dependent services
21                         + avformat              - libavformat dependent services
22                         + vorbis                - vorbis dependenent services
23                         + sdl                   - SDL dependent services
24                         + resample              - libresample dependent services
25                         + gtk2                  - pango and pixbuf dependent services
26                         + xine          - xine-derived services
27                         + bluefish              - Bluefish dependent services (*)
28                         + mainconcept   - mainconcept dependent services (*)
29                 + inigo                         - A media playing test application
30                 + valerie                       - Client API to access the server
31                 + miracle                       - The server implementation
32                 + humperdink            - The evil demo
33                 + albino                        - The simple but nice demo
34                 + tests                         - Reserved for regression and unit tests
35
36         Additional subdirectories may be nested below those shown and should be
37         documented in their parent.
38
39         (*) Not posted to CVS due to licensing issues.
40
41 Configuration
42 -------------
43
44         Configuration is triggered from the top level directory via a 
45         ./configure script.
46
47         Each source bearing subdirectory shown above have their own configure
48         script which are called automatically from the top level.
49
50         Typically, new modules can be introduced without modification to the 
51         configure script and arguments are accepted and passed through to all 
52         subdirectories.
53
54         Top level usage is:
55
56         ./configure --help                      - report all configure options
57         ./configure --prefix=[dir]      - target install directory (default: /usr/local)
58         ./configure --disable-[mod] - do not compile specified module(s)
59         ./configure --[other]           - pass through to children
60
61         NB: This script must be run to register new services after a CVS checkout
62         or subsequent update.
63         
64 Compilation
65 -----------
66
67         Makefiles are generated during configuration and these are based on
68         a per directory template which must be provided by the developer.
69
70 Testing
71 -------
72
73         To execute the mlt tools without installation, or to test a new version
74         on a system with an already installed mlt version, you should run:
75
76         . setenv
77
78         NB: This applies to your current shell only.
79
80 Installation
81 ------------
82
83         * NOT IMPLEMENTED YET *
84
85         The install is triggered by running make install or make install-strip
86         from the top level directory.
87         
88         The framework produces a single shared object which is installed in 
89         $prefix/lib/ and public header files which are installed in
90         $prefix/include/mlt/framework.
91
92         The client produces a single shared object which is installed in 
93         $prefix/lib/ and public header which are installed in 
94         $prefix/include/mlt/client.
95
96         The server produces a single exectuable which is installed in
97         $prefix/bin/. This is linked against the framework shared object and
98         posix libs but not against any of the modules.
99
100         The modules produce a shared object per module and update text files
101         containing a list of modules provided by this build. These are installed 
102         in $prefix/share/mlt/. It is at the discretion of the module to install
103         additional support files. 
104         
105         To allow the development of external components, mlt-client-config and
106         mlt-framework-config scripts are generated and installed in $prefix/bin.
107
108         After install, only those modules listed are usable by the server. No
109         module is loaded unless explicitly requested via server configuration
110         or usage.
111
112         External modules are also placed in this $prefix/share/mlt, and the 
113         installation of those must modify the text file accordingly before they
114         will be considered at runtime.
115
116 Development
117 -----------
118
119         All compilation in the project has {top-level-dir}/src on the include path. 
120         All headers are included as:
121
122                 #include <framework/file.h>
123         
124         All external modules have {prefix}/include/mlt on the include path. All 
125         headers should also be included as:
126
127                 #include <framework/file.h>
128
129         This allows migration of source between external and internal modules. 
130         The configuration and Makefile template requirements will require
131         attention though.
132
133 Summary
134 -------
135
136         1.      The server will interact with public interfaces from the framework only;
137         2.      The modules must expose public framework interfaces only;
138         3.      All modules are dynamically loaded at runtime.