Clafer ====== v0.3.5.20-01-2014 [Clafer](http://clafer.org) is a general-purpose lightweight structural modeling language developed at [GSD Lab](http://gsd.uwaterloo.ca/), [University of Waterloo](http://uwaterloo.ca). Clafer can be used for modeling of static hierarchical structures but has no support for modeling the change of the structures over time (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: 1. *Product-Line 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. 2. *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. 3. *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*. Clafer Compiler =============== Clafer compiler provides a reference language implementation. It translates models in Clafer to other formats (e.g. Alloy, XML, HTML, DOT) to allow for reasoning and processing with existing tools. Currently, the compiler is used by Clafer Instance Generator ([ClaferIG](https://github.com/gsdlab/claferIG)), Clafer Integrated Development Environment ([ClaferIDE](https://github.com/gsdlab/claferIDE)), Clafer Configurator ([ClaferConfigurator](https://github.com/gsdlab/ClaferConfigurator)), Clafer Multi-Objective Optimizer ([ClaferMOO](https://github.com/gsdlab/ClaferMooStandalone)) and [Visualizer](https://github.com/gsdlab/ClaferMooVisualizer), and Clafer Wiki ([ClaferWiki](https://github.com/gsdlab/claferwiki)). Contributors ------------ * [Kacper Bak](http://gsd.uwaterloo.ca/kbak), Ph.D. Candidate. Main developer. * [Jimmy Liang](http://gsd.uwaterloo.ca/jliang), MSc. Candidate. Main developer. * [Michał Antkiewicz](http://gsd.uwaterloo.ca/mantkiew), Research Engineer. Requirements, development, architecture, testing, technology transfer. * [Ed Zulkoski](http://gsd.uwaterloo.ca/ezulkosk), Pd.D. Candidate. Python IR Generator. * Luke Michael Brown, co-op student May-Aug 2013. Many improvements. * [Rafael Olaechea](http://gsd.uwaterloo.ca/rolaechea), Pd.D. Candidate. Multi-Objective Optimization extensions. Getting Clafer Tools -------------------- Binary distributions of the release 0.3.5 of Clafer Tools for Windows, Mac, and Linux, can be downloaded from [Clafer Tools - Binary Distributions](http://http://gsd.uwaterloo.ca/clafer-tools-binary-distributions). Clafer Wiki requires Haskell Platform and MinGW to run on Windows. In case these binaries do not work on your particular machine configuration, the tools can be built from source code, as described below. ### Dependencies for running * [Java Platform (JDK)](http://www.oracle.com/technetwork/java/javase/downloads/index.html) v6+, 32bit * [Python](http://www.python.org/download/) v2.7.* * Needed only by ClaferMOO * [Alloy4.1 and/or Alloy4.2](http://alloy.mit.edu/alloy/download.html) * [GraphViz](http://graphviz.org/) * `dot` is needed only in the `html` mode for SVG graph generation * [GNU Linear Programming Kit](http://www.gnu.org/software/glpk/) v4.52 ### Installation 1. download the binaries and unpack `` of your choice 2. add the `` to your system path so that the executables can be found 3. copy alloy's jars to the `/tools` folder On Linux 1. [libglpk-dev](http://www.gnu.org/software/glpk/) v4.52 * execute `sudo apt-get install libglpk-dev` on Ubuntu 2. [libgmp-dev](http://gmplib.org/) * execute `sudo apt-get install libgmp-dev` on Ubuntu On Windows 1. The binary distribution already includes the GNU Linear Programming Kit DLL `glpk_4_52.dll`. On Mac 1. install GPLK from [MacPorts](http://www.macports.org/) * execute `sudo port install glpk +universal` Integration with Sublime Text 2 ------------------------------- See [IDEs/clafer-README.md](IDEs/clafer-README.md) Installation From Hackage ------------------------- Dependencies * [The Haskell Platform](http://hackage.haskell.org/platform/) v2013.2.0.0 * GLPK v4.52 Clafer is now available on [Hackage](http://hackage.haskell.org/package/clafer-0.3.5/) and it can be installed using * `cabal update` * `cabal install clafer` * To automatically download Alloy jars, execute `make` in `clafer-0.3.5/tools` inside the Cabal's library folder You'll still need to install GLPK 4.52 for your operating system as described below. Building & Installation From Source Code ---------------------------------------- ### Additional dependencies for building * The dependencies for running * [The Haskell Platform](http://hackage.haskell.org/platform/) v2013.2.0.0 * [Alloy4.1 and/or Alloy4.2](http://alloy.mit.edu/alloy/download.html) * downloaded automatically during build * [Git](http://git-scm.com/) On Linux * [libglpk-dev](http://www.gnu.org/software/glpk/) v4.52 * `sudo apt-get install libglpk-dev` on Ubuntu On Windows * [MinGW+MSYS](http://mingw.org) * since the Haskell Platform already contains MinGW, you may choose to install MinGW+MSYS to the same location, e.g., `c:\...\Haskell Platform\2013.2.0.0` * add the `bin` folders of MinGW (`MinGW\bin`) and MSYS (`MinGW\MSYS\1.0\bin`) to your system path * `wget` will be automatically installed * [WinGLPK](http://winglpk.sourceforge.net/) v4.52 * inside the `w32` folder, copy `glpk_4_52.dll` to`glpk.dll` so that it can be found when building Haskell package `glpk-hs` * from `w32` folder, copy `glpk_4_52.dll` to `\AppData\Roaming\cabal\bin` On Mac only 1. install GPLK 4.52 from [MacPorts](http://www.macports.org/) 2. execute `sudo port install glpk +universal` ### Important: Branches must correspond 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 'master` are guaranteed to work well together. Development versions from branches `develop` should work well together but this might not always be the case. ### Building 1. install the dependencies 2. open the command line terminal. On Windows, open MinGW. 3. in some `` of your choice, execute * `git clone git://github.com/gsdlab/clafer.git` 4. in `/clafer`, execute * `cabal update` 5. On Linux and Mac execute * `make` 6. On Windows (in MinGW), execute * `make glpk="/c/"` ### Installation 1. On Linux and Mac execute * `make install to=` 2. On Windows (in MinGW), execute * `make glpk="/c/" to=/c/` 3. add the `` to your system PATH On Windows only * copy GLPK's dll `glpk-0.4.52.dll` to the `` folder or any other folder on the system path #### Note: > On Windows, use `/` with the `make` command instead of `\`. Usage ===== Clafer Compiler --------------- (As printed by `clafer --help`) ``` Clafer v0.3.5.20-01-2014 clafer [OPTIONS] [FILE] Common flags: -m --mode=CLAFERMODE Generated output type. Available CLAFERMODEs are: 'alloy' (default, Alloy 4.1); 'alloy42' (Alloy 4.2); 'xml' (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); 'python' (generates IR in python); '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' and 'alloy42' modes only). --timeout-analysis=INT Timeout for analysis. -l --no-layout Don't resolve off-side rule layout. --nl --new-layout Use new fast layout resolver (experimental). -c --check-duplicates Check duplicated clafer names. -f --skip-resolver Skip name resolution. -k --keep-unused Keep uninstantated abstract clafers ('alloy' and 'alloy42' modes only). -s --no-stats Don't print statistics. --schema Show Clafer IR (intermediate representation) XML schema. -v --validate Validate outputs of all modes. Uses 'tools/XsdCheck.class' for XML, 'tools/alloy4.jar' and 'tools/alloy4.2.jar' for Alloy models, and Clafer translator for desugared Clafer models. Use '--tooldir' to override the default location of these tools. --nr --noalloyruncommand For usage with partial instances: Don't generate the alloy 'run show for ... ' command, and rename @.ref with unique names ('alloy' and 'alloy42' modes only). --tooldir=DIR Specify the tools directory ('validate' only). Default: 'tools/'. -a --alloy-mapping Generate mapping to Alloy source code ('alloy' and 'alloy42' modes 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, simple (default), or full. --check-afm --afm Throws an error if the cardinality of any of the clafers is above 1. --sg --skip-goals Skip generation of Alloy code for goals. Useful for all tools working with standard Alloy. --meta-data Generate a 'fully qualified name'-'least-partially-qualified name'-'unique ID' map ('.cfr-map'). In Alloy, Alloy42, and Choco modes, generate the scopes map ('.cfr-scope'). -? --help Display help message -V --version Print version information ``` The dependencies among the command line arguments are described on the [model wiki](http://t3-necsis.cs.uwaterloo.ca:8091/ClaferTools/CommandLineArguments). 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=alloy42 ``` Options given at command line override the options given in the file using `//#` which, in turn, override the defaults. ### Using compiler directives Compiler directives are comments of the form ``` //# ``` The following directives are markers of locations in the input files for different purposes: * `//# FRAGMENT` - marks the beginning of the new [module fragment](http://gsd.uwaterloo.ca:8888/question/463/multi-fragment-modules). * `//# 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 `//# GRAPH` and `//# STATS` * `//# QUALITY_ATTRIBUTE` - is used by ClaferMooVisualizer and ClaferConfigurator to distinguish quality attributes, which should be filtered out, from other clafers. Need help? ========== * See [language's website](http://clafer.org) for news, technical reports and more * Check out a [Clafer tutorial](http://t3-necsis.cs.uwaterloo.ca:8091/Tutorial/Intro) * Try a live instance of [ClaferWiki](http://t3-necsis.cs.uwaterloo.ca:8091) * Try a live instance of [ClaferIDE](http://t3-necsis.cs.uwaterloo.ca:8094) * Try a live instance of [ClaferConfigurator](http://t3-necsis.cs.uwaterloo.ca:8093) * Try a live instance of [ClaferMooVisualizer](http://t3-necsis.cs.uwaterloo.ca:8092) * Take a look at (incomplete) [Clafer wiki](https://github.com/gsdlab/clafer/wiki) * Browse example models in the [test suite](https://github.com/gsdlab/clafer/tree/master/test/positive) and [MOO examples](https://github.com/gsdlab/clafer/tree/master/spl_configurator/dataset) * Post questions, report bugs, suggest improvements [GSD Lab Bug Tracker](http://gsd.uwaterloo.ca:8888/questions/). Tag your entries with `clafer` (so that we know what they are related to) and with `jimmy-liang` or `michal` (so that Jimmy or Michał gets a notification).