SVGK Raju - 2016-05-05

Quality Lines of Code (qLoc)

Pre-requisites

  • PERL - Minimum version requirement is 5.20.2 for unix flavors and 5.20.2 build 809 MSI package for windows operating system.
  • NCSL - NCSL is included in the qLoc distribution and is extracted into the qLoc directory during installation.
  • Diff - Diff is expected to be available on the Unix machines. However, the Windows distribution of qLoc contains GNU diff utility.

Installation

  • Windows
    Unzip qLoc.zip

  • Redhat
    gunzip qLoc.tar.gz
    tar -xvf qloc.tar

  • For other OS
    Please ask by raising a request with Authors.

Upgrade

Take backup of existing qloc.conf and ncsl/specfile files (if required).
Unzip qLoc latest version as explained in Installation section based on your operating system
Replace newly installed qloc.conf and ncsl/specfile with the backup files (if required)

Running qLoc

qLoc can be executed by issuing the command "perl qloc.pl" provided perl is in the Path.

Base code count usage

perl qloc.pl [-listExtensions] [-countExtensions ext1 ext2 ...] [-X Extension] [-inputFiles dir1/file1 dir2/file2 ...] [-filesListInFile InputFile] [-out OutputFile] [-clearCase LabelName] [-ignore InputFile] [-debug Level] [-cleartoolPath Path] [-D] [-F] [-H] [-U] [-R] [-L] [-M] [-version] [-help]

Diff code count usage

perl qloc.pl -diff [-inputFiles dir1/file1 dir2/file2] [-clearCase LabelName1 LabelName2] [-countExtensions ext1 ext2 ...] [-X Extension] [-filesListInFile InputFile] [-out OutputFile] [-ignore InputFile] [-debug Level] [-diffBinPath Path] [-cleartoolPath Path] [-D] [-F] [-H] [-U] [-R] [-L] [-M] [-version] [-help]
-listExtensions
Print supported file extensions
-ncslLangList
Print supported languages by ncsl
-countExtensions ext1 ext2 ...
Count files with extensions ext1,ext2,... only. Extensions are case sensitive
-inputFiles dir1/file1 dir2/file2 ...
Root path of directories/files
-diff -inputFiles dir1/file1 dir2/file2 ...
Difference between two files or directories. Both must be of the same type either file or directory. This option values count must be an even number.
-clearCase LabelName
ClearCase Label name. Use this option for base code count. Specify atleast one of -inputFiles or -filesListInFile option
-diff -clearCase LabelName1 LabelName2
Diff between ClearCase Label names and it is known as ClearCase Label diff. Specify atleast one of -inputFiles or -filesListInFile option.
-filesListInFile InputFile
InputFile contains complete path of files/directories for which code count needs to be calculated. Each path need to be separated by a new line. If ClearCase label is used, specify root path of the files/directories from which code count is required.
-diff -filesListInFile InputFile
InputFile In case ClearCase label diff, InputFile contains root path of files/directories from which diff count is required. Each path need to be separated by a new line. Otherwise (for normal diff), InputFile contains pairs of complete path of files/directories for which diff count needs to be calculated. Path in each pair need to be separated by a new line.
-diff -inputFiles dir1/file1 dir2/file2 ...
Path of pairs of directories/files.
-ignore InputFile
InputFile contains complete path of directories/files that need to be ignored from the count. Each path need to be separated by a new line.
-X Extension
Default extension for files without any extension.
-diffBinPath Path
Path of the diff binary file. In unix flavors diff path will be taken from path environment variable. In windows it is part of the installation directory. Change this path if required by using this option.
-cleartoolPath Path
Path of the cleartool program. Specify this if cleartool command is not part of the path environment variable.
-out OutFile
Output file to store the code count details.
-debug Level
Debug level 1, 2, or 3.
-D Suppress Directory sums
-F Suppress File counts
-H Suppress headers
-U Count unknown file types
-R No recursive directory count needed. Do not specify with -clearCase option
-L No language based sums
-M Suppress Control-M characters before doing count.
-version
Print Version of this program
-help
Print this help message

qLoc output

5.1. Base code count output

The output of the base count contains Type, Path, LOC, eLOC, lLOC, Comments, Blanks, and Total Lines.

Type can be File, Directory, Total, or Extension. When the type is directory, it sums the count of all the files and sub-directories within that. If no recursion option is selected it will not count sub-directories.
Path gives the complete path of the file or directory.
LOC gives Lines of Code count and does not include comments and blank lines.
eLOC gives effective LOC count. eLOC counts only those lines with executable content. eLOC does not count standalone braces and parentheses in addition to blanks and comments.
lLOC gives Logical LOC count. This count is implemented only for languages like C, C++, Perl, and Java where the statement terminator is a semicolon.
Comments gives the total number of Comment lines.
Blanks gives total number of blank lines.
Total Lines gives total number of lines in a file or directory.

Diff code count output

Given two directories of files, qLoc can count number of lines that have been added, deleted, and modified.

Diff count expects two files/directories as arguments and it generates counts for the files specified in the second argument based on the changes made over the files specified in the first argument.

First argument should be the baseline and second argument should be the updated file/directory. If file is found only in the first argument, status of the file will be mentioned as "New". However, if a file is not found in the second argument, status would be marked as "Deleted" and counts will be specified for the files specified in the first argument.

The output of the diff contains Type, Status, Path, New eLOC, Deleted eLOC, Modified eLOC, Changed LOC, Changed eLOC, Changed lLOC

Status refers to New, Modified, Deleted, Identical, or Ignored with respect to file / directory.
New eLoc gives the eLOC of the added lines in the file or directory.
Deleted eLOC gives the eLOC of the deleted lines in the file or directory.
Modified eLOC gives the eLOC of the modified lines in the file or directory.
Changed LOC, eLOC, lLOC are counted by considering only added and modified lines. Deleted and unchanged lines are not considered for these.

To store the output and errors you can give the command as follows:
perl qloc.pl .... > loc.csv 2> loc.error
loc.csv contains the output and loc.error contains error information.

Restrictions
qLOC will not count the files/directories with names that start with "." or contains "$".
qLOC will not follow symbolic links in unix flavors.
Diff count does not give directory sums.
qLoc suppresses all comments, white spaces, and blank lines in both the files before doing diff.

Known Issues

  • If a symbolic link file/directory created in unix and mapped to a windows machine, perl for windows cannot identify it as a symbolic link and is included in the code count by qLoc. Use -ignore option to ignore such files/directories.
  • qLoc creates some temporary files during its execution. By default those temporary files will be created in the temporary directory "\tmp\qLoc (unix flavours) or %TEMP%\qLoc (windows)". If the temporary directory is not found those temporary files will be created inside the qLoc installation directory (<qloc installation="" dir="">/tmp. Upon successful completion of qLoc, those temporary files will be deleted automatically. Due to any reason if qLoc is terminated before its completion users need to delete those files manually. The set of temporary file names used are labelFiles, changeDiff, newDiff, delDiff, onlyChangeDiff, diffFile, cmFile, nc-src-file, enc-src-file, ncsl-outfile, fileName1, fileName2 where * is a number (PID).</qloc>
  • Blank lines embedded within comments are not counted properly by ncsl
  • If ncsl finds a long string in a file, sometimes it fails to process it.
  • Sometimes minor differences are seen between solaris diff and GNU diff utilities when consecutive lines contain same content.
 

Last edit: SVGK Raju 2016-05-05