To obtain a pdf version of these instructions, click the ellipse (...) at the top right of this page, then select Export > Export to PDF.

Table of Contents

Information

The CodeMRI® executable cmri will create a Vault at your chosen location. Within the vault CMRI will designate Projects & Systems; projects being analogous to codebases and systems to snapshots. The source code will be stored in the project-system hierarchy. CMRI will also generate reports within the vault location.

Preface

Installation Instructions

1. Prepare for Install

• Create and or navigate to the directory in which CodeMRI® (CMRI) will be installed.

• Verify there is enough storage to install CMRI and store the codebases to be analyzed.

  • System storage can be revealed by typing df -h into the command line.

• If there is enough storage in the desired location, proceed to the installation.

2. Download & Install CodeMRI^® (CMRI)

2.1 Acquire CodeMRI^®(CMRI)

• Navigate to CodeMRI.com and sign In. If this is a new account, click sign up.  Navigate to your email client and validate the email. This email address will become the username for this account.

• Navigate to the Downloads page https://codemri.com/installers/ and Download the CodeMRI Platform - Linux ZIP File.

  • The CMRI Platform download link is protected, so you can't copy & paste the link from CodeMRI.com into the CLI.

  • Use a system that can browse CodeMRI.com, navigate to the Downloads page and download the CodeMRI Platform - Linux zip file.

  • Either physically move the zip to your Linux partition or copy it to your Linux partition or virtual machine using the scp command
    scp -r -i ~/path/to/<CMRI Platform zip filename> REMOTE_USERNAME@IP_ADDRESS:~/REMOTE_PATH

2.2 Unpack CodeMRI^®(CMRI)

• Navigate to the directory containing the CMRI Platform ZIP File & decompress the zip file using the command:
  $ unzip <CMRI Platform zip filename>

• Run setup.sh in the new CMRI Platform folder with using the command:
  $ ./setup.sh

a. At this point the installation process will begin.

• Read and type accept to accept the license agreement.

  • Upon completion, the following message should be displayed:
    CodeMRI is now installed and configured. Please reload your shell or log out then back in.
    You must log out and log in again to use CMRI.

3. Start CodeMRI^®

CMRI should now be operational, start Command Prompt and run the command cmri --help. You should see the following output on your terminal:

Welcome the CodeMRI(R) CLI Reference. The CodeMRI(R) Command-line Interface (CLI) provides an easy to use interface for administering and using your CodeMRI(R) product. To get started, see General Invocation.

Press q then enter to return to the terminal.

• Before using CMRI, you will need to create a vault. It's recommend to create a folder called “vault”.

  • Using CMRI in the installation directory will cause complications, you must create the vault in a different directory. 

  • Navigate to the directory where you want your vault to be created. Alternatively, specify the directory path using the --vault flag for the command below.

  • Run cmri vault create and answer the prompts given.

4. Log In

1. Log into CodeMRI® with your Silverthread account using the command account login.

   1. Enter the information associated with your CodeMRI.com account.

5. Scan Codebase

1. In order to scan your codebase, run the produce_reports job using the command job run produce_reports
   Several jobs will execute in order, processing the code and producing a set of xlsx spreadsheets. To view the final reports, navigate to your vault root. The reports can be found under the reports directory.
   Depending on the type of license you have, the produce_reports job may stop and ask for a license code even though you are logged in.

Once you receive the license code from Silverthread support, enter the code as instructed in the reply and re-run job run produce_reports.

Update from previous version

• Uninstall the existing CMRI Platform.

• Install the new version, using the installation guide above

  - Skip the process of creating a vault and logging in if there is an existing vault.

Glossary

• Benchmark: the top 20% of all comparable codebases, defined as those which are between half and twice the size of the scanned codebase.

• CMRI: the CodeMRI® executable.

• CodeMRI® Scanner: an application available for Windows that can generate metadata for a given codebase. Unlike Platform, scanner cannot generate analytics.

• CodeMRI® Platform: the full CMRI toolset.

• Component: a group of files defined as having some kind of related purpose. Components allow the user to manually express the defined architecture of their system. This allows CMRI to compare and analyze the similarities and differences of the actual codebase architecture with the theoretical architecture.

• Core: a cyclical group of files. Theoretically, a Core is any number of files n ≥ 2 in which the relationship of the system could be mapped as a self-contained loop. Emerging Cores are defined as Cores containing 30-150 files and have been proven to cause some financial and developmental impact. Severe Cores are defined as Cores with 150+ files and have been proven to impose significant negative impacts on the codebase.

• Design Structure Matrix (DSM): a visual representation of the hierarchical relationships of a codebase. Every file of the codebase is listed in order on both the x and y axes. The dots represent a direct relationship from the file on the y axis to the file on the x axis. A boxed group of dots indicates where a Core is hierarchically within the codebase. In a codebase with perfectly hierarchical architecture, all the dots would be below the diagonal; any dots above the diagonal are in violation of the optimal architecture. For further reading, go here.

• McCabe Complexity: a measure of the cyclomatic complexity of the code itself. Cyclomatic complexity typically refers to branches within the code in that code with excessive branching conditions will have higher complexity. Complex code is harder to understand and harder to test, making it confusing and fragile. Files with a McCabe complexity of 20-50 are defined as problematic and have been proven to cause some financial and developmental impact. Files with values of 50+ are said to have high complexity and have been proven to impose significant negative impacts on the codebase.

• Metadata: the file produced by scanning a codebase with the CodeMRI® Scanner. This file can then be scanned through the CodeMRI® Platform to produce diagnostic analysis of the codebase.

• Portfolio: an Excel file that contains a brief summary of the top-level health of a codebase.

• Project: a codebase or group of codebases that work together. Projects serve as a workspace to gather all the related systems/codebases you would like to scan and/or compare.

• Reports: the files and analytics produced by CMRI. They contain the diagnostic information regarding the health of the codebase including financial and timeframe metrics related to the impact of the codebase’s existing architectural design.

• System/Codebase: a snapshot of a project at a single point in time. 

• Technical Health Improvement Plan (THIP): an Excel document that details a series of steps determined by CMRI that provides the most efficient path to eliminate a Core from the scanned codebase. This includes metrics including the impact of each broken relationship, which files to locate the erroneous relationships, and more.

• Vault: a collection of one or more projects, containing a duplicate copy of scanned code, generated reports, and any other files produced by CMRI. The first step to starting CMRI in any directory is creating a Vault.

Customer Support

Phone: 800-674-9366 (9am - 5pm Eastern Time)

Email: support@silverthreadinc.com