This directory contains a template machine layer, with a description of what
each file should contain.

In order to create a new machine layer, create a new directory with the name of
the architecture. Copy the four files contained in this directory, and edit them
to implement the desired functions. To implement all the functions other files
may be created, but being careful that no one collide with anyone already in
charm.

Instead, in order to add a new suboption to an existing machine, for example
adding a new option "smp" to the architecture "elan", create two new files
inside the directory elan called "conv-mach-smp.h" and "conv-mach-smp.sh" with
the same meaning as the two conv-mach files. In this case, the normal
"conv-mach.h" file will be included into the code, followed by the specific
"conv-mach-smp.h" file. Thus, this second file need to take care of the
definitions already made by the former one.

The decision whether to implement a fully new machine.c, or base to an already
existing one, should be made primarly on who will start the job in the target
machine. For example the program directly (charmrun in net- versions), mpirun in
mpi- versions, qsub, psub of any other scheduler. In particular, if it is
required that the program itself starts the job, then net- version is a good
option.

The files contain the following information:

* conv-mach.sh

	contains the definitions of the compailers available in the building
system, and the additional flags and options to pass to the commands. This file
is read by the buils shell script.


* conv-common.h

	contains the common definitions of the architecture, specified as
"define". The main options are described in the template. This file will be
included into the code by conv-config.h which is itself included into converse.h
(together with conv-mach.h and the other generated configurations).


* conv-mach.h

	this file is similar to conv-common.h as structure, but it allows to
specify subarchitectures (like 'gm' in "./build charm++ net-linux gm"). In this
way, a single conv-common.h will contain the common definitions for all the
architectures, a single machine.c will contain the common code, and the flags in
this file can select the code to be compiled.


* machine.c

	this file contains the implementation of the architecture in its
totality, meaning that subarchitectures (specified with "conv-mach-option.h"
files) will all link to this file, and it will need to have switches to
selectively compile the code. These are tipically in the form of:
 "#if CMK_OPTION_IN_CONV_MACH_H". the template file contains the description of
the methods that should be implemented, also considering the values set into the
two header files (conv-common/conv-mach).


Other three files are needed during the charm build: conv-mach-pre.h,
conv-mach-opt.h and conv-mach-opt.sh which are automatically generated by the
build script with the properties retrieved from the system and the compile time
options specified.


*** A more detailed description on which files are linked into charm. ***

When charm builds, the tmp directory is created and all source files are linked
inside it. Regarding the arch files, only two directories are linked: the base
directory and the architecture directory. With an example, if compiling
"net-linux", the base directory will be "net" and the architecture directory
"net-linux". This implies that the machine.c file present in the "net" directory
will be linked (together will all the conv-mach* files and conv-common.h), but
those present in "net-linux" will eventually overwrite them.
