home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / tools / analyze2 / analyze.doc next >
Text File  |  1987-01-28  |  13KB  |  463 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.                      C-SM  ANALYZE and MAINTENANCE PACKAGE
  8.  
  9.                     Copyright (C) Parvenu Systems  1986, 1987
  10.  
  11.  
  12.  
  13.  
  14.  
  15.         The ANALYZE package is a set of procedures and utilities which
  16.         simplify the development, documentation and maintenance of
  17.         'C' source code.
  18.  
  19.         Maintenance personnel needing to make changes or additions to an
  20.         existing package MUST have a way to find what functions are in
  21.         the package.
  22.  
  23.         Development personnel MUST be able to keep track of what functions
  24.         are done and in what file. A major desire of development personnel
  25.         is to avoid duplication of effort along the way, and to avoid
  26.         having to maintain 3 or 4 separate documents in parallel.
  27.  
  28.         The ANALYZE and HEADER utilities provide for these needs and
  29.         become particularly important as the number of files making up
  30.         the product grows larger.
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.                                 ANALYZE.EXE
  71.  
  72.  
  73.         analyze         synopsis:
  74.  
  75.          Description  : analyzes one or a list of files for the following:
  76.            1) function definitions
  77.            2) function calls
  78.            3) statistics of file[s] - chars, lines, comment percentage etc.
  79.            4) balance of 'fences' {}[]() .
  80.  
  81.            Will resolve references to called functions or macros whose
  82.            definitions appear in any of the analyzed files.  These may
  83.            include both .c and .asm source files and .h include files.
  84.            Procs from .asm files are assumed to conform to the leading
  85.            underscore ('_') naming convention required by MicroSoft 'C'
  86.            for linking.
  87.  
  88.            Output is to stdout. Usually redirected to file or printer
  89.  
  90.            Usage:
  91.  
  92.            Command options allow modified uses of the program for specific
  93.            uses.  Also allow user to analyze a list of files in convenient
  94.            ways. Option flags may appear in any order or in any place on
  95.            the command line and may be combined ie: -dsb  specifies 3 flags.
  96.  
  97.               -d                 prints only the [d]efined functions along
  98.                                  with the file name in which efined.  This
  99.                                  listing may then be sorted to make a
  100.                                  "function directory"
  101.  
  102.               -s                 Prints the statistical analysis of file[s].
  103.                                  Shows total files, lines, chars, and comment
  104.                                  to code percentage.
  105.  
  106.               -b                 Prints out any unbalances found.  Handles
  107.                                  braces, brackets, parenthesis, and both
  108.                                  single and double quotes.
  109.  
  110.                -f<filename>      Analyze each of the files found in a
  111.                                  'list file' where each file is named on a
  112.                                  separate line. Note no space following -f
  113.  
  114.                -m<make filename> Analyze each of the "dependant source files"
  115.                                  from the 'makefile' of the form required
  116.                                  by MicroSoft Make v. 4.x
  117.                                  Note no space following -m
  118.  
  119.                ?                 Lists the available options.
  120.  
  121.            Single or multiple filenames may be specified on the command line.
  122.                   wildcards are acceptable ie: *.c or a??.c
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.                                 HEADERS.EXE
  137.  
  138.  
  139.         headers         synopsis:
  140.  
  141.         description  :  Extract and print function headers.
  142.  
  143.         Headers and/or revision histories may be extracted from files
  144.         containing source code with function headers and revision
  145.         history info blocked out in a manner similar to the example
  146.         shown in appendix a.
  147.  
  148.         Output is to stdout - may be redirected to file or prn
  149.  
  150.         Format of the function headers is not critical.  The style may
  151.         be varied to suit individual taste.  The only requirements
  152.         are the 'trigger chars' which mark the start and end of each
  153.         block:
  154.            The first line of the function header must contain "*@H**"
  155.            The last line of the function header must contain "**@H*"
  156.            The first line of the revision history must contain "*@R**"
  157.            The last line of the revision history must contain "**@R*"
  158.  
  159.         Options available are:
  160.  
  161.          -f<filename>        Extract headers from the files found in a
  162.                              'list file' where each file is named on a
  163.                              separate line. Note no space following -f
  164.  
  165.          -m<make filename>   Extract headers from all the
  166.                              "dependant source files" from the 'makefile'
  167.                              of the form required by MicroSoft Make v. 4.x
  168.                              Note no space following -m
  169.  
  170.          -h                  Extract headers only - (default)
  171.          -r                  Extract revision history only
  172.          -b                  Extract headers & revision histories
  173.  
  174.           ?                  Lists the available options.
  175.  
  176.         Usage: headers [-fmhrb] [file1.c] [. . fileN.c]
  177.                wildcards are acceptable ie: *.c or a??.c
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.                      PROJECT DEVELOPMENT SUGGESTIONS
  203.  
  204.  
  205.         The analyze procedures may help with project development when
  206.         adopting some standards and using these procedures throughout
  207.         the project from start to finish as follows:
  208.  
  209.         1) During the design phase the module descriptions start the steps
  210.            which will carry through the entire project.
  211.  
  212.         2) During the initial coding phase each module is marked out by
  213.            using the standard module header shown below combined with
  214.            the module description from the design documentation.
  215.            When block marked and moved into the module header it becomes
  216.            the code module description.  This should not change if the
  217.            design was well thought out.
  218.  
  219.         3) The Standard Module Header includes a Revision History block
  220.            which should be maintained as a development history during
  221.            the coding and testing phase, and then following release may
  222.            become a true revision history for the module.
  223.  
  224.         4) Once the coding and debugging phase is underway and the number
  225.            of files is growing, the use of MAKE (tm) MicroSoft and
  226.            ANALYZE will begin to show its worth:
  227.  
  228.             a)  A list of the files (.c and .asm) source is made up.
  229.                 This file will contain 'target' and 'dependant' files
  230.                 and be your 'makefile'.
  231.  
  232.             b)  The ANALYZE utility is run using the 'defined' option:
  233.                    analyze -d -mmakefile > map.lst
  234.  
  235.             c)  The result ( map.lst ) will be a complete list of
  236.                 functions (and macros) defined, showing the filename
  237.                 in which they are defined.
  238.  
  239.             d)  The map output may then be sorted with DOS 'sort' command
  240.                 to make 'roadmaps' any way you want.
  241.                     sort < map.lst > fmap.lst   ( alphabetical by function )
  242.  
  243.            The resulting 'roadmaps' make it infinitely easier for development
  244.            team members to find any functions in the growing number of files.
  245.  
  246.            Perhaps more importantly this helps avoid duplication of effort
  247.            since it is no longer easier to 'write it yourself' than to find
  248.            out if it already exists!  It also eliminates most tendency to
  249.            make the source files into incredible monsters.
  250.  
  251.         5) ANALYZE has another capability which can be quite useful during
  252.            design work where an error in coding can not be spotted.
  253.            Although analyze should generally be run on source which has
  254.            been successfully compiled, running it with the -b (balance)
  255.            option can tell you if a problem stems from an unmatched brace
  256.            or parenthesis.  The compiler will also complain about these
  257.            things but not always specifically.
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.                         PROJECT DOCUMENTATION SUGGESTIONS
  269.  
  270.  
  271.            Finally the coding is done and tested!  Now the real work of
  272.            documentation and maintenance manuals begins.
  273.  
  274.            ANALYZE and HEADERS are used to produce the real meat of the
  275.            maintenance manual.
  276.  
  277.             a)  A final fmap.lst is made as in step 4 above.
  278.  
  279.             b)  The ANALYZE utility is run using the 'statistics' option:
  280.                    analyze -smmakefile > call.lst
  281.  
  282.             The results are the "function directory" as used during
  283.             development and a complete cross reference of defined and
  284.             called functions ( and the filename where the called
  285.             function resides ).
  286.  
  287.            And finally the Standard Module Header proves its mettle by
  288.            running the HEADER utility (using the same 'make' file).
  289.                    headers -mmakefile > prn
  290.  
  291.            This will extract the Standard Module Header from each function
  292.            definition giving valuable information about each function
  293.            such as:
  294.                calling sequence
  295.                description
  296.                warnings (if any)
  297.  
  298.            If desired the HEADER utility will extract the revision history
  299.            block separately or along with the Standard Module Header.
  300.  
  301.            All three of the outputs produced above correspond in structure
  302.            so personnel desiring to follow or find something have a very
  303.            desirable tool to do so.
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.                               APPENDIX  a.
  335.  
  336.  
  337.  
  338.         An example of some Standard Module Header layouts:
  339.  
  340.         For 'c' source code:
  341.  
  342.         /*@H**********************************************************
  343.          * DECLARATION.... new_function
  344.          * PARAMETERS..... parameter name and type
  345.          * RETURNS........ Type & values
  346.          * Entry
  347.          *   Conditions...
  348.          * EXTERNALS
  349.          *  -referenced...
  350.          *
  351.          *  -modified.....
  352.          *
  353.          * WARNINGS....... None
  354.          *
  355.          * SOURCE FILE.... Same
  356.          *
  357.          * DESCRIPTION....
  358.          *
  359.          *********************************************************@H*/
  360.  
  361.         /*@R**********************************************************
  362.          * Revision History - new_function
  363.          *
  364.          * Date       Engineer       Description
  365.          *                          Original release
  366.          *
  367.          *********************************************************@R*/
  368.  
  369.  
  370.          For assembly source code:
  371.  
  372.  
  373.          ;-*@H**-------------------------------------------------
  374.          ;    Name:   ... _new_funct
  375.          ;
  376.          ;    Entry:  ...
  377.          ;
  378.          ;    Exit:   ...
  379.          ;
  380.          ;    Notes:  ...
  381.          ;
  382.          ;    Desc:   ...
  383.          ;---------------------------------------------**@H*-----
  384.          ;-*@R**-------------------------------------------------
  385.          ;    Created:
  386.          ;
  387.          ;    Last update: ..
  388.          ;------------------------------**@R*---------------------
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.                                 APPENDIX b
  401.  
  402.  
  403.         Files on the diskette:
  404.            1) read.me           This file
  405.            2) analyze.exe       Executable analyze program
  406.            3) headers.exe       Executable header program
  407.            4) analyze.doc       Instructions and suggestions for use
  408.            5) fmap.bat          Batch file to make a "function directory"
  409.  
  410.         Files included if your package is registered:
  411.  
  412.           Source code to analyze:
  413.            1) analyze           Makefile for the analyze program
  414.            2) alz.c             Main source code file for analyze
  415.            3) anc.h             Include file for analyze
  416.            4) tokens.c          Tokenizer source code
  417.            5) tokens.h          Include file for tokenizer
  418.            6) type_t.def        Include file for tokenizer
  419.            7) statchar.c        Character reading and counting source
  420.            8) alzout.c          Reference resolution and printing source
  421.  
  422.           Source code to headers:
  423.            1) headers.c         Main source code file for headers
  424.  
  425.           Other files necessary to make executable files:
  426.            1) getargs.h         Include file for argument definitions
  427.                     Must reside in your INCLUDE directory for compiling.
  428.            2) getargs.obj       Argument processing code to link
  429.                     Must reside in your \obj directory for linking.
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.