docs/running-ant.txt

   1 Running the ant tasks
   2 ============================================================
   3
   4 This project supplies an ant build file.
   5
   6 When used without parameters it will
   7 - build the main tool, mjc2wsl
   8 - compile all the given MicroJava samples in a temp folder
   9 - translated these to WSL
  10 - run a transformation script for all of these files
  11 (if FermaT is found)
  12
  13 There are other tasks available, as well as the option of
  14 doing some of the above taks on their own.
  15
  16 Many of these can be given parameters, such as
  17
  18   ant mjc2wsl -Dfilename=temp/Rek1.obj -Dmjc2wsl.options=-q
  19
  20 Alternatively parameters can be specified in a file named
  21 "custom.properties" in the root folder of the project (next
  22 to "build.xml").
  23
  24
  25 General tasks
  26 -------------
  27
  28 all - the default one.
  29
  30 init - sets everything up, makes the folders, copies the
  31 samples as needed. Used by most, just in case.
  32
  33 clean - will clean up everything in the temp dirs and
  34 the bin dires, as well as the logs.
  35
  36
  37 mjc2wsl tasks
  38 -------------
  39
  40 mjc2wsl - run the tool on a single file given in "filename".
  41 influenced by "mjc2wsl.options"
  42
  43 mjc2wsl - runs the tool on all obj files in "samples.temp.dir"
  44
  45
  46 MicroJava tasks
  47 ---------------
  48
  49 These tasks use "compiler.class.jar" to get the classes,
  50 but will also look first into "compiler.class.dir" if there
  51 is any override.
  52
  53
  54 mj-decode - decode the bytecode given in "filename" into
  55 operation names and parameteres (uses
  56 "compiler.classname.decoder")
  57
  58 mj-decode-samples - decode the samples in "samples.temp.dir"
  59 and save everything in a file called "decoded.txt" in the
  60 same dir.
  61
  62 mj-compile - compile a file given with "filename" (uses
  63 "compiler.classname.compiler")
  64
  65 mj-samples - compile all the samples in "samples.temp.dir"
  66
  67 mj-run - run with MJVM the obj file given in "filename",
  68 give it "inputstring" as the inputstring (uses
  69 "compiler.classname.interpreter")
  70
  71
  72 WSL tasks
  73 ---------
  74
  75 All of these are influenced by "fermat.dir" - it needs to
  76 be setup properly.
  77
  78 wsl-run - run the wsl file given in "filename",
  79 give it "inputstring" as the inputstring.
  80
  81 wsl-transf - run the wsl transformation script (given in
  82 "transf.wsl.file" on "transf.filename". the result file ends
  83 with "_t".
  84
  85 wsl-transf-samples - transform all the wsl file in the
  86 samples folder, except those ending in "_t" (should be
  87 transformations results from earlier).
  88
  89
  90 Testing tasks
  91 -------------
  92
  93 There are two sets of tasks for comparing outputs of
  94 different versions of programs.
  95
  96 The fist set compares the original MicroJava code compiled
  97 into bytecode with the version translated into WSL (using
  98 mjc2wsl). These are "test-all-m" and "test-fn-m".
  99
 100 The second set compared the translated WSL with the
 101 transformed version. These are "test-all-t" and "test-fn-t".
 102
 103 In either case, the two versions of the program are run with
 104 inputs from the "${tests.dir}", the outputs are recordered
 105 and automatically compared (using customized perl scripts in
 106 the first version). For a given ${file.name} of the program,
 107 it will be run with inputs from any files that match
 108 "${file.name}*.txt". If there are none, then the program
 109 will not be tested.
 110
 111 Obviously this could prove to be problematic if some
 112 programs have names that are longer versions of other
 113 program names (like "chars" and "chars-and-numbers", where
 114 any test for the later would be (wrongly!) ran for the
 115 former as well).
 116
 117
 118 Manual testing helper tasks
 119 ---------------------------
 120
 121 test-run - run sequentially the '.obj', '.wsl' and '_t.wsl'
 122 versions of the same program. given are "file.dir" and
 123 "file.name" without an extension.
 124
 125 test-run-samples-dir - same as above, presumes that
 126 "file.dir" is "samples.temp.dir".
 127
 128
 129 Metrics tasks
 130 -------------
 131
 132 these tasks generate comparison outputs for transformed
 133 versions of WSL programs in a CSV file using the custom
 134 metrics script given in the `src-wsl` directory.
 135
 136
 137 Visual comparison tasks
 138 -----------------------
 139
 140 currently there is a task that can generate LaTeX sources
 141 and compile them into a pdf showing in parralel how
 142 the program looks in MicroJava, bytecode, translated WSL
 143 and transformed WSL.
 144
 145
 146 Logging
 147 ------------------------------------------------------------
 148
 149 Calls to some of the bigger tasks are automatically logged
 150 in the "log.dir" directory.
 151
 152 mjc2wsl-samples is logged in "mjc2wsl-TIMESTAMP.txt". the
 153 last run is always copied to "mjc2wsl.txt" (property
 154 "log.file.mjc2wsl")
 155
 156 wsl-transf-samples is logged in
 157 "transformations-TIMESTAMP.txt". The last run is always
 158 copied to "transformations.txt" (property
 159 "log.file.transformations")
 160
 161 similarly the testing tasks are logged.