201 lines
6.2 KiB
Plaintext
201 lines
6.2 KiB
Plaintext
@c This document is part of the TAME manual.
|
|
@c Copyright (C) 2018 R-T Specialty, LLC.
|
|
@c Permission is granted to copy, distribute and/or modify this document
|
|
@c under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
@c any later version published by the Free Software Foundation; with no
|
|
@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
|
|
@c A copy of the license is included in the section entitled ``GNU Free
|
|
@c Documentation License''.
|
|
|
|
@node Using TAME
|
|
@chapter Using TAME
|
|
@tame{} is The Adaptive Metalanguage,
|
|
a programming language and system of tools designed to aid in the
|
|
development; understanding; and maintenance of systems performing
|
|
numerous calculations on a complex graph of dependencies;
|
|
conditions; and a large number of inputs.
|
|
|
|
This system was developed at R-T Specialty@footnote{
|
|
Formerly LoVullo Associates.}
|
|
to handle the complexity of comparative insurance rating systems.
|
|
It is a domain-specific language@tie{}(DSL) that itself encourages,
|
|
through the use of templates,
|
|
the creation of sub-DSLs.
|
|
@tame{} itself is at heart a calculator@mdash{
|
|
}processing only numerical input and output@mdash{
|
|
}driven by quantifiers as predicates.
|
|
Calculations and quantifiers are written declaratively without concern
|
|
for order of execution.
|
|
|
|
The system has powerful dependency resolution and data flow capabilities.
|
|
|
|
@tame{} consists of a macro processor (implementing a metalanguage);
|
|
numerous compilers for various targets
|
|
(JavaScript, HTML documentation and debugging environment, LaTeX,
|
|
and others);
|
|
linkers; and supporting tools.
|
|
The input grammar is XML,
|
|
and the majority of the project
|
|
(including the macro processor, compilers, and linkers)
|
|
is written in XSLT.@footnote{
|
|
There is a reason for that odd choice;
|
|
until an explanation is provided,
|
|
know that someone is perverted enough to implement a full
|
|
compiler in XSLT.}
|
|
|
|
|
|
|
|
@menu
|
|
* Getting Started:: Getting started from a source repository checkout.
|
|
* Manual Compilation:: How to compile a source file by hand.
|
|
* Compiling With Make:: Using the Makefile (recommended).
|
|
@end menu
|
|
|
|
|
|
@node Getting Started
|
|
@section Getting Started
|
|
@cindex Saxon
|
|
@cindex HOXSL
|
|
@cindex bootstrap
|
|
To get started,
|
|
make sure Saxon version@tie{}9 or later is available and its path
|
|
set as @var{SAXON_CP};
|
|
that the path to hoxsl is set via @var{HOXSL};
|
|
and then run the @samp{bootstrap} script:
|
|
|
|
@float Figure, f:bootstrap
|
|
@example
|
|
$ export SAXON_CP=/path/to/saxon9he.jar
|
|
$ export HOXSL=/path/to/hoxsl/root
|
|
|
|
$ ./boostrap
|
|
@end example
|
|
@caption{Bootstrapping TAME in a source repository checkout}
|
|
@end float
|
|
|
|
|
|
|
|
@node Manual Compilation
|
|
@section Manual Compilation
|
|
@tip{Note: TAME is usually controlled through a Makefile;
|
|
@pxref{Compiling With Make} to avoid manual compilation
|
|
steps.}
|
|
|
|
@cindex tamed
|
|
@tame{} is controlled through the program in @command{bin/tame}.
|
|
When run,
|
|
it first spawns a daemon @command{bin/tamed} if it is not already
|
|
running.
|
|
@command{tamed} is needed to keep the JVM and compiled XSLT templates
|
|
in memory,
|
|
otherwise each file would incur a steep startup penalty.
|
|
|
|
@todo{Document commands.
|
|
Most developers do not build files directly,
|
|
so this is not essential yet.}
|
|
|
|
@float Figure, f:compile-ex
|
|
@example
|
|
$ bin/tame compile src/foo.xml src/foo.xmlo
|
|
$ bin/tame link src/foo.xmlo src/foo.xmle
|
|
$ bin/tame standalone src/foo.xmle src/foo.js
|
|
$ bin/tame summary src/foo.xmle src/foo.html
|
|
@end example
|
|
@caption{Compiling a JavaScript executable and Summary Page}
|
|
@end float
|
|
|
|
To kill the daemon,
|
|
pass @samp{--kill} to either @file{bin/tame} or @file{bin/tamed}.
|
|
For additional options and environment variables that influence
|
|
operation,
|
|
pass @samp{--help} to either command.
|
|
|
|
|
|
@node Compiling With Make
|
|
@section Compiling With Make
|
|
@cindex Make
|
|
TAME can generate a @url{https://gnu.org/software/make,GNU Makefile}
|
|
for you using @url{https://gnu.org/software/automake,Automake} and
|
|
@url{https://gnu.org/softeware/autoconf,Autoconf}.
|
|
This greatly simplifies building projects by automatically building
|
|
all dependencies as needed,
|
|
and only when they have changed.@footnote{@c
|
|
When their modification timestamps change, specifically.}
|
|
|
|
@cindex Makefile
|
|
The Makefile is generated by a @file{configure} script,
|
|
which itself generated by Autoconf using @file{configure.ac} in the
|
|
project root:
|
|
|
|
@float Figure, f:configure-ac
|
|
@example
|
|
AC_INIT([PROJECT_NAME], [0.0.0], [contact@@email])
|
|
|
|
m4_define(`calc_root', rater)
|
|
m4_include([rater/build-aux/m4/calcdsl.m4])
|
|
|
|
@end example
|
|
@caption{Example @file{configure.ac} in project root.}
|
|
@end float
|
|
|
|
@cindex submodule
|
|
By convention,
|
|
TAME is usually available as a submodule under @file{rater/}.
|
|
This confusing naming convention may change in the future.
|
|
|
|
Then, to generate the @file{Makefile}:
|
|
|
|
@float Figure, f:configure
|
|
@example
|
|
$ autoreconf -fvi
|
|
$ ./configure SAXON_CP=/path/to/saxon9he.jar
|
|
@end example
|
|
@caption{Invoking @file{configure} to generate @file{Makefile}.}
|
|
@end float
|
|
|
|
@todo{Add more sections.}
|
|
|
|
@menu
|
|
* Common Targets:: Common Makefile targets.
|
|
@end menu
|
|
|
|
|
|
@node Common Targets
|
|
@subsection Common Targets
|
|
A @dfn{target} is something that can be built.
|
|
Usually it is a specific file (e.g. @file{foo.js}),
|
|
but it can also be a command (also called a @dfn{phony target}).
|
|
Here are the most common phony targets that may be useful:
|
|
|
|
@table @samp
|
|
@item all
|
|
This is the default target (just type @samp{make}).
|
|
Build the UI and all suppliers.
|
|
Does not build the Summary Pages,
|
|
as they are considered to be debugging tools.
|
|
|
|
@item summary-html
|
|
Build all Summary Pages for programs in @file{suppliers/}.
|
|
This is equivalent to building each @file{suppliers/*.html} target
|
|
manually.
|
|
|
|
@item check
|
|
@item test
|
|
Run test cases in @file{test/}.
|
|
|
|
@item standalones
|
|
Build JavaScript executables for each program in @file{suppliers/}.
|
|
This is a dependency of @samp{summary-html}.
|
|
|
|
@item tamed-die
|
|
@item kill-tamed
|
|
Kill running tamed for effective user, if any
|
|
(@pxref{Manual Compilation}).
|
|
|
|
@item clean
|
|
Delete all file targets.
|
|
This may be necessary when upgrading TAME,
|
|
for example,
|
|
to rebuild all files using the new version.
|
|
@end table
|