README.txt 7.77 KB
Newer Older
Guillaume Lazzara's avatar
Guillaume Lazzara committed
1
Vaucanson, a generic library for finite state machines.
2
3
Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 The
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
===========================

Akim Demaille's avatar
Akim Demaille committed
19
:Date: 2006-05-31
20

21
Vaucanson_, a C++ generic library for weighted finite state machines.
22

23
.. _Vaucanson: http://vaucanson.lrde.epita.fr
24
25
26
27
28
29
30

.. contents::


Overview
========

Akim Demaille's avatar
Akim Demaille committed
31
32
33
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].
34
35
36
37
38
39
40

.. [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
41
42
43
44
45
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.
46

47
48
49
50
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
51
52
53
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.
54

55
56
57
Installation
============

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

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

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.

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

	make demos
	make sanity-check
	make check

76
77
78
79
80
``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
1.5GB of free space and several hours.
81

82
83
84
85
86
87

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
88
to spare, use::
89
90
91

	./configure --enable-vaucanswig

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

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

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

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

100
101
102
103
104
105
106
107
For further configure options, type::

	./configure --help


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

Akim Demaille's avatar
Akim Demaille committed
108
109
Use  ``CXXFLAGS_DEBUG``  or  ``CXXFLAGS_OPTIMIZE``  to pass  debug  or
optimization flags, not ``CXXFLAGS``.  For example::
110
111
112
113
114
115
116
117
118

	./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.


119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
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
157
158
159
vaucanswig
   VaucanSWIG sources and tests.  Very experimental.

160
161
162
Requirements
============

Jerome Galtier's avatar
Jerome Galtier committed
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
Akim Demaille's avatar
Akim Demaille committed
165
166
with  the  ISO  C++  standard  (ISO-IEC  14882)  to  permit  a  higher
portability in the future.
167

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

Akim Demaille's avatar
Akim Demaille committed
171
172
173
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.
174
175
176
177
178
179
180
181

.. _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/

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

Guillaume Lazzara's avatar
Guillaume Lazzara committed
189
190
.. _Boost-C++: http://www.boost.org/

Guillaume Lazzara's avatar
Guillaume Lazzara committed
191
192
193
194
195
`Boost-C++`_ has been introduced since Vaucanson 1.1. It is a C++ library
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
196
197
198

.. _python-docutils: http://www.python.org

Guillaume Lazzara's avatar
Guillaume Lazzara committed
199
200
You may need python-docutils_ if you want to build the documentation.

201
202
203
204

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

Akim Demaille's avatar
Akim Demaille committed
205
206
207
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.
208

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

212

213
214
215
216
217
218
219
220
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.

221
222
223
224
225
- 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``.

226
227
228
229
230
231
232
233
234
235
236
237
238
- 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


239
240
241
Licence
=======

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

245
Vaucanson was released under the GNU Lesser General Public Licence until
Akim Demaille's avatar
Akim Demaille committed
246
version 0.7.
247

248
249
250
251

Contacts
========

Akim Demaille's avatar
Akim Demaille committed
252
253
The team can be reached by mail at vaucanson@lrde.epita.fr. Snail mail
addresses follow.
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274

* 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
275
276
277
278

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