README.txt 6.71 KB
Newer Older
1
2
3
4
===========================
 Introduction to Vaucanson
===========================

Akim Demaille's avatar
Akim Demaille committed
5
:Date: 2006-05-31
6

7
Vaucanson_, a C++ generic library for weighted finite state machines.
8

9
.. _Vaucanson: http://vaucanson.lrde.epita.fr
10
11
12
13
14
15
16

.. contents::


Overview
========

Akim Demaille's avatar
Akim Demaille committed
17
18
19
Initiated  by Jacques  Sakarovitch  in 2000,  Vaucanson  is a  project
developed by the École Nationale Supérieure des Télécommunications [1]
and the EPITA Research and Development Laboratory (LRDE) [2].
20
21
22
23
24
25
26

.. [1] http://www.enst.fr

.. [2] http://www.lrde.epita.fr

The goal of this library is  to enable the development of C++ programs
in  an abstract  and  general way  with,  at the  same  time, a  large
Akim Demaille's avatar
Akim Demaille committed
27
28
29
30
31
specialization  power.   Indeed,  on   the  one  hand,  we  can  write
algorithms working on every  automaton with weights over any semirings
and  with words  from any  free  monoids.  And  on the  other hand,  a
particular  algorithm  can  be   specialized  for  a  particular  data
structure implementing only a pseudo behaviour.
32

33
34
35
36
Yet,   Vaucanson  is  an   ongoing  development   project.   Therefore
algorithms,  data  structures and  the  general  architecture are  not
totally stable and well tested.

Akim Demaille's avatar
Akim Demaille committed
37
38
39
Please send  any question or comments  to vaucanson@lrde.epita.fr, and
report bugs to either our issue tracker http://vaucanson.lrde.org/, or
to vaucanson-bugs@lrde.epita.fr.
40

41
42
43
Installation
============

44
45
To install Vaucanson on your system, type in the classical sequence at
the command prompt::
46
47

	./configure
Akim Demaille's avatar
Akim Demaille committed
48
	make
49
	make sanity-check
50
	make check ([1])
51
52
53
54
55
56
57
	make install (as root)

Note that an installation is  specific to the compiler used to install
it. Indeed, the call  to ``./configure`` enables some workarounds and,
consequently,  users must  compile  with the  same  compiler to  avoid
compatibility problems.

58
59
60
61
62
63
64
65
[1]: Optional: check  the whole library. Note that  this process takes
about 1.5 Go of free space (memory swap included) and several hours.

Additional features
-------------------

There  is a  Python  interpreter in  the  package. It  is disabled  by
default because its compilation takes  several hours. If you have time
Akim Demaille's avatar
Akim Demaille committed
66
to spare, use::
67
68
69
70
71
72
73
74
75
76

	./configure --enable-vaucanswig

There  is an  XML  I/O subsystem  in  the library.  It  is enabled  by
default,  but  requires a  working  installation  of another  software
package called Xerces-C++. If you do  not have this package, or if you
do not want to use XML I/O in Vaucanson, you can use::

	./configure --disable-xml

Akim Demaille's avatar
Akim Demaille committed
77
To specify a special path for the Xerces-C library::
78
79
80
81
82
83
84
85
86
87
88

	./configure --with-xerces=/absolute/path/to/xerces

For further configure options, type::

	./configure --help


Tweaking compilation options
----------------------------

Akim Demaille's avatar
Akim Demaille committed
89
90
Use  ``CXXFLAGS_DEBUG``  or  ``CXXFLAGS_OPTIMIZE``  to pass  debug  or
optimization flags, not ``CXXFLAGS``.  For example::
91
92
93
94
95
96
97
98
99

	./configure CXXFLAGS_DEBUG='-fstack-check -fbounds-check -ggdb'

This is because  Vaucanson tries to use some  particular default flags
with some specific  compilers such as GCC or  ICC.  Using ``CXXFLAGS``
conflicts   with   those   specific  flags;   ``CXXFLAGS_DEBUG``   and
``CXXFLAGS_OPTIMIZE`` override these default flags.


100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
Layout of the tarball
---------------------

The Vaucanson project directory layout is as follows:

argp
   A freestanding version of the GNU C Library's argp, a powerful
   command line argument parser.  Used by TAF-Kit.

build-aux
   Auxialiary tools used by the GNU Build System during "make"
   stages.

data
   Files to be installed on your system.

debian
   Data to generated Debian packages.

doc
   The documentations.

   manual
      The Vaucanson User Guide.
   share
      LaTeX components used to generate the documentation.
   xml
      The XML Proposal for Automata I/O.

include
   The code of the Vaucanson C++ Library.

src
   Demonstration tools, tests.

taf-kit
   TAF-Kit sources and tests.

Akim Demaille's avatar
Akim Demaille committed
138
139
140
vaucanswig
   VaucanSWIG sources and tests.  Very experimental.

141
142
143
Requirements
============

144
Vaucanson was tested with the `GNU C++ Compiler (GCC)`_ version 3.[34]
Akim Demaille's avatar
Akim Demaille committed
145
146
147
and 4.0,  and should work  with ICC_ 9.   The code is  fully compliant
with  the  ISO  C++  standard  (ISO-IEC  14882)  to  permit  a  higher
portability in the future.
148
149
150
151

.. _GNU C++ Compiler (GCC): http://gcc.gnu.org/
.. _ICC: http://www.intel.com/software/products/compilers/

Akim Demaille's avatar
Akim Demaille committed
152
153
154
High verbose  mode of the testing  suites uses the AT&T  dot format to
save automaton in  a human readable file.  Use  Graphviz_ to visualize
these .dot files.
155
156
157
158
159
160
161
162

.. _Graphviz: http://www.research.att.com/sw/tools/graphviz/

If  you want  to use  the XML  I/O system,  you will  need  the Apache
`Xerces-C++`_ library version 2.3 or above.

.. _Xerces-C++: http://xml.apache.org/xerces-c/

163
164
165
166
167
168
169
The C++ Application Binary Interface (ABI) of the Xerces-C++ library
must be the same as the C++ ABI of the compiler used to built
Vaucanson's XML I/O system.  In particular, users of Fink or
DarwinPorts on MacOS should pay attention to the compiler that was
used to build their version of the Xerces-C++ library, as it might
differ from the one used to build Vaucanson.

170
171
172
173

Using Vaucanson
===============

Akim Demaille's avatar
Akim Demaille committed
174
175
176
Vaucanson comes with several demos.  Looking  at them is a good way to
see what Vaucanson can do and how  it works.  They can be found in the
``src/demos`` directory.
177

Akim Demaille's avatar
Akim Demaille committed
178
179
The TAF-Kit  (Typed Automata Functions) documentation can  be found as
the first chapter of the User's Manual (see ``doc/manual``).
180

181

182
183
184
185
186
187
188
189
See Also
========

There are other sources of interest in the distribution.

- Headline news about the project can be found in the file ``NEWS`` at
  the root of the source tree.

190
191
192
193
194
- Frequently asked questions are answered in the file ``FAQ``.

- Some information about input and output of automata can be found in
  the file ``README-IO``.

195
196
197
198
199
200
201
202
203
204
205
206
207
- Documentation  about the  XML  I/O  subsystem can  be  found in  the
  ``doc/xml`` subdirectory.

- The library  reference manual, generated by Doxygen_,  is located in
  ``doc/ref``. It comes distributed as an archive of HTML files called
  ``ref.tar.gz``.

- Information about  the test suite generation mechanism  can be found
  in the file ``src/tests/test-suites/README``.

.. _Doxygen: http://www.doxygen.org


208
209
210
Licence
=======

211
Vaucanson is now released under the GNU General Public Licence. See the
212
file ``COPYING`` (at the root of the source tree) for details.
213

214
Vaucanson was released under the GNU Lesser General Public Licence until
Akim Demaille's avatar
Akim Demaille committed
215
version 0.7.
216

217
218
219
220

Contacts
========

Akim Demaille's avatar
Akim Demaille committed
221
222
The team can be reached by mail at vaucanson@lrde.epita.fr. Snail mail
addresses follow.
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243

* Vaucanson - ENST

  | Jacques Sakarovitch
  | 46, rue Barrault
  | F-75013 Paris
  | France

* Vaucanson - LIAFA

  | Sylvain Lombardy
  | 175, rue du Chevaleret
  | F-75013 Paris
  | France

* Vaucanson - LRDE

  | 24,rue Pasteur
  | Paristalie, batiment X, aile Mistral
  | F-94270 Le Kremlin Bicêtre cedex
  | France
Michaël Cadilhac's avatar
Michaël Cadilhac committed
244
245
246
247

.. Local Variables:
.. mode: rst
.. End: