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:
- Customize the arcs that are printed. To do so, modify the variables at the
beginning of the
DotFactory
class in theEDG
module, and then rebuild the project. - 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.
Linux
Search your package manager for a JDK (typically openjdk
) with at least version 11.
If you don't know how to search or install packages, you can check pkgs.org.
macOS
Follow this guide.
Windows
Download and install the Microsoft build (.msi) from their site.
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.
Linux
Install the package erlang
with the package manager included in your system.
If you don't know how to install packages, you can check [pkgs.org][pkgs-erlang].
macOS
Use your favourite package manager:
- Homebrew:
brew install erlang
- MacPorts:
port install erlang
Windows
You can download the Erlang/OTP installer from Erlang Solutions.