sgpemv2/doc/sgpem2uman.texi

\input texinfo   @c -*-texinfo-*-

@c %**start of header
@setfilename sgpem2uman.info
@settitle SGPEMv2 User Manual
@include vers-uman.texi
@c %**end of header

@dircategory SGPEM v2 - A Process Scheduling Simulator
@direntry
* Users: (sgpem2uman)Top
@end direntry

@c % --------------------------------------------------

@copying 
This is SGPEMv2 User Manual (version @value{VERSION}, 
@value{UPDATED}).

Copyright @copyright{} 2005 University of Padova, dept. of Pure 
and Applied Mathematics

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts.  A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end copying

@c % --------------------------------------------------

@titlepage
@title  SGPEMv2 User Manual
@subtitle for version @value{VERSION}, @value{UPDATED}
@author Giovanni Giacobbi (@email{ggiacobb@@studenti.math.unipd.it})
@author Filippo Paparella (@email{ironpipp@@gmail.com})
@author Paolo Santi (@email{psanti@@studenti.math.unipd.it})
@author Matteo Settenvini (@email{matteo@@member.fsf.org})
@author Marco Trevisan (@email{evenjn@@gmail.com})
@author Djina Verbanac (@email{betalgez@@yahoo.com})
@author Luca Vezzaro (@email{lvezzaro@@studenti.math.unipd.it})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
  
@c Output the table of contents at the beginning.
@contents

@c % --------------------------------------------------

@c SGPEMv2 User Manual

@c % --------------------------------------------------

@ifnottex
@node Top, History, (none), (dir)
@top Learn how to operate SGPEMv2
  
@insertcopying
@end ifnottex

@menu

* History::       The history of changes to this document.

* What is SGPEM:: Description and objectives of SGPEM v2.

* Installation::  Here we explain how to install SGPEM v2,
		  as well as providing some advice for 
                  believed-to-be useful compilation options.

* License:: A full copy of the GNU Free Documentation License 
            this manual is licensed into.

* Concept index:: Complete index.
@end menu


@c % --------------------------------------------------

@node       History, What is SGPEM, Top, Top
@unnumbered History

@table @strong

@item 2006, January 26th @r{--- Matteo Settenvini}
Add subsection about how to generate code documentation
via Doxygen.

@item 2005, December 11th @r{--- Matteo Settenvini}
Added full license text.

@item 2005, November 8th @r{--- Matteo Settenvini}
First draft of this document.

@end table


@c % --------------------------------------------------

@node    What is SGPEM, Installation, History, Top
@chapter What is SGPEM

@menu
* Description and aims::
* Features::
@end menu

@c % --------------------------------------------------

@node    Description and aims, Features, What is SGPEM, What is SGPEM
@section Description and aims
@cindex  SGPEM
@cindex  description

SGPEM is an Italian acronym, standing for ``@emph{Simulatore della Gestione dei Processi 
in un Elaboratore Multiprogrammato}'' (in English, ``@emph{Multitasking Computer Process 
Management Simulator}'').
It was initially developed for use inside the ``Operating Systems'' teaching,
part of the Computer Science course of the University of Padova, Italy.

SGPEMv2 is a didactic software aiming...

@c % --------------------------------------------------

@node    Features, (none), Description and aims, What is SGPEM
@section Features
@cindex  features

Main features are:

@itemize 
@item
Graphical display of simulated processes...

@end itemize

@c % --------------------------------------------------

@node    Installation, License, What is SGPEM, Top
@chapter Installation
@cindex  installation

@menu
* Prerequisites:: Programs and libraries needed to 
		  compile and run SGPEM

* Building::      Help for compiling SGPEM on 
		  your platform.

@end menu

@c % --------------------------------------------------

@node    Prerequisites, Building, Installation, Installation
@section Prerequisites
@cindex  requirements

Some software is needed in order to build and install SGPEM on your
personal computer. You will have the need of different pieces of
software installed, whether you are a developer, a user building it
from sources, or just a user that's running the binary a packager
has given to him.

And if you find this section misses something / it lists 
the wrong version of a program, please let us know!

@c % ---- new subsection
@subsection Developers

Other than the tools needed by users building from sources, 
you'll need:

@table @emph
@item GCC with C++ support
as well as the other standard GNU binutils and tools: make, sed, ld... 
GCC version >=3.4 is highly recommended. Please don't report 
compiling-related problems with any previous version.

@item Automake >= 1.9
We use a single @file{Makefile.am} to avoid
recursive make. Older versions of automake didn't play right 
with it. See @url{http://aegis.sourceforge.net/auug97.pdf} for
the motivations that led to this choice.

@item Autoconf, libtool, autopoint @dots{}
The standard autotool family.

@item Subversion >= 1.2
If you need to update the sources from our repository, or commit
your changes, you'll need Subversion built with SSL support.

@item Dejagnu >= 1.4
The testsuite framework we use as a platform for running tests.

@end table

@c % ---- new subsection
@subsection Building from source

Other than the runtime dependencies, you'll need:

@table @emph

@item SWIG >= 1.3.21
SWIG generates the C++ sources needed to build a module that 
Python can use, starting from a simple interface specification.

@end table

@c % ---- new subsection
@subsection Runtime dependencies

To run SGPEMv2, you require:

@table @emph

@item Gtkmm >= 2.8 with Cairo support
The popular C++ jacket for the even-more popular GIMP 
ToolKit. We use Cairo to draw our custom widgets.

@item Python >= 2.3
We use Python to let the user write her own policies
in a simple and complete language.

@end table


@c % --------------------------------------------------

@node    Building, (none), Prerequisites, Installation
@section Building
@cindex  compiling

@noindent To ensure a clean build, follow these steps:

@example 
@code{cd <this directory>}
@code{mkdir =build}
@code{cd =build}
@code{CXXFLAGS="what you want" ../configure --prefix=/usr/local}
@end example
@sp 2

@noindent This will check you have all the needed software installed.

@noindent Choosing good @env{CXXFLAGS} to optimize your build. 
For example, on my machine, I would use: 
@example 
@code{CXXFLAGS="-O3 -pipe -march=pentium4" ../configure --prefix=/usr/local}
@end example
@sp 2

@noindent Being a developer, though, if I had to debug SGPEM, I would type:
@example
@code{CXXFLAGS="-O0 -g -ggdb -pg" ../configure \}
@code{             --prefix=`pwd`/_inst}
@end example
@sp 2

@strong{Warning}: at the moment, we are aware that passing 
@option{--disable-shared} to configure doesn't work. We'll look into it
sooner or later, but in the meantime just build shared libraries.

@noindent Once succesfully configured SGPEMv2, just type:
@example
@command{make}
@end example
@sp 2

@noindent And upon a succesful build, you can install it just by:
@example
@code{su -c "make install"}
@end example
@sp 2

@noindent Root password will be required (of course, if you're 
installing it with a prefix placed inside your home directory, 
you won't need administrative rights, and just ``@samp{make install}'' 
will sufficit).

See the ``@file{INSTALL}'' file in this folder for an overview of other 
(less common) autoconf options.

@subsection Generating API documentation

We added Doxygen support to the project. If you've installed it, 
you can simply run @command{make apidox} from the package 
top source directory. The documentation will be outputted into
the @samp{$@{BUILD_DIR@}/docs/API/} directory.

If you'd like to generate nicier inheritance graphs, you've just to
install @command{dot}, part of the @emph{Graphviz} package.

@c % --------------------------------------------------

@c include license text
@node License, Concept index, Installation, Top
@include fdl.texi

@c % --------------------------------------------------

@node   Concept index, (none), License, Top
@unnumbered Index
     
@printindex cp
     
@bye