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