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

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

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

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

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

2. Download & Install CodeMRI^® (CMRI)

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

2.2. Navigate to the Downloads page https://codemri.com/installers/

2.3. Download the CodeMRI Platform - Linux zip file

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

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

b. 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.4. Navigate to the directory containing the CMRI Platform zip file.

2.5 Decompress the zip file using the command:

$ unzip <CMRI Platform zip filename>

If there is no preexisting unzip program, run:

$ sudo apt-get install unzip

On Red Hat and CentOS platforms, you will need to install unzip, bzip2, and some X11 libraries

$ sudo yum install unzip bzip2 libxcb libXext ncurses-compat-libs

2.6. Run setup.sh in the new CMRI Platform folder with sudo using the command:

$ sudo ./setup.sh

a. At this point the installation process will begin.

2.7. Read and type accept to accept the license agreement.

2.8. Upon completion, the following message should be displayed:

CodeMRI is now installed and configured. Please reload your shell or log out then back in.

2.9. You must log out and log in again to use CMRI.

3. Start CodeMRI^®

3.1. Navigate to the directory in which the vault will be placed. It's recommend to create a folder called “vault”.

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.

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