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 ≥ 17, Erlang/OTP 26, 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 ≥ 17 and Erlang/OTP 26

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 26

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 26, you should indicate the version of jinterface that matches the version of Erlang in your system.

1. Locate the directory in which Erlang is installed (typically /usr/lib/erlang). Other common locations are /usr/local/lib/erlang (admin-compiled), ~/.local/lib/erlang (user-compiled) and /usr/local/Cellar/erlang/VERSION/lib/erlang (Homebrew on macOS).
2. Enter the Erlang installation directory and look for a folder lib, and in it, a folder called jinterface-VERSION.
3. When running make commands, use:

make MVN_OPTIONS="-Djinterface.version=VERSION -Djinterface.erlangRoot=ERLANG_INSTALLATION"

The default values are VERSION=1.14 and ERLANG_INSTALLATION=/usr/lib/erlang.

With this change, you can now build the project with past and future versions of Erlang.

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):

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 17. 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 26. If you install a different version, you may need to follow the instructions above.