ColdFrame: Installation

Prerequisites

ColdFrame uses:

Modelling tool setup

These are documented separately:

ColdFrame setup

First, either download ColdFrame from the Releases folder, or clone it (git clone git@github.com:simonjwright/coldframe.git or git clone https://github.com/simonjwright/coldframe.git), and step into the coldframe-Release_yyyymmdd or just coldframe directory, as appropriate.

Say 

$ make setup

Amongst other things, this builds the tools supplied in source form in the tools/ subdirectory.

Environment variables

These are the main environment variables that can be used to control ColdFrame's code generation. The indicated defaults are as set up in the Makefile Makefile.inc. They can all be overridden except for ADA_PROJECT_PATH (which Makefile.inc extends).
Variable Meaning Default
ADA_PROJECT_PATH Where your GNAT Project .gpr files are. Makefile.inc adds its own location to your setting. -
BLANK_LINES Should the generated code have extra blank lines to improve legibility? yes
CASE_EXCEPTIONS The list of case exceptions to be used when generating code (for example, "GNAT"). $SCRIPTS/emacs_case_exceptions
COLDFRAME Where ColdFrame is installed (overridden in the Makefiles); set it to, for example, /where/ever/cf-20110720 -
COLDFRAMEOUT Where the .rr files, made by preprocessing ArgoUML's .uml files, are to be placed/found. $COLDFRAME/coldframeout
GENERATE_ACCESSORS Under what circumstances should accessor code be generated? defined
GENERATE_DIAGRAMS Should diagrams be generated as part of generating HTML? yes
GENERATE_EVENT_LOGGING Should additional code be generated to log event handing? no
GENERATE_STUBS Should stub code be generated instead of the normal code? no
GNATCHOP Older ColdFrame projects may have used Interface as a name; it became a keyword in Ada 2005. Modern versions of gnatchop need to be told to adopt Ada95 rules, but older versions wouldn't understand the flag. Set to gnatchop -gnat95 if this is the case. gnatchop
JAVA There should be no need to change this. java
MAXIMPLDEPTH It may be that there are subdirectories of Domain.impl to be searched for code bodies that need to be removed from the .gen directory. 1
MODELS Where model files are located (to be overridden with the location of a project's model files). $COLDFRAME/models
SAXON How to run Saxon. Shouldn't need to be overridden, but see here. $JAVA -cp $SAXON_CLASSPATH $SAXON_MAIN
SAXON_CLASSPATH Where Saxon's code is located. $COLDFRAME/tools/saxon.jar (see these notes)
SAXON_MAIN The Java main program that drives transformations. net.sf.saxon.Transform
(for Saxon 6.5.5 this would be com.icl.saxon.StyleSheet)
SCRIPTED_TESTING Where Scripted Testing is located. $HOME/scripted_testing
SCRIPTS Where ColdFrame's scripts are located. Shouldn't need to be overridden. $COLDFRAME/scripts
TASH Where Tcl Ada Shell is located. $HOME/tcladashell
UNIT_TEST_SUPPORT Should unit test support code (enabling inspection etc) be generated? no
VERBOSE Should ColdFrame be chatty as it generates code? no
XIA Where Xpath In Ada is located. $HOME/xia

Your Makefile

Your project will in general consist of a number of domains, and (unlike some other modelling tools, such as Rational Rose) ArgoUML offers no facility to keep the domains in separately-controlled files. Your choice is then to have one UML file per domain, one per project, or somethng in between.

ColdFrame supports having multiple domains per UML file.

Create a Makefile in the directory where your generated Domain.gen/ files (will) live (next to your implementation Domain.impl/ files).

It should begin by defining where your model (.uml) files live, so as to override ColdFrame's default: 

MODELS = /where/ever

and then include ColdFrame's standard Makefile: 

include $(COLDFRAME)/Makefile.inc

Next, define the domains: ColdFrame creates the intermediate .norm file names as it does other names in the model, by normalizing case and replacing spaces by underscores. Let's suppose that the model is /where/ever/Model.uml and it contains domains House Management and Digital IO (the latter containing a child package stereotyped «domain-interface» called Digital IO Interface with the tag {name=Digital IO}, see the section on testing with stubs): 

DOMAINS = House_Management Digital_IO Digital_IO_Interface

Tell ColdFrame about the relationship between Model.uml and the domains using the incantation 

$(addsuffix .norm,$(DOMAINS)): $(MODELS)/Model.norm-stamp ;

or, if you're using TextUML, 

$(addsuffix .norm,$(DOMAINS)): $(MODELS)/Model.tuml-norm-stamp ;

(or, of course, both). In either case, do not omit the space before the semicolon.

Later on, you'll add rules to build the executables, but to start with you can just generate the code: 

all:: $(addsuffix .gen,$(DOMAINS))

Creating your build directories

If you have a recent GNAT you can use the -p flag to tell gnatmake or gprbuild to create any needed directories as required.

Creating a GNAT Project file

If you don't need to override any of the ColdFrame.Project source, your project file can be pretty simple: the supplied Event_Test.gpr (in the test/ subdirectory) is 

with "ColdFrame";
with "Options";
with "aunit";

project Event_Test is

  for Main use ("event_test-harness");

  for Exec_Dir use ".";

  for Source_Dirs use
    ("Event_Test.impl",
     "Event_Test.gen",
     "Event_Test.test");

  for Object_Dir use ".build";
  package Builder renames Options.Builder;
  package Compiler renames Options.Compiler;
  package Binder renames Options.Binder;
  package Linker renames Options.Linker;

end Event_Test;

Add further domains as required, of course.

Overriding ColdFrame.Project source

If you need to override some of the Ada source code in the $COLDFRAME/project directory, life becomes complicated because you have to avoid circularity and having multiple occurrences of the same file; you can't use the supplied ColdFrame.gpr.

Suppose your overriding source is in ~/Base/Build/ColdFrameProject/project; change directory to ~/Base/Build/ColdFrameProject and say 

$ $COLDFRAME/scripts/install-project

This will place those of ColdFrame's files that you haven't overridden in ~/Base/Build/ColdFrameProject/inherited.

The project file now looks like 

with "Options";
with "aunit";

project Event_Test is

  for Main use ("event_test-harness");

  for Exec_Dir use ".";

  Project_Base = external ("HOME") & "/Base/Build/ColdFrameProject";

  for Source_Dirs use
    (
     "Event_Test.impl",
     "Event_Test.gen",
     "Event_Test.test",
     external ("COLDFRAME") & "/lib",
     Project_Base & "/project",
     Project_Base & "/inherited"
    );

  for Object_Dir use ".build";
  package Builder renames Options.Builder;
  package Compiler renames Options.Compiler;
  package Binder renames Options.Binder;
  package Linker renames Options.Linker;

end Event_Test;

Windows notes

ColdFrame is built on a Unix system and requires typical Unix utilities in order to function.

A Unix-like environment which has proved effective in the past is Cygwin.

When installing Cygwin, choose the 'developer' option.