
Building AMPlay
~~~~~~~~~~~~~~~

AMPlay runs perfectly well as interpreted BASIC, with verbose source.
It just isn't as fast as it could be.

Speeding things up can be done in two ways;

- Crunching (Using StrongBS or similar)
- Compiling (Using ABC or similar)

Most development of it will presumably take place with the interpreted
verbose source, because it's easy to tinker with. Neither the crunched
or compiled versions are sensibly edittable.

Note that crunching/compiling is an either/or question. Crunched code
is not compileable (or at least, not by any compiler I know of).

Once you've got a version of AMPlay that you're happy with, you'll
presumably want to either crunch or compile it to produce a faster
version that you'll actually release/use.

Before either crunching or compiling, you'll need to link all the code
into a single file.


Linking
~~~~~~~

Linking is the process of taking a program that uses libraries, and
pulling all the code that is used in those libraries into the main
program itself.

AMPlay is almost entirely written as libraries - the !runimage has very
little in it initially other than a load of library statements.

For AMPlay's own libraries, there's little point in using a linker
program to pull in the bits that are needed. All of those libraries
will be needed so it's simpler just to paste the whole libraries into
the runimage. DrWimp on the other hand, we only use parts of, so a
linker is useful there to pull in just the relevant bits.

How you go about linking will depend to a small extent on whether you
plan to compile or crunch the linked runimage afterwards. If you plan
to compile it, use !Linker, not !StrongBS. The reason for this is that
!StrongBS will strip comments as it links, and some of those comments
are directives for the compiler and need to be left in.

If using !Linker, use the copy supplied with AMPlay rather than the one
supplied with DrWimp 4.30 or earlier. The copy supplied with AMPlay has
been tweaked slightly to cope with larger file sizes - AMPlay is too
big for the earlier !Linkers to handle correctly.

Here's how I link AMPlay when building it for release:

- Copy !AMPlay into a temporary location for compiling (or take a
  backup first - either way, don't do this to your development copy).

- Take the supplied !RunImage, and strip out all the LIBRARY statements
  except the one for DrWimp_MJS.

- If making a debug version, append the contents of all the AMPlay
  library files after the END statement.

- If making a version with debugging removed, as above, but omit the
  Debug library.

- If making a version with debugging removed, search and replace within
  the file for "IF debug_status%", replacing with
  "REM IF debug_status%". Also manually comment out the lines in
  PROCuser_initialise that check for files to switch debugging on (it's
  around 60 lines into the PROC, and preceded by the comment
  "REM Debugging").

- Run !Linker, and drag the !RunImage and DrWimp_MJS files onto it, and
  click link. I save the resulting file as !RunImageL. The crunching
  and compiling instructions (below) assume !RunImageL as the name of
  the linked file.

This produces a linked !RunImage that contains all the code AMPlay
needs to run. It's worth editting the !Run file at this point to run
!RunImageL, just to be sure that it all still works. Assuming all is
well, proceed to either compiling or crunching.


Crunching
~~~~~~~~~

Crunching is the process of taking verbose, human readable BASIC, and
reducing it to as small a size as possible whilst at the same time
allowing the BASIC interpreter to still understand it. Typically this
comprises;

- Renaming variables to as short a name as possible.
- Renaming functions and procedures to as short a name as possible
- Concatenating lines and other programming structures into their
  shortest possible forms.
- Removing comments, whitespace, and optional programming constructs
  that help readability but don't affect code behaviour.

Note that several of these processes will cause the code to no longer
meet the requirements of the compiler, and will cause it to no longer
be edittable in most editors without corrupting the file.

I've tested crunching the linked AMPlay runimage with !StrongBS, and
found that it works well with the standard options.

Crunched code is still interpreted, so much of the speed benefits are
simply that the interpreter has less text to handle because the code is
smaller.

There's also the advantage that !StrongBS is freeware, whereas there is
no free BASIC compiler (as far as I know).

Note that !StrongBS needs aemulor to run on Iyonix or other 32-bit only
platforms.

There is an SBSMake file inside !AMPlay to stop !StrongBS from
complaining about the use of EVAL.

To produce a crunched version, simply drag the !RunImageL file created
by the linker onto the StrongBS iconbar icon. Click Squash, then click
Save. I save the file as !RunImageC


Compiling
~~~~~~~~~

This assumes you're using the ABC compiler from Castle.

This is the compiler I use to produce the released AMPlay application,
so the code already has the required tweaks and directives to compile
under ABC. Note that these directives are comments as far as the BASIC
interpreter is concerned. Don't strip comments from the file, or you'll
get compiler errors.

Firstly, are you sure that you have no further tweaks to make or bugs
to fix? Compiling AMPlay with ABC takes a little over an hour on an
Iyonix. On a StrongARM Risc PC it takes nearly four hours. It can get
tiresome if you compile it, and find a new bug shortly afterwards, so
make sure you're ready to release...

Although you don't intend to release or compile a crunched version, it
can be worthwhile running it through the cruncher to check for errors,
as this is much faster than letting the compiler produce errors.

- Create a linked !RunImageL as described above.

- Run ABC, and drag !RunImageL onto the ABC iconbar icon. I save the
  file it offers as !RunImageO.

Compilation then takes place, and about an hour later you should have a
compiled object file.



Switching between RunImages
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The version of the !Run file supplied with the source has a mechanism
whereby you can easily swap back and forth between the various
runimages. Near the start of the file is this;

| Uncomment one of these to select the executable type to run.
| This will need changing for production releases.
Set AMPlay$Type Unlinked
|Set AMPlay$Type Linked
|Set AMPlay$Type Crunched
|Set AMPlay$Type Compiled

Later sections of the file use the AMPlay$Type setting to choose what
wimpslot to set, and what file to run. Simply uncomment the one you
want to use, and comment out the others. Obviously the relevant runimage
needs to exist in order for this to work. !RunImageL for the linked
version, !RunImageC for the crunched version, and !RunImageO for the
compiled version are assumed.

AMPlay does all of its static allocation in the wimpslot at startup,
and the memory claimed here does not vary with database size (all that
does vary in that way goes in the dynamic area). Therefore, too small a
wimpslot tends to show up very quickly.


Producing a Release Version
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The procedure above makes all the bits needed for a release version. A
release version has just had some bits tidied up. A release version
does not need the runimage selection mechanism in the !run file, and
doesn't need the source files from which we built !RunImageO.

To produce a copy of AMPlay suitable for release;

- Produce a compiled version with debugging removed (unless you
  specifically want debugging included, or a crunched version).

- Delete or move elsewhere;
  - All the AMPlay library files and the lib directory.
  - !RunImage
  - !RunImageL
  - !RunImageC (if present)
  - SBSMake
  - Debug and or DebugLocal (if present)

- Rename !RunImageO to !RunImage

- Edit !Run to refer to !RunImage, and take out all the stuff to
  do with AMPlay$Type (examine the !run of the released app for
  comparison).

- Ensure the correct version of the help text, messages files and
  documentation are present.

- Ensure that the default skin is present and correct, and that no
  other skins are included inless you mean them to be.


Building AMPlayCFG
~~~~~~~~~~~~~~~~~~

Much the same procedure applies as for AMPlay. It's much smaller, and
fairly quick in the first place, so the benefits of compiling are less
but still worthwhile. It's also much quicker to compile.

The same is also true of AMPlayAPI and AMPlayRCG.

AMPlayCmd can also be compiled if you want to - there's no linking
needed. However you won't gain much by doing this, and I tend to leave
it verbose.

________________________________________________________________________
Copyright  2008 Mike Sandells, mike@mikejs.com
Last Modified: 30.05.2008
