Sunbelt Computer Software

The Seaflow compiler

Seaflow is a declarative language designed to address the asynchronous event 
conundrum by supporting some of the core principles of ReactiveX and reactive 
programming natively. Modern applications handle many asynchronous events, but 
it is difficult to model such applications using programming languages such as 
Java and JavaScript. One popular solution among the developers is to use 
ReactiveX implementations in their respective languages to architect event-driven 
reactive models. However, since Java and JavaScript are not designed for reactive 
programming, it leads to complex implementations where multiple programming 
styles are mixed-used.

It needs the OCaml llvm library, which is most easily installed through opam.

Install LLVM and its development libraries, the m4 macro preprocessor,
and opam, then use opam to install llvm.

The version of the OCaml llvm library must match the version of the LLVM
system installed on your system.

The stock C compiler compiles utils.o.  testall.sh runs the Seaflow
executable on each testcase (.flo file) to produce a .ll file, invokes
"llc" (the LLVM compiler) to produce a .s (assembly) file, then
invokes "cc" (the stock C compiler) to assemble the .s file, link in
utils.o, and generate an executable.  See testall.sh for details.
----------
If you get errors about llvm.analysis not being found, it's probably
because opam enviroment information is missing.  Either run

eval $(opam config env)

or run ocamlbuild like this:

opam config exec -- ocamlbuild <args>
------------------------------
Installation using Docker

* Install Docker on whatever operating system you're on

   Under Ubuntu,
   apt install docker.io

   You'll likely need to add yourself to the "docker" group:
  
   sudo usermod -aG docker <username>

   Log out and back in for this to take effect.  Run "groups" to
   make sure you're part of the "docker" group.

* Test your installation

   docker run hello-world

  If this fails, you will need to correct your installation.

* Move to where you unpacked the Seaflow source:

  cd seaflow

* Invoke docker

  docker run --rm -it -v ${PWD}:/home/seaflow -w=/home/seaflow columbiasedwards/plt

* Inside docker, compile Seaflow and run the regression tests:

  # make test
  ...
   test-arr-concat...OK
   test-arr1...OK
   test-arr10...OK
   test-arr11...OK
   test-arr12...OK
   test-arr13...OK
  ... etc

  # make clean

------------------------------
Installation under Ubuntu 20.04

Use LLVM 10. Install the matching version of the OCaml LLVM bindings:

sudo apt install ocaml llvm-10.0 llvm-10.0-dev llvm-runtime m4 opam
opam init
opam install llvm.10.0.0
eval `opam config env`

make
./testall.sh
------------------------------
Installation under Ubuntu 18.04

Use LLVM 9. Install the matching version of the OCaml LLVM bindings:

sudo apt install ocaml llvm-9 llvm-9-dev llvm-runtime m4 opam cmake
opam init
opam update
opam install llvm.9.0.0
eval `opam config env`

make
./testall.sh

------------------------------
Installation under Ubuntu 16.04

LLVM 3.8 is the default under 16.04. Install the matching version of
the OCaml LLVM bindings:

sudo apt install ocaml llvm llvm-runtime m4 opam cmake
opam init
opam install llvm.3.8
eval `opam config env`

make
./testall.sh

------------------------------
Installation under OS X

1. Install Homebrew:

   ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

2. Verify Homebrew is installed correctly:

   brew doctor

3. Install opam:

   brew install opam

4. Set up opam:

   opam init

5. Install llvm:

   brew install llvm

   Take note of where brew places the llvm executables. It will show
   you the path to them under the CAVEATS section of the post-install
   terminal output. For me, they were in /usr/local/opt/llvm/bin. Also
   take note of the llvm version installed. For me, it was 3.6.2.

6. Have opam set up your enviroment:

   eval `opam config env`

7. Install the OCaml llvm library:

   opam install llvm.3.6 

   Ensure that the version of llvm you install here matches the
   version you installed via brew. Brew installed llvm version 3.6.2,
   so I install llvm.3.6 with opam.

   IF YOU HAVE PROBLEMS ON THIS STEP, it's probably because you are
   missing some external dependencies. Ensure that libffi is installed
   on your machine. It can be installed with

   brew install libffi

   If, after this, opam install llvm.3.6 is still not working, try
   running

   opam list --external --required-by=llvm.3.6

   This will list all of the external dependencies required by
   llvm.3.6. Install all the dependencies listed by this command.

   IF THE PREVIOUS STEPS DO NOT SOLVE THE ISSUE, it may be a problem
   with using your system's default version of llvm. Install a
   different version of llvm and opam install llvm with that version
   by running:

   brew install homebrew/versions/llvm37
   opam install llvm.3.7

   Where the number at the end of both commands is a version different 
   from the one your system currently has.

8. Make sure testall.sh can access lli and llc
  
   Modify the definition of LLI and LLC in testall.sh to point to the absolute
   path, e.g., LLI="/usr/local/opt/llvm/bin/lli"

   - OR -

   Update your path, e.g.,
   
   export PATH=$PATH:/usr/local/opt/llvm/bin

   - OR -
   
   Create a symbolic link to the lli command:

   sudo ln -s /usr/local/opt/llvm/bin/lli /usr/bin/lli

   Create the symlink from wherever brew installs the llvm executables
   and place it in your bin. From step 5, I know that brew installed
   the lli executable in the folder, /usr/local/opt/llvm/bin/, so this
   is where I symlink to. Brew might install the lli executables in a
   different location for you, so make sure you symlink to the right
   directory.

   IF YOU GET OPERATION NOT PERMITTED ERROR, then this is probably a
   result of OSX's System Integrity Protection. 

   One way to get around this is to reboot your machine into recovery
   mode (by holding cmd-r when restarting). Open a terminal from
   recovery mode by going to Utilities -> Terminal, and enter the
   following commands:

   csrutil disable
   reboot
   
   After your machine has restarted, try the `ln....` command again,
   and it should succeed.

   IMPORTANT: the prevous step disables System Integrity Protection,
   which can leave your machine vulnerable. It's highly advisable to
   reenable System Integrity Protection when you are done by 
   rebooting your machine into recovery mode and entering the following
   command in the terminal:

   csrutil enable
   reboot

9. To run and test, navigate to the Seaflow folder. Once there, run

   make ; ./testall.sh

   Seaflow should build without any complaints and all tests should
   pass. However, error messages induced by failing tests may differ
   depending on your machine.

   IF RUNNING ./testall.sh FAILS ON SOME TESTS, check to make sure you
   have symlinked the correct executable from your llvm installation.
   For example, if the executable is named lli-[version], then the 
   previous step should have looked something like:

   sudo ln -s /usr/local/opt/llvm/bin/lli-3.7 /usr/bin/lli   

   As before, you may also modify the path to lli in testall.sh

------------------------------
To run and test:

$ make
ocamlbuild -use-ocamlfind -pkgs llvm,llvm.analysis -cflags -w,+a-4 seaflow.native
Finished, 22 targets (0 cached) in 00:00:01.
cc    -c -o utils.o utils.c
$ ./testall.sh
test-arr-concat...OK
test-arr1...OK
test-arr10...OK
test-arr11...OK
test-arr12...OK
...
fail-arr1...OK
fail-arr2...OK
fail-arr3...OK
fail-char1...OK