
This documents shows how to install all required tools from the paper 
¨Quantitative Program Sketching using Lifted Static Analysis¨
if there is NO INTERNET CONNECTION 

####################################################################################
## FamilySketcher2 --- Quantitative Program Sketcher using Lifted Static Analysis ## 
####################################################################################

FamilySketcher2 is a research prototype quantitative program sketcher designed for 
resolving numerical sketches using lifted static analysis based on abstract interpretation.



## Author

	Aleksandar Dimovski
	
	
# OFFLINE Installation

	$ cd Sketching2
The tool requires the following applications and libraries found in ´lib´ folder:
	```
	$ cd lib 
	```
* Menhir: LR(1) parser generator

	```
	$ sudo dpkg -i menhir_20200123-2_amd64.deb	
	```

* M4: macro processing language
	```
	$ cd m4 
	$ sudo dpkg -i * 
	$ cd ..
	```

* Initialize OPAM state [YOU NEED ONLINE CONNECTION for ´opam init´]
	```
	$ opam init      % [INTERNET] during initilization answer with ´Yes´ allowing opam to modify ~/.profile
	```	
	```
	$ eval $(opam env)      % update the current shell environment
	```  
* Conf-gmp

	```
	$ cd libgmp-dev
	$ sudo dpkg -i * 
	$ cd ..
	$ opam pin add conf-gmp conf-gmp.2
	```	
* Conf-mpfr

	```
	$ sudo dpkg -i libmpfr-dev_4.0.2-1_amd64.deb
	$ opam pin add conf-mpfr conf-mpfr.2
	```	
* APRON: numerical abstract domain library

	```
	$ opam pin add conf-perl conf-perl.1
	$ opam pin add camlidl camlidl.1.09
	$ opam pin add mlgmpidl mlgmpidl.1.2.12
	$ opam pin add ocamlbuild ocamlbuild.0.14.0
	$ opam pin apron apron.v0.9.13/
	```
* Set the Library Path variable in ~/.bashrc 
	```
	$ gedit ~/.bashrc
	```
Then, set the Library Path by appending at the end of the ~/.bashrc file:
	```
	LD_LIBRARY_PATH=/home/fase2022/.opam/default/share/apron/lib
	export LD_LIBRARY_PATH
	```
Log out of the current session, then log in and check:
	```
	$ echo $LD_LIBRARY_PATH
	```

* Zarith: arbitrary-precision integer operations

	```
	$ cd Sketching2
	$ cd lib
	$ opam pin zarith zarith.1.10/

	```
* Z3 solver: Micrsoft's Z3 SMT solver

	```
	$ sudo dpkg -i z3_4.8.7-4build1_amd64.deb
	$ cd ..
	```

# Compiling FamilySketcher2

Enter folder 
```
$ cd family_sketcher2
```
Once all required libraries are installed, 'ocamlbuild' can be used to build FamilySketcher with the following two commands:

```
$ eval $(opam config env)                 % It will setup environment variables, that are necessary for the toolchain to work properly

$ ocamlbuild Main.native -use-ocamlfind -use-menhir -pkgs 'apron,gmp,zarith' -I utils -I domains -I frontend -I main -libs boxMPQ,octD,polkaMPQ,str,zarith
```

# Test 

The program sketcher performs a forward reachability analysis and a backward termination analysis of program families and resolves the holes (features) so that 
the found solutions are 'correct & optimal' with respect to the final assertions and the given quantitative objective that counts the number of execution steps to termination. 

The following general command-line options are recognized
(showing their default value):

	 -tree					set to perform decision tree-based lifted analysis
	 -single 				set to perform brute force enumeration approach using single analysis for each variant
	 -main main                         set the analyzer entry point (defaults to main)
	 -domain boxes|octagons|polyhedra   set the abstract domain (defaults to boxes)
	 -joinfwd 2   			     set the widening delay in forward analysis


First examples

```
$ ./Main.native -tree -domain polyhedra bench/loop1a-5.c         
```
Detailed output: 
Forward analysis returns that the assertion is CORRECT for: A-B>=3 && B>=0 && A<=31 (note that both holes are of 5-bits size, so dom(A)=dom(B)=[0,31])
Backward analysis returns the ranking function at location [1:] is: 3A-3B+4
Solution: A=3 and B=0
Total Time: 0.016 sec

```
$ ./Main.native -tree -domain polyhedra bench/loop1b-5.c         
```
Detailed output: 
Forward analysis returns that the assertion is CORRECT for: solution (1) 1<=A-B<=7 && B>=0 && A<=31; and solution (2) A<=B && A>=0 && B<=31 (note that both holes are of 5-bits size, so dom(A)=dom(B)=[0,31])
Backward analysis returns the ranking function at location [1:] is: 3A-3B+4 for solution (1); and 4 for solution (2)
Solution (1): A=1 and B=0
Solution (2): A=0 and B=0
Total Time: 0.026 sec



################################################################################
##Brute Force approach --- Single-Program Analysis of all variants one by one ##
################################################################################

We stay in the same folder ¨family_sketcher2¨ as for FamilySketcher2, we run the same example files, but now  
we use command-line option ¨-single¨ instead of ¨-tree¨. 

# Test

First examples
```
$ ./Main.native -single -domain polyhedra bench/loop1a-5.c 
```
or you can redirect the output to a .txt file by: 
```
$ ./Main.native -single -domain polyhedra bench/loop1a-5.c >> loop1a-5.txt
```
Detailed output: 
SUMMARY RESULTS report all correct variants and the corresponding ranking functions
Solutions with minimal ranking function 13 are: A=3 and B=0; A=4 and B=1; ...; A=31 and B=28
Total Time: 4.66 sec

$ ./Main.native -single -domain polyhedra bench/loop1b-5.c >> loop1b-5.txt
```
Detailed output: 
SUMMARY RESULTS report all correct variants and the corresponding ranking functions
Solutions (1) with minimal ranking function 4 are: A=0 and B=0; A=0 and B=1; ...; A=31 and B=31
Solutions (2) with minimal ranking function 7 are: A=1 and B=0; A=2 and B=1; ...; A=31 and B=30
Total Time: 4.77 sec



###########################################################################################
## Sketch 1.7.6 --- Program Sketcher available from https://people.csail.mit.edu/asolar/ ##
###########################################################################################

The tool can be downloaded either from https://people.csail.mit.edu/asolar/ or can be found here
as sketch-1.7.6.tar.gz. 

	$ cd Sketching2

* unzip the file sketch-1.7.6.tar.gz
	```
	$ tar -xf sketch-1.7.6.tar.gz
	```  
* copy ¨tests¨ folder to ¨sketch-1.7.6/sketch-frontend¨ 
	```
	$ cp -r ./tests ./sketch-1.7.6/sketch-frontend
	```	

# the following tools need to be installed: 
* bison and flex

	```
	$ cd lib
	$ cd bison
	$ sudo dpkg -i * 
	$ cd ..

	$ sudo dpkg -i flex_2.6.4-6.2_amd64.deb
	$ cd ..
	```

# under the sketch-1.7.6 directory, execute:
	```
	$ cd sketch-1.7.6
	$ cd sketch-backend
	$ chmod +x ./configure
	$ ./configure
	$ make
	$ cd ..
	```
	
# Testing the sketch
	```
	$ cd sketch-frontend
	$ chmod +x ./sketch
	$ ./sketch test/sk/seq/miniTest1.sk 
	```
	
# from "sketch-frontend" directory you can test all sketches. 
Note that we use the following ¨./sketch¨ options

option --bnd-cbits determines the size in bits of control holes [default is 5]
option --bnd-inbits determines the size in bits of inputs [default is 5]
option --bnd-unroll-amnt determines the unroll amount for loops [default is 8]

# Examples from the paper are in ¨tests¨ folder (copy 'tests' subfolder into 'sketch-1.7.6/sketch-frontend'): 	

# Test

First examples

```  (current folder: ~/Sketching2/sketch-1.7.6/sketch-frontend)
$ ./sketch --bnd-cbits 5 --bnd-inbits 5 --bnd-unroll-amnt 8 tests/loop1a.sk
```
Detailed output: 
Solution (optimal) is: ??_1=4 and ??_2=1 
Total Time: 0.192 sec   [* Note that Sketch reports the results in miliseconds]

```
$ ./sketch --bnd-cbits 5 --bnd-inbits 5 --bnd-unroll-amnt 11 tests/loop1b.sk
```
Detailed output: 
Solution (not optimal) is: ??_1=20 and ??_2=17 
Total Time: 0.203 sec  