Introduction to Mash hacking in OTcl
------------------------------------
by José María González


Mash is written in two different languages, C++ and
OTcl (an object-oriented tcl flavor). Developers may 
want to make changes in both worlds, and the method to
test changes is different:

If you make some changes in the C++ sources, the only
way to try them is recompiling the full mash script.

If you want to make changes in the otcl basis, there
are two options.

a) The first one consists of making your changes
directly on the full vic script (mash/bin/vic).

The vic script is just a huge otcl file. It is
built by gathering the "source" otcl files (stored
at mash/tcl). The process is called expansion, and
is carried out when, after making mash, you type
"make vic" (or "make tools").

There's a expand tool ("tcl-expand.tcl") that
gets a file (mash/tcl/vic/main.tcl in the vic case)
and substitutes all the "import XXX" commands with
the otcl file where the XXX object is defined. This
process is recursive (the new otcl files may have
their own "import YYY" commands). Just in case
you're curious, tcl-expand.tcl knows which otcl
file XXX refers to by checking the mash/importTable
file.

So the mash/bin/vic script is produced by getting
all the source otcl files vic needs and getting rid
of the comments.

If you choose to make changes this way, modify the
mash/bin/vic script. To test your changes, open
mash.exe and type the following in the console:

% cd mash/bin
% set argc 2; set argv 224.4.4.4/4444
% source vic

b) The alternative is modyfing the sources themselves
(mash/tcl). Change whatever you want in that directory.
To test your changes, there are two options:

b.1) rebuild the mash script. Go to the mash directory
and then make vic ("make vic" is the command in any
Unix flavor. I'm sure there's something similar in
Windows).

Note: If you have created any new object in a new
file, you need remake the import table first ("make
import" in Unix).

You can try the new vic script as we discussed
before.

b.2) try mash autoexpand capabilities. When the mash
binary finds an "import XXX" command, it tries to do
the same substitution than the tcl-expand.tcl script
(this works at least in Unix). You could try your
changes as follows:

- click on mash.exe

% cd mash/tcl/vic
% set argc 2; set argv 224.4.4.4/4444
% source vic

And that's it.

The first solution is the best if you just want to
play a little with mash (add labels to know what's
happening, redefining your own scripts, etc.). The
changes are never "committed", and if you make the
tool again, they will be lost (the script will be
overwritten).

Changes using the second method will stay forever,
but won't surface just by clicking on vic. You have
to rebuild the vic script for that.