tame/doc/usage.texi

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