compbench-devel

[Frederic T. <xf...@us...>]

Update of /cvsroot/compbench/CompBenchmarks++
In directory sc8-pr-cvs4.sourceforge.net:/tmp/cvs-serv27176

Added Files:
	howto_improve_compiler_support.h howto_kb.h 
	howto_new_compiler_support.h 
Log Message:
First import.

--- NEW FILE: howto_new_compiler_support.h ---
/* ----------------------------------------------------------------------------
   $Id: howto_new_compiler_support.h,v 1.1 2007/05/01 14:38:18 xfred Exp $

   This is free software.
   For details, see the GNU Public License in the COPYING file, or
   Look http://www.fsf.org
   ------------------------------------------------------------------------- */

#ifndef H_CBMHOWTO_NEW_COMPILER_SUPPORT
#define H_CBMHOWTO_NEW_COMPILER_SUPPORT

/*! \page new_compiler_support Supporting a new compiler
 *
 * \section new_compiler_support_introduction Introduction
 *
 * This page presents a method to get a new compiler supported by
 * CompBenchmarks. Basically, "supported" means here :
 * - CompBenchmarks knows how to pass options to compiler, how to get its
 *   version, and such things. This is a new C++ class.
 * - \ref howto_kb "Knowledge base" has been updated for this compiler,
 * - That testsuite is aware of it.
 *
 * \section new_compiler_support_core C++ core
 *
 * You should build a new directory in source root; if your compiler is
 * name Foo, corresponding directory should be
 * ./libcompbenchmarks/Compiler/Compiler-FOO/. 
 * ./libcompbenchmarks/Compiler/Makefile.am needs to be updated, and
 * Makefile.am for your new directory must be created.
 *
 * You can take a look to ./libcompbenchmarks/Compiler/Compiler-TCC/* files
 * to get a example : it provides a straightforward inheritance of the
 * abstract CBM::Compiler class, which is used by all supported compilers.
 *
 * ./libcompbenchmarks/Compiler/Compiler.cpp must also be updated, since
 * its CBM::CompilerSelector class is used to detect if a given binary is
 * compatible with one of the supported compilers.
 *
 * \section new_compiler_support_kb Updating knowledge-base
 *
 * \ref howto_kb "Knowledge base page" is a good starting point.
 *
 * \section new_compiler_support_ts Testsuite
 *
 * In source directory, please take a look at ./CBM-PI/t/lib/compilers.pl
 * file.
 */

#endif

--- NEW FILE: howto_improve_compiler_support.h ---
/* ----------------------------------------------------------------------------
   $Id: howto_improve_compiler_support.h,v 1.1 2007/05/01 14:38:18 xfred Exp $

   This is free software.
   For details, see the GNU Public License in the COPYING file, or
   Look http://www.fsf.org
   ------------------------------------------------------------------------- */

#ifndef H_CBMHOWTO_IMPROVE_COMPILER_SUPPORT
#define H_CBMHOWTO_IMPROVE_COMPILER_SUPPORT

/*! \page improve_compiler_support Improving compiler's support
 *
 * \section improve_compiler_support_introduction Introduction
 *
 * This page intends to provide clues in order to improve a supported compiler's
 * \ref howto_kb "knowledge base", including :
 * - Fixing option descriptions/logics,
 * - Introducing new options,
 * - Updating testsuite.
 *
 * As a reminder, the \ref howto_kb_logics "logic" in libcompbenchmarks
 * refers to the meta-informations that are provided to make software aware
 * of things like options incompatibilities, while
 * \ref howto_kb_xmltags "descriptions" are just plain text giving help
 * about options.
 *
 * \section improve_compiler_support_fix Updating logics and descriptions
 *
 * Either user interfaces or compbenchmarks-core program (using -qac \<compiler\> -A "<options>"), can enlight inconsistancies in option descriptions or
 * logics. Unless there is a bug in C++ core, modifying knowledge base files
 * is suffiscient to fix that.
 * 
 * \ref howto_kb "Knowledge base page" should give you method to get the
 * files you'll have to modify to update logics and descriptions.
 *
 * Once done, you'll have to update testsuite.
 *
 * \section improve_compiler_support_ts Updating testsuite
 *
 * Since version 0.5.0, CompBenchmarks++ comes with a large testsuite that
 * must be updated according to modifications, including knowledge-base related
 * modifications.
 *
 * In source directory, please take a look at ./CBM-PI/t/lib/compilers.pl
 * file.
 *
 */

#endif

--- NEW FILE: howto_kb.h ---
/* ----------------------------------------------------------------------------
   $Id: howto_kb.h,v 1.1 2007/05/01 14:38:18 xfred Exp $

   This is free software.
   For details, see the GNU Public License in the COPYING file, or
   Look http://www.fsf.org
   ------------------------------------------------------------------------- */

#ifndef H_CBMHOWTO_KB
#define H_CBMHOWTO_KB

/*! \page howto_kb Knowledge base
 *
 * \section howto_kb_presentation Presentation
 *
 * Knowledge base (KB) is formerly XML files that describes known options for a given
 * compiler branch (eg. gcc version 2.95.x). These files are distrbuted throught many
 * directories, according to related compiler and branch.
 *
 * \section howto_kb_hierarchy Hierarchy
 *
 * KB can be found either in extracted tarball source at ./libcompbenchmarks/share/KB
 * or in $PREFIX/share/compbenchmarks/$VERSION/KB/share/compbenchmarks/0.5.0/KB/ when
 * version $VERSION of CompBenchmarks has been installed in $PREFIX directory
 * (--prefix option to ./configure).
 *
 * For convenience, we'll call this directory knowledge-base root directory ($KB_ROOT).
 *
 * \subsection howto_kb_compilers Compilers
 *
 * Each compiler has a dedicated directory right in root KB directory. Directory's name
 * is just compiler's name in lower case : like $KB_ROOT/g++ or $KB_ROOT/tcc for g++
 * and tcc compilers.
 *
 * \subsection howto_kb_branches Branches
 *
 * Since various branches of a given compiler can propose various options or
 * behaviours, branch related directories have been introduced in compiler's
 * directories. For instance, g++/2.95.x and gcc/3.0.x can be found in KB root
 * directory.
 *
 * \subsection howto_kb_files Files
 *
 * For a supported compiler's branch, the description.xml file is mandatory and
 * is the entry point for internal option description logic. This file is used to
 * retrieve supported options.
 *
 * \section howto_kb_option_merging Option merging
 *
 * It's usual for a newer version of a given compiler to re-use part of options of
 * previous branches. This behaviour can be quickly traduced using the \<include/\>
 * directive.
 *
 * \section howto_kb_xmltags XML description tags
 *
 * This section gives complete list of XML tags supported in knowledge base files :
 * - \<options/\> is the main/root element of all files,
 * - \<option/\> introduces a new option,
 * - \<include/\> can be used to merge descriptions given by another file.
 *
 * See $KB_ROOT/gxx/2.95.x/description.xml for a complete sample.
 *
 * \section howto_kb_logics XML logic related tags
 *
 * Previous tags allow users to define options for a given compiler's branch.
 * The term 'logics' refers to checks applied to selected options within a context
 * (compiler, branch, architecture, and so on). Logics are valid XML blocks given
 * in \<option/\>; they can have many meanings :
 * - Option is implied by another, so that it should be useless in certains situations (\<logic-option-implied-by/\>),
 * - Option is exlusive within a set of options; that means it cannot be used if another option of the set has been spoted (\<logic-option-exlusive/\>).
 * - Option is known to disable or enable a features (e.g. symbol alignments);
 * an extended \<logic-option-exlusive/\> form may be used to detect such behaviours
 * and inform user that some options are known to be incompatibles.
 *
 * See $KB_ROOT/gxx/2.95.x/arch.xml for sample.
 *
 * \section howto_kb_further Further readings
 *
 * A look in previous sample files should make you able to :
 * - \ref improve_compiler_support "Improve or fix a compiler support",
 * - \ref new_compiler_support "Introduce support for a new compiler".
 * 
 */

#endif