README file for the SourceProfiler (srcprof)
Copyright 1998-2015 by The Software Samurai
on the web:  http://www.SoftwareSam.us/
Software released under GPL3+, and documentation released under FDL1.3+
=======================================================================

Unpack this archive using the following command (see below for details):
                tar -xjvf srcprof-x.x.xx.tar.bz2

  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
This package contains the SourceProfiler (srcprof) source and documentation. 
SourceProfiler scans source code modules and analyzes the 'maintainability' 
of the code using the following data.
   a) total number of lines in the file
   b) number of source lines
   c) number of comment lines
   d) number of source lines with comments
   e) blank lines
   f) character count
   g) byte count

SourceProfiler is able to parse and analyze source code for the following languages:
   C, C++, Java, Javascript, Flash ActionScript, Objective-C, C#
   Assembler for Intel, Motorola, 8051, 68HC11, 68HC12 and similar,
   Python, Perl, shell scripts,
   Visual Basic, Texinfo, HTML, CSS
Support for additional programming languages and scripting languages is planned.

  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
The directory tree of files included in this SourceProfiler release 
is organized as follows.

SourceProfiler/         // Main application directory
   SrcProf.hpp          // SrcProf class definition and other definitions
   SrcProf.cpp          // Main SourceProfiler module
   SrcProf_File.hpp     // File manipulation definitions
   SrcProf_File.cpp     // File manipulation
   SrcProf_List.cpp     // Creating and formatting lists of filenames
   SrcProf_Analyze.cpp  // Source code analysis
   SrcProf_Dialog.cpp   // User interface based on the NcDialog API
   gString.cpp          // gString source. required only for Text-Mode-only build
   GlobalDef.hpp        // Global definitions and includes needed by all applications
                        //   based on the NcDialog API
   NcDialog.hpp         // NcDialog class definition
   NcWindow.hpp         // NcWindow class definition
   NCurses.hpp          // NCurses class definition
   NCursesKeyDef.hpp    // Keycode definitions
   gString.hpp          // gString class definition
   Makefile             // Makefile for building the application
                        //   (both Interactive and Text modes)
   Make_textonly        // Makefile for building the application (Text Mode only)

   README               // Package description, release notes (this file)
   VERSION_HISTORY      // Change log

   /Texinfo             // Directory containing documentation in Texinfo format
     srcprof.info       // NcDialog API documentation in 'info' format
     srcprof.html       // NcDialog API documentation in HTML format
     infodoc-styles.css // CSS style definition required by the HTML documentation

To read the full Texinfo documentation for this package, type: 
                   info -f srcprof.info
or even better, open the 'srcprof.html' file in your favorite browser.


  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
-- ========================================
-- Building the SourceProfiler application:
-- ========================================
               This is just a quick reference.
   See the SourceProfiler online documentation for full details.
   Open a terminal window and navigate to the documentation 
   directory.
            Example:  cd SourceProfiler/Texinfo
   Then open the documentation file to the installation chapter.
            info -f srcprof.info -n 'Building from Source'
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

   1) Open a terminal window.
   2) Navigate to the directory where you want to unpack the archive.
            (See tree structure of the archive above.)
   3) Copy the compressed archive to the target directory.
            Example: cp ~/Downloads/srcprof-0.0.18.tar.bz2
   4) Unpack the archive:
      a) If your target directory already contains an 'SourceProfiler' directory, 
         then rename it before unpacking the new archive.
            Example:  mv SourceProfiler SourceProfiler_OLD
      b) All contents of the compressed archive will be unpacked into a tree 
         whose base directory is 'SourceProfiler'. 
      c) Unpack the archive.
            tar -xjvf srcprof-x.x.xx.tar.bz2
   5) Navigate to the directory which contains the source code.
            cd SourceProfiler
   6) Build the application.
      a) Be sure that your compiler version is 4.8.0 or greater.
            g++ --version
      b) Be sure that the installed 'ncursesw' library version is 5.9 or 
         greater (dual-mode build).
            Example: ls -l /usr/lib64/libncursesw*
      c1) Build the application with both Interactive Mode and Text Mode.
          a) Open SrcProf.hpp.
          b) Set the COMM_LINE_ONLY conditional compilation flag to (0).
          c) Build the NcDialog API, available as a separate download.
          d) Copy the header files and the NcDialog.a library to the 
             SourceProfiler directory:
               gmake refreshlib
             (This assumes that the NcDialog and SourceProfiler directories
              are on the same level.
          e) Compile:
               gmake clean
               gmake
      c2) Build the application with only Text Mode.
          (ncursesw and NcDialog API not required)
          a) Open SrcProf.hpp.
          b) Set the COMM_LINE_ONLY conditional compilation flag to (1).
          c) Compile:
               gmake -f Make_textonly clean
               gmake -f Make_textonly
      d) The build should be clean with no errors and no warnings.
         If there are errors, then the most likely cause would be that the 
         compiler cannot find some necessary headers or cannot find the 
         'ncursesw' library. Check your LIB_PATH and other environment variables.
   7) Once you have a clean build, run the application.
      a) For dual-mode build:
            ./srcprof -i -a
               and
            ./srcprof -i -a
      b) For text-only build:
            ./srcprof -a
      c) If the application reports analysis for the SourceProfiler source code, 
         then build is complete.
      d) If the application does not run or reports errors, then verify that 
         all necessary libraries are installed on your system. Type the command:
            ldd srcprof
          This will tell you all the needed libraries.
   8) Copy the binary file to one of the directories on your search path.
      a) Display the search path:
            echo $PATH
      b) Choose the target directory and copy the binary file to it.
   9) Optionally install the online documentation.
      See the documentation for details.


  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
-- ===============================================
-- NOTES on the current release of SourceProfiler:  
-- ===============================================

-- Version 0.0.18: Released 29-Oct-2015
   -- Currently-supported source-data formats are fully functional.
   -- Documentation has been fully updated.
   -- Support for the following is not yet fully implemented:
      - PHP
      - Ruby
      - PL/SQL
      - additional languages as requested

   -- SourceProfiler is distributed with the build-option flag:
        #define COMM_LINE_ONLY (1)
      This means that the text-only-interface build is the default.

      -- Building 'srcprof' with the dual-mode interface requires the 
         NcDialog API. This is available from the author's website as a 
         separate download.
      -- After building the NcDialog API library, copy the required '.hpp' 
         files and the 'NcDialog.a' link library to the SourceProfiler 
         directory.
