tame/doc/usage.texi

@c  This document is part of the TAME manual.
@c  Copyright (C) 2014-2021 Ryan Specialty Group, 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 Algebraic 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 Ryan Specialty Group@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.
* Parallel Builds:: Building multiple files concurrently.
@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


@node Parallel Builds
@subsection Parallel Builds
@cindex Make, parallel builds
GNU Make offers parallel builds through the @code{-j} flag,
  which specifies the maximum number of concurrent jobs.
This is supported by both @command{tame} and @command{tamed}.

@command{tamed} starts by spawning a single runner,
  which is marked as available.
When a command is issued to @command{tame},
  it will reserve the first available runner it finds by marking it as
    busy.
Once the runner is finished,
  it will be marked as available once again.
If all available runners are busy,
  @command{tame} issues a signal to @command{tamed} to spawn another
    runner,
      which @command{tame} then reserves and marks as busy.
No runners are ever freed (terminated) until @command{tamed} itself
  terminates.

For example,
  to build with up to four concurrent runners,
    use @samp{-j4}:

@float Figure, f:make-j
@example
$ make -j4
@end example
@caption{Compiling with four concurrent runners}
@end float

@cindex build, memory
@tip{Compiling and linking large packages can be memory intensive.
     While runner memory consumption may vary,
       it's wise to profile the memory usage of a single runner and
         use that to estimate how many concurrent runners your system
           can support.}

@cindex Saxon
@tip{Saxon is also multi-threaded under certain circumstances,
       so you should allocate fewer jobs than you have available CPU
         cores.
     GNU Make also offers a @code{-l} flag that tells it not to spawn
       more jobs if the system is above the indicated load.
     But note that,
       even if a runner is idle,
         it is still using up memory.}