# e-Knife: Erlang slicing with the Expression Dependence Graph
You can find more details and contact information at the project's [homepage](https://kaz.dsic.upv.es/e-knife/). You can also test it through [this website](https://mist.dsic.upv.es/e-knife-constrained/).
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](#build).
2. Output the graph to a dot file, and then manually delete unwanted arcs and/or
use an interactive graphviz viewer, such as [XDot][xdot].
[xdot]: https://github.com/jrfonseca/xdot.py
## 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:
```bash
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:
```bash
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]):
```bash
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:
```bash
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:
```bash
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/
```
[so1]: https://stackoverflow.com/a/34326368
### 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.
Linux
Search your package manager for a JDK (typically `openjdk`) with at least version 17.
If you don't know how to search or install packages, you can check [pkgs.org][pkgs-jdk].
macOS
Follow [this guide][java-install-macos].
Windows
Download and install the Microsoft build (.msi) from [their site][w10-java-download].
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][erlang-solutions].