# The components description file

Each component that can be used by the user in one of its projects must be described by a text file.

- Location and encoding
- Structure of the description text file
- Where does this description file have to go ?

## Location and encoding

This file is located in the component directory, and its name is the name of the component shared library, but with a `.component` extension.

Example :

      $ cd /opt/gambas/lib
      $ ls *.la
      lib.gb.db.la*        lib.gb.db.postgresql.la*  lib.gb.example.la*    lib.gb.qt.ext.la*  lib.gb.qt.la*
      lib.gb.db.mysql.la*  lib.gb.eval.la*           lib.gb.qt.editor.la*  lib.gb.qt.kde.la*
      $ ls *.component
      lib.gb.component     lib.gb.eval.component  lib.gb.qt.editor.component  lib.gb.qt.kde.component
      lib.gb.db.component  lib.gb.qt.component    lib.gb.qt.ext.component

This text file must be written with the `UTF-8` encoding.

## Structure of the description text file

The first line must be :

      [Component]

Then you have the Key, that is the internal name of the component.

      Key=gb.my.component

You have then Name of the component, i.e. its full description in natural language.

      Name=This a wonderful component !

This description can be translated in any language, by prefixing the Name entry with the language identifier between brackets. Don't forget that you must write the strings with the `UTF-8` character encoding.

      Name[fr]=C'est un composant merveilleux !

Then you can specify the authors of the component : this is a comma-separated list of names.

      Author=Benoît Minisini,Mister Bean

Then you must specify the list of controls that will appear in the IDE toolbox.

      Controls=Label,Image,TextLabel,ProgressBar,Button...

If this component needs other components, you can specify them with the Require entry.

      Require=gb.qt,gb.db

There are other entries in the description file, but they are not documented yet, because they are subject to any change.

## Where does this description file have to go ?

You must put the `*.component` file in the same directory where the component sources are.

Then, you must modify your `Makefile.am` so that this description file is installed correctly by Automake.

Just add the `*.component` file in the `EXTRA_DIST` directive.

      EXTRA_DIST=*.component

And install the file with the `intsall-exec-local` hook.

      install-exec-local:
              @cp -f *.component $(libdir)