This directory contains the maker scripts. They are a replacement for classic
makefiles. The scripts are never to be called by the user or developer directly.
They are found and used by the script "make.pl" from the upper directory.


General requirements for a maker script
---------------------------------------

The script file name must end with ".maker.pm", otherwise it will not be found
by "make.pl".

The script must be written in the Perl programming language.

The script must define a package with the same name as the file name without
ending. We call it the (sub-)project name.

Within that package, the script must define a set of functions as described
blow.

At execution, the current directory is always set to the top-level directory,
there where "make.pl" is. All paths are relative to that point.


GetDepedencies
--------------

This function returns an array of project names. Those projects are always built
before.

In addition to the dependencies defined by this function, every project
implicitly depends on the project "defaults".


IsEssential
-----------

Returns 0 or 1:

0 means that the project is not so essential and that the user may want to
ignore a failure with building the project.

1 means that the project is so essential, that the overall building shall always
be stopped on a failure with building the project.


GetFileHandlingRules
--------------------

Returns an array of file handling rules. These rules are used by "make.pl" to
decide whether a file should be deleted by the clean command, whether it should
be copied by the install command, and whether it should have execution
permission then.

For most files, the rules from the project "defaults" are already correct. But
other projects can give some additional rules for their individual files.

Each rule is a string of the form:

  <op><flag>[<op><flag>[<op><flag>...]]:<pattern>

With:

  <op> is either a + for setting the flag, or a - for removing the flag.

  <flag> is the name of the flag, which can be:
    clean    - The file has to be deleted by the clean command.
    install  - The file has to be installed by the install command.
    exec     - The file is an executable.
    private  - The file must not be released, in addition to files
               which have "clean" set (developer's private stuff).
    nobackup - The file must not be backed up, in addition to files
               which have "clean" set (developer's private stuff).

  <pattern> is a pattern for matching the file path. It's a Perl regular
  expression.

The flag operations of a rule are applied to all files whose file paths match
the pattern. Hereby the path is relative to the current directory (there where
"make.pl" is), and the path elements are separated by slashes, even on Windows.

If there are contrary rules, the later one counts. The project dependencies are
respected.

Be careful when writing the regular expressions. One error could mean that the
clean command deletes some or all of the source files. Please study all existing
rules before making new ones. Make backups before testing.


GetExtraBuildOptions
--------------------

"make.pl" defines some user options for the build command. Each project may
define additional options though this function. It returns an array of
references where each reference refers an array of three strings: The name of
the option, the default value, and a description.


Build
-----

This function performs compilation, linkage and maybe other things for building
the project. Output files which are up to date should not be re-generated (this
is usually solved by using unicc). The beginning of the function body should
look like:

  shift;
  my %options=@_;

Thereby the hashes variable %options contains all the options. Hash index is the
option name, hash value is the option value. Following options are defined by
default:

  "compiler"
    Name of compiler and linker to be used.

  "cpus"
    Number of CPU's to be used.

  "debug"
    Whether to produce debug information. Must be "yes" or "no".

  "unicc"
    Relative path to the unicc directory.

  "unicc_call"
    Reference to an array which contains the first arguments for calling
    unicc.pl. It's like:
    [ 'perl', catfile($options{'unicc'},'unicc.pl'),
      '--compiler', $options{'compiler'},
      '--cpus', $options{'cpus'},
      $options{'debug'} eq 'yes' ? ('--debug') : () ]

  "utils"
    Relative path to the utils directory.

  "projects"
    This is for "make.pl" and should not be used by the projects.

  "continue"
    This is for "make.pl" and should not be used by the projects.

In addition, there are all the extra options defined through
GetExtraBuildOptions from all the projects.

The Build function has to return 1 on success. On failure, it may either return
0 or call the Perl function die.
