/** 
* @file:   README
* @author: Brian Sheely
*          bsheely@eecs.utk.edu
* @defgroup papi_components Components
* @brief Component Readme file
*/

/** @page component_readme Component Readme 
@section Creating New Components

The first step in creating a new component is to create a new directory inside the components directory. The naming convention is to use lower case letters for the directory name. At a minimum, this directory will contain all header files and source code required to build the component along with a Rules file which contains the build rules and compiler settings specific to that component. The Rules file must be named using the format Rules.x where x is the name of the directory. There are no restrictions on the naming of header or source files.

If the component requires user input for any of the compiler settings, then the component directory will also contain the files required to generate a configure script using autoconf. The configure script can be used to generate a Makefile which the Rules file will include. The file configure.in is required in order to generate configure. It should specify that the Makefile that gets generated is named Makefile.x where x is the name of the component directory. Finally, configure also needs an input file to create the Makefile. That file must be named Makefile.x.in where x is the name of the component directory.

The following comments apply to components that are under source control. Although configure is generated, it requires the correct version of autoconf. For that reason, configure should be placed under source control. The generated Makefile should not be placed under source control.

In summary, the additional files required for configuration based on user input are: configure.in, configure (generated by autoconf), Makefile.x.in, and Makefile.x (generated by configure) where x is the name of the component directory.

There is one final very important naming convention that applies to components. The array of function pointers that the component defines must use the naming convention papi_vector_t _x_vector where x is the name of the component directory. 


Adding tests to the components:
-------------------------------

In order to add tests to a component that will be compiled together with PAPI when typing 'make' (as well as cleaned up when 'make clean' or 'make clobber' is typed and installed when 'make install-all' or 'make install-tests' is called), the following steps need to be carried out:

    1. create a directory with name 'tests' in the specific component directory
    2. add your test files and a Makefile to the 'tests' directory (see the example test and Makefile in components/example/tests)
    3. The components/< component >/tests/Makefile has to have a rule with the name '< component >_tests'; e.g. for tests added to the example component, the name of the rule would be 'example_tests'. See:
	TESTS = HelloWorld
	example_tests: $(TESTS)
    4. Include components/Makefile_comp_tests to your component test Makefile
	(see components/example/tests/Makefile for more details)
	5. You may also define 'clean' and/or 'install' targets (as shown in the example) which will be called during those parts of the build.  If these targets are missing it will just print a message reporting the missing target and continue.

NOTE: there is no need to modify any PAPI code other than adding your tests and a Makefile to your component and follow step 1 to 4 listed above.



@section Component Specific Information

Some components under source control have additional information specific to their build process or operation. That information can be found in a README file inside the component directory. If the README doesn't exist, no special information is necessary.

*/