Difference between revisions of "SAPL"

From Clean
Jump to navigationJump to search
 
(76 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
{|style="width:100%; border:none"
 
{|style="width:100%; border:none"
|style="width:70%; vertical-align: top; padding-right: 20px;"|
+
|style="width:70%; vertical-align: top; padding-right: 40px;"|
  
 
[[File:sapl-logo.png|left|text-top|300px|SAPL]]
 
[[File:sapl-logo.png|left|text-top|300px|SAPL]]
  
SAPL is a purely functional, intermediate language and related infrastructure for supporting cross-compilation of lazy functional languages to different target platforms. It currently supports [[Clean]] and [http://www.haskell.org/ghc/‎ Haskell/GHC] as source languages and provides JavaScript as target platform, however a [http://www.dartlang.org‎ DART] target is under development. SAPL is extensively used in the [[ITasks]] project, furthermore various GHC based projects are experimenting with SAPL.
+
<span style="font-size:130%">'''Note:''' ''The SAPL compiler infrastructure project is no longer in development. The content on these pages is provided as a historical reference only. The SAPL language and the SAPL to JavaScript compiler is integrated with the Clean compiler and still in development / maintaned, but the GHC to SAPL compiler is not maintained any more, because of the lack of resources to keep up with the changes of the SAPL language and the GHC compiler.''</span>
  
== Getting started ==
 
  
So far, no official version of the SAPL compiler infrastructure is released. The current development version can be
+
SAPL is a purely functional, intermediate language and related infrastructure for supporting cross-compilation of lazy functional languages to different target platforms. It currently supports [[Clean]] and [http://www.haskell.org/ghc/‎ Haskell/GHC] as source languages and provides JavaScript as target platform, however a [http://www.dartlang.org‎ DART] and Java target is under development. SAPL is extensively used in the [[ITasks]] project, furthermore various GHC based projects are experimenting with SAPL.
checked out from https://svn.cs.ru.nl/repos/clean-sapl. Build instructions can be found at [[SAPL/Build]]
 
  
== Usage ==
+
== Overview ==
  
Compiling Clean or Haskell to JavaScript consists of three easy steps. First, you need to compile
+
SAPL infrastructure consists of a few main parts built around the [[SAPL Language]].
the necessary source code modules to the SAPL language. The execution of this step depends on the source language you would like to use.
 
Instructions for Clean and Haskell/GHC can be found at [[SAPL/Clean]] and [[SAPL/GHC]], respectively.
 
  
=== Linking ===
+
==== Source filters ====
  
The second step is to collect and combine, starting with some root expressions, the necessary functions recursively
+
Source filters convert the source language to the SAPL language. Currently we have source filters for Clean and Haskell/GHC. For Clean, the filter is integrated into the compiler. As for Haskell/GHC, a separate compiler is provided based on the original one.
into one SAPL file. Engaging on this linking step helps with reducing the final code size as much as possible.
+
Detailed instructions for their usages can be found at [[SAPL/Clean]] and [[SAPL/GHC]], respectively.
The linking is done using the <tt>sl</tt> command. A simple example for its usage is as follows:
 
  
<pre>
+
==== SAPL linker ====
sl --include-dir=build --expr=Main.main out.sapl
+
 
</pre>
+
SAPL has hierarchical module support based on directory layout. Prior to the target compilation a linking
 +
step is required to collect and combine, based on arbitrary root expressions, the necessary functions recursively from the separate modules into one SAPL file which will be the input of the target compilers.
 +
 
 +
As the SAPL language is designed for easy parsing, linking is very fast and straightforward compared to the linking
 +
of the target languages (e.g. JavaScript) and helps with minimizing the size of the output code.
 +
 
 +
==== Flavours ====
 +
 
 +
A flavour is a kind of configuration file used by the target compilers. It provides information about how to compile the built-in functions of a given source language to a given target language. It must be in sync with the source filter and source language dependent part of the run-time system. Flavours are provided for all the combinations of source and target languages.
 +
 
 +
==== Target compilers ====
 +
 
 +
A target compiler transforms SAPL code into a given target language. The compilation must be aided by a flavour for the correct compilation of the built-in functions. The SAPL library supports the development of target languages by providing a lexer and parser for the SAPL language along with language transformation functions (e.g. Topological ordering of let definitions), and other support functions (e.g. strictness propagation, type inference etc). Currently JavaScript is the only target language supported, however DART and Java targets are under development.
 +
 
 +
==== Target run-time ====
 +
 
 +
Run-time functions are necessary to execute the target code. Some of these are independent of the source language and cope with e.g. lazy evaluation, while some are dependent of the source language and must be in sync with the source filter and the supporting flavour. Some language features must be supported by the run-time system, for the current state of/features supported by the run-times please consult with the appropriate page:
 +
 
 +
* [[Clean/JavaScript]]
 +
* [[Haskell/GHC/JavaScript]]
 +
 
 +
== Tutorial (Clean) ==
 +
 
 +
The SAPL compiler and linker is fully integrated into the upcoming version of the Clean compiler.
 +
Until that becomes available, please contact me for instructions by dlacko@gmail.com.
 +
 
 +
== Tutorial (GHC) ==
 +
 
 +
As for GHC a carefully adjusted environment must be used for the SAPL compilation (e.g. 32bit compiler must be used,
 +
for more explanation please consult to [[Sapl/GHC]]). We use [http://www.vagrantup.com Vagrant] to provide this environment by virtualisation.
 +
However, you don't need any knowledge on Vagrant, all you have to do is to install [http://www.vagrantup.com/downloads.html Vagrant] in one simple step (you also need to install a low level virtualizer e.g. [https://www.virtualbox.org/ VirtualBox] and some SSH client if you do not have one installed), check out the following SVN URL
 +
 
 +
https://svn.cs.ru.nl/repos/clean-sapl/trunk/platforms/GHC/vagrant
 +
 
 +
and in directory where you checked out type
  
It links for the <tt>main</tt> function in the module called <tt>Main</tt> and collects all the necessary functions into the <tt>out.sapl</tt> file.
+
  $ vagrant up
The module search path is the <tt>build</tt> directory in the current directory. Multiple root expressions and include directories can be provided. For the other command line arguments please type
+
followed by
  
<pre>
+
  $ vagrant ssh
sl --help
+
and you find yourself using a shell where all the SAPL components are available precompiled. The current directory outside the virtual machine can be accessed at the directory <tt>/vagrant</tt>.
</pre>
+
Now, create a <tt>hello.hs</tt> with the well knows "Hello, World!" example:
  
=== Final compilation ===
+
  $ mkdir hello
 +
  $ cd hello
 +
  $ cat > hello.hs
 +
    main = putStrLn "Hello, World!"^D
 +
First step, compile it to SAPL:
 +
  $ ghcsapl hello.hs
 +
It creates a <tt>Main.sapl</tt>, as SAPL file names are the names of the modules rather than the original file names.
  
The result of the <tt>sl</tt> command can be compiled to JavaScript using the <tt>sapl2js</tt> command.
+
If you are brave enough, have a look at the generated SAPL source code. It consists of three simple lines only,
The following example compiles <tt>out.sapl</tt> to JavaScript and places the result in the file <tt>out.js</tt>.
+
with references to functions located in other modules, e.g. <tt>System.IO</tt>. For proper compilation you need to collect the
 +
necessary functions from these modules. Precompiled SAPL files can be found in <tt>~/sapl/packages</tt>,
 +
the base system modules are in <tt>core/base</tt> and <tt>core/ghc-prim</tt> within that. Use the <tt>sl</tt> command for linking:
  
<pre>
+
  $ sl -I ~/sapl/packages/core/base -I ~/sapl/packages/core/ghc-prim -i Main.sapl -e Main.main hello.sapl
sapl2js -f clean -o out.js out.sapl
+
This command produces a <tt>hello.sapl</tt> file which is already self-contained.
</pre>
+
Finally the
 +
  $ sapl2js -f ghc hello.sapl
 +
produces JavaScript output of approximately 1300 bytes as <tt>hello.js</tt>. Please note the usage of the "ghc" flavour.
 +
I recommend one optimal step, the utilization of [https://developers.google.com/closure/compiler/ closure compiler] to reduce code size and execution time:
 +
  $ java -jar ~/sapl/tools/closure-compiler.jar --js_output_file hello_opt.js hello.js
 +
For the execution check out the necessary run-time from the following URLs:
  
Please note the usage of the <tt>-f</tt> command line argument. The target code depends on the source language as different languages
+
* https://svn.cs.ru.nl/repos/clean-sapl/trunk/platforms/GHC/run-time
use different ''primitive/built-in functions''. Thus, during the final compilation step, the compiler must be aware of the primitive
+
* https://svn.cs.ru.nl/repos/clean-sapl/trunk/platforms/Common/run-time
functions contained by the SAPL source code.  
 
  
This information is provided by the so called '''flavor''' file to the final compiler. The file has an extension of ".f" and it describes
+
It contains a template HTML file named <tt>client.html</tt> for the execution of a function placed in a file <tt>main.js</tt>.
how to compile the primitive functions of a given source language to a given target language. As currently we have two source languages and one target platform, two flavor files are provided: one for the compilation of Clean to JavaScript (clean.f) and one
+
So all you need is to copy all the files of the run-time and either <tt>hello.js</tt> or <tt>hello_opt.js</tt> (renamed to <tt>main.js</tt>)
for compilation of Haskell/GHC to JavaScript (ghc.f).
+
into one common directory.
The compiler looks up the flavor file in the following directories in the given order:
 
 
# in the current directory
 
# in the directory which contains the executable of the compiler (bindir)
 
# bindir/../lib/sapl/
 
# bindir/../lib/
 
  
For further command line arguments please type
+
For more elaborated projects I also recommend to create a <tt>Makefile</tt>. For this simplistic case it could be like this:
  
 
<pre>
 
<pre>
sapl2js --help
+
SL=sl --include-dir=~/sapl/packages/core/base \
 +
      --include-dir=~/sapl/packages/core/ghc-prim
 +
S2JS=sapl2js -f ghc
 +
GHCSAPL=ghcsapl -O2
 +
CC=java -jar ~/sapl/tools/closure-compiler.jar 
 +
 
 +
all: create hello_opt.js
 +
 +
hello_opt.js:
 +
    $(GHCSAPL) --make hello.hs
 +
    $(SL) -i Main.sapl -e Main.main hello.sapl
 +
    $(SAPL2JS) hello.sapl
 +
    $(CC) --js_output_file hello_opt.js hello.js
 
</pre>
 
</pre>
  
=== Execution ===
+
== Publications ==
  
For the execution of the final script you need to cope with the SAPL run-time engine.
+
There are two publications that are closely related to the current form of SAPL, however, both of them are slightly outdated. The SAPL language described in the first paper is already modified several times for various reasons, but the compilation scheme is still basically the same. As for the second paper, most of the shortcomings listed there are solved after the publication (some of them by adjusting the SAPL language itself) and currently the transformation scheme support all of the Haskell/GHC language features. The third paper describes the original SAPL language the first time.
It consists of the actual run-time functions and the implementation of the primitive functions.  
 
This latter depends on the source language, thus, you need (partly) different run-time  
 
for different source languages.
 
  
Template HTML as well as the necessary JavaScript files for GHC and Clean can be found at https://svn.cs.ru.nl/repos/clean-sapl/platforms/GHC/run-time
+
# László Domoszlai and E. Bruel and J.M. Jansen. Implementing a non-strict purely functional language in JavaScript. ''Acta Univ. Sapientiae. Informatica'', 3(1):76-98, 2011
and at https://svn.cs.ru.nl/repos/clean-sapl/platforms/Clean/run-time. You also need to borrow the common
+
# László Domoszlai and Rinus Plasmeijer. Compiling Haskell to JavaScript through Clean's core. ''Annales Univ. Sci.'', 36:117--142, 2012. Selected papers of 9th Joint Conference on Mathematics and Computer Science, MaCS 2012, February 9-12, 2012, Siófok, Hungary
part of the RTS from https://svn.cs.ru.nl/repos/clean-sapl/platforms/Common/run-time.
+
# J.M. Jansen and P. Koopman, and R. Plasmeijer. Efficient interpretation by transforming data types and patterns to functions. ''Selected Papers of the 7th Symposium on Trends in Functional Programming, TFP'06'', volume 7, pages 73-90, Nottingham, UK, 2006.
  
 +
== Contact ==
  
 +
If you have any question related to any part of the SAPL infrastructure, please do not hesitate to contact to László Domoszlai by dlacko@gmail.com.
  
 
|style="width:30%; vertical-align: top; padding-right: 20px;"|
 
|style="width:30%; vertical-align: top; padding-right: 20px;"|

Latest revision as of 14:01, 18 September 2017

SAPL

Note: The SAPL compiler infrastructure project is no longer in development. The content on these pages is provided as a historical reference only. The SAPL language and the SAPL to JavaScript compiler is integrated with the Clean compiler and still in development / maintaned, but the GHC to SAPL compiler is not maintained any more, because of the lack of resources to keep up with the changes of the SAPL language and the GHC compiler.


SAPL is a purely functional, intermediate language and related infrastructure for supporting cross-compilation of lazy functional languages to different target platforms. It currently supports Clean and Haskell/GHC as source languages and provides JavaScript as target platform, however a DART and Java target is under development. SAPL is extensively used in the ITasks project, furthermore various GHC based projects are experimenting with SAPL.

Overview

SAPL infrastructure consists of a few main parts built around the SAPL Language.

Source filters

Source filters convert the source language to the SAPL language. Currently we have source filters for Clean and Haskell/GHC. For Clean, the filter is integrated into the compiler. As for Haskell/GHC, a separate compiler is provided based on the original one. Detailed instructions for their usages can be found at SAPL/Clean and SAPL/GHC, respectively.

SAPL linker

SAPL has hierarchical module support based on directory layout. Prior to the target compilation a linking step is required to collect and combine, based on arbitrary root expressions, the necessary functions recursively from the separate modules into one SAPL file which will be the input of the target compilers.

As the SAPL language is designed for easy parsing, linking is very fast and straightforward compared to the linking of the target languages (e.g. JavaScript) and helps with minimizing the size of the output code.

Flavours

A flavour is a kind of configuration file used by the target compilers. It provides information about how to compile the built-in functions of a given source language to a given target language. It must be in sync with the source filter and source language dependent part of the run-time system. Flavours are provided for all the combinations of source and target languages.

Target compilers

A target compiler transforms SAPL code into a given target language. The compilation must be aided by a flavour for the correct compilation of the built-in functions. The SAPL library supports the development of target languages by providing a lexer and parser for the SAPL language along with language transformation functions (e.g. Topological ordering of let definitions), and other support functions (e.g. strictness propagation, type inference etc). Currently JavaScript is the only target language supported, however DART and Java targets are under development.

Target run-time

Run-time functions are necessary to execute the target code. Some of these are independent of the source language and cope with e.g. lazy evaluation, while some are dependent of the source language and must be in sync with the source filter and the supporting flavour. Some language features must be supported by the run-time system, for the current state of/features supported by the run-times please consult with the appropriate page:

Tutorial (Clean)

The SAPL compiler and linker is fully integrated into the upcoming version of the Clean compiler. Until that becomes available, please contact me for instructions by dlacko@gmail.com.

Tutorial (GHC)

As for GHC a carefully adjusted environment must be used for the SAPL compilation (e.g. 32bit compiler must be used, for more explanation please consult to Sapl/GHC). We use Vagrant to provide this environment by virtualisation. However, you don't need any knowledge on Vagrant, all you have to do is to install Vagrant in one simple step (you also need to install a low level virtualizer e.g. VirtualBox and some SSH client if you do not have one installed), check out the following SVN URL

https://svn.cs.ru.nl/repos/clean-sapl/trunk/platforms/GHC/vagrant

and in directory where you checked out type

 $ vagrant up 

followed by

 $ vagrant ssh

and you find yourself using a shell where all the SAPL components are available precompiled. The current directory outside the virtual machine can be accessed at the directory /vagrant. Now, create a hello.hs with the well knows "Hello, World!" example:

 $ mkdir hello
 $ cd hello
 $ cat > hello.hs
   main = putStrLn "Hello, World!"^D

First step, compile it to SAPL:

 $ ghcsapl hello.hs

It creates a Main.sapl, as SAPL file names are the names of the modules rather than the original file names.

If you are brave enough, have a look at the generated SAPL source code. It consists of three simple lines only, with references to functions located in other modules, e.g. System.IO. For proper compilation you need to collect the necessary functions from these modules. Precompiled SAPL files can be found in ~/sapl/packages, the base system modules are in core/base and core/ghc-prim within that. Use the sl command for linking:

 $ sl -I ~/sapl/packages/core/base -I ~/sapl/packages/core/ghc-prim -i Main.sapl -e Main.main hello.sapl

This command produces a hello.sapl file which is already self-contained. Finally the

 $ sapl2js -f ghc hello.sapl

produces JavaScript output of approximately 1300 bytes as hello.js. Please note the usage of the "ghc" flavour. I recommend one optimal step, the utilization of closure compiler to reduce code size and execution time:

 $ java -jar ~/sapl/tools/closure-compiler.jar --js_output_file hello_opt.js hello.js

For the execution check out the necessary run-time from the following URLs:

It contains a template HTML file named client.html for the execution of a function placed in a file main.js. So all you need is to copy all the files of the run-time and either hello.js or hello_opt.js (renamed to main.js) into one common directory.

For more elaborated projects I also recommend to create a Makefile. For this simplistic case it could be like this:

SL=sl --include-dir=~/sapl/packages/core/base \
      --include-dir=~/sapl/packages/core/ghc-prim
S2JS=sapl2js -f ghc
GHCSAPL=ghcsapl -O2
CC=java -jar ~/sapl/tools/closure-compiler.jar   

all: create hello_opt.js
	
hello_opt.js:
    $(GHCSAPL) --make hello.hs
    $(SL) -i Main.sapl -e Main.main hello.sapl
    $(SAPL2JS) hello.sapl
    $(CC) --js_output_file hello_opt.js hello.js

Publications

There are two publications that are closely related to the current form of SAPL, however, both of them are slightly outdated. The SAPL language described in the first paper is already modified several times for various reasons, but the compilation scheme is still basically the same. As for the second paper, most of the shortcomings listed there are solved after the publication (some of them by adjusting the SAPL language itself) and currently the transformation scheme support all of the Haskell/GHC language features. The third paper describes the original SAPL language the first time.

  1. László Domoszlai and E. Bruel and J.M. Jansen. Implementing a non-strict purely functional language in JavaScript. Acta Univ. Sapientiae. Informatica, 3(1):76-98, 2011
  2. László Domoszlai and Rinus Plasmeijer. Compiling Haskell to JavaScript through Clean's core. Annales Univ. Sci., 36:117--142, 2012. Selected papers of 9th Joint Conference on Mathematics and Computer Science, MaCS 2012, February 9-12, 2012, Siófok, Hungary
  3. J.M. Jansen and P. Koopman, and R. Plasmeijer. Efficient interpretation by transforming data types and patterns to functions. Selected Papers of the 7th Symposium on Trends in Functional Programming, TFP'06, volume 7, pages 73-90, Nottingham, UK, 2006.

Contact

If you have any question related to any part of the SAPL infrastructure, please do not hesitate to contact to László Domoszlai by dlacko@gmail.com.

News

  • January 2 2014: The first draft version of the SAPL wiki is added