source: trunk/FACT++/MAINPAGE@ 13281

Last change on this file since 13281 was 12821, checked in by tbretz, 13 years ago
Added groff and ps2pdf
File size: 11.7 KB
Line 
1// **************************************************************************
2/** @mainpage
3
4@brief FACT++ - The FACT slow control software
5
6@author thomas.bretz@epfl.ch et al.
7<!--@version 1.0-->
8
9<hr width="100%">
10
11@section toc Table of contents
12<table border='1' bgcolor=#FAFAFA width='100%'>
13<tr>
14<td>
15<ul>
16<li> @ref install_sec
17 <ul>
18 <li> @ref rootwarning
19 <li> @ref packages
20 <li> @ref installroot
21 </ul>
22<li> @ref demos
23<li> @ref dimremarks
24<li> @ref addtab
25<li> @ref Documentation
26<li> @ref References
27 <ul>
28 <li> @ref generalref
29 <li> @ref boostref
30 <li> @ref fitsref
31 <li> @ref qtroot
32 </ul>
33<li> @ref availableprograms
34<li> @ref Examples
35</ul>
36</tr>
37</td>
38</table>
39
40@section install_sec Installation
41
42FACT++ can be downloaded from the svn by
43
44\verbatim
45 svn checkout https://fact.isdc.unige.ch/svn/trunk/FACT++ [localdir]
46\endverbatim
47
48it includes a dim version which is automatically compiled.
49
50For compilation use
51
52\verbatim
53 ./configure
54 make
55\endverbatim
56
57Check the \b ./configure options with \b --help. It might look
58confusing, but some features like FITS or QT4 can be switched off,
59if the necessary library is not at hand and the feature is not needed.
60For example, if the GUI is not needed its compilation can be switched
61off by disabling QT4 support with \b --without-qt4.
62
63If you use a custom built root version on your system without QT
64support, but have a distribution packe (e.g. debian package) with
65QT support available, you can give the path to root executables,
66for example, with <B>--with-rootsys=/usr/bin</B>. All other paths
67are extracted from subsequent calls to \b root-config.
68
69Running \b ./configure will take some time. It tries to really check
70carefully that everything needed is available on your system, so that you
71get errors before you start compilation.
72
73If \b ./configure fails and you send a bug report please attach
74the file config.log.
75
76If \b make fails and you send a bug report please attach
77the complete output of <B>make V=1</B>.
78
79\b Reminder: These programs use shared libraries, i.e. whenever you re-compile
80part of the project some of them might be re-compiled as well. As a result
81already running programs might crash unexpectedly! This is \b not a bug.
82
83In principle configure also supports
84
85\verbatim
86 make install
87\endverbatim
88
89which would install the package and the libraries in your system,
90although at the moment this is not recommended
91
92@subsection rootwarning ROOT warnings during compilation
93
94During compilation of the GUI you get some warning from root's TQtWidget.h.
95These warnings are completely harmless and can be ignored. However, it is sometimes
96advicable to get rid of them to get a clean compiler run which makes development
97easier.
98
99Therefore replace
100\verbatim
101inline void resize(const QSize &size) { QPixmap newSize(size); *(QPixmap *)this = newSize; }
102\endverbatim
103by
104\verbatim
105inline void resize(const QSize &sz) { QPixmap newSize(sz); *(QPixmap *)this = newSize; }
106\endverbatim
107in TQtWidget.h
108
109
110@subsection packages Required packages
111
112The following section gives a list of packages which were necessary after
113a fresh Ubuntu 11.04 installation. In addition to all the development
114packages the corresponding package with the library is needed.
115
116<i>Required (configure will fail without them)</i>
117- subversion
118- gcc
119- g++
120- make
121- libreadline6-dev
122- libboost-all-dev
123- libx11-dev (needed for lesstif, qt4, root)
124
125<i>FITS file support (datalogger, event builder)</i>
126- libccfits-dev
127
128<i>MySQL support (command line options, scheduler)</i>
129- libmysqlclient-dev (optional for MySQL support)
130- libmysql++-dev (option for MySQL support)
131
132<i>If you want 'did'</i>
133- lesstif2-dev
134
135<i>To compile the GUIs</i>
136- libqt4-dev
137- root (see section about root, currently recommended versions 5.18/00b-5.26/00e)
138
139<i>To compile the raw data viewer</i>
140- libglu1-mesa-dev
141
142<i>To create your own documentation</i>
143- graphviz
144- doxygen
145- help2man
146- groff
147- ps2pdf
148
149<i>For developers</i>
150- autoconf
151- autoconf-archive
152- libtool
153- qt4-designer
154
155If you intend to change only Makefile.am but not configure.ac the \b automake
156package instead of the \b autoconf package should be enough.
157
158<i>Some nice to have (FACT++)</i>
159- colorgcc
160- colordiff
161
162<i>Some nice to have (system)</i>
163- fte
164- efte
165- htop
166
167<i>Documentation (usually accessible through http://localhost/ for the tools above:</I>
168- autoconf-doc
169- gcc-doc
170- graphviz-doc
171- libboost-doc
172- libmysql++-doc
173- libtool-doc
174- make-doc
175- qt4-dev-tools [qt4-assistant]
176- qt4-doc-html
177
178
179<!--
180VIEWER
181libqwt5-qt4-dev
182libqwt5-doc
183-->
184
185@subsection installroot How to install root 5.26/00 on Ubuntu 11.04 (natty)
186
187- install gpp4.4, gcc4.4, g++4.4 (root does not compile with gcc4.5)
188- make links to hidden X11 libraries:
189<B><pre>
190cd /usr/local
191sudo ln -s x86_64-linux-gnu/libX* .
192</pre></B>
193- in the root source directory
194<B><pre>
195./configure --enable-qt --with-cc=gcc-4.4 --with-cxx=g++-4.4 --with-xrootd-opts=--syslibs=/usr/lib/x86_64-linux-gnu --prefix=/usr/local
196</pre></B>
197- \b make
198- <b>sudo make install</b>
199- pray
200- don't forget to set LD_LIBRARY_PATH correctly before you try to start the fact gui
201
202
203@section demos Current demonstration programs
204
205- \b dserver2: A virtual board (A TCP/IP server). It is sending a
206 "hello" message after accepting a communication and then in 3s
207 intervals the current UTC time. The board can be set to state 1 or back
208 to state 0 (just as a demonstration)
209- \b dclient5: A control program. It accesses two viratual boards (start them
210 with 'dserver2 5000' and 'dserver2 4001') If both boards are connected the START
211 command can be issued to get them to state 'Running'. In this state
212 an asynchronous time stamp can be requested sending the TIME command.
213 to get back from Running to Connected use STOP.
214- \b test3: a dim console which allows to control all dim servers
215 by sending commands via the dim network.
216- Both, \b dclient5 and \b test3 accept the command line options -c0, -c1, -c2
217 to switch between different console types (or no console in the case of
218 \b dclient5). In the console you get help with 'h' and the available
219 command with 'c' You get the avilable command-line options with --help
220
221First start the two dserver2s. Then start a dclient5 (if you want it
222with console use one of the -c options) and a test3 console (with one
223of the console options if you like) you can now control the hardware
224boards with the START, STOP and TIME commands or stop (Ctrl-C) and
225start one of the programs to see what's happening. In the test3 case
226you first have to \e cd to the server to which you want to talk by \b
227DATA_LOGGER. Don't forget to start \b dns if you want to control dclient5
228from test3 via Dim.
229
230@section dimremarks Remarks about Dim usage
231
232To be able to write all received data directly to the FITS files,
233padding has been disabled calling dic_diable_padding() and
234dis_disable_padding(). This is done in our own error handler
235DimErrorRedirecter. Since this should be one of the first
236objects created in any environment it is quite save. However, every
237Dim client or server in our network which does not use the
238DimErrorRedirecter \b must call these two functions as early as
239possible.
240
241<!--
242@section exitcodes Exit Code
243@section newcommand How to add a new command?
244@section description How to add help textes to services and commands?
245-->
246
247@section blocking Blocking programs at startup
248
249At startup most programs try to resolve the name of the dim-dns
250as well as their local IP address. After this Dim is initialized
251and tries to contact the dns. These are so far the only blocking operations.
252Be patient at program startup. They will usually timeout after a while and
253give you proper informations.
254
255
256@section addtab How to add a new tab in the gui?
257
258Do the following steps in exactly this order:
259- Insert the new page from the context menu of the QTabWidget
260- Copy the QDockWidget from one of the other tabs to the clipboard
261- Paste the copied QDockWidget and add it to the new tab (only the tab should be highlited)
262- Now click on the context menu of the region in the tab (QWidget) and change the layout to grid layout
263
264
265@section Documentation
266
267Each program has an extensive help text (except the examples). This
268help text can be displayed with the \b --help option. For each program
269a man-page is automatically created (from the help-output), which (at
270the moment) can be accessed with <B>man ./program.man</B> (Don't forget
271the ./ before the filename). With <B>make program.html</B> and
272<B>make program.pdf</B> a HTML page and a pdf document can be created
273from the man-page.
274
275With <B>make doxygen-doc</B> the HTML documentation as well as a pdf
276with the whole code documentation can be created.
277
278@section References
279
280@subsection generalref General references
281- <A HREF="http://www.cplusplus.com/reference">The C++ reference</A>
282- <A HREF="http://www.boost.org">boost.org: The boost C++ libraries</A>
283- <A HREF="http://www.highscore.de/cpp/boost/titelseite.html">Boris Sch&auml;ling: Die Boost C++ Bibliotheken</A>
284- <A HREF="http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html">GNU Readline</A>
285- <A HREF="http://www.gnu.org/software/ncurses">GNU Ncurses</A>
286- <A HREF="http://dim.web.cern.ch/">Distributed Information Management (DIM)</A>
287- <A HREF="http://dim.web.cern.ch/dim/cpp_doc/DimCpp.html">Distributed Information Management (DIM) - C++ reference</A>
288- <A HREF="http://qt.nokia.com/">Qt homepage</A>
289- <A HREF="http://qt.nokia.com/downloads/">Qt downloads</A>
290
291@subsection boostref Boost references
292- <A HREF="http://www.boost.org/doc/libs/1_45_0/libs/bind/bind.html">boost::bind (V1.45.0)</A>
293- <A HREF="http://www.boost.org/doc/libs/1_45_0/doc/html/boost_asio.html">boost asio (V1.45.0)</A>
294- <A HREF="http://www.boost.org/doc/libs/1_45_0/doc/html/date_time.html">boost date_time (V1.45.0)</A>
295- <A HREF="http://www.boost.org/doc/libs/1_45_0/doc/html/program_options.html">boost program_options (V1.45.0)</A>
296- <A HREF="http://www.boost.org/doc/libs/1_45_0/libs/filesystem/v3/doc/index.htm">boost filesystem (V1.45.0)</A>
297- <A HREF="http://www.boost.org/doc/libs/1_45_0/libs/regex/doc/html/index.html">boost regex (V1.45.0)</A>
298- <A HREF="http://www.boost.org/doc/libs/1_45_0/libs/system/doc/index.html">boost system (error codes) (V1.45.0)</A>
299- <A HREF="http://www.boost.org/doc/libs/1_45_0/doc/html/thread.html">boost thread (V1.45.0)</A>
300- <A HREF="http://www.boost.org/doc/libs/1_45_0/libs/conversion/lexical_cast.htm">boost lexical_cast (V1.45.0)</A>
301
302@subsection fitsref FITS references
303- <A HREF="http://heasarc.gsfc.nasa.gov/docs/heasarc/fits.html">The FITS data format</A>
304- <A HREF="http://heasarc.gsfc.nasa.gov/fitsio/">FITS homepage</A>
305- <A HREF="http://heasarc.gsfc.nasa.gov/fitsio/CCfits/">CCfits - A C++ wrapper to cfitsio</A>
306- <A HREF="http://heasarc.gsfc.nasa.gov/docs/software/ftools/fv/">fv - A very simple viewer to FITS file contents</A>
307- <A HREF="http://www.star.bris.ac.uk/~mbt/topcat/">topcat - <B>T</B>ool for <B>OP</B>erations on <B>C</B>atalogues <B>A</B>nd <B>T</B>ables
308
309@subsection qtroot How to integrate root in QT?
310
311- <A HREF="http://doc.trolltech.com/4.3/designer-creating-custom-widgets.html">QT4: Creating custom widgets</A>
312- <A HREF="http://root.cern.ch/download/doc/26ROOTandQt.pdf">root: QT integration (pdf)</A>
313
314
315@section availableprograms Available programs
316
317- dns: Dim's domain-name-server (needed for any communication between Dim servers and clients)
318- did: A simple graphical interface to analyse everything in a Dim network
319
320@section Examples
321
322There are a few example programs
323- \b ./argv: Example for usage of the class Configure (command line options, configuration file)
324- \b ./time: Example for the usage of the class Time (time input/output, conversion)
325- \b ./log, \b ./logtime: A simple Dim-Service/-Client combination using MessageDimRX/MessageDimTX
326
327**/
328// **************************************************************************
Note: See TracBrowser for help on using the repository browser.