← Back to branch summary

~ubuntu-branches/ubuntu/hardy/codeblocks/hardy-backports

« back to all changes in this revision

Viewing changes to src/plugins/contrib/lib_finder/lib_finder/readme.txt

  • Committer: Bazaar Package Importer
  • Author(s): Michael Casadevall
  • Date: 2008-07-17 04:39:23 UTC
  • Revision ID: james.westby@ubuntu.com-20080717043923-gmsy5cwkdjswghkm
Tags: upstream-8.02
Import upstream version 8.02

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/plugins/contrib/lib_finder/lib_finder/readme.txt
 
1
This folder contains configuration files for libraries.
 
2
Configurations are stored in XML format and must have .xml extension.
 
3
 
 
4
The main skeleton of library configuration is as follows:
 
5
 
 
6
 
 
7
<library name="Library Name" global_var="Global Var Name">
 
8
 
 
9
    <!--... Global configuration here ...-->
 
10
 
 
11
    <config>
 
12
        <!--... Library configurtion 1 ...-->
 
13
 
 
14
    </config>
 
15
 
 
16
    <config description="Some description">
 
17
        <!--... Library configurtion 2 ...-->
 
18
    </config>
 
19
 
 
20
    <config>
 
21
        <!--... Some shared configuration ...-->
 
22
        <config>
 
23
            <!--... Library configurtion 3 ...-->
 
24
        </config>
 
25
 
 
26
        <config>
 
27
            <!--... Library configurtion 4 ...-->
 
28
        </config>
 
29
    </config>
 
30
 
 
31
    <!--... more configurations here ...-->
 
32
 
 
33
 
 
34
</library>
 
35
 
 
36
LibFinder assumes that each library may have different number of configurations
 
37
(static library / dll / debug version etc. ), each of these configurations is
 
38
set inside <config> </config> node. If configuration is in nested block (
 
39
inside other configuration node), it will inherit settings of all parent nodes
 
40
and global configuration. Final configurations are made from <config> nodes which
 
41
don't have sub-configurations.
 
42
 
 
43
Configurable options are described below.
 
44
 
 
45
 
 
46
* Filters
 
47
 
 
48
Filters are used to show some requirements for the library before it's detected.
 
49
All filters are located inside <filters> node in <config> one. There are following
 
50
types of filters:
 
51
 
 
52
  - File filter:
 
53
 
 
54
        file option is used to to notify that library must have specified file. File names are
 
55
        relative to base library directory. There's no need to check all files included with library.
 
56
        But given list of files must not be ambiguous. Here's example of file option from wxWidgets library:
 
57
 
 
58
            <file name="include/wx/wx.h"/>
 
59
            <file name="include/wx/wxprec.h"/>
 
60
 
 
61
   - Platform filter:
 
62
 
 
63
        platform filter may be used to allow specific configuration for one platform only: for example:
 
64
 
 
65
            <platform name="win"/>
 
66
 
 
67
        will allow this cofiguration (all all sub-configurations) to be added for windows hosts only.
 
68
 
 
69
        There are following names which can be used:
 
70
 
 
71
           win, windows, lin, linux, unix, un*x, mac, macosx,
 
72
           bsd, freebsd, netbsd, openbsd, darwin, solaris
 
73
 
 
74
        More than one platform may be specified in one filter, for example:
 
75
 
 
76
            <platform name="win|lin"/>
 
77
 
 
78
        will allow this configuration on windows and linux hosts
 
79
 
 
80
    - Compiler filter
 
81
 
 
82
        compiler filter may be used to notify that given configuration is dedicated for one compiler only.
 
83
        Similarily to platform, you may specify more than one compiler. Names of compilers are declared in
 
84
        compiler plugin. In the time of wrigting this section the full list of supported compilers was:
 
85
 
 
86
           cygwin, dmc, dmd, gdc, arm-elf-gcc, avr-gcc, msp430-gcc, ppc-gcc,
 
87
           tricore-gcc, icc, msvctk, msvc8, ow, sdcc, tcc, gcc, mingw(?)
 
88
 
 
89
        Example of compiler filter:
 
90
            <compiler name="dmc|gcc"/>
 
91
 
 
92
    - Executable filter:
 
93
 
 
94
        this filter may be used to check whether there's specified executable available on host system.
 
95
        It may be used to check whether there's some configuration-script available. For example:
 
96
 
 
97
            <exec name="wx-config"/>
 
98
 
 
99
        checks whether we can incoke wx-config which is required on unix host to fetch configuration of
 
100
        wxWidgets.
 
101
 
 
102
* Compiler Settings
 
103
 
 
104
In compiler settings section you may set configuration which will be added into current compilation options
 
105
for the compile time. All settings should be placed inside <settings> node.
 
106
 
 
107
There are following settings which can be added:
 
108
 
 
109
    - Path option
 
110
 
 
111
        path option is used to add one of paths for library configuration. Like in global vars, there are
 
112
        three types of paths: include, lib, obj. These paths should be global, what can be done easily by using variables (it will be describedd later). Global Variable allow only one path to be defined
 
113
        but LibFinder tries to set additional directories through CFLAGS and LFLAGS. Paths can be defined
 
114
        with following tags:
 
115
 
 
116
            <path include="include path"/>
 
117
            <path lib="lib path"/>
 
118
            <path obj="obj path"/>
 
119
 
 
120
    - Libraries
 
121
 
 
122
        this option is used to add library to linker settings, for example:
 
123
 
 
124
            <add lib="wxmsw26"/>
 
125
 
 
126
        will add wxmsw26 library to build options
 
127
 
 
128
    - Defines
 
129
 
 
130
        this option can be used to add extra defines like:
 
131
            <add define="HAVE_W32API_H"/>
 
132
 
 
133
    - Extra compiler / linker flags
 
134
 
 
135
        this option can be used to set additional compiler / linker flags. Tag describing
 
136
        flags can be defined like in following forms (example from wxWidgets configuration):
 
137
 
 
138
            <add cflags="-DHAVE_W32API_H"/>
 
139
            <add lflags="-lwxmsw26"/>
 
140
 
 
141
        The example above show how to add define and library to gcc-like compilers. Note that
 
142
        preffered way should be through <add lib="..."/> and <add define="..."/>
 
143
 
 
144
* Pkg-config support
 
145
 
 
146
    There may be special switch dedicated to pkg-config available in <config> section.
 
147
    This switch is both filter and setting so it should be placed directly inside <config>
 
148
    node. It's main purpose is to check whether pkg-config does have configuration of
 
149
    some library and add pkg-config queries while compiling sources, for example:
 
150
 
 
151
    <config description="OpenGL Framework (pkg-config)">
 
152
        <pkgconfig name="libglfw"/>
 
153
    </config>
 
154
 
 
155
    checks whether there's libglfw available in pkg-config and will let use it when such
 
156
    configuration will be choosen.
 
157
 
 
158
    Such extra configuration dedicated to pkg-config entry is also generated automatically
 
159
    when name of global variable is same as pkg-config entry.
 
160
 
 
161
* Variables
 
162
 
 
163
LibFinder allow to use variables what gives more flexibility.
 
164
In order to use variable, You can use $(VARIABLE_NAME) anywhere in path, flags options and
 
165
in library name. If variable named VARIABLE_NAME is declared, it will be replace by
 
166
corresponding value.
 
167
 
 
168
There's one variable always defined: $(BASE_DIR) and it contains global path to library root folder
 
169
(paths of required files are relative to this base path). And it should be always used when declaring
 
170
paths for this library, like:
 
171
 
 
172
    <path include="$(BASE_DIR)/include"/>
 
173
 
 
174
Additional variables may be produced from names of directories in required files. If there is
 
175
*$(VARIABLE_NAME) instead of directory, it does mean that any directory will match here
 
176
and that variable named VARIABLE_NAME wil be set to this directory name. F.ex. :
 
177
 
 
178
        <file name="lib/*$(CONFIG_NAME)/msw/wx/setup.h"/>
 
179
 
 
180
will set variable CONFIG_NAME with names of all directories inside lib, containing msw/wx/setup.h.
 
181
(Of course, this path will be used when other file requirements are met).
 
182
 
 
183
If variable is declared in more than one path, is must be same in all paths, otherwise, this will
 
184
be threated like file name mismatch.
 
185