User Manual

There are 3 steps for setting up ActiveDocumentation.

• Installing srcML.
• Installing the plugin.
• Running the tool (Adding spmf.jar library and Running the web-app).

The browser or system might block the download or execution. When prompted, override the block to proceed.

1. Installing srcML

srcML is a foundational library used for parsing the code in the tool.

macOS

Install Homebrew if not installed.

1. Check if you have Homebrew installed, using the command brew -v
2. If you don’t have Homebrew in your system, install it using the instructions on the Homebrew website.
3. Add the path of brew to $PATH:

• If your laptop is Apple Silicon, run eval $(/opt/homebrew/bin/brew shellenv)
• Else, run eval $(/usr/local/bin/brew shellenv)

4. Close your terminal and re-open it after completing installing brew.

Create /usr/local/lib/ and /usr/local/bin/ directories if they do not exists.

1. Run ln /usr/local/lib

• If the output is ln: /usr/local/lib: Is a directory, then the directory exists.
• If the output is ln: /usr/local/lib: No such file or directory, then the directory does not exists and it should be created:
  • Run sudo mkdir -p -m 775 /usr/local/lib (enter your password when prompted)

2. Run ln /usr/local/bin

• If the output is ln: /usr/local/bin: Is a directory, then the directory exists.
• If the output is ln: /usr/local/bin: No such file or directory, then the directory does not exists and it should be created:
  • Run sudo mkdir -p -m 775 /usr/local/bin (enter your password when prompted)
  • Run command echo $PATH
  • If /usr/local/bin is not in the environmental variable, add it by running export PATH=$PATH:/usr/local/bin

3. If you created any directory, close your current terminal, and open a new one.

Install the following packages with Homebrew:

1. Install antlr2. Note that this library is disabled in brew, so, we need to take additional steps. Learn more.

• Run brew install antlr2 (there would be errors.)
• Run export HOMEBREW_NO_INSTALL_FROM_API=1
• Run brew edit antlr2 which will automatically download the repository
• Again run brew install antlr2 (there would be errors.)
• Again run brew edit antlr2 which will automatically edit the repository file using vim
• Type i to enable editing
• Find the line keg_only :versioned_formula add # in front of it to comment out the line
• Find the line disable! date: "xxxx", because: xxxx, add # before it to comment out this line (Note that xxx is a placeholder.)
• Click on the escape button and type :wq to save and exit edit
• Run HOMEBREW_NO_INSTALL_FROM_API=1 brew install antlr2

2. Install boost brew install boost
3. Install cmake brew install cmake

Download and unzip the srcML package for macOS from here.

1. Navigate to the unzipped downloaded package. cd srcML.
2. Run sudo cp lib/libsrcml.dylib /usr/local/lib (enter your password when prompted)
3. Run sudo cp bin/srcml /usr/local/bin

Check if srcML is installed correctly.

1. In terminal navigate to your desired directory.
2. Create and open a new java file by running vim mycode.java.
3. Type i to enable editing.
4. Type public class A {}.
5. Type :wq to save the changes and quit.
6. Run srcml mycode.java. You may receive a popup saying srcml is blocked.
7. You need to unblock the app:

• Open System Settings, Privacy & Security tab.
• Scroll down to the Security section.
• Look for the message "srcml" was blocked from use ... and click on Allow Anyway.
• Close your terminal and open a new one.

8. Again run srcml mycode.java. You may receive a popup saying libsrcml.dylib is blocked.
9. Again you need to unblock the app:

• Open System Settings, Privacy & Security tab.
• Scroll down to the Security section.
• Look for the message "libsrcml.dylib" was blocked from use ... and click on Allow Anyway.
• Close your terminal and open a new one.

10. Again run srcml mycode.java.
11. Check to see if the output is an xml text. The output would look like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<unit xmlns="http://www.srcML.org/srcML/src" revision="0.9.5" language="Java" filename="mycode.java"><class><specifier>public</specifier> class <name>A</name> <block>{}</block></class></unit>

12. [Optional step] Run rm mycode.java to delete the created java file.

Windows

Download and install srcML.

1. Download the installer for Windows: 32bit or 64bit.
2. Open the installation wizard to install srcML:

• Windows may block opening the wizard. Click on "More info" and then click on "Run anyway".
• Click on "Next", then "I Agree"
• Select "Do not add srcML to the system PATH" and click on "Next"
• Make sure the path that is selected for installation is C:\Program Files\srcML 0.9.5\. On Windows, this is likely not the default installation path, so be sure to change it if not.
• Select "Do not create shortcuts", and click on "Install"

3. After the installation is completed, add srcML path: (learn more)

• Open the Start Search, type in “env”, and choose “Edit the system environment variables”.
• Click the “Environment Variables…” button.
• Under the “System Variables” section (the lower half), find the row with Path in the first column, and click edit.
• The “Edit environment variable” UI will appear. Here, you can click “New” and type in C:\Program Files\srcML 0.9.5\bin.
• Dismiss all of the dialogs by choosing “OK”. Your changes are saved.

4. Close and re-open the terminal.
5. To test it, in the terminal run $env:PATH and check if C:\Program Files\srcML 0.9.5\bin exists in the output.

Troubleshooting

In the case that you install srcML, but run the console and get the error: Cannot run program “C:\Program Files\srcML 0.9.5\bin\srcml” Because the system cannot find the file specified In the bin folder there is a srcml.exe, it is likely that you have not:

• installed the right version of srcML 0.9.5, and/or
• installed srcML in the right path

Uninstall all places where srcML has been installed. Make sure you have the right srcML version. Follow the installation wizard and be sure to select the correct path for installation: "C:\Program Files\srcML 0.9.5".

Check if srcML is installed correctly.

1. In terminal, navigate to your desired directory.
2. Create a new java file by running notepad mycode.java.
3. In the opened note, type public class A {}.
4. Save the file and close the notepad.
5. In the terminal, run srcml mycode.java.
6. Check to see if the output is an xml text. The output would look like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<unit xmlns="http://www.srcML.org/srcML/src" revision="0.9.5" language="Java" filename="mycode.java"><class><specifier>public</specifier> class <name>A</name> <block>{}</block></class></unit>

7. [Optional step] Run del mycode.java to delete the created java file.

Linux

Download and Install srcML.

Download the proper file from http://131.123.42.38/lmcrs/beta/ and install it.

Troubleshooting

When installing srcML, you may encounter the following error message: srcml: error while loading shared libraries: libcrypto.so.1.1: cannot open shared object file: No such file or directory.

This issue may arise due to differences in OpenSSL versions on modern Linux systems. To resolve this problem, please follow these steps:

1. Download the required libssl package: wget http://nz2.archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2.19_amd64.deb

2. Install the downloaded package using dpkg (replace libssl1.1_1.1.1f-1ubuntu2.19_amd64.deb with the actual filename if it has changed): sudo dpkg -i libssl1.1_1.1.1f-1ubuntu2.19_amd64.deb

Ensure that you are using the most up-to-date .deb files.

Check if srcML is installed correctly.

1. Using any approach you like, create a Java file (for example, mycode.java) and write a sample Java code snippet (for example, public class A {}).
2. Save the Java file on your desired directory.
3. In terminal navigate to that directory.
4. Run srcml mycode.java.
5. Check to see if the output is an xml text. The output would look like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<unit xmlns="http://www.srcML.org/srcML/src" revision="0.9.5" language="Java" filename="mycode.java"><class><specifier>public</specifier> class <name>A</name> <block>{}</block></class></unit>

2. Installing the plugin

ActiveDocumentation is implemented for two IDEs; IntelliJ and Visual Studio (VS Code).

IntelliJ IDE

1. Download ActiveDocumentationPlugin.zip.

• ActiveDocumentationPlugin.zip is the plugin file (Do NOT unzip the file).

2. Install ActiveDocumentationPlugin.zip as instructed in the official website.

Visual Studio

To install the VS Code extension:

1. Update your IDE to the recent version as instructed on the official website.

• You can check to see if an update is available by choosing "Help" from the menu bar, and then choosing "Check for Updates".

1. Download activedoc-0.0.3.vsix.
2. Open VS Code.
3. Go to the Extensions view by clicking on the square icon on the sidebar or pressing Ctrl+Shift+X.
4. Click on the "..." menu at the top of the Extensions view and select "Install from VSIX...".
5. Navigate to the activedoc-0.0.3.vsix file, select it, and click "Open".
6. Watch for messages from the IDE in the bottom left corner indicating the successful installation.

3. Running the tool

1. Open your desired java projects in the IDE (IntelliJ or VS Code).

• Make sure only ONE project is open in the IDE.
• If more projects are open, close all and re-open one project.

2. Download spmf.jar.

• This file is a library which is essential for the process of extracting design rules from the codebase.

3. Copy spmf.jar to the root directory of the project.

• Note: spmf.jar should be added for all java projects you wish to work on.

4. Download the zipped package for the web-app.
5. Unzip the package.
6. Open index.html in the browser (preferably Chrome).

• If the web-app doesn't respond, refresh the web-app.

Notes

• If after mining design rules, no design rule is found, make sure spmf.jar files is correctly added to the root directory.
• If the IDE throws an error for websocket, Address already in use, close the IDE and wait for a few minutes, and open the IDE again. (This error is not relevant to the IDE, so clearing the cache is not effective.)