<commit_before>![Sulong Logo](https://raw.githubusercontent.com/mrigger/sulong-logos/master/sulong_black_with_text_transparent_300x185.png)

Sulong (Graal LLVM) is an interpreter for LLVM IR written in
Java using the Truffle language implementation framework and Graal as a
just-in-time (JIT) compiler.

With Sulong you can execute C/C++, Fortran, and other programs written
in a LLVM language on the JVM. To execute a program by Sulong, you have
to compile the program to LLVM IR by a LLVM front end such as Clang. By
using Truffle and Java the interpreter implementation is simple and is
thus a great platform for experimentation. On the other hand, dynamic
optimizations and JIT compilation with Graal still provides native
execution speed (improving performance is work in progress). Through
Truffle's language interoperability capabilities, you will soon be able
to call functions from/to other languages on Truffle such as Ruby,
JavaScript, or R.

The project bases on the LLVM IR parser of the
[llvm-ir-editor project](https://github.com/amishne/llvm-ir-editor)
by <NAME>.

External Dependencies
---------------------

Make sure you have GCC-4.6, G++-4.6, and GFortran-4.6 installed. For
a full list of external dependencies on Ubuntu you can look at our
[Travis configuration](https://github.com/graalvm/sulong/blob/master/.travis.yml).

On the Mac you can use Homebrew:

    brew tap homebrew/versions
    brew install gcc46 --with-fortran
    brew link --force gmp4

On some versions of Mac OS X, `gcc46` [may fail to install with a segmentation
fault](https://github.com/Homebrew/homebrew-versions/issues/515). A fix for this
is to `brew edit gcc46` and replace the patch `p0` with
[patch-10.10.diff](https://gist.githubusercontent.com/chrisseaton/7008085997269e3478e1/raw/46bff773d37914d6e66d0d8e1cab0d50d77e7280/patch-10.10.diff),
shasum `51814a0d79a9f21344c76f2d4235b59d9a4bc1601117e8ca5bfabdb82305aad0`.

However you install GCC on the Mac, you may then need to manually link the
gcc libraries we use into a location where they can be found, as
`DYLD_LIBRARY_PATH` cannot normally be set on the Mac.

    ln -s /usr/local/Cellar/gcc46/4.6.4/lib/gcc/4.6/libgfortran.3.dylib /usr/local/lib

How to get started?
-------------------

First create a new directory, which will contain the needed GraalVM
projects:

    mkdir graalvm
    cd graalvm

Then, download mx, which is the build tool used by Sulong:

    git clone https://github.com/graalvm/mx
    export PATH=$PWD/mx:$PATH

Afterwards, use git to clone the Sulong project and its dependencies:

    git clone https://github.com/graalvm/sulong

Next, build the project:

    cd sulong
    mx build

The mx tool will ask you to choose between its server and jvmci
configuration. For now, just select server. You can read the differences
between the configurations on
[the Graal wiki](https://wiki.openjdk.java.net/display/Graal/Instructions). The first
build will take some time because mx has not only to build Sulong,
but also its dependencies and the Graal VM.

Now, Sulong is ready to start. You can for example compile a C file named
`test.c` (see further below) with mx and then use Sulong to execute it:

    mx su-clang -S -emit-llvm -o test.ll test.c
    mx su-run test.ll

Libraries to load can be specified using the `-l` flag, as in a compiler:

    mx su-run -lz test.ll

If you want to use the project from within Eclipse, use the following
command to generate the Eclipse project files (there is also mx ideinit
for other IDEs):

    mx eclipseinit

If you want to inspect the command line that mx generates for a mx
command you can use the -v flag.

Sulong Library Files
--------------------

You can package LLVM bitcode and a list of library dependencies using the
`su-link` linker command to create a `.su` file which is easy to manage and
distribute. You can also specify other libraries to load when this library
is loaded using the `-l` flag:

    mx su-link -o test.su -lz test.ll

You can run this `.su` file directly and it will know to load dependencies that
you specified at link-time:

   mx su-run test.su

These `.su` files can be loaded wherever Sulong can load a native library.
For example we could create our own library `libhelper` and then load it when
running a program:

    mx su-link -o libhelper.su helper.ll
    mx su-run -lhelper main.ll
  
We can also reference our `.su` library when creating another `.su` library.
Our `libhelper` will then be loaded automatically as a dependency of
`libanotherhelper`, just as with native dynamic libraries.

    mx su-link -o libanotherhelper.su -lhelper anotherhelper.ll
    mx su-run -lanotherhelper main.ll<commit_msg>Remove README I didn't implement<commit_after>![Sulong Logo](https://raw.githubusercontent.com/mrigger/sulong-logos/master/sulong_black_with_text_transparent_300x185.png)

Sulong (Graal LLVM) is an interpreter for LLVM IR written in
Java using the Truffle language implementation framework and Graal as a
just-in-time (JIT) compiler.

With Sulong you can execute C/C++, Fortran, and other programs written
in a LLVM language on the JVM. To execute a program by Sulong, you have
to compile the program to LLVM IR by a LLVM front end such as Clang. By
using Truffle and Java the interpreter implementation is simple and is
thus a great platform for experimentation. On the other hand, dynamic
optimizations and JIT compilation with Graal still provides native
execution speed (improving performance is work in progress). Through
Truffle's language interoperability capabilities, you will soon be able
to call functions from/to other languages on Truffle such as Ruby,
JavaScript, or R.

The project bases on the LLVM IR parser of the
[llvm-ir-editor project](https://github.com/amishne/llvm-ir-editor)
by <NAME>.

External Dependencies
---------------------

Make sure you have GCC-4.6, G++-4.6, and GFortran-4.6 installed. For
a full list of external dependencies on Ubuntu you can look at our
[Travis configuration](https://github.com/graalvm/sulong/blob/master/.travis.yml).

On the Mac you can use Homebrew:

    brew tap homebrew/versions
    brew install gcc46 --with-fortran
    brew link --force gmp4

On some versions of Mac OS X, `gcc46` [may fail to install with a segmentation
fault](https://github.com/Homebrew/homebrew-versions/issues/515). A fix for this
is to `brew edit gcc46` and replace the patch `p0` with
[patch-10.10.diff](https://gist.githubusercontent.com/chrisseaton/7008085997269e3478e1/raw/46bff773d37914d6e66d0d8e1cab0d50d77e7280/patch-10.10.diff),
shasum `51814a0d79a9f21344c76f2d4235b59d9a4bc1601117e8ca5bfabdb82305aad0`.

However you install GCC on the Mac, you may then need to manually link the
gcc libraries we use into a location where they can be found, as
`DYLD_LIBRARY_PATH` cannot normally be set on the Mac.

    ln -s /usr/local/Cellar/gcc46/4.6.4/lib/gcc/4.6/libgfortran.3.dylib /usr/local/lib

How to get started?
-------------------

First create a new directory, which will contain the needed GraalVM
projects:

    mkdir graalvm
    cd graalvm

Then, download mx, which is the build tool used by Sulong:

    git clone https://github.com/graalvm/mx
    export PATH=$PWD/mx:$PATH

Afterwards, use git to clone the Sulong project and its dependencies:

    git clone https://github.com/graalvm/sulong

Next, build the project:

    cd sulong
    mx build

The mx tool will ask you to choose between its server and jvmci
configuration. For now, just select server. You can read the differences
between the configurations on
[the Graal wiki](https://wiki.openjdk.java.net/display/Graal/Instructions). The first
build will take some time because mx has not only to build Sulong,
but also its dependencies and the Graal VM.

Now, Sulong is ready to start. You can for example compile a C file named
`test.c` (see further below) with mx and then use Sulong to execute it:

    mx su-clang -S -emit-llvm -o test.ll test.c
    mx su-run test.ll

Libraries to load can be specified using the `-l` flag, as in a compiler:

    mx su-run -lz test.ll

If you want to use the project from within Eclipse, use the following
command to generate the Eclipse project files (there is also mx ideinit
for other IDEs):

    mx eclipseinit

If you want to inspect the command line that mx generates for a mx
command you can use the -v flag.

Sulong Library Files
--------------------

You can package LLVM bitcode and a list of library dependencies using the
`su-link` linker command to create a `.su` file which is easy to manage and
distribute. You can also specify other libraries to load when this library
is loaded using the `-l` flag:

    mx su-link -o test.su -lz test.ll

You can run this `.su` file directly and it will know to load dependencies that
you specified at link-time:

   mx su-run test.su
{'fraction_non_alphanumeric': 0.07770961145194274, 'fraction_numerical': 0.02772097250624858, 'mean_word_length': 3.704970603955104, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 16, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6452025', 'n_tokens_mistral': 2833, 'n_tokens_neox': 2641, 'n_words': 1204}