README.txt 7.26 KB
Newer Older
Guillaume Lazzara's avatar
Guillaume Lazzara committed
1
Vaucanson, a generic library for finite state machines.
Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
2
Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 The
3
Vaucanson Group.
Guillaume Lazzara's avatar
Guillaume Lazzara committed
4
5
6
7
8
9
10
11
12
13

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

The complete GNU General Public Licence Notice can be found as the
'COPYING' file in the root directory.

The Vaucanson Group consists of people listed in the 'AUTHORS' file.
Guillaume Lazzara's avatar
Guillaume Lazzara committed
14

15
16
17
18
===========================
 Introduction to Vaucanson
===========================

19
Vaucanson_, a C++ generic library for weighted finite state machines.
20

21
.. _Vaucanson: http://vaucanson.lrde.epita.fr
22
23
24
25
26
27
28

.. contents::


Overview
========

Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
29
30
31
Initiated by Jacques Sakarovitch in 2000, Vaucanson is a project
developed by the `École Nationale Supérieure des Télécommunications`__
and the `EPITA Research and Development Laboratory (LRDE)`__.
32

Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
33
34
__ http://www.enst.fr
__ http://www.lrde.epita.fr
35

Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
36
37
38
39
40
41
42
The goal of this library is to enable the development of C++ programs
manipulating weighted finite automata in an abstract and general way
with, at the same time, a large specialization power.  On the one
hand, we can write algorithms working on every automaton with weights
in any semiring and with words from any free monoids.  And on the
other hand, a particular algorithm can be specialized for a particular
data structure.
43

Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
44
45
Yet, Vaucanson is an ongoing development project.  Therefore
algorithms, data structures and the general architecture are not
46
47
totally stable and well tested.

Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
48
Please send any question or comments to vaucanson@lrde.epita.fr, and
Akim Demaille's avatar
Akim Demaille committed
49
50
report bugs to either our issue tracker http://vaucanson.lrde.org/, or
to vaucanson-bugs@lrde.epita.fr.
51

Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
52

53
54
55
Installation
============

56
57
To install Vaucanson on your system, type in the classical sequence at
the command prompt::
58
59

	./configure
Akim Demaille's avatar
Akim Demaille committed
60
	make
Guillaume Lazzara's avatar
Guillaume Lazzara committed
61
	make install (as root)
62
63
64
65
66
67

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.

68
69
70
71
72
73
Between ``make`` and ``make install``, you may also want to run::

	make demos
	make sanity-check
	make check

74
75
76
77
``make demos`` will build example binaries in ``src/demos/``.  ``make
sanity-check`` will make sure that Vaucanson's header files can be
included and compiled.  ``make check`` will run the test suite to
check the whole library.  Running the test suite may require up to
Jerome Galtier's avatar
Jerome Galtier committed
78
10GB of free space and several hours.
79

80
81
82
83

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

Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
84
85
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
86
to spare, use::
87
88
89

	./configure --enable-vaucanswig

Akim Demaille's avatar
Akim Demaille committed
90
To specify a special path for the Xerces-C library::
91
92
93

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

Guillaume Lazzara's avatar
Guillaume Lazzara committed
94
95
To specify a special path for the Boost-C++ library::

96
	./configure --with-boost=/absolute/path/to/boost
Guillaume Lazzara's avatar
Guillaume Lazzara committed
97

Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
98
99
100
Vaucanson can use two graph implementations: ``listg`` is a
representation based on adjacency lists, while ``bmig`` is a
representation using Boost Multi-Index containers.  The default
101
implementation is ``listg`` and you can select the other with::
Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
102

103
	./configure --default-graph-impl=bmig
Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
104

105
106
107
108
109
For further configure options, type::

	./configure --help


110
111
112
113
114
115
Layout of the tarball
---------------------

The Vaucanson project directory layout is as follows:

build-aux
Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
116
117
   Auxialiary tools used by the GNU Build System during ``configure``
   and ``make`` stages.
118
119

data
Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
120
121
   Data files to be installed on your system.  They include an XML schema,
   example automata, and Emacs customizations.
122
123

debian
Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
124
   Data to generate Debian packages.
125
126

doc
Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
127
   The documentation.
128
129

   manual
130
      The Taf-Kit manual.
Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
131
   ref
Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
132
      Doxygen_ documentation (automatically generated from the source code)
Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
133
134
135
136
137
138

gnulib
   Portability functions from the ``gnulib`` library.

lib
   Instantiation of some contexts as libraries.
139
140
141
142

include
   The code of the Vaucanson C++ Library.

Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
143
144
145
m4
   Portability macros from the ``gnulib`` library.

146
src
Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
147
148
149
150
   Benchmarks, demonstration executables, and test cases.

tools
   Developer scripts.
151
152
153
154

taf-kit
   TAF-Kit sources and tests.

Akim Demaille's avatar
Akim Demaille committed
155
156
157
vaucanswig
   VaucanSWIG sources and tests.  Very experimental.

158

159
160
161
Requirements
============

Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
162
163
164
Vaucanson was tested with the `GNU Compiler Collection (GCC)`_ version
4.1.x and 4.2.x, and with ICC_ version 9 and 10.1.  The code is fully
compliant with the ISO C++ standard (ISO-IEC 14882) to permit a higher
Akim Demaille's avatar
Akim Demaille committed
165
portability in the future.
166

Jerome Galtier's avatar
Jerome Galtier committed
167
.. _GNU Compiler Collection (GCC): http://gcc.gnu.org/
168
169
.. _ICC: http://www.intel.com/software/products/compilers/

Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
170
171
172
TAF-Kit and some test cases can use the AT&T dot format to save
automaton in a human readable file.  You should install Graphviz_ to
visualize these ``.dot`` files or run the test suite.
173
174
175

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

Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
176
177
The XML I/O system is based on the Apache `Xerces-C++`_ library
version 2.3 or above.
178
179
180

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

181
182
183
184
185
186
187
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.

Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
188
.. _Boost: http://www.boost.org/
Guillaume Lazzara's avatar
Guillaume Lazzara committed
189

Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
190
`Boost`_ has been introduced since Vaucanson 1.1. It is a C++ library
Guillaume Lazzara's avatar
Guillaume Lazzara committed
191
192
193
194
which provides many useful objects, including hash tables. Currently,
Boost is used in algorithms only, but its use shall be extended to
automata structures and other portions of code. You must install this
library on your system.
Guillaume Lazzara's avatar
Guillaume Lazzara committed
195

196
197
198
199

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

Akim Demaille's avatar
Akim Demaille committed
200
201
202
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.
203

204
205
The TAF-Kit (Typed Automata Functions) documentation can be found in
``doc/manual``.
206

207

208
209
210
211
212
213
214
215
216
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.

- The library  reference manual, generated by Doxygen_,  is located in
Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
217
  ``doc/ref``.
218
219
220
221
222
223
224

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

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


225
226
227
Licence
=======

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

231
Vaucanson was released under the GNU Lesser General Public Licence until
Akim Demaille's avatar
Akim Demaille committed
232
version 0.7.
233

234
235
236
237

Contacts
========

Akim Demaille's avatar
Akim Demaille committed
238
239
The team can be reached by mail at vaucanson@lrde.epita.fr. Snail mail
addresses follow.
240
241
242
243

* Vaucanson - ENST

  | Jacques Sakarovitch
Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
244
  | Ecole nationale supérieure des télécommunications
245
  | 46, rue Barrault
Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
246
  | 75634 Paris CEDEX 13
247
248
  | France

Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
249
* Vaucanson - IGR
250
251

  | Sylvain Lombardy
Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
252
253
254
  | Laboratoire d'informatique de l'Institut Gaspard Monge
  | Université Paris-Est Marne-la-Vallée
  | 77454 Marne-la-Vallée CEDEX 2
255
256
257
258
  | France

* Vaucanson - LRDE

Alexandre Duret-Lutz's avatar
Alexandre Duret-Lutz committed
259
260
261
  | Laboratoire de Recherche et Développement de l'EPITA
  | 14-16 rue Voltaire
  | 94276 Le Kremlin-Bicêtre CEDEX
262
  | France
Michaël Cadilhac's avatar
Michaël Cadilhac committed
263
264
265
266

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