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/).
* 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.
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](#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 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](#build).
#### 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"
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
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/
```
[credit]: https://stackoverflow.com/a/34326368
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
### 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.
<details><summary>Linux</summary>
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][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 24. If you install a different version,
you may need to follow [the instructions above](#i-cant-useinstall-erlangotp-24).
<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-jdk]: https://pkgs.org/search/?q=erlang
[erlang-solutions]: https://www.erlang-solutions.com/downloads