README.txt 5.9 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
100
101
102

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


Requirements
============

103
Vaucanson was tested with the `GNU C++ Compiler (GCC)`_ version 3.[34]
Akim Demaille's avatar
Akim Demaille committed
104
105
106
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.
107
108
109
110

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

Akim Demaille's avatar
Akim Demaille committed
111
112
113
114
115
A  known bug in  GCC 4.0.0  for MacOs  is supported  to make  the code
compliant  with this specific  compiler version,  but MacOs  users are
encouraged to  upgrade their compiler.   They should also  notice that
their  platform   allows  to  select  their   default  compiler  using
``gcc_select``.  GCC 4.0 is preferred.
116

Akim Demaille's avatar
Akim Demaille committed
117
118
119
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.
120
121
122
123
124
125
126
127

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

128
129
130
131

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

Akim Demaille's avatar
Akim Demaille committed
132
133
134
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.
135

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

139
140
141
142
143
144
145
146
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.

147
148
149
150
151
- 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``.

152
153
154
155
156
157
158
159
160
161
162
163
164
- 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


165
166
167
Licence
=======

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

171
Vaucanson was released under the GNU Lesser General Public Licence until
Akim Demaille's avatar
Akim Demaille committed
172
version 0.7.
173

174
175
176
177

Contacts
========

Akim Demaille's avatar
Akim Demaille committed
178
179
The team can be reached by mail at vaucanson@lrde.epita.fr. Snail mail
addresses follow.
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200

* 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
201
202
203
204

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