Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		 Previous revision
Next revisionBoth sides next revision
internal:abi [2016/10/30 17:37] – created temainternal:abi [2016/11/14 14:48] – sbs
Line 2: Line 2:
  
 ===== Concept separation ===== ===== Concept separation =====
 +''TODO(aretm,30/10/2016) CHECK THAT THIS PAGE MATCHES THE IMPLEMENTATION!''
  
 ==== First level ==== ==== First level ====
Line 51: Line 52:
   * on SBIs without the PHM API, both ''libphm.a'', ''libphm.compat.a'' and ''libphm.diag.a'' are empty libraries.   * on SBIs without the PHM API, both ''libphm.a'', ''libphm.compat.a'' and ''libphm.diag.a'' are empty libraries.
   * on SBIs with the PHM API, ''libphm.a'' and ''libphm.diag.a'' contain the PHM, and ''libphm.compat.a'' contains the malloc wrappers.   * on SBIs with the PHM API, ''libphm.a'' and ''libphm.diag.a'' contain the PHM, and ''libphm.compat.a'' contains the malloc wrappers.
 +
 +
 +===== Naming =====
 +
 +On one filesystem root, there may be one or more host environments (multiple binary installs of the same version of sac2c). So we identify the host environment like everyone else does, using a canonical specifier string.
 +
 +We can have multiple versions.
 +
 +So we adopt the naming scheme used by ''gcc'' and everyone else:
 +<code>
 +$prefix
 +    `--- bin
 +    |     `------ sac2c-VERSION
 +    `--- share
 +    |        `------ doc
 +    |        |        `---- sac2c
 +    |        `------ man
 +    |        |        `---- man1
 +    |        |                `----- sac2c.1
 +    |        `------ sac2c
 +    |                 `---- VERSION1
 +    |                 |        `---- sac2crc
 +    |                 `---- VERSION2
 +    |                 |        `---- sac2crc
 +    |                 `---- ...
 +    `--- lib / sac2c / VERSION / modlibs
 +    |        `------ target-env1
 +    |        |           `--------- sbi1 (eg "mt-rc1")
 +    |        |           `--------- ...
 +    |        |           `--------- sbi2 (eg "mt-rc2")
 +    |        |           |            `--------- libScalarArithMod.a
 +    |        |           |            `--------- libScalarArithMod-bigcaches.a
 +    |        |           |            `--------- libScalarArithMod-specx1000.a
 +    |        |           |            `--------- libScalarArithMod-variant1.a
 +    |        |           |            `--------- libScalarArithMod-variant2.a
 +    |        |           |            `--------- libScalarArithMod-....a
 +    |        |           `--------- sbi3 (eg "cuda")
 +    |        |           |            `--------- libScalarArithMod.so
 +    |        |           `--------- sbi4 (eg "cuda+omp")
 +    |        |                        `--------- libScalarArithMod.so
 +    |        `------ target-env2
 +    |        `------ ...
 +    `--- lib / sac2c / VERSION / rt
 +    |        `------ target-env1
 +    |        |           `--------- sbi1 (eg "mt-rc1")
 +    |        |           |            `--------- libsac.a
 +    |        |           |            `--------- libphm.a
 +    |        |           |            `--------- libphm.diag.a
 +    |        |           |            `--------- libphm.compat.a
 +    |        |           `--------- sbi2 (eg "mt-rc2")
 +    |        |           |            `--------- libsac.a
 +    |        |           |            `--------- libphm.a
 +    |        |           |            `--------- libphm.diag.a
 +    |        |           |            `--------- libphm.compat.a
 +    |        |           `--------- ...
 +    |        `------ target-env2
 +    |        `------ ...
 +    |
 +    `--- libexec / sac2c / VERSION /
 +                    `----- sac2c
 +                    `----- sac2c-d
 +                    `----- sac2c-p
 +                    `----- tree
 +                             `--- target-env1
 +                             |      `----- libFibreIOTree.so
 +                             |      `----- ...
 +                             `--- target-env2
 +                                    `----- libFibreIOTree.so
 +                                    `----- ...
 +</code>
 +
 +==== Notes ====
 +
 +We want to support installing with ''--prefix=/usr/local'' (or maybe even ''--prefix=/usr'') which means all the SaC hierarchy will be overlapping with whatever other tools are already there. This is why it is important to add sub-directories ''share/doc/sac2c'', ''libexec/sac2c'', ''lib/sac2c'', and so on.
 +
 +
 +===== Search =====
 +
 +<callout>
 +=== Alert! ===
 +
 +Needs re-writing by Hans or Artem!
 +
 +</callout>
 +We distinguish between:
 +
 +  - //default// path(s): the directories populated during installation, which may be "system wide"
 +  - //custom// paths(s): the directories written to by ''sac2c'', which are likely not system wide (especially when the user does not have write permission to the installation directories)
 +
 +At invocation time, a search path must be decided:
 +
 +  - the search path starts with ''$prefix'' (the default path)
 +  - if a ''~/.sac2c'' file does not exist, then:
 +       - ''sac2c'' asks the user for a custom destination directory for generated files. If the user has no clue, the user is suggested to use the proposed path ''~/.sac'';
 +       - the decided path is written to ''~/.sac2c''.
 +  - ''~/.sac2c'' is loaded, and the path in there is added at the beginning of the search path.
 +  - If the user specifies (on the command line) an additional prefix, prepend that to the search path.
 +  - Prepend the directory of -o to the search path.
 +
 +At invocation time, a output path must be decided:
 +
 +  - if ''-o'' is specified, use that as output path.
 +  - if ''-o'' is not specified and -install is not specified, use ''.'' as output path.
 +  - if ''-install'' is specified, then...
 +  - the output path is initialized to ''$prefix'' (the default path)
 +  - if a ''~/.sac2c'' file does not exist, then:
 +      - ''sac2c'' asks the user for a custom destination directory for generated files. If the user has no clue, the user is suggested to use the proposed path ''~/.sac'';
 +      - the decided path is written to ''~/.sac2c''.
 +  - ''~/.sac2c'' is loaded, and the output path is set to the content of that file.
 +
 +==== Notes ====
 +
 +All this is for modules. If we encounter something that is not a module, then -install is not valid. Moreover, if ''-o'' is not specified the output file name defaults to ''./a.out'' if ''-o'' is specified, the output file name is set to that.
 +
 +
 +===== Configuration - sac2crc =====
 +
 +We want to reuse the existing "target" mechanism of the ''sac2crc'' parser, namely:
 +
 +  * inheritance
 +  * flexibility: letting each level override variables / append values to variables of levels inherited.
 +
 +==== To identify configuration sections for environment / SBI / variants ====
 +
 +
 +We do this by adding new resources:
 +
 +  * ''TARGET_ENV'' identifies the target environment;
 +  * ''SBI'' identifies the SBI;
 +
 +We also eliminate ''LIB_VARIANT''; it is obsoleted by the joint use of ''TARGET_ENV'' and ''SBI''.
 +
 +==== Structuring sac2crc ====
 +
 +The power of the target mechanism at the same time is its weakness. In order to avoid complete chaos we informally distinguish between 3 different types of targets:
 +
 +  - basic targets that define a combination of TARGET_ENV and basis-SBI. For example, we have:<code>
 +target default_sbi:
 +TARGET_ENV       :=  "host"
 +SBI              :=  "seq"
 +MT_MODE          :=  0
 +BACKEND          :=  "C99"
 +RC_METHOD        :=  "local"
 +...
 +
 +target default_mt :: default_sbi:
 +SBI              := "mt"
 +MT_MODE          :=  1
 +USE_PHM_API      :=  1
 +
 +target omp :: default_sbi:
 +SBI              := "omp"
 +BACKEND          := "omp"
 +MT_MODE          :=  2
 +MT_LIB           := "omp"
 +CFLAGS           += " "
 +LDFLAGS          += " "
 +</code>
 +  - modifier targets that define properties or variants that are mainly orthorgonal to the basic targets. These targets do not inherit from any basic targets. Examples are: <code>
 +target add_pth:
 +LIBS             +=  " -D_THREAD_SAFE -pthread "
 +CFLAGS           +=  " -D_THREAD_SAFE -pthread"
 +SBI              +=  "-pth"
 +MT_LIB           :=  "pthread"
 +
 +target add_lpel:
 +SBI              +=  "-lpel"
 +MT_LIB           :=  "lpel"
 +CFLAGS           +=  " "
 +LIBS             :=  "  -llpel "
 +RC_METHOD        :=  "local_pasync_norc_desc"
 +
 +
 +target add_rt:
 +SBI              +=  "-rtspec"
 +RTSPEC           :=  1
 +</code>
 +  - pre-defined final targets that are often-used combinations of one basic target with a set of modifier targets. These should be defined by means of inheritance only. Examples are: <code>
 +target seq :: default_sbi:
 +
 +target mt_pth :: default_mt :: add_pth:
 +
 +target mt_pth_rt :: mt_pth :: add_rt:
 +
 +target mt_lpel :: default_mt :: add_lpel:
 +</code>
 +
 +For better maintainability of the developer version, the monolithic ''sac2crc'' file is split up into several files that contain logically coherent sets of targets. All these can be found in the setup directory. They are being combined via autoconf/configure through the file ''sac2crc.pre.in'' in that very directory.