sgpemv2/doc/sgpem2dman.texi

880 lines
26 KiB
Plaintext

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename sgpem2dman.info
@settitle SGPEMv2 Developer Manual
@include vers-dman.texi
@c %**end of header
@dircategory SGPEM v2 - A Process Scheduling Simulator
@direntry
* Developers: (sgpem2dman)Top
@end direntry
@c % --------------------------------------------------
@copying
This is SGPEMv2 Developer 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 Developer 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 SGPEM v2 Developer Manual
@c % --------------------------------------------------
@ifnottex
@node Top, History, (none), (dir)
@top How to contribute to development
@insertcopying
@end ifnottex
@menu
* History:: The history of changes to this document.
* Directory overview:: How SGPEM sources are organized
* Coding style:: Here there are the rules you should abid
to when working on SGPEM
* Committing changes:: Some notes on how we keep our
versions organized, how to use
our repository, and how we would
like you to commit patches
* License:: The full text of the license under which this
manual is given to you
* Concept index:: Complete index
@end menu
@c % --------------------------------------------------
@node History, Directory overview, Top, Top
@unnumbered History
@table @strong
@item 2006, January 24th, @r{--- Luca Vezzaro}
Updated some code snippets whose style were
inconsistent with our coding rules. Added the point on
operator overloading to the coding conventions.
@item 2005, December 26th, @r{--- Matteo Settenvini}
Changed directory layout for @samp{src}. Added
@samp{swe/prototypes} to repository layout.
Added one more convention about C++ header files and their
licensing.
@item 2005, December 11th @r{--- Matteo Settenvini}
Added sources' directory description and repository usage
guidelines. Included full FDL license text.
@item 2005, November 8th @r{--- Matteo Settenvini}
First draft of this document
@end table
@c % --------------------------------------------------
@node Directory overview, Coding style, History, Top
@chapter Directory overview
@cindex directory layout
If you need to work on SGPEM sources, you'll probably
be interested in understanding how this package directory
structure is organized.
What follows is the tree you'll find after uncompressing
the SGPEM tar archive.
@table @samp
@item config/
Files used by Autotools while configuring
and compiling SGPEM.
@item data/
Various data SGPEM will use at runtime, like icons,
images, XML DTDs, User Interface (@file{*.ui})
definition files, and so on.
@item doc/
Inside this directory you'll find the User and Developer
Manuals, like the one you're reading, ready to be compiled.
@item desktop/
The desktop menu entries for FreeDesktop compliant
Desktop Environments.
@item distro/
Files used to prepare a package for a specific platform,
maybe containing the installer data.
@item m4/
M4 macros used by Autoconf.
@item po/
Here are stored the Gettext PO catalogs. If you are a
translator, you should first look here in order to
localize SGPEM into your language.
@item src/
The source files of SGPEM.
@end table
@c % --------------------------------------------------
@node Coding style, Committing changes, Directory overview, Top
@chapter Coding style
@cindex coding style
In this chapter we explore some self-imposed coding standards
we tried to follow when coding SGPEM.
If you plan to extend it in any way, you should abid to the
guidelines explained thereafter.
@menu
* Editors :: Some things you should know about indentation
and editors
* Coding in C++::
@end menu
@c % --------------------------------------------------
@node Editors, Coding in C++, Coding style, Coding style
@section Editors
@cindex editors
@cindex emacs
@c this needs rework, of course
IDEs are a bad choice, since usually they leave your directory
dirty, and full of temporary or project files. Please avoid their
use if not strictly necessary.
A good choice for an editor is @acronym{GNU}
Emacs, but every other editor that both insert spaces instead of
tabulation characters and has a good Unicode support will do.
Your files should be in ``UNIX mode''; that is, only a char is used
for a newline. On DOS-based systems, usually two chars are employed:
the newline char and the carriage return one.
Failure to check your text files are correctly saved wastes space
and others' patience, so please take care.
This command usually fixes the problem (@emph{note}: run it as
it is only if no binary files are present in the current directory!):
@example
for i in *; do tr -d '\r' < $i > $i.d; mv $i@{.d,@}; done
@end example
``Emacs-style'' indentation is useful to ensure that your file will
be correctly indented if another developer on another machine
opens it with Emacs, Vim, Notepad, or what else he likes. A good
idea is to use an editor which substitutes the @key{TAB} character
with spaces. Most UNIX editors indent text files cleverly.
@acronym{GNU} Emacs has another nice property: it can automatically indent
code in a whole region for you, with @kbd{M-x indent-region}.
Moreover, if you can get accustomed to it, you can activate the
automatic indentation while in a programming mode, by
typing @kbd{C-c C-a}.
Experienced programmers find it saves quite a lot of time, but
we guess it's just a matter of taste.
@c % --------------------------------------------------
@node Coding in C++, (none), Editors, Coding style
@section Coding in C++
@cindex c++
@cindex coding, style
SGPEM is mostly written in C++, an Object Oriented language
ideated by Bjarne Stroustrup and standardized in 1998 by ISO.
Here are explained some guidelines you should keep well in mind
if you want to contribute to this project.
@menu
* C++ Coding Style::
* C++ Coding Conventions::
@end menu
@c % --------------------------------------------------
@node C++ Coding Style, C++ Coding Conventions, Coding in C++, Coding in C++
@subsection C++ Coding Style
@cindex coding style
These are some notes on coding style, and things
you should keep in mind whenever extending SGPEM
source code.
Patches to the source that don't uniform to these
guidelines are likely to be rejected and need rework.
Coding styles are highly subjective and are often the
cause of harsh holy wars. Here we try also to give
a rationale of these choices, supporting our statements.
@enumerate
@item
Left curly braces go on a newline, respect to
the statement that comes before them. Right curly
braces are to be put into a newline too.
It may make you feel uneasy at first, but this
behaviour is preferable because it clearly let you
identify code blocks.
Moreover, it is observed that putting left curly
braces on the same line of a statement isn't a rule
you always follow: a lot of exceptions are raised by
particular situations, like: ``should my brace go on the
same line after a class initialization list? and after
a @code{for} loop declaration? what happens after
namespaces declaration?''
So it's best to stick to a well known practice and
put it always on a newline.
A lot of complex software projects follow this rule
because it also increases manutenibility: keep in mind
that you aren't writing code for yourself, but for others
to read.
@item
The return type for every function goes on a
line, while the function name and its parameters
go on the following, without any leading space.
This makes easier to @command{grep}
the source. For example, if you're searching for a
declaration of @code{int foo::bar()} inside a large
directory, grepping for: @samp{'/^foo::bar/g'} will
immediately pop out the correct result, whereas,
if you didn't follow this rule, you would have
searched for @samp{'/foo::bar/g'}, thus finding
@strong{all} recurrences of the function in the code,
even function calls.
@item
Use the following example to understand how we want
you to space expressions:
@example
@code{ type var = exp1 OP (exp2 OP fun1(exp3)); }
@end example
And for parameters, the following spacing is preferable:
@example
@code{ function(par1, par2 = value, ...)}
@end example
@item
Please define pointers like @code{type* var}
instead of @code{type *var}.
@item
Labels go indented on the same level of the
containing code block. For example:
@example
@verbatim
switch(x)
{
case 1:
// foo
case 2:
// bar
default:
// baz
}
@end verbatim
@end example
Remember that also @code{public}, @code{protected} and
@code{private} are labels.
@item
Put incomplete class declarations before their interface,
documenting it. For example:
@example
@verbatim
//! I'm a useless class
/** This class is completely useless. */
class C;
// [...]
class C
{
public:
// [...]
};
@end verbatim
@end example
@item
All header files of the libs and the engine
follow a common model. Try to adhere to it
by looking at existing headers. Document them
fully, even if it is tedious, using a
Doxygen-like syntax. The payback will be
high, I assure you.
@item
Class names are composed of UpperCamelCase words.
Member functions are composed of
lowercase words @strong{except}, separated by
an underscore, since both the STL and Gtk-- use
this convention.
Member data are lowercase words (can be
separated by an underscore).
Enums members are lowercase and they have
a prefix that tells something about their
function, e.g., in an enum named @emph{signal},
``@code{signal_*;}''.
Macro names are written all in capital.
@item
Private member object and function names always
begin with an underscore. Public and protected
ones don't.
@item
Some (broken?) versions of autotools had problems with extensions
other than @samp{.cc} for C++ implementation files (e.g.
automake didn't produce correct implicit rules for them).
Consequently, in order to avoid problems, we require you
to use the following extensions:
@itemize
@item
@samp{.cc} : C++ implementation files
@item
@samp{.hh} : C++ header files
@item
@samp{.tcc} : Template implementation files
@end itemize
You can also add to the end of your @file{~/.emacs} the line:
@example
@code{(add-to-list 'auto-mode-alist (cons "\\.tcc\\'" 'c++-mode))}
@end example
to automatically associate the @samp{.tcc} extension to
the @samp{c++-mode}.
@end enumerate
@c % --------------------------------------------------
@node C++ Coding Conventions, (none), C++ Coding Style, Coding in C++
@subsection C++ Coding Conventions
@cindex coding conventions
Some common rules you should keep in mind when writing
new code:
@enumerate
@item
Never use @code{std::cout/cerr} if you can do
without them.
Use @code{printf()} and @code{fprintf()} from
@code{cstdio} instead,so that marking strings
for @command{gettext} translation will be easier.
@item
Don't use ``@code{using}'' directives into the
global space, even in a @samp{.cc}, and neither in other
namespaces. If you don't keep this in mind,
you're buying to everybody a (big) problem.
``@code{using}'' makes sense
at the beginning of a function to improve
code readability, and you should be specific:
@enumerate
@item
``@code{using namespace std;}'' is bad
@item
``@code{using std::string;}'' is good
@end enumerate
@item
When treating long template names, remember that
@code{typedef} (along with @code{typename} as
needed) are your best friends, expecially at
the beginning of class declarations or function
definitions.
@item
``@emph{Syscalls}'' are evil for portability.
Thread calls can sometimes escape this rule (since
they're quite different from system to system,
and @acronym{GNU}/Linux
ones are really good), but
remember that every UNIX/Win32/Solaris/etc.
native call you use means extra-work somewhere
in the near future.
If a portable toolkit we're using provides the
same functionality, it should be preferred to a
system call.
@item
You should start all your source files, both header
and implementation ones, with a license notice, like
this (no leading white lines):
@smallexample
@group
// path/from/topsrcdir/file.ext - Copyright @strong{<year>}, University
// of Padova, dept. of Pure and Applied
// Mathematics
//
// This file is part of SGPEMv2.
//
// This 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.
//
// SGPEMv2 is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with SGPEMv2; if not, write to the Free Software
// Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
@end group
@end smallexample
The style you use to comment this out obviously changes with
the language you're employing.
@item
Only exportable classes and functions inside
a library should be marked with correct
visibility attribute (usually a macro we defined
as @code{DLL_EXPORT}). All the others are marked with
@option{--visibility=hidden} from the compiler, and aren't
available outside the @acronym{DSO, Dynamic Shared Object}
they live in, so that they don't clutter
the @acronym{DSO} namespace.
@item
When you do something, remember to update the
@emph{ChangeLog}. This is essential.
More on this on @ref{Committing changes}.
@item
Remember macros for inclusion at the beginning of header
files, as well in template implementation files.
In the latter case, you may want to include the template
implementation files in the corresponding header files.
An example of a correct inclusion directive is:
@example
@verbatim
#ifndef HELLO_WORLD_HH
#define HELLO_WORLD_HH 1
// interface definitions
#endif
@end verbatim
@end example
@item
Please follow this order when declaring a class interface:
@enumerate
@item
Incomplete declarations of nested classes and
friend functions / classes declarations.
@item
Typedefs
@item
Enums
@item
Non-static member functions
@item
Static member functions
@item
Static constant data members
@item
Variable data members
@end enumerate
Static non-const data members shouldn't exist.
Nested classes go declared @strong{outside} their
containing class. For example:
@example
@verbatim
class C;
class C
{
class D;
// ...
};
class C::D
{
// ...
};
@end verbatim
@end example
The order for visibility should be: @code{public}, then
@code{protected}, then @code{private}.
@item
Use operator overloading with care, only define
overloaded operators if the use of that operator is a
natural way to perform a particular operation on the
object(s).
In case operator overloading is considered the
best choice, a lot of operators should still be avoided
due to their profound integration with the language,
and their tendency to lead to ugly bugs. Some
examples of these operators are: the casting operator,
@code{operator delete}, @code{operator new},
@code{operator ^}.
@item
The C++ standard library is your best friend. For example,
if you need to allocate some temporary variable on the heap,
use an @code{auto_ptr<>} that does the right thing even when
an exception is raised, and that respects
@acronym{RAII,Resource Acquisition Is Initialization}.
Also using extensively algorithms like @code{for_each} and
@code{copy} greatly helps.
@item
Use @code{glib::ustring} in place of @code{std::string} as
often as possible, to ensure Unicode support.
@item
If you need a smart pointer, be sure to check out
@code{glib::RefPtr<>}.
@end enumerate
@c % --------------------------------------------------
@node Committing changes, License, Coding style, Top
@chapter Committing changes
@cindex repository
@cindex subversion
SGPEM sources are held in a repository managed by
Subversion. This is not an introduction on how to
use this tool. For that, you should refer to its own
manual, located at @url{http://svnbook.red-bean.com/}.
Rather, it sets some ``best practices'' you ought
to follow committing changes to the repository.
@menu
* Introduction and goals::
* Repository layout::
* Basic svn usage::
* Gold rules on committing::
* How to write good log messages::
* Conflicts resolution::
@end menu
@c % --------------------------------------------------
@node Introduction and goals, Repository layout, Committing changes, Committing changes
@section Introduction and goals
@cindex repository
@cindex subversion
The Subversion repository, commonly referred to just as ``repository'',
is the place where all the material produced within this project will
live.
There is a strong need to maintain an history of development data,
even on plain documentation, whether it is a proprietary file format
describing an UML chart, or some lovely C source code.
Mantaining versioned files for everything makes developers more free to cut,
modify, hack, and revamp them, with the safety that older versions
can always be fetched again.
This document describes some guidelines for maintaining the
repository as clean as possible, by defining some restrictive
rules that developers must respect in order to avoid abusing
of the customizability this tool offers.
@c % --------------------------------------------------
@node Repository layout, Basic svn usage, Introduction and goals, Committing changes
@section Repository layout
@cindex repository
@cindex directory layout
The layout you'll find inside the repository will be:
@table @samp
@item swe/branches
This is the same as tags, except that commits are allowed inside the
branch. Please refer to common development models to decide what
should or should not be done inside a branch. Note that
branching isn't something everybody should do: it should be agreed
together with the project administrator.
The format of a branch is:
@example
<@emph{version_number}>-r<@emph{revision_number}>--<@emph{branch_name}>
@end example
Example:
@example
1.2-r164--guirestyle
@end example
@c -- end swe/branches
@item swe/docs
(@emph{subdirectories}: @samp{internals}, @samp{externals},
@samp{manuals}, @samp{misc})
Contains all drafts intended for the developers. This
directory doesn't support tagging and branching because drafts
has ``eternal'' life. If needs arise, they'll rather need to be
renamed appending their version to their filename (-01, -02, etc.).
@c -- end swe/docs
@item swe/prototypes
A number of explorative prototypes we've set up to assess
availability and workingness of needed technologies.
@c -- end swe/prototypes
@item swe/tags
It contains copies of the @samp{trunk/} directory. Note that
tagging the trunk directory reflects in a double space only
for your local working copy, while it is a @math{O(1)}
operation for the server. Changes and commits are NOT
allowed here. Please note that tagging must be agreeded
with project administrator.
The format of a tag is:
@example
<@emph{version_number}>
@end example
Example:
@example
1.0
@end example
@c -- end swe/tags
@item swe/trunk
(@emph{subdirectories}: @samp{doc}, @samp{src}, @dots{})
This is the main development area where source files are held.
Usually, official releases spin off the trunk.
For a list of the directories layed out therein, please
refer to @ref{Directory overview}.
@c -- end swe/trunk
@end table
@c % --------------------------------------------------
@node Basic svn usage, Gold rules on committing, Repository layout, Committing changes
@section Basic svn usage
@cindex repository
@cindex svn
@cindex locking files
In your daily use of the repository you will mostly need to know a
very small subgroup of svn commands. Other ones are usually for fine
tuning operations (like setting file binary flags, keyword expansion, managing
the repository tree, etc.), which are tasks carried out by the repository
administrator.
Here there's a quick reference about such commands:
@table @samp
@item svn checkout @emph{http://svn.thgnet.it/swe/drafts}
Downloads a copy of the current @samp{drafts/} directory contents.
Checking out the root repository dir (@samp{swe/}) may
result, in near future, to a @strong{big} download, as
branch and tags will be stored inside the root directory.
@item svn update @r{(}@emph{short form}@r{:} svn up@r{)}
Recursively updates the current directory to the
latest revision. Use option @option{-r N} to update to a
specific revision.
@item svn status
Shows the status of @strong{your} working copy against
the repository.
@item svn diff
Shows differences in unified diff format between your working
copy and the base version of the current revision selected
(usually it means the latest). If you want to compare two different
revisions you can add a @option{-r N:M} parameter.
@item svn lock @emph{filename}
Locks a file so that everybody except the lock owner can't commit
over it. This is particularly useful for binary files:
you should always try to acquire a lock before starting editing.
@end table
@c % --------------------------------------------------
@node Gold rules on committing, How to write good log messages, Basic svn usage, Committing changes
@section Gold rules on committing
@cindex committing
A versioning system, by definition, records everything that goes through it.
So it may be a good idea not to commit garbage or make changes that will
probably be rejected by the team. The repository mustn't be used as a
temporary file storage system (so just don't use it to transfer files from
work to home or vice-versa!).
When you commit something, it should be an acceptable piece of work.
Of course, it can happen that later inspection demonstrates
it's better to revert some changesets, but that's the purpose of
having a centralized versioning system.
Avoid big commits altogether. A detailed description of your intentions
should hit the mailing list @emph{before} even starting to write such a
patch. Then, committing your work must happen via
@strong{small incremental patches}.
Also please avoid making structural tree changes (creating,
moving, removing, renaming directories) without asking first
the repository administrator.
Everything can be reverted by @command{svn}, but that's not an
excuse for sloppiness.
@c % --------------------------------------------------
@node How to write good log messages, Conflicts resolution, Gold rules on committing, Committing changes
@section How to write good log messages
@cindex log messages
Be as descriptive as possible, concisely. If your changeset was discussed on
the mailing list or at a meeting, make a clear reference to it.
Please be consistent with the message format. Use a clean english language,
employing only abbreviations contained in the glossary document.
Always prepend a dash (@minus{}) for each changeset description,
followed by a space. This will make clear, in case of line wrapping,
what is part of the list and what is simply a new line.
Every sentence must end with a full stop. If a particular description
is composed by several sub-descriptions, use a colon (@samp{:}), and
use a tab space to indent the inner list.
You can use only one level of nesting for lists. If you need more,
you are probably making an oversized commit.
An example of the log format is the following:
@example
- Change description 1.
- Change description 2:
<tab> - Part 1 of change description 2.
<tab> - Part 2 of change description 2.
- Change description 3. This particular change has a very long message
describing this atomic commit.
@end example
@c % --------------------------------------------------
@node Conflicts resolution, (none), How to write good log messages, Committing changes
@section Conflicts resolution
@cindex conflicts
@cindex merging
As in any other concurrent development system, conflicts may happen.
this will be demanded to the official @cite{Subversion Book (ch. 3 sect. 5.4)}
for an explanation on how to handle them.
We will just quote something to keep well in mind, however:
@quotation
In the end, it all comes down to one critical factor: user communication.
When users communicate poorly, both syntactic and semantic conflicts
increase. No system can force users to communicate perfectly, and no system
can detect semantic conflicts. So there's no point in being lulled into a
false promise that a locking system will somehow prevent conflicts; in
practice, locking seems to inhibit productivity more than anything else.
@end quotation
@cite{Version Control with Subversion, a.k.a. ``The Subversion Book''}
@c % --------------------------------------------------
@c include license text
@node License, Concept index, Committing changes, Top
@include fdl.texi
@c % --------------------------------------------------
@node Concept index, (none), License, Top
@unnumbered Concept Index
@printindex cp
@bye