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 netlrts- versions),
  21 mpirun in mpi- versions, qsub, psub of any other scheduler. In particular, if it
  22 is required that the program itself starts the job, then netlrts- version is a
  23 good 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++ netlrts-linux gm"). In
  46 this 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 "netlrts-linux", the base directory will be "netlrts" and the architecture
  74 directory "netlrts-linux". This implies that the machine.c file present in the
  75 "netlrts" directory will be linked (together will all the conv-mach* files and
  76 conv-common.h), but those present in "netlrts-linux" will eventually overwrite
  77 them.