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

Download installation scripts.

1. Open Terminal and run cd ~/Desktop (Or navigate to your desired directory).
2. Run mkdir macOS_installation_scripts.
3. Run cd macOS_installation_scripts.
4. Run curl -OL https://github.com/ourcodeinc/ActiveDocumentation-webapp/releases/download/v0.0.1/ActiveDocumentation-macOS_installation_scripts.zip. This command downloads the installer scripts.
5. Run unzip ActiveDocumentation-macOS_installation_scripts.zip

1. Install Homebrew if not installed.

1. Run ./1_install_homebrew.sh
2. Check for messages and errors.
3. Close your terminal and reopen it.

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

1. Run cd ~/Desktop/macOS_installation_scripts
2. Run ./2_create_directories.sh
3. Check for messages and errors.
4. Close your terminal and reopen it.

3. Install the required packages:

1. Run cd ~/Desktop/macOS_installation_scripts
2. Run ./3_install_libraries.sh
3. Check for messages and errors.

4. Install srcML.

1. Run ./4_install_srcml.sh
2. check for messages and errors.
3. Close your terminal and reopen it.

5. Check if srcML is installed correctly.

1. Run cd ~/Desktop/macOS_installation_scripts
2. Run ./5_test_srcml.sh
3. check for messages and errors.

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.)