Grey Cubicles

Install CodeMRI On Linux

To obtain a pdf version of these instructions, click the ellipse (...) at the top right of this page.

 

Table of Contents

 

 

Information and System Requirements

The CodeMRI® executable CMRI will create a DataVault (folder).  CMRI will copy the codebase to be scanned to this vault, and the CodeMRI® reports it generates will be stored there.  The vault must have at least one project, which is a codebase or group of codebases that work together.  Each project must have at least one system, which is a snapshot of a project at a single point in time.

System Requirements for All CMRI Installations

  • 16GB RAM

  • 4 or more CPUs

  • 40GB available storage + 5GB per scan to be performed

  • Administrator access

 

Additional System Requirements for Linux Installations

  • Ubuntu LTS 14.04/16.04/18.04, Red Hat 7+, CentOS Linux 7+

 

Preface

CodeMRI® Platform (CMRI) is an installable command line utility for Windows and Linux that generates Silverthread CodeMRI® Care and/or Silverthread CodeMRI® Portfolio reports for software systems. It is intended for use on code bases of any size and generates reports in Microsoft Excel format. All instructions imply you are working in a command-line environment. 

 

 

Installation Instructions

Upgrade Notice

Prior to version 1.24.27, CodeMRI® Platform required a separate installation of Understand. Beginning with CodeMRI® Platform 1.24.27, this requirement has been lifted. You may uninstall Understand by removing the /opt/understand directory.

1. Prepare for Install

1.1. Create and or navigate to the directory in which CMRI will be installed.

1.2. Verify there is enough storage for CMRI and the duplicate codebase.

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. If you haven't already done so, navigate to CodeMRI.com and sign In. If this is a new account, click sign up.  Enter your email address and password.  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 CMRI Platform 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.

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

 

Installation will fail if the install path contains any spaces. 

Please be sure to extract the installer into a path whose name contains no spaces. For example, /opt/cmri. If the installation path contains any spaces, the installation may fail or CodeMRI may fail to work properly.

 

2.5 Decompress the zip file using the command:

$ unzip <CMRI Platform zip filename>

a. Use the command ls to display the name of the download.

b. 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. Please wait for the installation process to finish; it may take a few minutes depending on your machine's specifications.

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

******************** CodeMRI is now installed and configured. Please reload your shell or log out then back in. To launch the CodeMRI Platform, run "cmri".

2.9. You must reload your shell or log out then back in to use CMRI.

 

3. Start CodeMRI®

3.1. Navigate out of the CMRI directory and into the directory in which the vault will be placed.

 

a. Using CMRI in the installation directory will cause complications, you must navigate to a different directory. 

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

 

Use arrow keys or PageUp/PageDown to scroll. Press `q` to return to the CLI. CodeMRI CLI Reference ********************* 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.

 

a. Press q then enter to return to the terminal.

3.3. Before using your CMRI installation, you will need to create a vault. Run cmri vault create and answer the prompts shown below.

a. Contact information for vault creation does not need to match the license email.

Would you like to create a new vault here? (y/n)

 

y

 

What organization owns this vault? (Silverthread Client)

The Daystrom Institute

What is the group that owns this vault? (Engineering)

Software Management

Who is the primary contact for this vault? (John Doe)

Nyota Uhura

Where is the primary contact located? (Nowhere, OK) San Fransisco, CA

What is the primary contact's e-mail address? (unknown@silverthreadinc.com)

 

nuhura@daystrom.starfleet.fed

 

What is the primary contact's phone number? (000-000-0000)

477-477-4747

4 CPUs, 8903 MB of memory available. Defaulting to 2 workers.

Welcome to CMRI Development Platform v1.19.3.300.   Type help or ? to list commands. 

==================================

0 projects and 0 systems selected.

 

3.4. Create and select a project.

a. Start the shell by running cmri shell.

b. Use the project add command as shown below to add a new project. CodeMRI will select the project automatically after it is added.

 

> project add --name ProjectName

==================================

1 projects and 0 systems selected.

3.5. Create and select a system.

a. Use the system add command as shown below to add a new system. CodeMRI will select the system automatically after it is added:

 

> system add --name "MyProject" --version 47.0 --origin "/path/to/source_code.zip"

Successfully added new system to selected project(s). ==================================

1 projects and 1 systems selected.

 

 

 

4. Scan Codebase

4.1. Log into CMRI with your Silverthread account using the command account login.

      a. If you are running in an environment without Internet access, you may skip this step.

account login

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

4.3. Run the job produce_reports.

job run produce_reports

Several jobs will execute in order, processing the code and producing a set of Microsoft Excel Spreadsheets. To view the final reports, navigate to your vault root. The reports can be found in the vault root under the reports directory.

 

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 Pacific Time)

Email: support@silverthreadinc.com

 
 
 
 
 
 
 
 
 
 

©2020 by Silverthread, Inc. 

(617) 603-0075

(800) 674-9366