Newer
Older
# 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/).
* 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.
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"
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
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.
<details><summary>Linux</summary>
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].
</details>
<details><summary>macOS</summary>
Follow [this guide][java-install-macos].
</details>
<details><summary>Windows</summary>
Download and install the Microsoft build (.msi) from [their site][w10-java-download].
</details>
[pkgs-jdk]: https://pkgs.org/search/?q=jdk
[java-install-macos]: https://mkyong.com/java/how-to-install-java-on-mac-osx/
[w10-java-download]: https://docs.microsoft.com/en-us/java/openjdk/download
### 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](#i-cant-useinstall-erlangotp-26).
<details><summary>Linux</summary>
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].
</details>
<details><summary>macOS</summary>
Use your favourite package manager:
* Homebrew: `brew install erlang`
* MacPorts: `port install erlang`
</details>
<details><summary>Windows</summary>
You can download the Erlang/OTP installer from [Erlang Solutions][erlang-solutions].
</details>
[pkgs-erlang]: https://pkgs.org/search/?q=erlang
[erlang-solutions]: https://www.erlang-solutions.com/downloads