e-Knife: Erlang slicing with the Expression Dependence Graph

You can find more details and contact information at the project's homepage. You can also test it through this website.

This project consists of three modules:

• e-Knife: the frontend for the EDG, which implements the necessary tools to slice Erlang programs.
• EDG: the generic library that implements the graph and slicing techniques.
• Miscellaneous: various shared utilities.

Build

Requirements: Java ≥ 11, Erlang/OTP 24, Maven and Make.

Just run make release to generate the zipped release e-knife-VERSION.zip. You'll also find it unzipped in the dist folder, ready to be run.

Run

Requirements: Java ≥ 11 and Erlang/OTP 24

The release version contains a jar file and a folder (ebin) with additional resources. It is important to keep them in the same directory.

You'll probably want to generate slices, so you should run e-Knife. Run it without args to obtain a list and explanation of arguments.

java -jar path/to/eknife.jar

For example, to slice test.erl with the slicing criterion 5, Res and save the slice to test-sliced.erl, you can use the following command:

java -jar path/to/eknife.jar -i test.erl -l 5 -v Res -o test-sliced.erl

View the sliced graph

To produce a graph, you must specify the optional argument -G.

In non-trivial programs, the graph can be too complicated to be useful. You can either:

1. Customize the arcs that are printed. To do so, modify the variables at the beginning of the DotFactory class in the EDG module, and then rebuild the project.
2. Output the graph to a dot file, and then manually delete unwanted arcs and/or use an interactive graphviz viewer, such as XDot.

Import into an IDE

In most Java IDEs you'll find an option to import an existing Maven project, and thus load the project structure and settings from the pom.xml files.

Otherwise, you can treat each folder (EDG, e-Knife and Miscellanea) as a separate module, with the following dependencies:

• e-Knife requires EDG and Miscellanea.
• EDG requires Miscellanea.
• Miscellanea has no dependencies.

You'll need to run make beams to compile the necessary Erlang files before running the program.

License

This project is licensed under GNU Affero Public License (Version 3.0), with the exception of the jinterface files, placed under e-Knife/src/com/ericsson, which are the property of Ericsson AB and are licensed under the Apache License (Version 2.0).

You should have received a copy of the GNU Affero Public License along with this program. If not, see https://www.gnu.org/licenses.

Troubleshooting

I can't use/install Erlang/OTP 24

Part of the process requires some communication with an Erlang process. To that end, the jinterface library must match the version of Erlang installed in your machine. If your installation of Erlang is not OTP 24, you should replace the bundled jinterface library with the one from your Erlang installation.

Before running make, you must replace the package com.ericsson.otp.erlang from e-Knife/src/main/java with the one that corresponds to your Erlang version. You can either copy the files from your local installation (if available) or download it from the OTP repository. After that, rebuild the project.

Copy jinterface from existing installation

Your Erlang distribution will most likely be installed at /usr/lib/erlang, /usr/local/lib/erlang, ~/.local/lib/erlang or /usr/local/Cellar/erlang/VERSION/lib/erlang. Then, the library is located in lib/jinterface-VERSION/java_src

In some distributions (such as Ubuntu), you may need to install the erlang-jinterface package.

As an example:

pkg="com/ericsson/otp/erlang"
erlang="/usr/lib/erlang"
rm -rf e-Knife/src/main/java/$pkg
mv $erlang/lib/jinterface-1.12/java_src/$pkg e-Knife/src/main/java/$pkg

Download jinterface from the repository

Check the version of OTP that you have installed by running the following snippet ([credit][so1]):

erl -eval '{ok, Version} = file:read_file(filename:join([code:root_dir(), "releases", erlang:system_info(otp_release), "OTP_VERSION"])), io:fwrite(Version), halt().' -noshell

Then, download the corresponding release:

VERSION=22.2.7
wget https://github.com/erlang/otp/archive/OTP-$VERSION.tar.gz

Finally, extract lib/jinterface-$ver/java_src to the corresponding location:

VERSION=22.2.7
pkg="com/ericsson/otp/erlang"
ji_path="lib/jinterface-1.10.1/java_src"
dest="e-Knife/src/main/java/$pkg"
rm -rf $dest
tar -xf OTP-$VERSION.tar.gz otp-OTP-$VERSION/$ji_path/$pkg
mv otp-OTP-$VERSION/$ji_path/$pkg $dest
rm -rf otp-OTP-$VERSION/

UnsupportedClassVersionError: eknife/EKnife has been compiled by a more recent version of the Java Runtime

e-Knife requires at least Java 11. Your version may be lower. You can check it by running java -version. To install a more modern version, check the instructions below, according to your operating system.

Cannot run program "erl": error=2, No such file or directory

You haven't installed Erlang, or it is not correctly setup to be available on your PATH. Please install Erlang/OTP 24. If you install a different version, you may need to follow the instructions above.