home *** CD-ROM | disk | FTP | other *** search
/ Complete Linux / Complete Linux.iso / docs / devel / modula_2 / ipdm2s.man < prev    next >
Encoding:
Text File  |  1994-05-20  |  31.6 KB  |  711 lines
  1.  
  2. +------------------------------------------------------------------------------+
  3. |                                                                              |
  4. |                                                                              |
  5. |                  M o d u l a - 2 *   Programming Environment                 |
  6. |                                                                              |
  7. |                                  created by                                  |
  8. |                                                                              |
  9. |            Thomas Gauweiler,  Stefan U. Haenssgen,  Ernst A. Heinz           |
  10. |              Paul Lukowicz,  Hendrik Mager,  Michael Philippsen              |
  11. |                                                                              |
  12. |                            email:  msc@ira.uka.de                            |
  13. |                                                                              |
  14. |                                                                              |
  15. |                    registration email:  ipdm2s@ira.uka.de                    |
  16. |                                                                              |
  17. |                                                                              |
  18. |         Institute for Program Structures and Data Organization (IPD)         |
  19. |                           Department of Informatics                          |
  20. |                            University of Karlsruhe                           |
  21. |                                 F.R. Germany                                 |
  22. |                                                                              |
  23. |                                April 10, 1994                                |
  24. |                                                                              |
  25. |                                                                              |
  26. +------------------------------------------------------------------------------+
  27.  
  28. +------------------------------------------------------------------------------+
  29. |                                                                              |
  30. |                                                                              |
  31. |                  IPD  Modula-2*  Non - commercial  License                   |
  32. |                                                                              |
  33. |  IPD Modula-2* is distributed by the Institute for Program Structures and    |
  34. |  Data Organization (hereafter called "IPD") from the Dept. of Informatics    |
  35. |  at the University of Karlsruhe, a public institution in the German federal  |
  36. |  state of Baden-Wuerttemberg. IPD hereby grants to you a non-transferable,   |
  37. |  non-exclusive, royalty free worldwide license to use, copy, modify,         |
  38. |  prepare integrated and derivative works of, and distribute IPD Modula-2*    |
  39. |  for non-commercial purposes, subject to your agreement to the following     |
  40. |  terms and conditions:                                                       |
  41. |                                                                              |
  42. |   - The IPD Modula-2* Non-commercial License shall be included in the code   |
  43. |     and must be retained in all copies of IPD Modula-2* (full or partial;    |
  44. |     original, modified, derivative, or otherwise).                           |
  45. |                                                                              |
  46. |   - You acquire no ownership right, title, or interest in IPD Modula-2*      |
  47. |    except as provided herein.                                                |
  48. |                                                                              |
  49. |   - You agree to make available to IPD all improvements, enhancements,       |
  50. |     extensions, and modifications to IPD Modula-2* which are made by you or  |
  51. |     your sublicensees and distributed to others and hereby grant to IPD an   |
  52. |     irrevocable, fully paid, worldwide, and non-exclusive license under      |
  53. |     your intellectual property rights, including patent and copyright, to    |
  54. |     use and sublicense, without limititation, these modifications.           |
  55. |                                                                              |
  56. |   - IPD Modula-2* is a research work which is provided ``as is''. IPD and    |
  57. |     its contributors herewith disclaim all warranties with regard to this    |
  58. |     software, including all implied warranties of merchantability and        |
  59. |     fitness of purpose. In no event shall IPD or any of its contributors be  |
  60. |     liable for any special, direct, indirect, or consequential damages or    |
  61. |     any damages whatsoever resulting from loss of use, data, or profits,     |
  62. |     whether in an action of contract, negligence, or other tortious action,  |
  63. |     arising out of or in connection with the use or performance of this      |
  64. |     software.                                                                |
  65. |                                                                              |
  66. |                                                                              |
  67. +------------------------------------------------------------------------------+
  68.  
  69.  
  70.  
  71. +------------------------------------------------------------------------------+
  72. |                                                                              |
  73. |                                                                              |
  74. |                    I P D   M o d u l a - 2 *   M a n u a l                   |
  75. |                                                                              |
  76. |                          Part I  ---  General Topics                         |
  77. |                                                                              |
  78. |                                                                              |
  79. |                           written by Ernst A. Heinz                          |
  80. |                                                                              |
  81. |                                                                              |
  82. +------------------------------------------------------------------------------+
  83.  
  84.  
  85. +---------+
  86. | Credits |
  87. +---------+
  88.  
  89. The Modula-2* environment was developed at the Institute for Program Structures
  90. and Data Organization (IPD), Department of Informatics, University of Karlsruhe,
  91. F.R. Germany. During the long time of its creation the IPD Modula-2* system
  92. engaged many people as the following list of kernel contributors demonstrates:
  93.  
  94.  - Thomas Gauweiler     (distribution, documentation, msmfg, test suite)
  95.  - Stefan U. Haenssgen  (debugger, msXDW, xmsp)
  96.  - Ernst A. Heinz       (compiler, demos, documentation, drivers, libraries)
  97.  - Paul Lukowicz        (compiler, demos)
  98.  - Hendrik Mager        (semantic analysis)
  99.  - Michael Philippsen   (benchmarks, compiler, test suite)
  100.  
  101. We thank Walter F. Tichy and Christian G. Herter for their initial definition
  102. of the Modula-2* language extensions.
  103.  
  104. Furthermore, Juergen Fritsch deserves due credits for his corrections and
  105. extensions of the Modula-2* parallel libraries "msEnum", "msReduce", and
  106. "msScan" --- thank you, Juergen!
  107.  
  108.  
  109. +---------------+
  110. | Functionality |
  111. +---------------+
  112.  
  113. We have experienced our Modula-2* system to be a very useful tool for research,
  114. education, and even large scale program development.
  115.  
  116. The outstanding advantages of the IPD Modula-2* system follow from its unique
  117. support of explicitly parallel high-level language constructs on a variety of
  118. parallel and sequential machines. This and the fact that it does not cost
  119. anything if solely used for research and/or educational purposes, make our
  120. Modula-2* system an attractive and valuable platform for classes and courses in
  121. parallel programming. The Modula-2* parallel libraries "msEnum", "msReduce", and
  122. "msScan", included in the system with complete source codes, surely add to this
  123. attraction. These libraries efficiently implement various primitive parallel
  124. operations like reductions and scans for one-dimensional arrays.
  125.  
  126. But the IPD Modula-2* system is  n o t  only directed towards parallel
  127. programming. Beside its explicitly parallel features, it is a complete
  128. sequential Modula-2 programming environment offering:
  129.  
  130.  - an optimizing compiler translating Modula-2 source programs to portable C,
  131.  - transparent interfacing and full integration of foreign modules written in C,
  132.  - a sophisticated cross-architecture make facility generating standard Unix
  133.    makefiles that trigger the separate compilation of Modula-2 and generated or
  134.    foreign C modules (including automatic re-compilation whenever necessary),
  135.  - X Windows and Emacs development support,
  136.  - and some basic libraries (e.g. "msFIO", "msIO", "msMath", and "msTimer").
  137.  
  138. Although the translation to C causes some complications and disadvantages,
  139. mainly the missing option of runtime range and index checking, we are still
  140. convinced that its gains clearly outnumber the associated problems. The central
  141. arguments for C as an "intermediate" language are availability, portability, and
  142. resulting native code quality. Furthermore, many real parallel computer systems
  143. do not even support lower-level languages than C which was quite important for
  144. our Modula-2* effort.
  145.  
  146. The biggest drawback of the IPD Modula-2* system is the lack of good and
  147. consistent symbolic debugging support in terms of the language. Naturally, you
  148. can always use your favourite C debugger to investigate the generated C codes.
  149. Beside "debugging by value printing" this is what we usually do. It actually
  150. works fine because the generated C programs resemble the Modula-2 originals very
  151. closely as for structure, readability, and identifiers. But the scheme is far
  152. from satisfactory, of course!
  153.  
  154.  
  155. +--------------+
  156. | Availability |
  157. +--------------+
  158.  
  159. The IPD Modula-2* system is available for 386/486/Pentium PCs running Linux,
  160. R3000/R4000 DECStations running Ultrix, SPARC Sun-4s or SparcStations running
  161. SunOS, 680x0 Sun-3s running SunOS, and MasPar MP-1/MP-2 massively parallel
  162. systems with DECStation frontends running MP-Ultrix.
  163.  
  164. In addition to the above platforms on which the IPD Modula-2* environment
  165. actually runs, it is able to generate code for 386/486/Pentium PCs running
  166. BSDI/386 Unix and Kendall Square Research KSR-1/KSR-2 parallel systems
  167. running KSR-OS. Program development for these target machines is supported
  168. by an easy-to-use and fully automatic cross-architecture make facility.
  169.  
  170. The following table lists all the machines and their symbolic architecture
  171. names currently supported by the IPD Modula-2* system.
  172.  
  173. I386  =  386/486/Pentium PC running BSDI/386 Unix (sequential)
  174. KSRP  =  Kendall Square Research KSR-1/KSR-2 running KSR-OS (parallel)
  175. KSRS  =  Kendall Square Research KSR-1/KSR-2 running KSR-OS (sequential)
  176. LINX  =  386/486/Pentium PC running Linux (sequential)
  177. MASP  =  MasPar MP-1/MP-2 with DECStation frontend running MP-Ultrix (parallel)
  178. MIPS  =  R3000/R4000 DECStation running Ultrix (sequential)
  179. SUN3  =  680x0 Sun-3 running SunOS (sequential)
  180. SUN4  =  SPARC Sun-4/SparcStation running SunOS (sequential)
  181.  
  182.  
  183. +--------------+
  184. | Distribution |
  185. +--------------+
  186.  
  187. You can get the IPD Modula-2* distributions for all supported architectures by
  188. anonymous ftp from "ftp.ira.uka.de" [129.13.10.90] in the directory
  189. "pub/programming/modula2star". Please do not forget to use binary mode when
  190. retrieving any of them! Their names and functionalities are listed below.
  191.  
  192.  - "ipdm2s-install"               (installation script)
  193.  - "ipdm2s.doc.tar"               (documentation archive)
  194.  - "ipdm2s.<VERSION>.<ARCH>.tgz"  (distribution archives)
  195.  
  196. The IPD Modula-2* distribution contains only binaries. Unfortunately, we cannot
  197. make the sources of our system publicly available. (:-Considering the state of
  198. our sources and the many hacks contained therein, this seems to be a wise scheme
  199. anyhow ...-:) The documentation archive features abundant gzip'ed documentation
  200. (well, at least sort of) and comes in "tar" format. The distribution archives
  201. are in gzip'ed "tar" format and consist of:
  202.  
  203.  - compiler "msc",
  204.  - symbolic source-level debugger prototype "msdb" (available for SUN4 only),
  205.  - makefile generator "msmfg",
  206.  - main cross-architecture make facilty driver "mm",
  207.  - several useful command scripts (e.g. "mmclean", "msdel", "msrun", "msproj"),
  208.  - graphical X Windows environment panel "xmsp",
  209.  - Emacs elisp-mode "m2s.el" for Modula-2*,
  210.  - parallel libraries "msEnum", "msReduce", and "msScan",
  211.  - some basic libraries (e.g. "msFIO", "msIO", "msMath", "msTimer"), and
  212.  - collected Modula-2* example programs.
  213.  
  214.  
  215. +--------------+
  216. | Registration |
  217. +--------------+
  218.  
  219. Although IPD Modula-2* does not cost anything if solely used for research and/or
  220. educational purposes, we ask you to send a registration email to our electronic
  221. registration secretary "ipdm2s@ira.uka.de". Please clearly state your name and
  222. current affiliation as well as all archives you retrieved, installed, and intend
  223. to use. Thank you very much for your co-operation in advance!
  224.  
  225. Keeping such a registration database is advantageous for both you and us. In
  226. case of bug fixes and updates, we can directly inform each registered user. As
  227. for funding the future of IPD Modula-2*, evidence of a world-wide user base may
  228. decide between "life and death".
  229.  
  230. For further information and bug reports please contact the IPD Modula-2* team
  231. at "msc@ira.uka.de".
  232.  
  233.  
  234. +---------------------+
  235. | Language Extensions |
  236. +---------------------+
  237.  
  238. The programming language Modula-2* was developed to support high-level and
  239. machine-independent parallel programming. As described in [1], it embodies the
  240. following features:
  241.  
  242.  - An arbitrary number of processes operate on data in the same  s i n g l e 
  243.    address space. Note that shared memory is not required. The single address
  244.    space merely permits all memory to be addressed uniformly but not necessarily
  245.    at uniform speed.
  246.  
  247.  - Synchronous and asynchronous parallel computations as well as arbitrary
  248.    nestings thereof can be formulated in a totally machine-independent way.
  249.  
  250.  - Procedures may be called in any context, sequential or parallel, and at any
  251.    nesting depth. Additional parallel computations can be spawned inside
  252.    procedures (recursive parallelism).
  253.  
  254.  - All abstraction mechanisms of Modula-2 are available for parallel programs.
  255.  
  256. Despite its many achievements, Modula-2* extends Modula-2 with just two new
  257. language constructs of simple and compact nature:
  258.  
  259. 1.  The distribution of array data may optionally be specified by so-called
  260.     a l l o c a t o r s.  These are machine-independent layout hints for the
  261.     compiler without any semantic meaning.
  262.  
  263.       Allocator ::= LOCAL | SPREAD | CYCLE | SBLOCK | CBLOCK .
  264.  
  265.       ArrayType ::= ARRAY <SimpleType> [<Allocator>]
  266.                           {"," <SimpleType> [<Allocator>]} OF <Type> .
  267.  
  268.     Date arrays will only be physically distributed over the available processor
  269.     memories if any of their dimensions are decorated with allocators other than
  270.     LOCAL. If no allocator is specified at all it defaults to LOCAL. Therefore,
  271.     the below declarations of B and C are effectively equivalent.
  272.  
  273.     VAR  A: ARRAY[1..n] SPREAD OF INTEGER;
  274.          B: ARRAY[1..n], [1..n] OF INTEGER;
  275.          C: ARRAY[1..n] LOCAL, [1..n] LOCAL OF INTEGER;
  276.          D: ARRAY[1..n] SBLOCK, [1..n] SBLOCK OF INTEGER;
  277.  
  278. 2.  To support explicitly parallel computations, Modula-2* introduces the
  279.     F O R A L L  statement in a synchronous and an asynchronous version.
  280.  
  281.       ForallStatement ::= FORALL <Ident> ":" <SimpleType> IN (PARALLEL | SYNC)
  282.                           [  <VariableDeclaration>
  283.                           BEGIN      ]
  284.                             <StatementSequence>
  285.                           END .
  286.  
  287.     Here, <SimpleType> denotes an enumeration or a possibly non-static subrange,
  288.     i.e. the boundary expressions may contain variables. The FORALL creates as
  289.     many (conceptual) processes as there are elements in <SimpleType>. The
  290.     identifier introduced by the FORALL statement is local to it and serves as a
  291.     runtime constant for every created process. The runtime constant of each
  292.     process is initialized to a unique value of <SimpleType>.
  293.        All processes created by a FORALL obtain private instances of variables
  294.     declared in the optional <VariableDeclaration> part. Then they execute the
  295.     statements in <StatementSequence>. The END of a FORALL imposes a synchroni-
  296.     zation barrier on the participating processes; termination of the whole
  297.     FORALL is delayed until all created processes have finished their execution
  298.     of <StatementSequence>.
  299.        The processes of a synchronous FORALL execute <StatementSequence> in
  300.     lock-step, while they run concurrently in the asynchronous case. Hence, for
  301.     non-overlapping vectors X, Y, Z an asynchronous FORALL statement suffices to
  302.     implement the vector addition X=Y+Z.
  303.  
  304.     FORALL i: [1..n] IN PARALLEL
  305.       Z[i] := X[i] + Y[i];
  306.     END;
  307.  
  308.     In contrast to the above, parallel modifications of overlapping data
  309.     structures may require synchronization. Here, synchronous FORALLs even allow
  310.     for easy formulation of arbitrary irregular data permutations.
  311.  
  312.     FORALL i: [1..n] IN SYNC
  313.       X[i] := X[p(i)];
  314.     END;
  315.  
  316.     The above synchronous FORALL permutes vector X according to permutation
  317.     function p(). The synchronous semantics ensure that all RHS elements X[p(i)]
  318.     are read and temporarily stored before any LHS variable X[i] is written.
  319.        The behaviour of branches and loops inside synchronous FORALLs is defined
  320.     with a MSIMD (multiple SIMD) machine in mind. Consequently, Modula-2* does
  321.     not require any synchronization between different branches of synchronous
  322.     CASE or IF statements. The exact synchronous semantics of all Modula-2*
  323.     statements, including nested FORALLs, and the effects of allocator
  324.     declarations are described in [2] and [3].
  325.        To illustrate the syntax and semantics of private variable declarations
  326.     inside FORALLs we close this section with an example of a naively parallel
  327.     matrix multiply combined with a matrix transposition that computes the
  328.     resulting matrix C according to C=trans(A*B).
  329.  
  330.     FORALL i: [1..n] IN PARALLEL
  331.       FORALL j: [1..n] IN PARALLEL
  332.         VAR Cij, k: INTEGER;
  333.       BEGIN
  334.         Cij := 0;
  335.         FOR k:=1 TO n DO            (* calculate vector product of i-th row   *)
  336.           INC(Cij, A[i,k]*B[k,j]);  (* of A and j-th column of B in local Cij *)
  337.         END;
  338.         C[j,i] := Cij;              (* transposition by storing Cij in C[j,i] *)
  339.       END;
  340.     END;
  341.  
  342.  
  343. +------------+
  344. | Literature |
  345. +------------+
  346.  
  347. [1]  S.U. Haenssgen, E.A. Heinz, P. Lukowicz, M. Philippsen, and W.F. Tichy.
  348.      "The Modula-2* environment for parallel programming."
  349.      In Proceedings of the Working Conference on Programming Models for
  350.      Massively Parallel Computers, Berlin, Germany, September 20-22, 1993.
  351.      (available by anonymous ftp from i41s10.ira.uka.de [129.13.13.110]
  352.       in directory "pub/m2s" as "pmmp93.ps", "pmmp93.ps.gz", or "pmmp93.ps.Z")
  353.  
  354. [2]  W.F. Tichy and C.G. Herter.
  355.      "Modula-2*: An extension of Modula-2 for highly parallel,
  356.       portable programs."
  357.      Technical Report No. 4/90, Department of Informatics,
  358.      University of Karlsruhe, January 1990.
  359.      (available by anonymous ftp from i41s10.ira.uka.de [129.13.13.110]
  360.       in directory "pub/m2s" as "m2s90.ps", "m2s90.ps.gz", or "m2s90.ps.Z")
  361.  
  362. [3]  J.R. Smith.
  363.      "The design and analysis of parallel algorithms.
  364.       Chapter 3: Modula-2*."
  365.      Oxford University Press, December 1992.
  366.  
  367. [4]  M. Philippsen, E.A. Heinz, and P. Lukowicz.
  368.      "Compiling machine-independent parallel programs."
  369.      ACM SIGPLAN Notices, Volume 28, No. 8, pages 99-108, August 1993.
  370.  
  371. [5]  M. Philippsen, T.M. Warschko, W.F. Tichy, C.G. Herter, E.A. Heinz,
  372.      and P. Lukowicz.
  373.      "Project Triton: Towards improved programmability of parallel computers."
  374.      In D.J. Lija and P.L. Bird (editors), The Interaction of Compilation
  375.      Technology and Computer Architecture, Kluwer Academic Publishers, 1994.
  376.  
  377.  
  378.  
  379. +------------------------------------------------------------------------------+
  380. |                                                                              |
  381. |                                                                              |
  382. |                    I P D   M o d u l a - 2 *   M a n u a l                   |
  383. |                                                                              |
  384. |                       Part II  ---  Using the Software                       |
  385. |                                                                              |
  386. |                                                                              |
  387. |                          written by Thomas Gauweiler                         |
  388. |                                                                              |
  389. |                                                                              |
  390. +------------------------------------------------------------------------------+
  391.  
  392.  
  393. +--------------+
  394. | Installation |
  395. +--------------+
  396.  
  397. You get the package with two files: a tar file and the script ipdm2s-install
  398. 1) use ipdm2s-install with two arguments:
  399.    1st: the architecture (eg.SUN4, MIPS)
  400.    2nd: the directory where msc should be installed, further called <MSC_HOME>
  401.    ipdm2s-install untars the files and generates several files and scripts.
  402.  
  403. 2) edit the file "architectures" for your system (see below).
  404.  
  405. 3) if you want cross compilation, make sure that rlogin doesn't require
  406.    the password. Otherwise rsh breaks with "Permission denied".
  407.  
  408. 4) every user has to extend his paths with <MSC_HOME>/bin
  409.  
  410.  
  411. +---------------+
  412. | File Concepts |
  413. +---------------+
  414.  
  415. The programs "msc" and "msmfg" assume a fixed pre-defined directory structure.
  416. You can use msproj with the argument for the target architecture to create
  417. this structure.
  418.  
  419. The suffix of definition modules is .msd and the files are in the directory ./msd.
  420. The suffix of the main module is .msm, found in ./msm and the suffix of the
  421. implementation modules is .msi, you can find them in ./msi.
  422.  
  423. ./msd and ./msi contain machine independent files. The following files
  424. depend on the used machine, therefore they are stored in different architecture
  425. directories.
  426.  
  427. After compiling using the script mm you find the generated definitions
  428. (*.h) in ./sym/<ARCH>, the generated implementations (*.c) in ./imp/<ARCH>,
  429. the (by the c-compiler) generated objects (*.o) in ./obj/<ARCH> and last
  430. but not least the linked binaries in ./bin/<ARCH>.
  431. The generated makefile is in ./mkf/<ARCH>.
  432.  
  433. At this time there are the following architectures available:
  434. for sequential: SUN3 for Sun 680x0, SUN4 for Sparc, I386 for BSD386, 
  435.             LINX for 386/486/Pentium PC running Linux,
  436.                 MIPS for DECstation, KSRS for KSR sequential
  437. real parallel:  MASP for Maspar, KSRP for KSR parallel.
  438.  
  439. The msc compiler binary is available for
  440. SUN4 for Sparc, MIPS for DECstation, LINX for Linux
  441.  
  442.  
  443. +---------------------+
  444. | Compiling and so on |
  445. +---------------------+
  446.  
  447. 1)  create a working directory.
  448. 2)  type msproj <ARCH> (ex. msproj SUN4) to create the directory structure.
  449. 3)  Copy your Modula-2* sources to ./msd and ./msi, foreign modules (.c)
  450.     to ./imp/<ARCH>, their headers (.h) to ./sym/<ARCH>
  451. 4)  if you don't use Xwindows:
  452. 4a) Compile on your own machine for its architecture:
  453.     type <MSC_HOME>/mm <main_module_name>
  454. 4b) If you want cross compiling for architecture <ARCH>:
  455.     type <MSC_HOME>/mm <main_module_name>:<ARCH>
  456. 4c) If you want cross compiling on machine <MACH> for your own architecture
  457.     type <MSC_HOME>/mm <main_module_name>@<MACH>
  458. 4d) If you want cross compiling on machine <MACH> for architecture <ARCH>
  459.     type <MSC_HOME>/mm <main_module_name>@<MACH>:<ARCH> or
  460.     type <MSC_HOME>/mm <main_module_name>:<ARCH>@<MACH>
  461. 4)  if you use XWindows type xmsp for a panel, it calls mm.
  462. "mm" looks on what architecture you are, determine several parameters for "msmfg"
  463. and invokes it.
  464. "msmfg" parses your sources, looks for their dependencies and generates a makefile
  465. "mm" invokes "make" for compiling.
  466.  
  467. If you give "mm" more than one parameter, "mm" passes them as additional parameters
  468. to "msmfg". Therefore there is no blank between <Module_Name> and :<ARCH> or
  469. @<MACH> !
  470.  
  471.  
  472. +---------+
  473. | Options |
  474. +---------+
  475.  
  476. a) common options for "msmfg" and "msc"
  477. -target_arch <Arch>     set the architecture for generated code
  478. -verbose                verbose - control messages
  479. -help                   help
  480. -path                   add new paths
  481. -noproject              the project dir structure is not used
  482. -tab                    set the path for syntax tables
  483.             only for msc developers
  484. -silent                 nearly no output is generated
  485. -msm, -msd, -msi, -sym, set the file extensions for different compiler phases
  486. -imp, -obj              (defaults: .msm, .msd, .msi, .h, .c, .o)
  487.             set in the architecture file
  488.  
  489. b) options only for msmfg
  490. -source_arch <Arch>     necessary for finding the right msc-compiler
  491.             ($MSC_HOME/bin/$SOURCE_ARCH/msc.$SOURCE_ARCH)
  492. -system                 generate $SYSTEMMODULE.o etc.
  493.             only for msc developer
  494. -compiler <name>        set the value for $CC
  495. -linker <name>          set the value for $LN
  496. -machine <name>         set the value of machine name for rsh command
  497. -master_mkf <name>      for using another master makefile (default: master)
  498. -debug                  using debug mode (analog for '-master_mkf master.debug')
  499. -optimize               using optimize mode (analog '-master_mkf master.optimize')
  500. -profile                using profile mode (analog '-master_mkf master.profile')
  501. -oforc                  generates -o Option for cc *.c too
  502.             if not set then mv command will be generated
  503. -rlo                    remote link only
  504. -list            prints the import structure of your program
  505.  
  506. c) options only for msc
  507. be careful, they may be obsolete
  508. -c            generate type casts to make programs lint free
  509. -g1             generate GRL description of the dependence graph
  510.                 including only SYNC dependences
  511. -g2             generate GRL description of the dependence graph
  512.                 including pseudo and SYNC dependences
  513.                 (pseudo dependences are shown in dotted style)
  514. -g3             generate GRL description of the dependence graph
  515.                 including normalized and SYNC dependences
  516.                 (normalized dependences are shown in dashed style)
  517. -g4             generate GRL description of the dependence graph
  518.                 including normalized, pseudo, and SYNC dependences
  519.                 (normalized dependences are shown in dashed style,
  520.                 pseudo dependences are shown in dotted style)
  521. -h              print help information
  522. -i              generate header files for imported modules
  523. -ldir             specify directory where msc finds its tables
  524. -m              print test output (memory)
  525. -P              specify number of PEs to generate code for
  526. -r              generate runtime checks
  527. -s              print test output (dependence analysis statistics)
  528. -s1             print test output (SYNC dependences)
  529. -s2             print test output (pseudo dependences)
  530. -s0             no sync point optimization
  531. -q              quiet - don't print the header
  532. -t              print test output (time)
  533. -w              suppress warning diagnostics
  534. -z              do not perform subscript analysis
  535. -_              try to generate code in spite of errors (no direct exit)
  536.  
  537.  
  538.  
  539. +---------+
  540. | Scripts |
  541. +---------+
  542.  
  543. all script work with the schema:
  544.         <script> <programname>[".msm"]":"<ARCH>"@"<MACHINE>
  545.  
  546. If there are others options behind the first one, these are passed through as
  547. parameters to the invoked programs.
  548.  
  549.  
  550. liball
  551. it generates a main module, which imports all DEFINITION MODULEs in the current
  552. directory.
  553.  
  554. msdel [<programname>]":"<ARCH>
  555. msrm [<programname>]":"<ARCH>
  556. these scripts delete the files in ./sym/ARCH, ./imp/ARCH, ./obj/ARCH, ./bin/ARCH
  557. msdir use rm in interactive mode. This is essential if you have c-sources
  558. for foreign modules in ./imp/ARCH
  559.  
  560.  
  561. msproj <ARCH>
  562. creates a directory structure for your project in your current directory. It moves
  563. source files which already there to the several places.
  564.  
  565.  
  566. mm <programname>[".msm"][":"[<ARCH>]]["@"[<MACHINE>]]
  567. generates a new makefile with "msmfg" for the program and invokes "make" for
  568. (cross-)compiling and linking
  569.  
  570.  
  571. msclean <programname>[".msm"][":"[<ARCH>]]["@"[<MACHINE>]]
  572. removes all generated files (convex hull). It works similair to "mm", but invokes
  573. "make" for making target 'clean:'.
  574.  
  575. msrun <programname>[".msm"][":"[<ARCH>]]["@"[<MACHINE>]]
  576. executes your program. It's only necessary, if the program should run on 
  577. another machine.
  578.  
  579.  
  580. xmsp [<programname>[".msm"]][":"[<ARCH>]]["@"[<MACHINE>]]
  581. X-version for mm, with several features.
  582. It requires a proper searchpath in path variable of .cshrc. Please make sure
  583. that it includes <MSC_HOME>/bin
  584.  
  585.  
  586. +---------------+
  587. | Several Files |
  588. +---------------+
  589.  
  590. .mspath
  591. this file is searched in <PROJECTDIR>, ~<USER> and <MSC_HOME> (in this order). 
  592. It contains search paths which will be concatenated. Msmfg and Msc look for the 
  593. sources there.
  594.  
  595. architectures
  596. it stands in <MSC_HOME> and contains several options for msmfg, which
  597. depends on the used architecture
  598.  
  599. master.makefiles
  600. found in <MSC_HOME>/mkf/<ARCH>/. These files are the header of every generated
  601. makefile and contain several make variables, which only depend on the
  602. architecture but not the compiled program.
  603. There is also a special master makefile for debug, optimize and profile mode.
  604. The master makefile is searched on the paths. If you have a personal version
  605. in your project directory then this one is used.
  606.  
  607. Xmsp
  608. it includes informations for the panel.
  609.  
  610.  
  611. +--------------------------+
  612. | Adding New Architectures |
  613. +--------------------------+
  614.  
  615. a) use the script newarch. It transforms the foreign library modules.
  616. b) correct the new entry in architectures, especially the new machine name
  617. c) change the options for the c compiler of the target architecture in the
  618.    files <MSC_HOME>/mkf/<NEW_ARCH>/master*
  619. d) try to compile the library with
  620.    cd <MSC_HOME>/lib; mm alllib:<NEW_ARCH> -system
  621.  
  622.  
  623. +------------------+
  624. | Network Problems |
  625. +------------------+
  626.  
  627. Depending on the administration of the network, there may be some trouble with
  628. mounting. Normally paths like /home/<MACHINE>/<USER> should work, but pwd
  629. returns extended paths with some stuff like tmp_mnt/ or anything else before the
  630. common path. Therefore these paths have to be converted by sed. You find the
  631. essential command in the variable "MM_SED" in ipdm2s-install. If you have
  632. already installed the package then change the variable in script mm.
  633.  
  634.  
  635. +------------+
  636. | Known Bugs |
  637. +------------+
  638.  
  639. msc:
  640. - VAR parameters in procedures are handled as call by value/result (sometimes
  641.   named as copy in / copy out semantic) not as call by reference.
  642. - The with statement doesn't work with forall loops.
  643. - Importing only module names may cause msc hanging on an endless loop with
  644.   printing  'Error'.
  645.   To avoid this, you have to import the identifier explicitly with the 'FROM'
  646.   statement, even if you don't use unqualified the identifier.
  647.  
  648. msmfg:
  649. - if you crosscompile, sometimes your program isn't link by make in the first
  650.   time. In this case, just repeat your command.
  651.   The reason are delays in the NFS.
  652.  
  653. libraries:
  654. - msFIO for I386:
  655.   breaks with segmentation fault in Close
  656. - msMath:
  657.   some funktions are not available on all architectures
  658. - msMath for MIPS:
  659.   log2, exp10, exp2 return wrong values
  660.  
  661.  
  662. +----------+
  663. | Appendix |
  664. +----------+
  665.  
  666. Module msEnum
  667. -------------
  668.   allows for efficient enumeration operations
  669.   on arbitrarily large and distributed arrays.
  670.   especially used for parallel extensions.
  671.  
  672. Module msFIO
  673. ------------
  674.   use it for file access
  675.  
  676. Module msIO
  677. -----------
  678.   all output goes to "stdout", all input comes from "stdin"
  679.  
  680. Module msMath
  681. -------------
  682.   some math stuff, uses the standard mathlib
  683.  
  684.  
  685. Module msRandom
  686. ---------------
  687.  
  688.  
  689. Module msReduce
  690. ---------------
  691.   allows for efficient reduction operations on
  692.   arbitrarily large and distributed arrays
  693.   especially used for parallel extensions.
  694.  
  695.  
  696. Module msScan
  697. -------------
  698.   allows for efficient scan operations on
  699.   arbitrarily large and distributed arrays
  700.   especially used for parallel extensions.
  701.  
  702.  
  703. Module msTimer
  704. --------------
  705.   for measuring time
  706.  
  707.  
  708. Module msXDW
  709. ------------
  710.   an interface to X-Windows
  711.