Congegni
/
libretime
mirror of https://github.com/libretime/libretime.git
7
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

added development environment documentation

This commit is contained in:
maroy 2004-07-23 15:33:30 +00:00
parent 13ecac28d0
commit 38c61b0dd5
16 changed files with 1535 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
livesupport/doc/developmentEnvironment/autoconfConfigureConventions.html Normal file
View File

@ -0,0 +1,68 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=UTF-8"
http-equiv="content-type">
<title>autoconf configure file conventions</title>
<meta content="$Author: maroy $" name="author">
</head>
<body>
<h1>Preface</h1>
This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a>
project, Copyright &#169; 2004 <a href="http://www.mdlf.org/">Media
Development Loan Fund</a>, under the GNU <a
href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
<ul>
<li>Author: $Author: maroy $</li>
<li>Version: $Revision: 1.1 $</li>
<li>Location: $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/autoconfConfigureConventions.html,v $</li>
</ul>
<h1>Scope</h1>
This document describes the autoconf configure file conventions for the
LiveSupport
project. See also the generic description of the <a
href="file:///home/darkeye/src/livesupport/livesupport/doc/developmentEnvironment/fileConventions.html">file
conventions</a> in the LiveSupport
project.<br>
<h1>Introduction</h1>
Autoconf configure input files are processed by GNU <a
href="http://www.gnu.org/software/autoconf/">autoconf</a> and <a
href="http://www.gnu.org/software/automake/">automake</a> to generate
a configure script, which in turn generates Makefiles and other files
based on the system specifics it is run on. These are text
based files, thus they should adhere to the <a
href="fileConventions.html#textConventions">generic text-based
conventions</a>.<br>
<h1>Naming</h1>
Autoconf configure files are named either <code>configure.ac</code>
(for autoconf) or sometimes <code>configure.am</code> (for automake).<br>
<h1>Structure</h1>
Autoconf configure files are partitioned by using the following 80
column
wide partitioning comment:<br>
<pre>dnl-----------------------------------------------------------------------------<br>dnl This is the title of the partition<br>dnl-----------------------------------------------------------------------------<br></pre>
The file has the
following mandatory structure:<br>
<ul>
<li>Header</li>
<li>Additional sections+</li>
</ul>
<h2>Header</h2>
The header holds all information mandated by the <a
href="fileConventions.html#header">generic guidelines</a>, but
starting with the autoconf comment sequence <code>dnl</code>. Note the
80
column wide partitioning delimiter enclosing the header.<br>
<pre>dnl-----------------------------------------------------------------------------<br>dnl Copyright (c) 2004 Media Development Loan Fund<br>dnl<br>dnl This file is part of the LiveSupport project.<br>dnl http://livesupport.campware.org/<br>dnl To report bugs, send an e-mail to bugs@campware.org<br>dnl<br>dnl LiveSupport is free software; you can redistribute it and/or modify<br>dnl it under the terms of the GNU General Public License as published by<br>dnl the Free Software Foundation; either version 2 of the License, or<br>dnl (at your option) any later version.<br>dnl<br>dnl LiveSupport is distributed in the hope that it will be useful,<br>dnl but WITHOUT ANY WARRANTY; without even the implied warranty of<br>dnl MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the<br>dnl GNU General Public License for more details.<br>dnl<br>dnl You should have received a copy of the GNU General Public License<br>dnl along with LiveSupport; if not, write to the Free Software<br>dnl Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA<br>dnl<br>dnl<br>dnl Author : $Author: maroy $<br>dnl Version : $Revision: 1.1 $<br>dnl Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/autoconfConfigureConventions.html,v $<br>dnl-----------------------------------------------------------------------------<br></pre>
<h2>Additional sections</h2>
Additional sections contain the autoconf configuration macro calls.
Bigger
parts of the file may be partitioned by the partitioning commend seen
above.<br>
<h1>Template</h1>
See a generic <a href="templates/configure.ac">template
for autoconf configurations</a>. You may freely copy this
template when starting to create a new document.<br>
<br>
</body>
</html>

74
livesupport/doc/developmentEnvironment/buildEnvironment.html Normal file
View File

@ -0,0 +1,74 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=UTF-8"
http-equiv="content-type">
<title>Build environment</title>
<meta content="$Author: maroy $" name="author">
</head>
<body>
<h1>Preface</h1>
This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a>
project, Copyright &#169; 2004 <a href="http://www.mdlf.org/">Media
Development Loan Fund</a>, under the GNU <a
href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
<ul>
<li>Author: $Author: maroy $</li>
<li>Version: $Revision: 1.1 $</li>
<li>Location: $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/buildEnvironment.html,v $<br>
</li>
</ul>
<h1>Scope</h1>
This document describes the build environment for components of the
LiveSupport project.<br>
<h1>Introduction</h1>
As seen in the <a href="directoryStructure.html">directory structure</a>
description, each component is contained in its own directory, and has
the same general directory layout, which includes a Makefile on the top
of the directory. All components are build by <a
href="http://www.gnu.org/directory/make.html">GNU make</a> working on
that Makefile. This document describes the targets for that Makefile.<br>
<br>
Parts of this document is inspired by the <a
href="http://www.gnu.org/prep/standards.html">GNU Coding Standards</a>
<a href="http://www.gnu.org/prep/standards_50.html">Makefile
Conventions Standard targets</a>.<br>
<h2>Make targets<br>
</h2>
The following make targets are required for all components to support:<br>
<ul>
<li>all</li>
<li>clean</li>
<li>depclean</li>
<li>doc<br>
</li>
<li>dist</li>
<li>check</li>
</ul>
<h4>all</h4>
Compile all source files for this component.&nbsp; As a result, the
component is ready to be run (if an executable) or linked to (if a
library).<br>
This target traverses the dependent modules, and executes the all
target on them, if their targets do not exist.<br>
<h4>clean</h4>
Delete all files generated by the all target, but only for this module
(e..g. no files for dependent modules are deleted).<br>
<h4>depclean</h4>
Delete all the dependent target files. Executing the depclean target
with an all target afterwards results in a full recompilation of all
the dependent modules.<br>
<h4>doc</h4>
Generate the documentation for this component. This would include
processing info pages, or using tools to generate documentation based
on comments in the source code (like javadoc).<br>
<h4>dist</h4>
Create a distribution package for this component. This involves
possibly compiling, document generation and other tasks, and results in
an archive containing the distribution.<br>
<h4>check</h4>
Run all tests, especially unit tests, for the component. This usually
results in a generated test-report.<br>
<br>
</body>
</html>

200
livesupport/doc/developmentEnvironment/cxxHeaderFileConventions.html Normal file
View File

@ -0,0 +1,200 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=UTF-8"
http-equiv="content-type">
<title>C++ header file conventions</title>
<meta content="$Author: maroy $" name="author">
</head>
<body>
<h1>Preface</h1>
This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a>
project, Copyright &#169; 2004 <a href="http://www.mdlf.org/">Media
Development Loan Fund</a>, under the GNU <a
href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
<ul>
<li>Author: $Author: maroy $</li>
<li>Version: $Revision: 1.1 $</li>
<li>Location: $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/cxxHeaderFileConventions.html,v $</li>
</ul>
<h1>Scope</h1>
This document describes C++ header file conventions for the
LiveSupport
project. See also the generic description of the <a
href="file:///home/darkeye/src/livesupport/livesupport/doc/developmentEnvironment/fileConventions.html">file
conventions</a> in the LiveSupport
project.<br>
<h1>Introduction</h1>
C++ header files are files containing declarations of structures,
functions and classes, that may be shared among object files, by
including them with the pre-processor directive <code>#include</code>
in multiple source files. They are text
based files, thus they should adhere to the <a
href="fileConventions.html#textConventions">generic text-based
conventions</a>.<br>
<br>
The LiveSupport project uses a strong object oriented approach. Part of
this approach is to group declarations of classes into their own files:
one header file and one source file for each class. Therefore each C++
header file contains the declaration of exactly one C++ class, although
inner types are defined in the same file.<br>
<h1>Naming</h1>
A C++ header files name reflects the class it is defining. Class names
begin with a capital letter, followed by lower case letters. In case of
a multiple word class name, the first letter of each word is
capitalized. Example class names are <code>Foo</code> and <code>FooBar</code>.<br>
<br>
As the name of the header file reflects the name of the class defined
in it, the header file will be named exactly as the class inside, with
the <code>.h</code> extension. Thus a class named <code>Foo</code> is
defined in
the header file <code>Foo.h</code>, and the class named <code>SomeOtherLongNamedClass</code>
is defined in the header file named <code>SomeOtherLongNamedClass.h</code>.<br>
<h1>Structure</h1>
C++ files are partitioned by using the following 80 column wide
partitioning comment:<br>
<pre>/* ==================================================== name of the partition */<br></pre>
Note that the comment is always 80 columns wide, independent of the
length of the text within.<br>
<br>
The file has the
following mandatory structure:<br>
<ul>
<li>Header</li>
<li>Include files &amp; namespaces</li>
<li>Constants</li>
<li>Macros</li>
<li>Data types</li>
<li>External data signatures</li>
<li>Function Prototypes</li>
<li>Footer<br>
</li>
</ul>
<h2>Header</h2>
The header holds all information mandated by the <a
href="fileConventions.html#header">generic guidelines</a>. It begins
with the generic header information, enclosed in 80
column wide partitioning delimiters.<br>
<br>
After this a macro definition follows, prohibiting the multiple time
inclusion of the header file. The name of the header-identity macro is
derived from the full name the file is expected to be included as. The
macro name is formed by replacing all non-alphanumeric characters from
the expected include definition with the '_' (underscore) character.
For a header file that will be included with the line:<br>
<pre><code>#include "Foo.h"</code><br></pre>
the identity macro is defined as <code>Foo_h</code>. For a header file
that is expected to be included as:<br>
<pre><code>#include "LiveSupport/Foo/Bar.h"<br></code></pre>
the identity macro is defined as <code>LiveSupport_Foo_Bar_h</code>.<br>
<br>
After the identity macro, a preprocessor check is performed to see if
the file is being processessed by a C++ compiler (and say not a C
compiler).<br>
<h3>Sample</h3>
A sample for a C++ header file header follows, where the file itself
would be expected to be included as <code>"LiveSupport/Foo/Bar.h"</code>.<br>
<br>
<pre>/*------------------------------------------------------------------------------<br><br> Copyright (c) 2004 Media Development Loan Fund<br> <br> This file is part of the LiveSupport project.<br> http://livesupport.campware.org/<br> To report bugs, send an e-mail to bugs@campware.org<br> <br> LiveSupport is free software; you can redistribute it and/or modify<br> it under the terms of the GNU General Public License as published by<br> the Free Software Foundation; either version 2 of the License, or<br> (at your option) any later version.<br> <br> LiveSupport is distributed in the hope that it will be useful,<br> but WITHOUT ANY WARRANTY; without even the implied warranty of<br> MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the<br> GNU General Public License for more details.<br> <br> You should have received a copy of the GNU General Public License<br> along with LiveSupport; if not, write to the Free Software<br> Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA<br> <br> <br> Author : $Author: maroy $<br> Version : $Revision: 1.1 $<br> Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/cxxHeaderFileConventions.html,v $<br> <br>------------------------------------------------------------------------------*/<br>#ifndef LiveSupport_Foo_Bar_h<br>#define LiveSupport_Foo_Bar_h<br> <br>#ifndef __cplusplus<br>#error This is a C++ include file<br>#endif<br><br></pre>
<h2>Include files &amp; namespace <br>
</h2>
This section contains all the include files that the header file needs
to include, plus namespace declarations. The include files are listed
in a most generic to most specific order: firts system include files,
then other LiveSupport module include files, and finnally include files
from the same module / product are listed.<br>
<br>
After the includes, namespace definitions follow. Each LiveSupport
object is contained in its own namespace inside the <code>LiveSupport</code>
namespace, thus this is a nested namespace declaration.<br>
<br>
After the namespace declarations, the namespaces used within the
include file itself are listed with <code>using namespace</code>
clauses. Note that the <code>using namespace</code> clauses are
strictly within the namespace declaration clauses, so that they only
take effect within the header file, but not afterwards.<br>
<h3>Sample</h3>
A sample include files &amp; namespaces section follows.<br>
<pre>/* =============================================== include files &amp; namespaces */<br><br>#ifdef HAVE_CONFIG_H<br>#include "configure.h"<br>#endif<br><br>#if HAVE_STDLIB_H<br>#include &lt;stdlib.h&gt;<br>#else<br>#error need stdlib.h<br>#endif<br><br>#include &lt;string&gt;<br><br><br>namespace LiveSupport {<br>namespace Foo {<br><br>using namespace LiveSupport::Core;<br><br></pre>
<h2>Constants</h2>
The constants section contains static constant values defined in the
header file.
Nowhere in the header file may be other static constants defined. This
section is
rarely used, as static constants&nbsp; outside classes are discurraged,<br>
<h3>Sample</h3>
A sample constants section follows.<br>
<pre>/* ================================================================ constants */<br><br>/**<br> * The contant value of foo bar.<br> */<br>static const int fooBarConst;<br></pre>
<h2>Macros</h2>
The macros section contains any macros defined in the header file.
Nowhere in the header file may be other macros defined. This section is
rarely used, as macros are discurraged,<br>
<h3>Sample</h3>
A sample macros section follows.<br>
<pre>/* =================================================================== macros */<br><br>/**<br> * Some very important macro.<br> */<br>#define SOME_MACRO "some macro"<br></pre>
<h2>Data types</h2>
This section contains the data type definitions of the header file,
most notable the definition of the class this header file is named
after.<br>
<br>
The class itself and all its members (including private members) are
described by <a href="http://www.doxygen.org/">doxygen</a> comments.
The Java style of commenting is to be used.&nbsp; For the comment
describing the entire class, the <code>@author</code> and <code>@version</code>
tags are mandatory. For each member function, all parameters, the
return value and all possibly thrown exceptions are to be documented.<br>
<br>
The class lists its members in the following order:<br>
<ul>
<li>private</li>
<li>protected</li>
<li>public</li>
</ul>
Within each of the above blocks, the order is the following:<br>
<ul>
<li>static data members</li>
<li>dynamic data members</li>
<li>constructors</li>
<li>destructor</li>
<li>static functions</li>
<li>dynamic functions</li>
</ul>
For proper indentation of the above blocks, see the example below.<br>
<h3>Sample</h3>
A sample data types section follows.<br>
<pre>/* =============================================================== data types */<br><br>/**<br> * Hello class.<br> * The only purpose of this class is to say hello.<br> *<br> * @author $Author: maroy $<br> * @version $Revision: 1.1 $<br> */<br>class Hello<br>{<br> private:<br> /**<br> * Our famous hello string.<br> */<br> static const std::string helloWorld;<br><br> public:<br> /**<br> * Default constructor.<br> */<br> Hello (void) throw ()<br> {<br> }<br><br> /**<br> * Say hello.<br> *<br> * @return the string "Hello, World!"<br> * @exception std::exception on problems<br> */<br> const std::string<br> hello (void) throw (std::exception)<br> {<br> return helloWorld;<br> }<br>};<br><br></pre>
<h2>External data structures<br>
</h2>
The external data structures section contains any external data
definitions needed by the header file, that may be defined externally.
Nowhere in the header file may other external data definitions exist.
This section is
rarely used, as external data definitions are discouraged.<br>
<h3>Sample</h3>
A sample external data structures section follows.<br>
<pre>/* ================================================= external data structures */<br><br>/**<br> * An externally defined data, which the linker will find.<br> */<br>extern int fooBarInt;<br><br></pre>
<h2>Function prototypes<br>
</h2>
The function prototypes section contains any function prototypes
defined by the header file, that are not members of classes.
Nowhere in the header file may other such definitions exist.
This section is seldom used, as functions outside classes are
discouraged.<br>
<h3>Sample</h3>
A sample function prototypes section follows.<br>
<pre>/* ====================================================== function prototypes */<br><br>/**<br> * An important foo function.<br> *<br> * @return the result of foo.<br> */<br>int foo(void) throw ();<br></pre>
<h2>Footer</h2>
The footer of the header file closes the namespace brackets opened in
the include files &amp; namespaces section, and also ends the header
identity macro #ifdef section opened in the header.<br>
<h3>Sample</h3>
A sample footer section follows.<br>
<br>
<pre>} // namespace Foo<br>} // namespace LiveSupport<br><br>#endif // LiveSupport_Foo_Bar_h<br></pre>
<h1>Template</h1>
See a <a href="templates/Bar.h">template
C++ header file</a>. You may freely copy this
template when starting to create a new header file.<br>
<br>
</body>
</html>

151
livesupport/doc/developmentEnvironment/cxxSourceFileConventions.html Normal file
View File

@ -0,0 +1,151 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=UTF-8"
http-equiv="content-type">
<title>C++ source file conventions</title>
<meta content="$Author: maroy $" name="author">
</head>
<body>
<h1>Preface</h1>
This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a>
project, Copyright &#169; 2004 <a href="http://www.mdlf.org/">Media
Development Loan Fund</a>, under the GNU <a
href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
<ul>
<li>Author: $Author: maroy $</li>
<li>Version: $Revision: 1.1 $</li>
<li>Location: $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/cxxSourceFileConventions.html,v $</li>
</ul>
<h1>Scope</h1>
This document describes C++ source file conventions for the
LiveSupport
project. See also the generic description of the <a
href="file:///home/darkeye/src/livesupport/livesupport/doc/developmentEnvironment/fileConventions.html">file
conventions</a> in the LiveSupport
project.<br>
<h1>Introduction</h1>
C++ source files are files containing implementations of functions and
definitions of static data. They are text
based files, thus they should adhere to the <a
href="fileConventions.html#textConventions">generic text-based
conventions</a>.<br>
<br>
The LiveSupport project uses a strong object oriented approach. Part of
this approach is to group implementations of classes into their own
files: one header file and one source file for each class. Therefore
each C++ source file contains implementation of exactly one C++ class,
although static (local) functions may be defined as well.<br>
<h1>Naming</h1>
A C++ source files name reflects the class it is implementing. Class
names begin with a capital letter, followed by lower case letters. In
case of a multiple word class name, the first letter of each word is
capitalized. Example class names are <code>Foo</code> and <code>FooBar</code>.<br>
<br>
As the name of the source file reflects the name of the class it
implements, the source file will be named exactly as the class inside,
with the <code>.cxx</code> extension. Thus a class named <code>Foo</code>
is implemented in the source file <code>Foo.cxx</code>, and the class
named <code>SomeOtherLongNamedClass</code> is implemented in the
source file named <code>SomeOtherLongNamedClass.cxx</code>.<br>
<h1>Structure</h1>
C++ files are partitioned by using the following 80 column wide
partitioning comment:<br>
<pre>/* ==================================================== name of the partition */<br></pre>
Note that the comment is always 80 columns wide, independent of the
length of the text within.<br>
<br>
Local data type definitions and function prototypes required
doxygen-style commenting.<br>
<br>
Function implementations and static data definitions were already
commented for doxygen at their place of declaration. Therefore these
are preceded by the following simple comment header.<br>
<pre>/*------------------------------------------------------------------------------<br>&nbsp;* Function implementation below.<br> *----------------------------------------------------------------------------*/<br></pre>
<br>
The file has the
following mandatory structure:<br>
<ul>
<li>Header</li>
<li>Include files &amp; namespaces</li>
<li>Local data structures<br>
</li>
<li>Local constants &amp; macros<br>
</li>
<li>Local function prototypes<br>
</li>
<li>Module code<br>
</li>
</ul>
<h2>Header</h2>
The header holds all information mandated by the <a
href="fileConventions.html#header">generic guidelines</a>. It contains
with the generic header information, enclosed in 80
column wide partitioning delimiters.<br>
<h3>Sample</h3>
A sample for a C++ source file header follows.<br>
<pre>/*------------------------------------------------------------------------------<br><br> Copyright (c) 2004 Media Development Loan Fund<br> <br> This file is part of the LiveSupport project.<br> http://livesupport.campware.org/<br> To report bugs, send an e-mail to bugs@campware.org<br> <br> LiveSupport is free software; you can redistribute it and/or modify<br> it under the terms of the GNU General Public License as published by<br> the Free Software Foundation; either version 2 of the License, or<br> (at your option) any later version.<br> <br> LiveSupport is distributed in the hope that it will be useful,<br> but WITHOUT ANY WARRANTY; without even the implied warranty of<br> MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the<br> GNU General Public License for more details.<br> <br> You should have received a copy of the GNU General Public License<br> along with LiveSupport; if not, write to the Free Software<br> Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA<br> <br> <br> Author : $Author: maroy $<br> Version : $Revision: 1.1 $<br> Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/cxxSourceFileConventions.html,v $<br> <br>------------------------------------------------------------------------------*/<br><br></pre>
<h2>Include files &amp; namespaces <br>
</h2>
This section contains all the include files that the source file needs
to include, plus namespace references. The include files are listed in
a most generic to most specific order: first system include files, then
other LiveSupport module include files, and finally include files from
the same module / product are listed. The last one is the header file
for the class this source file implements.<br>
<br>
After the includes, the namespaces used within the source file itself
are listed with <code>using namespace</code> clauses. The order of the
<code>using namespace</code> declarations is also from most generic to
most specific, the last one being the namespace of the class this
source file implements.<br>
<h3>Sample</h3>
A sample include files &amp; namespaces section follows.<br>
<pre>/* =============================================== include files &amp; namespaces */<br><br>#ifdef HAVE_CONFIG_H<br>#include "configure.h"<br>#endif<br><br>#if HAVE_STDLIB_H<br>#include &lt;stdlib.h&gt;<br>#else<br>#error need stdlib.h<br>#endif<br><br>#include &lt;string&gt;<br><br>#include &lt;LiveSupport/Foo/Bar.h&gt;<br><br><br>using namespace LiveSupport::Core;<br>using namespace LiveSupport::Foo;<br><br></pre>
<h2>Local data structures<br>
</h2>
The constants section contains locally defined data structures, that
are not used anywhere outside this source file.
Nowhere in the source file may be other data structure definitions.
This section is
rarely used, as reusable data structures are encouraged.<br>
<h3>Sample</h3>
A sample local data structures section follows.<br>
<pre>/* =================================================== local data structures */<br><br>/**<br> * The union of foo.<br> */<br>union foo {<br> int foo;<br> long bar;<br>};<br></pre>
<h2>Local constants &amp; macros</h2>
The local constants &amp; macros section contains any macros and
constant values used in this source file. It also contains the
definitions for constant values of the class this source file
implements. Nowhere in the source file may be other macros or constants
defined.<br>
<br>
Having local constants is discouraged. Have private static class
members instead.<br>
<h3>Sample</h3>
A sample local constants &amp; macros section follows.<br>
<pre>/* ================================================ local constants &amp; macros */<br><br>/*------------------------------------------------------------------------------<br>&nbsp;* The famous foo string for the class Bar.<br> *----------------------------------------------------------------------------*/<br>const std::string Bar::fooStr = "foo";<br><br></pre>
<h2>Local function prototypes<br>
</h2>
This section contains the prototypes for local functions, which are
only used in this source file. Nowhere else in the source file may
function prototypes be other than in this section. This section is
rarely used, local functions are discouraged. Use private class member
functions instead.<br>
<h3>Sample</h3>
A sample local function prototypes section follows.<br>
<pre>/* =============================================== local function prototypes */<br><br>/**<br> * Some local function.<br> *<br> * @param parameter some parameter<br> * @return a very big return value.<br> */<br>int<br>localFunction(int parameter) throw ();<br><br></pre>
<h2>Module code<br>
</h2>
This section contains the implementation for the class it is made for.
Also contains the implementation for all local functions. The
implementation order is not defined.<br>
<h3>Sample</h3>
A sample module code section follows.<br>
<pre>/* ============================================================= module code */<br><br>/*------------------------------------------------------------------------------<br>&nbsp;* Return the famous bar string.<br> *----------------------------------------------------------------------------*/<br>const std::string<br>Bar :: sayBar(void) throw (std::exception)<br>{<br> if (barInt) {<br> throw std::exception();<br> }<br><br> return barStr;<br>}<br><br></pre>
<h1>Template</h1>
See a <a href="templates/Bar.cxx">template
C++ source file</a>. You may freely copy this
template when starting to create a new source file.<br>
<br>
</body>
</html>

163
livesupport/doc/developmentEnvironment/directoryStructure.html Normal file
View File

@ -0,0 +1,163 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=UTF-8"
http-equiv="content-type">
<title>Directory structure</title>
<meta content="$Author: maroy $" name="author">
</head>
<body>
<h1>Preface</h1>
This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a>
project, Copyright &#169; 2004 <a href="http://www.mdlf.org/">Media
Development Loan Fund</a>, under the GNU <a
href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
<ul>
<li>Author: $Author: maroy $</li>
<li>Version: $Revision: 1.1 $</li>
<li>Location: $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/directoryStructure.html,v $<br>
</li>
</ul>
<h1>Scope</h1>
This document describes the directory structure used for all component
of the LiveSupport project.<br>
<h1>Introduction</h1>
It is important to define a common and uniform directory structure in
order to allow more seamless cooperation between participants of the
project. It also helps referencing the various components (modules,
etc.), as all the components will have a predictable and stable file
hierarchy.<br>
<br>
As seen below, the main inspiration for each components directory
structure is the <a href="http://www.pathname.com/fhs/">Filesystem
Hierarchy Standard</a>.<br>
<h1>Overall structure</h1>
The base livesupport directory contains all the special tools needed to
build, test and run LiveSupport, along with all the source code that
constitutes LiveSupport itself.<br>
<br>
The self written part of LiveSupport project consists of re-usable
modules, and products.
Modules are components that do not execute by themselves, but have a
useful, preferably generic functionality. Products are the executable
components that are actually run by users.<br>
<br>
Both modules and products may reference (depend on) other modules, but
circular reference is not allowed.<br>
<br>
Other needed parts of the directory structure are involved with
external libraries LiveSupport depends on, and a running environment
where LiveSupport can run.<br>
<br>
The directory structure is organized in the following way:<br>
<br>
<code></code>
<pre>livesupport<br>|-- Makefile<br>|-- doc<br>|-- etc<br>|-- modules<br>| |-- module1<br>| |-- module2<br> ...<br>| `-- moduleN<br>|-- products<br>| |-- product1<br>| |-- product2<br>| ...<br>| `-- productN<br>|-- tools<br>| |-- tool1<br>| |-- tool2<br>| ...<br>| `-- tool3<br>`-- usr<br></pre>
<br>
<h2>Referencing modules and the running environment<br>
</h2>
As a consequence of the directory structure above, if a module is
referencing an other (e.g. moduleX), than it can be sure that it is
located at <code>../moduleX</code>. If a product is referencing the
same module, it can be sure that it is located at <code>../../modules/moduleX</code>.<br>
<br>
Furthermore, if a module or product is referencing the running
environment under <code>livesupport/usr</code>, it can also be sure
that it is located at <code>../../usr</code> from either the module or
the product directory.<br>
<br>
Referencing always means exactly that: no contents are copied from one
module directory to an other. For example for a module or product to
reference the shared libraries of moduleX means to do exactly that:
link to the library <code>../../modules/moduleX/lib/libmoduleX.so</code>.<br>
<h1>Top-level Makefile</h1>
The top-level Makefile provides targets that effect the whole of the
LiveSupport project. Currently the only target is <code>doc</code>,
which generates the documentations for the whole project under the doc
directory.<br>
<br>
<h1>Documentation directory</h1>
The doc directory contains generic documentation with respect to the
whole LiveSupport project. Documentation pertaining to a module or
products should go under the modules' or products' directory,
respectively.<br>
<h1>Configuration files</h1>
Under the <code>etc</code> directory project-wide configuration files
are found, like the ones used by the top-level Makefile.<br>
<h1>Module structure</h1>
Each module has the same directory structure, which is as follows:<br>
<br>
<pre>moduleX<br>|-- Makefile<br>|-- bin<br>|-- etc<br>|-- include<br>| `-- LiveSupport<br>| `-- ModuleX<br>|-- lib<br>|-- src<br>|-- tmp<br>`-- var<br></pre>
<h4>Makefile</h4>
A makefile executable by <a
href="http://www.gnu.org/directory/make.html">GNU make</a>. See the <a
href="buildEnvironment.html">build environment</a> document for a
detailed description.<br>
<h4>bin</h4>
Directory containing all executables, either if these are executable
used for building the module, or executables resulting from the build.<br>
<h4>etc</h4>
All configuration files go here.<br>
<h4>include</h4>
The public C/C++ header files for this module. The include files are
stored in a subdirectory that completely replicates the namespacing of
the module itself, in a case-sensitive manner. Thus a header file name <code>Foo.h</code>
for <code>ModuleX</code> would be contained in the directory <code>include/LiveSupport/ModuleX/Foo.h</code>,
and would be included with the line:<br>
<br>
<pre>#include "LiveSupport/ModuleX/Foo.h"<br></pre>
<h4>lib</h4>
Directory containing all shared and static libraries that are generated
by building the module. All external, third-party libraries used by
this module should be installed into the <code>../../usr/lib</code>
directory. The libraries are named resembling the full namespacing of
the module, but all lower cased. For example, the library for moduleX
would be named <code>liblivesupport_modulex.so</code>, and thus would
be linked to with the linker option <code>-L../../modules/moduleX/lib
-llivesupport_modulex</code>.<br>
<h4>src</h4>
Contains all source files. A source file is a file which is processed
(compiled, etc.) by the build process, and as a result some target
files are generated from it.<br>
<h4>tmp</h4>
A temporary directory, holding temporary files used by the build
process. This directory either does not exist in the configuration
management system, or is empty there.<br>
<h4>var</h4>
Directory containing data. This can range from XML data to HTML pages
to all other files that are not source files (are not processed by the
build process). Note that web-page scripting files like PHP files also
fall into this category.<br>
<h1>Product structure</h1>
The directory structure for a product is in essence the same as for
modules, described above, with the difference that products don't have
externally visible include files, thus their directories don't contain
an <code>include</code> directory.<br>
<h1>Tools structure</h1>
The tools directory is an archive of tools and external libraries used
for either building or running the LiveSupport system. These tools are
installable to the usr directory of the LiveSupport directory tree.<br>
Each tool has its own directory, where several versions of the same
tool may reside. Thus the generic directory structure is as follows:<br>
<pre>tools<br>|-- tool1<br>| |-- tool1-X<br>| |-- tool1-Y<br>| ...<br>| `-- tool1-Z<br> ...<br>`-- toolN<br> |-- toolN-A<br> |-- toolN-B<br> ...<br> `-- toolN-C<br></pre>
Thus a user can select version X of toolK to be installed by selecting
the directory <code>tools/toolK/toolK-X</code>. Each tool directory
has the following structure:<br>
<pre>toolK-X<br>|-- bin<br>| `-- install.sh<br>|-- etc<br>|-- src<br>| `-- toolK-X.tar.gz<br>`-- tmp<br></pre>
The script <code>bin/install.sh</code> is responsible for installing
the specific tool under the <code>livesupport/usr</code> directory.
This typically involves the following steps:<br>
<pre>cd tmp<br>tar xfz ../src/toolK-X.tar.gz<br>./configure --prefix=../../../../usr<br>make install<br></pre>
In case the source needs to patched before compilation, the patches may
be contained in the <code>etc</code> directory.<br>
<h1>usr structure</h1>
The usr directory is similar to the /usr system directory on UNIX
systems (see the <a href="http://www.pathname.com/fhs/">Filesystem
Hierarchy Standard</a>). This directory contains all the external tools
needed by either developing or running the LiveSupport system. This
directory is separate from the system /usr directory in order to
facilitate changing the configuration for LiveSupport related libraries
and tools in user space.<br>
<br>
</body>
</html>

114
livesupport/doc/developmentEnvironment/fileConventions.html Normal file
View File

@ -0,0 +1,114 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=UTF-8"
http-equiv="content-type">
<title>File Conventions</title>
<meta content="$Auhor$" name="author">
</head>
<body>
<h1>Preface</h1>
This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a>
project, Copyright &#169; 2004 <a href="http://www.mdlf.org/">Media
Development Loan Fund</a>, under the GNU <a
href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
<ul>
<li>Author: $Author: maroy $</li>
<li>Version: $Revision: 1.1 $</li>
<li>Location: $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/fileConventions.html,v $</li>
</ul>
<h1>Scope</h1>
This document describes the conventions used for files in the
LiveSupport project.<br>
<h1>Introduction</h1>
To facilitate cooperation between multiple contributors, it is
advisable to have common file conventions, so as the result of
different peoples work have a uniform look and form. This document
lists the file conventions for the different file formats used by the
project.<br>
<br>
Where the description of the conventions is ambiguous, the examples
given are binding, and are to be followed.<br>
<h1>Generic conventions</h1>
In general, all documents have the following structure:<br>
<ul>
<li>header</li>
<li>partition1</li>
<li>partition2</li>
<li>...</li>
<li>partitionN</li>
</ul>
<h2><a name="header"></a>header<br>
</h2>
The header of the file holds:<br>
<ul>
<li>a reference to the LiveSupport project itself</li>
<li>copyright information</li>
<li>reference to the license of the file</li>
<li>the latest author of the file</li>
<li>the current version of the file</li>
<li>the full location of the file in the configuration management
system<br>
</li>
</ul>
Following the GNU GPL <a
href="http://www.gnu.org/licenses/gpl.html#SEC4">guidelines</a> on
applying a license term to source files, the typical header for a text
file looks like the following:<br>
<br>
<pre><code> Copyright (c) 2004 Media Development Loan Fund<br> <br> This file is part of the LiveSupport project.<br> http://livesupport.campware.org/<br> To report bugs, send an e-mail to bugs@campware.org<br> <br> LiveSupport is free software; you can redistribute it and/or modify<br> it under the terms of the GNU General Public License as published by<br> the Free Software Foundation; either version 2 of the License, or<br> (at your option) any later version.<br> <br> LiveSupport is distributed in the hope that it will be useful,<br> but WITHOUT ANY WARRANTY; without even the implied warranty of<br> MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the<br> GNU General Public License for more details.<br> <br> You should have received a copy of the GNU General Public License<br> along with LiveSupport; if not, write to the Free Software<br> Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA<br> <br> <br> Author : $Author: maroy $<br> Version : $Revision: 1.1 $<br> Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/fileConventions.html,v $<br></code><br></pre>
Note the CVS keywords (as an example) for having up-to-date information
on the author, version and location of the file.<br>
<h2>partitions</h2>
Each file is split into separate partitions, and maintains its
structure with the fixed sequence of these partitions. File formats
differ heavily on the capabilities of defining partitions - some have
explicit support (like HTML with headers and paragraphs), while in some
the commenting feature can be used to visually split up the file (like
comments in source code).<br>
<br>
The exact nature and sequence of the partitions is dependent on the
nature of the file itself.<br>
<h2><a name="textConventions"></a>Generic text-based conventions</h2>
The majority (if not) all sources files are text-based. As a general
rule, text-based files adhere to the following conventions in the
LiveSupport project:<br>
<h3>UTF-8</h3>
Whenever possible, the text files should be saved in the <a
href="http://www.unicode.org/glossary/#UTF_8">UTF-8</a> character
encoding, to enable all characters within covered by the Unicode
character set.<br>
<h3>80 columns</h3>
Don't exceed 80 columns for any line in the file, unless it's
absolutely necessary (like having a single expression over 80 columns
that can not be broken up by a new-line character).<br>
<h3>no tabs - 4 spaces</h3>
Don't use the tab character in text files - use 4 spaces instead for
indentation.<br>
<h1>Specific conventions</h1>
For specific file conventions, see the separate descriptions below.<br>
<h2>html</h2>
<a href="htmlFileConventions.html">convention</a> and <a
href="templates/htmlDocumentTemplate.html">template</a>.<br>
<h2>shell scripts</h2>
<a href="shellScriptConventions.html">convention</a> and <a
href="templates/shellScriptTemplate.sh">template</a>.<br>
<h2>Makefiles</h2>
<a href="makefileConventions.html">convention</a> and <a
href="templates/Makefile">template</a>.<br>
<h2>Autoconf configure files<br>
</h2>
<a href="autoconfConfigureConventions.html">convention</a> and <a
href="templates/configure.ac">template</a>.<br>
<h2>C++ files</h2>
There are specific conventions for the header files and the source
files.<br>
<h3>C++ header files</h3>
<a href="cxxHeaderFileConventions.html">convention</a> and <a
href="templates/Bar.h">template</a>.<br>
<h3>C++ source files</h3>
<a href="cxxSourceFileConventions.html">convention</a> and <a
href="templates/Bar.cxx">template</a>.<br>
<br>
</body>
</html>

93
livesupport/doc/developmentEnvironment/htmlFileConventions.html Normal file
View File

@ -0,0 +1,93 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=UTF-8"
http-equiv="content-type">
<title>HTML file conventions</title>
<meta content="$Author: maroy $" name="author">
</head>
<body>
<h1>Preface</h1>
This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a>
project, Copyright &#169; 2004 <a href="http://www.mdlf.org/">Media
Development Loan Fund</a>, under the GNU <a
href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
<ul>
<li>Author: $Author: maroy $</li>
<li>Version: $Revision: 1.1 $</li>
<li>Location: $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/htmlFileConventions.html,v $</li>
</ul>
<h1>Scope</h1>
This document describes the HTML file conventions for the LiveSupport
project. See also the generic description of the <a
href="fileConventions.html">file conventions</a> in the LiveSupport
project.<br>
<h1>Introduction</h1>
HTML pages written as part of the LiveSupport documentation should
conform to either the <a href="http://www.w3.org/TR/html4/">HTML 4.01
Transitional</a> or <a href="http://www.w3.org/TR/xhtml1/">XHTML 1.0
Transitional</a> specifications.<br>
<h1>Naming</h1>
HTML document files are named by the following rules:<br>
<ul>
<li>there are no spaces in the file name</li>
<li>the file name begins with a lower case letter</li>
<li>for file names containing multiple words, each additional word
begins with a capital letter</li>
<li>the extension of the file is <code>.html</code> (not <code>.htm</code>)<br>
</li>
</ul>
For example, a file with a single-word name may be named like: <code>single.html</code>,
whereas a file with multiple word name would be like: <code>multipleWordNameFile.html</code>.<br>
<h1>Structure</h1>
Each HTML file is partitioned by using the <code>&lt;h1&gt;</code>
element to mark the start and name of each partition. The file has the
following mandatory structure:<br>
<ul>
<li>Preface</li>
<li>Scope</li>
<li>Introduction?</li>
<li>Additional sections+</li>
</ul>
<h2>HTML header</h2>
The HTML header of the document should describe the title and author of
the document. The following HTML code should be inside the <code>&lt;head&gt;</code>
element for the HTML page:<br>
<br>
<pre><code> &lt;title&gt;The title of the file&lt;/title&gt;<br> &lt;meta name="author" content="$Author: maroy $"/&gt;<br></code></pre>
<h2>The Preface section</h2>
This section holds the following specific text:<br>
<br>
<blockquote>This document is part of the <a
href="http://livesupport.campware.org/">LiveSupport</a> project,
Copyright &#169; 2004 <a href="http://www.mdlf.org/">Media Development Loan
Fund</a>, under the GNU <a href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
<ul>
<li>Author: $Author: maroy $</li>
<li>Version: $Revision: 1.1 $</li>
<li>Location: $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/htmlFileConventions.html,v $</li>
</ul>
</blockquote>
<h2>The Scope section</h2>
This section describes the scope of the document in short form. This
details the areas which the document covers, and sometimes holds
references to related documents.<br>
<h2>The Introductions section</h2>
This optional section introduces the topic of the document to the
reader.<br>
<h2>Additional sections</h2>
These section hold the real content of the document, with freely named
sections and sub-sections. The normal HTML heading elements (<code>&lt;h1&gt;</code>,
<code>&lt;h2&gt;</code>, ...) should be used to mark and group the
sections. Sample source code included in the HTML document should be
put inside a <code>&lt;pre&gt;&lt;code&gt;...&lt;/code&gt;&lt;/pre&gt;</code>
block, like the following:<br>
<br>
<pre><code> // some sample code here<br> int i = 1;<br></code></pre>
<h1>Template</h1>
See a generic <a href="templates/htmlDocumentTemplate.html">template
for HTML documents</a>. You may freely copy this
template when starting to create a new document.<br>
<br>
</body>
</html>

37
livesupport/doc/developmentEnvironment/index.html Normal file
View File

@ -0,0 +1,37 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=UTF-8"
http-equiv="content-type">
<title>LiveSupport development environment</title>
<meta content="$Author: maroy $" name="author">
</head>
<body>
<h1>Preface</h1>
This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a>
project, Copyright &#169; 2004 <a href="http://www.mdlf.org/">Media
Development Loan Fund</a>, under the GNU <a
href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
<ul>
<li>Author: $Author: maroy $</li>
<li>Version: $Revision: 1.1 $</li>
<li>Location: $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/index.html,v $</li>
</ul>
<h1>Scope</h1>
This document gives an overview of the LiveSupport development
environment.<br>
<h1>Introduction</h1>
The LiveSupport project defines a uniform development environment to
enhance collaboration of participants in the project. The following
aspects of the environment are defined so far:<br>
<ul>
<li><a href="fileConventions.html">file conventions</a></li>
<li><a href="directoryStructure.html">directory structure</a></li>
<li><a
href="file:///home/darkeye/src/livesupport/livesupport/doc/developmentEnvironment/buildEnvironment.html">build
environment</a></li>
</ul>
<br>
<br>
</body>
</html>

143
livesupport/doc/developmentEnvironment/makefileConventions.html Normal file
View File

@ -0,0 +1,143 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=UTF-8"
http-equiv="content-type">
<title>Makefile conventions</title>
<meta content="$Author: maroy $" name="author">
</head>
<body>
<h1>Preface</h1>
This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a>
project, Copyright &#169; 2004 <a href="http://www.mdlf.org/">Media
Development Loan Fund</a>, under the GNU <a
href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
<ul>
<li>Author: $Author: maroy $</li>
<li>Version: $Revision: 1.1 $</li>
<li>Location: $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/makefileConventions.html,v $</li>
</ul>
<h1>Scope</h1>
This document describes the Makefile file conventions for the
LiveSupport
project. See also the generic description of the <a
href="file:///home/darkeye/src/livesupport/livesupport/doc/developmentEnvironment/fileConventions.html">file
conventions</a> in the LiveSupport
project. This document does not describe the mandatory targets for
Makefiles, see the <a href="buildEnvironment.html">build environment</a>
description for such details.<br>
<h1>Introduction</h1>
Makefiles are text-based files processed by <a
href="http://www.gnu.org/software/make/">GNU make</a>. As text based
files, they should adhere to the <a
href="fileConventions.html#textConventions">generic text-based
conventions</a>.<br>
<h1>Naming</h1>
Makefiles are always named <code>Makefile</code>. In case they are
input files for automake or autoconf, they can be named <code>Makefile.in</code>
or <code>Makefile.am</code>.<br>
<h1>Structure</h1>
Makefiles are partitioned by using the following 80 column wide
partitioning comment:<br>
<pre>#-------------------------------------------------------------------------------<br># This is the title of the partition<br>#-------------------------------------------------------------------------------<br></pre>
The file has the
following mandatory structure:<br>
<ul>
<li>Header</li>
<li>General command definitions</li>
<li>Basic directory and file definitions</li>
<li>Configuration parameters</li>
<li>Dependencies</li>
<li>Targets</li>
<li>Specific targets</li>
<li>Pattern rules<br>
</li>
</ul>
<h2>Header</h2>
The header holds all information mandated by the <a
href="fileConventions.html#header">generic guidelines</a>, but
starting with the Makefile comment character <code>#</code>. Note the
80
column wide partitioning delimiter enclosing the header.<br>
<pre>#-------------------------------------------------------------------------------<br># Copyright (c) 2004 Media Development Loan Fund<br>#<br># This file is part of the LiveSupport project.<br># http://livesupport.campware.org/<br># To report bugs, send an e-mail to bugs@campware.org<br>#<br># LiveSupport is free software; you can redistribute it and/or modify<br># it under the terms of the GNU General Public License as published by<br># the Free Software Foundation; either version 2 of the License, or<br># (at your option) any later version.<br>#<br># LiveSupport is distributed in the hope that it will be useful,<br># but WITHOUT ANY WARRANTY; without even the implied warranty of<br># MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the<br># GNU General Public License for more details.<br>#<br># You should have received a copy of the GNU General Public License<br># along with LiveSupport; if not, write to the Free Software<br># Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA<br>#<br>#<br># Author : $Author: maroy $<br># Version : $Revision: 1.1 $<br># Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/makefileConventions.html,v $<br>#-------------------------------------------------------------------------------<br></pre>
<h2>General command definitions<br>
</h2>
This section contains definitions to commands used when executing the
make targets within this Makefile. All the commands should be collected
here, and a variable defined for them. This insures easy overview of
the commands the Makefile uses, and also makes it easy to migrate to
new commands, or the same commands in different locations.<br>
<br>
No external commands may be directly referenced outside this section.<br>
<h3>Sample</h3>
A sample general command definitions section follows.<br>
<pre>#-------------------------------------------------------------------------------<br># General command definitions<br>#-------------------------------------------------------------------------------<br>MKDIR = mkdir -p<br>RM = rm -f<br>RMDIR = rm -rf<br>DOXYGEN = doxygen<br><br></pre>
<h2>Basic directory and file definitions</h2>
This section contains definitions for the directories and files
referenced in this Makefile. All directories referenced from the
Makefile, and all external files referenced by the Makefile should be
collected here. This insures easy adoption in case some external
directories or files change.<br>
<br>
No directories or external files may be directory referenced outside
this section.<br>
<br>
When referencing other LiveSupport modules, typically the following
variables are defined for them:<br>
<pre><code>MODULEX_DIR = ${MODULES_DIR}/moduleX<br>MODULEX_INCLUDE_DIR = ${MODULEX_DIR}/include<br>MODULEX_LIB_DIR = ${MODULEX_DIR}/lib<br>MODULEX_LIB = livesupport_modulex<br></code></pre>
<h3>Sample</h3>
A sample directory and file definition section follows.<br>
<pre>#-------------------------------------------------------------------------------<br># Basic directory and file definitions<br>#-------------------------------------------------------------------------------<br>BASE_DIR = .<br>DOC_DIR = ${BASE_DIR}/doc<br>DOXYGEN_DIR = ${DOC_DIR}/doxygen<br>ETC_DIR = ${BASE_DIR}/etc<br>SRC_DIR = ${BASE_DIR}/src<br>TMP_DIR = ${BASE_DIR}/tmp<br><br><br>USR_DIR = ${BASE_DIR}/../../usr<br>USR_INCLUDE_DIR = ${USR_DIR}/include<br>USR_LIB_DIR = ${USR_DIR}/lib<br>BOOST_INCLUDE_DIR = ${USR_INCLUDE_DIR}/boost-1_31<br>LIBXMLPP_INCLUDE_DIR = ${USR_INCLUDE_DIR}/libxml++-1.0<br><br>MODULES_DIR = ${BASE_DIR}/../../modules<br><br>HELLOLIB_DIR = ${MODULES_DIR}/hello<br>HELLOLIB_INCLUDE_DIR = ${HELLOLIB_DIR}/include<br>HELLOLIB_LIB_DIR = ${HELLOLIB_DIR}/lib<br>HELLOLIB_LIB = livesupport_hello<br><br>VPATH = ${SRC_DIR}<br><br>HELLO_EXE = ${TMP_DIR}/hello<br><br>DOXYGEN_CONFIG = ${ETC_DIR}/doxygen.config<br><br></pre>
<h2>Configuration parameters</h2>
This section contains the parameters passed to the building tools
(compiler, linker, etc.) When invoking building tools, they should be
parametrized by the definitions made here.<br>
<h3>Sample<br>
</h3>
A sample configuration parameters section follows.<br>
<pre>#-------------------------------------------------------------------------------<br># Configuration parameters<br>#-------------------------------------------------------------------------------<br>CPPFLAGS = <br>CXXFLAGS = -pedantic -Wall \<br> &nbsp;-I${USR_INCLUDE_DIR} -I${HELLOLIB_INCLUDE_DIR} \<br> -I${INCLUDE_DIR} -I${TMP_DIR}<br>LDFLAGS = -L${USR_LIB_DIR} -L${HELLOLIB_LIB_DIR} -L${LIB_DIR}<br><br></pre>
<h2>Dependencies</h2>
The dependencies section lists the objects that are build by implicit
rules, and that main targets depend on. This is the place where all
object files are listed, basically, for each library or executable.<br>
<br>
No object files that are built by this Makefile should be directly
referred to outside this section.<br>
<h3>Sample</h3>
A sample dependencies section follows.<br>
<pre>#-------------------------------------------------------------------------------<br># Dependencies<br>#-------------------------------------------------------------------------------<br>HELLO_EXE_OBJS = ${TMP_DIR}/main.o<br><br></pre>
<h2>Targets</h2>
This section lists all the explicit, external targets for the makefile.
For a list of targets required, see the <a href="buildEnvironment.html">description</a>
of the build environment. All targets in this section are marked as
.PHONY, as these targets are not building the files they are named
after.<br>
<br>
No explicit targets should be defined in the Makefile outside this
directory.<br>
<h3>Sample</h3>
A sample targets section follows.<br>
<pre>#-------------------------------------------------------------------------------<br># Targets<br>#-------------------------------------------------------------------------------<br>.PHONY: all dir_setup doc clean docclean depclean distclean<br> <br>all: dir_setup ${HELLO_EXE}<br> <br>dir_setup: ${TMP_DIR} ${DOXYGEN_DIR}<br> <br>doc:<br> ${DOXYGEN} ${DOXYGEN_CONFIG}<br> <br>clean:<br> ${RM} ${HELLO_EXE_OBJS} ${HELLO_EXE}<br> <br>docclean:<br> ${RMDIR} ${DOXYGEN_DIR}/html<br> <br>depclean: clean<br> <br>distclean: clean docclean<br> ${RMDIR} ${TMP_DIR}/config* ${TMP_DIR}/autom4te*<br> <br></pre>
<h2>Specific targets</h2>
This section defines the targets for files to be built by the Makefile.
These are the targets that specify how files are built, but are not
covered by pattern rules.<br>
<h3>Sample</h3>
A sample specific targets section follows.<br>
<pre>#-------------------------------------------------------------------------------<br># Specific targets<br>#-------------------------------------------------------------------------------<br>${HELLO_EXE}: ${HELLO_EXE_OBJS}<br> ${CXX} ${LDFLAGS} -o $@ $^ -l${HELLOLIB_LIB}<br> <br>${TMP_DIR}:<br> ${MKDIR} ${TMP_DIR}<br> <br>${DOXYGEN_DIR}:<br> ${MKDIR} ${DOXYGEN_DIR}<br> <br></pre>
<h2>Pattern rules</h2>
Pattern rules are the generic rules to build target files from object
files. Define these pattern rules in this section.<br>
<br>
No pattern rules should exist outside this section.<br>
<h3>Sample</h3>
A sample pattern rules section follows.<br>
<pre>#-------------------------------------------------------------------------------<br># Pattern rules<br>#-------------------------------------------------------------------------------<br>${TMP_DIR}/%.o : ${SRC_DIR}/%.cxx<br> ${CXX} ${CPPFLAGS} ${CXXFLAGS} -c -o $@ $&lt;<br><br></pre>
<br>
<h1>Template</h1>
See a generic <a href="templates/Makefile">template
for Makefiles</a>. You may freely copy this
template when starting to create a new Makefile.<br>
<br>
</body>
</html>

77
livesupport/doc/developmentEnvironment/shellScriptConventions.html Normal file
View File

@ -0,0 +1,77 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=UTF-8"
http-equiv="content-type">
<title>shell script conventions</title>
<meta content="$Author: maroy $" name="author">
</head>
<body>
<h1>Preface</h1>
This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a>
project, Copyright &#169; 2004 <a href="http://www.mdlf.org/">Media
Development Loan Fund</a>, under the GNU <a
href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
<ul>
<li>Author: $Author: maroy $</li>
<li>Version: $Revision: 1.1 $</li>
<li>Location: $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/shellScriptConventions.html,v $</li>
</ul>
<h1>Scope</h1>
This document describes the shell script file conventions for the
LiveSupport
project. See also the generic description of the <a
href="file:///home/darkeye/src/livesupport/livesupport/doc/developmentEnvironment/fileConventions.html">file
conventions</a> in the LiveSupport
project.<br>
<h1>Introduction</h1>
Shell scripts are text-based executable shell command files. As text
based files, they should adhere to the <a
href="fileConventions.html#textConventions">generic text-based
conventions</a>.<br>
<h1>Naming</h1>
Shell script files are named by the following rules:<br>
<ul>
<li>there are no spaces in the file name</li>
<li>the file name begins with a lower case letter</li>
<li>for file names containing multiple words, each additional word
begins with a capital letter</li>
<li>the extension of the file is <code>.sh</code><br>
</li>
</ul>
For example, a file with a single-word name may be named like: <code>single.sh</code>,
whereas a file with multiple word name would be like: <code>multipleWordNameFile.sh</code>.<br>
<h1>Structure</h1>
Shell script files are partitioned by using the following 80 column
wide partitioning comment:<br>
<pre>#-------------------------------------------------------------------------------<br># This is the title of the partition<br>#-------------------------------------------------------------------------------<br></pre>
The file has the
following mandatory structure:<br>
<ul>
<li>Reference to the shell<br>
</li>
<li>Header</li>
<li>Additional sections+</li>
</ul>
<h2>Reference to the shell<br>
</h2>
This is the mandatory reference to the shell executable each script has
to begin with:<br>
<pre><code>#!/bin/sh</code><br></pre>
<h2>Header</h2>
The header holds all information mandated by the <a
href="fileConventions.html#header">generic guidelines</a>, but
starting with the shell comment character <code>#</code>. Note the 80
column wide partitioning delimiter enclosing the header.<br>
<pre>#-------------------------------------------------------------------------------<br># Copyright (c) 2004 Media Development Loan Fund<br>#<br># This file is part of the LiveSupport project.<br># http://livesupport.campware.org/<br># To report bugs, send an e-mail to bugs@campware.org<br>#<br># LiveSupport is free software; you can redistribute it and/or modify<br># it under the terms of the GNU General Public License as published by<br># the Free Software Foundation; either version 2 of the License, or<br># (at your option) any later version.<br>#<br># LiveSupport is distributed in the hope that it will be useful,<br># but WITHOUT ANY WARRANTY; without even the implied warranty of<br># MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the<br># GNU General Public License for more details.<br>#<br># You should have received a copy of the GNU General Public License<br># along with LiveSupport; if not, write to the Free Software<br># Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA<br>#<br>#<br># Author : $Author: maroy $<br># Version : $Revision: 1.1 $<br># Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/shellScriptConventions.html,v $<br>#-------------------------------------------------------------------------------<br></pre>
<h2>Additional sections</h2>
Additional sections contain the executing code of the script. Bigger
parts of the script may be partitioned by the partitioning commend seen
above.<br>
<h1>Template</h1>
See a generic <a href="templates/shellScriptTemplate.sh">template
for shell scripts</a>. You may freely copy this
template when starting to create a new document.<br>
<br>
</body>
</html>

70
livesupport/doc/developmentEnvironment/templates/Bar.cxx Normal file
View File

@ -0,0 +1,70 @@
/*------------------------------------------------------------------------------
Copyright (c) 2004 Media Development Loan Fund
This file is part of the LiveSupport project.
http://livesupport.campware.org/
To report bugs, send an e-mail to bugs@campware.org
LiveSupport 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.
LiveSupport 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 LiveSupport; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Author : $Author$
Version : $Revision$
Location : $Source$
------------------------------------------------------------------------------*/
/* =============================================== include files & namespaces */
#ifdef HAVE_CONFIG_H
#include "configure.h"
#endif
#include <LiveSupport/Foo/Bar.h>
using namespace LiveSupport::Core;
using namespace LiveSupport::Bar;
/* =================================================== local data structures */
/* ================================================ local constants & macros */
/*------------------------------------------------------------------------------
* Our famous foo string.
*----------------------------------------------------------------------------*/
const std::string Bar::fooStr = "foo";
/* =============================================== local function prototypes */
/* ============================================================= module code */
/*------------------------------------------------------------------------------
* Return the famous bar string.
*----------------------------------------------------------------------------*/
const std::string
Bar :: sayBar(void) throw (std::exception)
{
if (barInt) {
throw std::exception();
}
return barStr;
}

111
livesupport/doc/developmentEnvironment/templates/Bar.h Normal file
View File

@ -0,0 +1,111 @@
/*------------------------------------------------------------------------------
Copyright (c) 2004 Media Development Loan Fund
This file is part of the LiveSupport project.
http://livesupport.campware.org/
To report bugs, send an e-mail to bugs@campware.org
LiveSupport 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.
LiveSupport 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 LiveSupport; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Author : $Author$
Version : $Revision$
Location : $Source$
------------------------------------------------------------------------------*/
#ifndef LiveSupport_Foo_Bar_h
#define LiveSupport_Foo_Bar_H
#ifndef __cplusplus
#error This is a C++ include file
#endif
/* =============================================== include files & namespaces */
#ifdef HAVE_CONFIG_H
#include "configure.h"
#endif
#include <string>
namespace LiveSupport {
namespace Foo {
using namespace LiveSupport::Core;
/* ================================================================ constants */
/* =================================================================== macros */
/* =============================================================== data types */
/**
* Bar class.
* This does nothing.
*
* @author $Author$
* @version $Revision$
*/
class Bar
{
private:
/**
* A static member variable.
*/
static const std::string barStr;
/**
* A member variable.
*/
int barInt;
public:
/**
* Default constructor.
*/
Bar (void) throw ()
{
}
/**
* Say something.
*
* @param parameter a parameter we don't care about.
* @return the bar string.
* @exception std::exception on some problems.
*/
const std::string
sayBar (void) throw (std::exception)
{
return barStr;
}
};
/* ================================================= external data structures */
/* ====================================================== function prototypes */
} // namespace Foo
} // namespace LiveSupport
#endif // LiveSupport_Foo_Bar_H

123
livesupport/doc/developmentEnvironment/templates/Makefile Normal file
View File

@ -0,0 +1,123 @@
#-------------------------------------------------------------------------------
# Copyright (c) 2004 Media Development Loan Fund
#
# This file is part of the LiveSupport project.
# http://livesupport.campware.org/
# To report bugs, send an e-mail to bugs@campware.org
#
# LiveSupport 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.
#
# LiveSupport 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 LiveSupport; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
#
# Author : $Author$
# Version : $Revision$
# Location : $Source$
#
#-------------------------------------------------------------------------------
#-------------------------------------------------------------------------------
# General command definitions
#-------------------------------------------------------------------------------
MKDIR = mkdir -p
RM = rm -f
RMDIR = rm -rf
DOXYGEN = doxygen
#-------------------------------------------------------------------------------
# Basic directory and file definitions
#-------------------------------------------------------------------------------
BASE_DIR = .
DOC_DIR = ${BASE_DIR}/doc
DOXYGEN_DIR = ${DOC_DIR}/doxygen
ETC_DIR = ${BASE_DIR}/etc
SRC_DIR = ${BASE_DIR}/src
TMP_DIR = ${BASE_DIR}/tmp
VPATH = ${SRC_DIR}
MODULES_DIR = ${BASE_DIR}/../../modules
HELLOLIB_DIR = ${MODULES_DIR}/hello
HELLOLIB_INCLUDE_DIR = ${HELLOLIB_DIR}/include
HELLOLIB_LIB_DIR = ${HELLOLIB_DIR}/lib
HELLOLIB_LIB = livesupport_hello
HELLO_EXE = ${TMP_DIR}/hello
DOXYGEN_CONFIG = ${ETC_DIR}/doxygen.config
#-------------------------------------------------------------------------------
# Configuration parameters
#-------------------------------------------------------------------------------
CPPFLAGS =
CXXFLAGS = -pedantic -Wall \
-I${TMP_DIR} -I${HELLOLIB_INCLUDE_DIR}
LDFLAGS = -L${HELLOLIB_LIB_DIR}
#-------------------------------------------------------------------------------
# Dependencies
#-------------------------------------------------------------------------------
HELLO_EXE_OBJS = ${TMP_DIR}/main.o
#-------------------------------------------------------------------------------
# Targets
#-------------------------------------------------------------------------------
.PHONY: all dir_setup doc clean docclean depclean distclean
all: ${HELLOLIB_LIB} dir_setup ${HELLO_EXE}
dir_setup: ${TMP_DIR} ${DOXYGEN_DIR}
doc:
${DOXYGEN} ${DOXYGEN_CONFIG}
clean:
${RM} ${HELLO_EXE_OBJS} ${HELLO_EXE}
docclean:
${RMDIR} ${DOXYGEN_DIR}/html
depclean: clean
${MAKE} -C ${HELLOLIB_DIR} clean
distclean: clean docclean
${RMDIR} ${TMP_DIR}/config* ${TMP_DIR}/autom4te*
#-------------------------------------------------------------------------------
# Specific targets
#-------------------------------------------------------------------------------
${HELLO_EXE}: ${HELLO_EXE_OBJS}
${CXX} ${LDFLAGS} -o $@ $^ -l${HELLOLIB_LIB}
${TMP_DIR}:
${MKDIR} ${TMP_DIR}
${DOXYGEN_DIR}:
${MKDIR} ${DOXYGEN_DIR}
${HELLOLIB_LIB}:
${MAKE} -C ${HELLOLIB_DIR} all
#-------------------------------------------------------------------------------
# Pattern rules
#-------------------------------------------------------------------------------
${TMP_DIR}/%.o : ${SRC_DIR}/%.cxx
${CXX} ${CPPFLAGS} ${CXXFLAGS} -c -o $@ $<

49
livesupport/doc/developmentEnvironment/templates/configure.ac Normal file
View File

@ -0,0 +1,49 @@
dnl-----------------------------------------------------------------------------
dnl Copyright (c) 2004 Media Development Loan Fund
dnl
dnl This file is part of the LiveSupport project.
dnl http://livesupport.campware.org/
dnl To report bugs, send an e-mail to bugs@campware.org
dnl
dnl LiveSupport is free software; you can redistribute it and/or modify
dnl it under the terms of the GNU General Public License as published by
dnl the Free Software Foundation; either version 2 of the License, or
dnl (at your option) any later version.
dnl
dnl LiveSupport is distributed in the hope that it will be useful,
dnl but WITHOUT ANY WARRANTY; without even the implied warranty of
dnl MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
dnl GNU General Public License for more details.
dnl
dnl You should have received a copy of the GNU General Public License
dnl along with LiveSupport; if not, write to the Free Software
dnl Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
dnl
dnl
dnl Author : $Author$
dnl Version : $Revision$
dnl Location : $Source$
dnl-----------------------------------------------------------------------------
dnl-----------------------------------------------------------------------------
dnl NOTE: Run all configure related scripts from the tmp directory of the
dnl project.
dnl This is due to the fact that configure spreads a lot of trash around,
dnl like atom4te cache directories, config.* files, etc. into the directory
dnl it is being run from. We clearly don't want these in our base directory.
dnl-----------------------------------------------------------------------------
AC_INIT(Hello, 1.0, bugs@campware.org)
AC_PREREQ(2.59)
AC_COPYRIGHT([Copyright (c) 2004 Media Development Loan Fund under the GNU GPL])
AC_REVISION($Revision$)
AC_CONFIG_SRCDIR(../src/main.cxx)
AC_CONFIG_HEADERS(configure.h)
AC_PROG_CXX()
AC_CHECK_HEADERS(unistd.h getopt.h)
AC_CONFIG_FILES(../Makefile:../etc/Makefile.in)
AC_OUTPUT()

29
livesupport/doc/developmentEnvironment/templates/htmlDocumentTemplate.html Normal file
View File

@ -0,0 +1,29 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=UTF-8"
http-equiv="content-type">
<title>HTML document template</title>
<meta content="$Author$" name="author">
</head>
<body>
<h1>Preface</h1>
This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a>
project, Copyright &#169; 2004 <a href="http://www.mdlf.org/">Media
Development Loan Fund</a>, under the GNU <a
href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
<ul>
<li>Author: $Author$</li>
<li>Version: $Revision$</li>
<li>Location: $Source$</li>
</ul>
<h1>Scope</h1>
Describe the scope of your document here, e.g. what topic it is all
about<br>
<h1>Introduction</h1>
Introduce the content of the document to your reader<br>
<h1>Additional sections</h1>
Write about your topic in details here..<br>
<br>
</body>
</html>

33
livesupport/doc/developmentEnvironment/templates/shellScriptTemplate.sh Executable file
View File

@ -0,0 +1,33 @@
#!/bin/sh
#-------------------------------------------------------------------------------
# Copyright (c) 2004 Media Development Loan Fund
#
# This file is part of the LiveSupport project.
# http://livesupport.campware.org/
# To report bugs, send an e-mail to bugs@campware.org
#
# LiveSupport 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.
#
# LiveSupport 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 LiveSupport; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
#
#
# Author : $Author$
# Version : $Revision$
# Location : $Source$
#-------------------------------------------------------------------------------
#-------------------------------------------------------------------------------
# This script does nothing else, but says hello.
#-------------------------------------------------------------------------------
echo "Hello!";