# 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. Enter an Erlang shell with `erl` and check the version that shows at startup. 2. Look up the version of `jinterface` required by your version of Erlang/OTP on [this table](https://mist.dsic.upv.es/git/program-slicing/erlang-jinterface#usage). 3. When running `make` commands, use: ```bash make MVN_OPTIONS="-Djinterface.version=VERSION" ``` The default values can be seen at [e-Knife/pom.xml](e-Knife/pom.xml). With this change, you can now build the project with past and future versions of Erlang. #### The table in step 2 doesn't have a compatible version with my system! In that case, you can specify the location for `jinterface` in your system by editing `e-Knife/pom.xml`: ```xml <dependency> <groupId>program-slicing</groupId> <artifactId>erlang-jinterface</artifactId> <scope>system</scope> <version>VERSION</version> <systemPath>ERLANG_ROOT_PATH/lib/jinterface-VERSION/priv/OtpErlang.jar</systemPath> </dependency> ``` However, this means that `make` and `mvn package` commands won't include the `jinterface` jar, and you will have to launch e-Knife with: ``` java -cp e-Knife.jar:JINTERFACE_JAR eknife.EKnife [ARGUMENTS] ``` ### 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