Skip to content

Home

Jump to bottom
Sahar Mehrpour edited this page Sep 28, 2023 · 14 revisions

ActiveDocumentation is implemented as IntelliJ plugin. This tool has 2 components. The IDE connector and the Main component. The IDE connector must be installed as a plugin for IntelliJ. The Main component is a web-application and is executable in the browser.

Installing srcML

Install srcML version 0.9.5 from http://131.123.42.38/lmcrs/beta/

macOs

If the operating system is macOS and the installation failed with incompatible version errors, use the following instruction:

  1. Install the following packages with homebrew:
    • antlr2
    • boost
    • cmake
  2. Then from the El Capitan package (also available in this package), put the executable srcml file in /usr/local/bin and libsrcml.dylib in /usr/local/lib.

Windows

  1. Make sure you are installing srcML 0.9.5. The current srcML version is 1.0.0, so you will have to go to the "previous releases" link at the bottom of the "srcML Download" page.
  2. On Windows, use the installation wizard to install srcML.
  3. 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.

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

Linux

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.

To verify the successful installation of the correct version of srcml and check its version:

  1. Use the following command to list the installed srcml packages: apt list --installed | grep srcml

  2. To confirm whether srcml is correctly installed and functioning, run: srcml <supported_file_name>

Preparing the Environment for using the tool

Download the crowdCode source code to play with the app (learningDR branch): https://github.com/devuxd/CrowdCoding-ActiveDocumentation

There might be some errors in code (unknown libraries). As we are not going to run CrowdCode (at least for now), you can ignore them.

(Note the 3 files: ruleTable.json, tagTable.json, and spmf.jar)

Installing the IntelliJ plugin

Download the latest version of ActiveDocumentation plugin: https://github.com/devuxd/ActiveDocumentation/blob/version4-learning-DR/ActiveDocumentationPlugin.zip

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

Install ActiveDocumentationPlugin.zip as instructed in the official website. https://www.jetbrains.com/help/idea/managing-plugins.html#install_plugin_from_disk

After installing the plugin, the tool starts upon opening projects in the IDE.

Installing the Web App

Download the web app of ActiveDocumentation: (learningDR branch) https://github.com/devuxd/active-doc-client

Install the dependencies (node modules) for the app: npm install --legacy-peer-deps

Run the app:

  • Mac: npm run start-Mac
  • Linux: npm run start-Linux
  • Windows: npm run start-Windows

Notes

  • Only one project should be open in IntelliJ.
  • There should be 2 files in the root directory of the project: ruleTable.json and tagTable.json.
  • To work with mining rules, place a copy of spmf.jar in the root directory of the project.

Troubleshooting

Error in Chrome Possible solution
npm run start* takes too long to start Open active-doc-client project in Webstorm or Visual Studio (not IntelliJ) and run the script from the IDE terminal - Restart the system (to free ports)
The tool fails to connect to the IDE WebSocket connection to 'ws://localhost:8887/' failed: Error in connection establishment: net::ERR_CONNECTION_REFUSED Check if a project is open in IntelliJ - Restart IntelliJ - Restart the system (to free ports)
The tool doesn't show rules and tags Check the open project in the IDE - Restart the IDE and refresh the web app
The rules are shown, but no match or violation is detected Check whether srcML created the ASTs - Check the srcML version
The mined rules are not shown Check if srcMl works properly - Check if spmf.jar library exists in the root directory of the project
Clone this wiki locally