Changed the interOperate to a global variable so that it is initialized from
[charm.git] / src / arch / template / README
1 This directory contains a template machine layer, with a description of what
2 each file should contain.
3
4 In order to create a new machine layer, create a new directory with the name of
5 the architecture. Copy the four files contained in this directory, and edit them
6 to implement the desired functions. To implement all the functions other files
7 may be created, but being careful that no one collide with anyone already in
8 charm.
9
10 Instead, in order to add a new suboption to an existing machine, for example
11 adding a new option "smp" to the architecture "elan", create two new files
12 inside the directory elan called "conv-mach-smp.h" and "conv-mach-smp.sh" with
13 the same meaning as the two conv-mach files. In this case, the normal
14 "conv-mach.h" file will be included into the code, followed by the specific
15 "conv-mach-smp.h" file. Thus, this second file need to take care of the
16 definitions already made by the former one.
17
18 The decision whether to implement a fully new machine.c, or base to an already
19 existing one, should be made primarly on who will start the job in the target
20 machine. For example the program directly (charmrun in net- versions), mpirun in
21 mpi- versions, qsub, psub of any other scheduler. In particular, if it is
22 required that the program itself starts the job, then net- version is a good
23 option.
24
25 The files contain the following information:
26
27 * conv-mach.sh
28
29         contains the definitions of the compailers available in the building
30 system, and the additional flags and options to pass to the commands. This file
31 is read by the buils shell script.
32
33
34 * conv-common.h
35
36         contains the common definitions of the architecture, specified as
37 "define". The main options are described in the template. This file will be
38 included into the code by conv-config.h which is itself included into converse.h
39 (together with conv-mach.h and the other generated configurations).
40
41
42 * conv-mach.h
43
44         this file is similar to conv-common.h as structure, but it allows to
45 specify subarchitectures (like 'gm' in "./build charm++ net-linux gm"). In this
46 way, a single conv-common.h will contain the common definitions for all the
47 architectures, a single machine.c will contain the common code, and the flags in
48 this file can select the code to be compiled.
49
50
51 * machine.c
52
53         this file contains the implementation of the architecture in its
54 totality, meaning that subarchitectures (specified with "conv-mach-option.h"
55 files) will all link to this file, and it will need to have switches to
56 selectively compile the code. These are tipically in the form of:
57  "#if CMK_OPTION_IN_CONV_MACH_H". the template file contains the description of
58 the methods that should be implemented, also considering the values set into the
59 two header files (conv-common/conv-mach).
60
61
62 Other three files are needed during the charm build: conv-mach-pre.h,
63 conv-mach-opt.h and conv-mach-opt.sh which are automatically generated by the
64 build script with the properties retrieved from the system and the compile time
65 options specified.
66
67
68 *** A more detailed description on which files are linked into charm. ***
69
70 When charm builds, the tmp directory is created and all source files are linked
71 inside it. Regarding the arch files, only two directories are linked: the base
72 directory and the architecture directory. With an example, if compiling
73 "net-linux", the base directory will be "net" and the architecture directory
74 "net-linux". This implies that the machine.c file present in the "net" directory
75 will be linked (together will all the conv-mach* files and conv-common.h), but
76 those present in "net-linux" will eventually overwrite them.