NiCad clone detection system, Version 7.0 (15 Jan 2024)
-------------------------------------------------------
Software Technology Laboratory, Queen's University
April 2010 (Revised Jan 2024)

Copyright 2011-2024, J.R. Cordy & C.K. Roy

This directory contains all of the parsers and tools necessary to
install and run the NiCad near-miss clone detection system.
NiCad should compile and run correctly on all Linux, MacOS systems,
as well as in Cygwin and Msys2 (MinGW) on Windows.

Installing and Running NiCad
----------------------------
NiCad can be installed on Ubuntu, Mac OS X, Cygwin, MinGW and other 
Unix-like systems with a GCC compiler and an OpenTxl distribution.

1. NiCad 7.0 requires that OpenTxl 11 or later be installed on your system.  
   OpenTxl can be downloaded from: 

      https://github.com/CordyJ/OpenTxl/releases

   Install OpenTxl 11 or later before proceeding.

2. NiCad optimizes by using precompiled TXL programs.  Use the command:

      make

   in this directory to compile all of the NiCad tools and TXL plugins 
   before using NiCad. 

3. (Installation-free option) NiCad requires no further installation for 
   personal use. If you are not planning to install NiCad globally for 
   everyone on your system, and just want to use it yourself in this 
   directory, you can stop here and move on to "Testing NiCad" below.

4. (Optional system installation option) To install NiCad permanently for 
   everyone on the computer (for example, if you have a research group 
   all working on the same compute server), use the command:

      sudo ./InstallNicad.sh 

Using NiCad
-----------

1. In a command line window, change directory to any writable directory
   where you intend to run NiCad. If you are using the installation-free 
   option and running NiCad in place, change to this directory.

      cd nicad

2. To run NiCad on a system or application, locate the root source directory
   of the system or application and run the nicad command on it, 
   specifying the analysis granularity and language of the system.

   For example, if you are using the installation-free option,

      ./bin/nicad functions java examples/JHotDraw default-report

   or if NiCad has been installed system-wide,

      nicad functions java examples/JHotDraw default-report

   NiCad can handle three granularities: files, functions and blocks.

   NiCad comes with plugins to handle systems with source files written in the 
   languages: C (.c), C# (.cs), Java (.java), Python (.py), PHP (.php), Ruby (.rb), 
   WSDL (.wsdl) and ATL (.atl). 

   Plugins for other languages can easily be added once you have a TXL grammar
   for the language.

3. Output from NiCad can be found in the ./nicadclones subdirectory of the directory
   where the nicad command is run. For example, results from the command shown above
   can be found in ./nicadclones/JHotDraw. 

   You can find the results in the system or application's clone results directory,
   e.g., ./nicadclones/JHotDraw/JHotDraw_functions--blind-clones for the command above.

   NiCad results are reported in three ways: as clone pairs in XML-like format,
   as clone classes in XML-like format (both with and without original sources), 
   and as browsable HTML pages with clone classes and original source for each clone.

   For the command above, the following results files will be created in the system
   or application's clone results directory:

      Clone pairs in XML-like format:
          JHotDraw_functions-blind-clones-0.30.xml

      Clone classes (clusters) in XML-like format:
          JHotDraw_functions-blind-clones-0.30-classes.xml

   If reports are specified in the configuration (as in "default-report" above)
   then the following additional results files will be created:

      Clone classes (clusters) with original sources for clones in XML-like format:
          JHotDraw_functions-blind-clones-0.30-classes-withsource.xml

      Clone classes (clusters) with original sources for clones as an HTML web-page report:
          JHotDraw_functions-blind-clones-0.30-classes-withsource.html

      The HTML web-page report can be opened and viewed in any standard web browser.

   The 0.30 (or equivalently, 0.00, 0.10, 0.20, ...) indicates the near-miss 
   difference threshold used by NiCad in the clone detection run, where 0.00 means 
   exact clones, 0.10 means at most 10% different pretty-printed lines, and so on.
   The default near-miss threshold is 0.30, as shown above.

4. NiCad supports a wide range of customized clone detection options including
   renaming, filtering, abstraction and custom normalization before comparison 
   using configuration files stored in the ./config subdirectory of the NiCad 
   installation directory.  To use a configuration, run NiCad giving the name of 
   the configuration as the last parameter on the command line.  

   E.g., to use the consistent renaming configuration with HTML web-page reporting,

      ./bin/nicad functions java systems/JHotDraw rename-consistent-report

   Or if NiCad is installed system-wide,

      nicad functions java systems/JHotDraw rename-consistent-report

   When using different configurations, the requested transformations will be 
   applied and the results reported in different results directory, e.g., 

      JHotDraw_functions-clones
      JHotDraw_functions-blind-clones
      JHotDraw_functions-consistent-clones
      JHotDraw_functions-blind-abstract-clones

   and so on.

   The default configurations ("default" and "default-report"), specify blind
   renaming with a near-miss threshold of 0.30, to aggressively find Type 3-2 clones.

4. To re-run NiCad on a system, for example with a different configuration,
   you can simply run the NiCad command on the system again:

       ./bin/nicad functions java systems/JHotDraw type2-report

   Or if NiCad is installed system-wide,

       nicad functions java systems/JHotDraw type2-report

   NiCad will optimize to avoid re-running extraction for the same granularity,
   so subsequent runs on the same system will be significantly faster.

   To remove all clone detection results and intermediate files to start over 
   and force a new extraction from the same system, run the command:

       ./bin/nicadclean JHotDraw 

   Or if NiCad is installed system-wide,

       nicadclean JHotDraw 

   To remove all results and intermediate files of all previous NiCad runs,
   use the command:
     
       ./bin/nicadclean

    or:
        nicadclean

NiCadCross
-----------
NiCadCross is the NiCad cross-clone detector.  It does an cross-system test 
- that is, given two systems s1 and s2, it reports only clones of fragments 
of s1 in s2.  This is useful in incremental clone detection for new versions, 
or for detecting clones between two systems to be checked for cross-cloning.

NiCadCross is run in much the same way as NiCad, but giving a second system
source directory on the command line, for example:

      ./bin/nicadcross functions java systems/JHotDraw54b1 systems/JHotDraw76a2 default-report

Results are stored in the first system's cross-clone results directory, 
e.g., ./nicadclones/JHotDraw541/JHotDraw541_functions-blind-crossclones for the command above.

Maintenance and Extension of NiCad
-----------------------------------
Maintaining or adding NiCad TXL plugins is easy - you just create the new
programs with appropriate names (see the ./txl subdirectory of the NiCad 
installation directory for examples), and NiCad will automatically allow
your new plugins to be used as normalizations or languages.

If you plan to change, maintain or recompile the NiCad clone comparison
tools themselves, you will require Turing+ 6.2 or later to be installed on your system.  
See the ./src/tools subdirectory of the NiCad source distribution for details.  

Turing+ can be downloaded from: 
 
      https://github.com/CordyJ/TuringPlus/releases

Rev 23.5.24