Clafer is a general-purpose lightweight structural and behavioral modeling language developed by GSD Lab, University of Waterloo, and MODELS group at IT University of Copenhagen. Clafer can be used for modeling of static hierarchical structures and for modeling the change of the structures over time (behavior). Clafer allows for naturally expressing variability in both the structure and behavior. The main goal of Clafer is to make modeling more accessible to a wider range of users and domains.
There are many possible applications of Clafer; however, three are prominent:
-
Product-Line Architecture Modeling - aims at representing and managing commonality and variability of assets in product lines and creating and verifying product configurations. Clafer naturally supports multi-staged configuration. By applying modeling patterns, Clafer can be used for feature modeling, architecture modeling (e.g., by applying EAST-ADL), and behavior modeling (e.g., hierarchical state transition systems). All these aspects naturally include variability.
-
Multi-Objective Product Optimization - aims at finding a set of products in a given product line that are optimal with respect to a set of objectives. Clafer multi-objective optimizer generates a Pareto front of optimal product configurations.
-
Domain Modeling - aims at improving the understanding of the problem domain in the early stages of software development and determining the requirements with fewer defects. This is also known as Concept Modeling or Ontology Modeling.
-
Concept Behavior Modeling - aims at eliciting how a structure of a concept evolved over time and checking properties of possible behaviors.
May applications actually combine the three. For example, see Technical Report: Case Studies on E/E Architectures for Power Window and Central Door Locks Systems.
For examples of behavior modeling, see Behavioral Modeling section on the wiki. Currently; however, no reasoning capability is available for behavior modeling.
Clafer compiler provides a reference implementation of Clafer, the language. It translates models in Clafer to other formats (e.g., Alloy, JSON, JS, HTML, DOT) to allow for reasoning and processing with existing tools (Alloy Analyzer, Choco3, and GraphViz).
Currently, the compiler is used by
- Backends
- Alloy-based Instance Generator (ClaferIG),
- Choco3-based Instance Generator and Multi-Objective Optimizer (chocosolver.
- Web Frontends
- Clafer Integrated Development Environment (ClaferIDE),
- Clafer Configurator (ClaferConfigurator),
- Multi-Objective Visualizer and Explorer, and
- Clafer Wiki (ClaferWiki).
- Michał Antkiewicz, Main developer.
- Kacper Bak, Original developer.
- Jimmy Liang, Developer.
- Luke Michael Brown, co-op student May-Aug 2013. Many improvements.
- Paulius Juodisius, customized BNFC generator and layout resolver.
- Rafael Olaechea, Multi-Objective Optimization extensions.
Clafer can be installed from a binary distribution (preferred), from Hackage, and from the source code.
Regardless of the installation method, the following are
Optional:
- Java Platform (JDK) v8+, 64bit
- only needed for running Alloy validation
- 32bit on Windows
- Alloy4.2
- only needed for Alloy output validation
- GraphViz
- the program
dotis needed only in thehtmlmode for SVG graph generation
- the program
Binary distributions of the release 0.5.1 of Clafer Tools for Windows, Mac, and Linux, can be downloaded from Clafer Tools - Binary Distributions.
- Download the binaries and unpack
<target directory>of your choice. - Add the
<target directory>to your system path so that the executables can be found.
Clafer is available on Hackage and it can be installed using either stack or cabal-install.
Stack is the only requirement: no other Haskell tooling needs to be installed because stack will automatically install everything that's needed.
- Install
stack- (first time only) Execute
stack setup.
- (first time only) Execute
- Execute
stack install clafer.
Dependencies
- Use
ghcupto installghc,cabal, andstack cabal updatecabal install alex happycabal install exe:clafer- on Windows
cd C:\Users\<user>\AppData\Roaming\cabal\x86_64-windows-ghc-9.6.4\clafer-0.5.1 - on Linux
cd ~/.cabal/bin/ - to automatically download Alloy jars, execute
make alloy4.2.jar,- move
alloy4.2.jarto the location of the clafer executable.
Dependencies
On Windows
- MSYS2
- it is installed automatically by
stack setup - update MSYS2 following the update procedure:
stack exec pacman -- -Systack exec pacman -- --needed -S bash pacman pacman-mirrors msys2-runtime- restart shell if the runtime was updated
stack exec pacman -- -Su
stack exec pacman -- -S make wget unzip diffutils
- it is installed automatically by
All related projects are following the simultaneous release model.
The branch master contains releases, whereas the branch develop contains code under development.
When building the tools, the branches should match.
Releases from branches 'masterare guaranteed to work well together. Development versions from branchesdevelop` should work well together but this might not always be the case.
- in some
<source directory>of your choice, execute
git clone git://github.com/gsdlab/clafer.git
- in
<source directory>/clafer, executestack setup. This will install all dependencies, build tools, and MSYS2 (on Windows). cd <source directory>
makeon Linux/Macstack exec makeon Windows
- Execute
make install to=<target directory>on Linux/Macstack exec make install to=<target directory>on Windows
On Windows, use
/with themakecommand instead of\, e.g.,make install to=/c/clafer-tools-0.5.1/
See ClaferToolsST
See clafer-vim
(As printed by clafer --help)
Clafer 0.5.1
clafer [OPTIONS] [FILE]
Common flags:
-m --mode=CLAFERMODE Generated output type. Available
CLAFERMODEs are: 'alloy' (default,
Alloy 4.2); 'json' (intermediate
representation of Clafer model);
'clafer' (analyzed and desugared
clafer model); 'html' (original model
in HTML); 'graph' (graphical
representation written in DOT
language); 'cvlgraph' (cvl notation
representation written in DOT
language); 'choco' (Choco constraint
programming solver). Multiple modes
can be specified at the same time,
e.g., '-m alloy -m html'.
-o --console-output Output code on console.
-i --flatten-inheritance Flatten inheritance ('alloy' mode
only).
--timeout-analysis=INT Timeout for analysis.
-l --no-layout Don't resolve off-side rule layout.
-n --nl --new-layout Use new fast layout resolver
(experimental).
-c --check-duplicates Check duplicated clafer names in
the entire model.
-f --skip-resolver Skip name resolution.
-k --keep-unused Keep uninstantated abstract clafers
('alloy' mode only).
-s --no-stats Don't print statistics.
-v --validate Validate outputs of all modes. Uses
'<tooldir>/alloy4.2.jar' for Alloy
models, '<tooldir>/chocosolver.jar'
for Alloy models, and Clafer
translator for desugared Clafer
models. Use '--tooldir' to override
the default location ('.') of these
tools.
--tooldir=DIR Specify the tools directory
('validate' only). Default: '.'
(current directory).
-a --alloy-mapping Generate mapping to Alloy source
code ('alloy' mode only).
--self-contained Generate a self-contained html
document ('html' mode only).
--add-graph Add a graph to the generated html
model ('html' mode only). Requires
the "dot" executable to be on the
system path.
--sr --show-references Whether the links for references
should be rendered. ('html' and
'graph' modes only).
--add-comments Include comments from the source
file in the html output ('html' mode
only).
-e --ecore2clafer Translate an ECore model into
Clafer.
--ss=SCOPESTRATEGY --scope-strategy Use scope computation strategy:
none or simple (default).
--check-afm --afm Throws an error if the cardinality
of any of the clafers is above 1.
--meta-data Generate a 'fully qualified
name'-'least-partially-qualified
name'-'unique ID' map ('.cfr-map').
In Alloy and Choco modes, generate
the scopes map ('.cfr-scope').
-? --help Display help message
-V --version Print version information
--numeric-version Print just the version number
The dependencies among the command line arguments are described on the model wiki.
Multiple modes can be used at the same time. For example,
clafer model.cfr -m alloy -m json -m html -m graph --self-contained --show-references --no-stats
The mode -m alloy is only the default mode if no other modes are given. When other modes are given, the mode -m alloy must be added explicitly if needed.
Additionally, [OPTIONS] can also be specified directly in the model file by inserting the following compiler directive as the first line of the file:
//# [OPTIONS]
for example
//# --keep-unused -m=alloy
Options given at command line override the options given in the file using //# which, in turn, override the defaults.
Compiler directives are comments of the form
//# <directive name>
The following directives are markers of locations in the input files for different purposes:
//# FRAGMENT- marks the beginning of the new module fragment.//# GRAPH- marks the insertion point for a graph rendering. The graph is only produced in HTML mode with the argument--add-graph.//# STATS- marks the insertion point for module statistics. The statistics can be omitted using the argument--no-stats.//# SUMMARY- shorthand for//# GRAPHand//# STATS
Here is some information about the development of the Clafer compiler.
We are following the simplified version of the successful Git branching model.
The branch master is for releases and hot fixes only.
The branch develop is for minor development and for integration of features from feature branches.
For any substantial work, branch off from develop and create a pull request back into develop after the work is completed.
We do testing and code review before merging into develop.
If the develop is ahead, merge it into the feature branch and perform integration testing there.
To make a release, we create a pull request from develop into master.
We tag master with version numbers after each release merge.
We have switched to Haskell Tool Stack. Install the tool first.
We have both automated tests and regression tests.
To run the automated tests (including both unit tests and doctests), execute
stack test
To only run unit tests, execute stack test test-suite.
To only run doctests, execute stack test doctests.
Note: it is still possible to run
cabal testas previously; however, theMakefileusesstackby default.
For instructions for adding new modules to the doctest suite, see cabal integration.
To run all the automated tests and the regression tests, execute
make test
We do test-driven development in the following way:
- create a test case Clafer model in either
test/positiveortest/negativedepending on whether a test case should compile successfully or return an error. For example, see a positive test case test/positive/redefinition.cfr. - produce the intended compiler output automatically if possible and manually fix the output. Save the intended output as a regression test case. For example, see test/regression/redefinition.cfr.reg.
- implement the feature to reproduce the intended output: compiler the test case and execute
cd test
make diffRegressions
this will show you how the current output diverges from the intended output.
We are using a customized version of BNCF.
Clone the repository and install a binary of bnfc so that it's visible in your PATH.
After changing the grammar, execute
make grammar
- Visit language's website.
- Report issues to issue tracker