User Guide for Build-Browser
----------------------------

Pre-Requisites: Python 2.6.6 or 2.7.* is already installed on the machine.
--------------

Assumptions:
-----------
1. C source files by '.c'  files.
2. The object files by '.o' files.
3. The machine description files by '.md' files.
4. The archive files by '.a'  files.
5. The assembler source files  by '.S'. 
6. The executable files do not have any extension.
7. The header files are excluded from considerations.


Program Manual
--------------
The Build-Browser Program,  bb.py, examines output of  make and generates dependancy tree(s) as the per the command line options.<\br>
         The output of the command
        
             $ ./bb.py -h
        
        is as follows:
        
        --------------------------------------------------------------------------
        Usage: ./bb.py [options] -s src_dir <log_filename>
        options
               -h, --help              show this help message
               -s, --source=src_dir       dir which will apprear as $SOURCE
               -r                      uses reverse mapping 
                                    from source -> target
               -i                     enter interactive search
               -o, --output=filename       output file name for -x and -t
               -t                      store the tree in output file
               -x                     store the XML format in a output file
               -x,-i and -t are mutually exclusive options
        
        default file name for -x is cc1.xml
        default file name for -t is cc1.txt
        log_filename is optional and by default it is make.log
        
                New Options:
               -g                       view generator executables (Requires bu-
        ild directory to search for generators) Supports -r, -i/-t/-x
               -b --build=build_dir       path to build directory which will be s-
        earched for generators and source files
               -e                      print executables generated.
        
        --------------------------------------------------------------------------
        
        Note the following:
        
        - Providing a complete path  with '-s' option is  mandatory. 
        - bb.py should be an executable file. Use the command 
          
          $ chmod u+x bb.py
        
          Alternatively, use the command
          
          $ python bb.py ...
        
        Recommendation is to  use bb.py with '-i' option to interactively identify the sources on which a given target depends.  In order to identify the targets which depend on a given source, use of  the '-r' option.

Examples:
--------

        Eg 1: Find out the source of the target "toplev.o" :--

	    Execute bb.py on the "make.log".
        
            $ ./bb.py -i -s $SOURCE make.log
        
            You will have to answer the  questions posed by bb.py. Remember this
            is an  interactive session, you  will have to enter  other commands,
            observe the results, till you are satisfied.
        
            As a special  case, if you enter "^cc1$" (without  quotes, there are
            just 5 characters  carrot-c-c-1-dollar) you will be able  to see the
            sources on which the target cc1 depends.

        Eg 2: List all '.c' files that depend on regex.o :--

            For the targets that depend on regex.o, we need 
	    to use the reverse mapping mode. The command will be:
        
            $ ./bb.py -r -i -s $SOURCE make.log
        
            (-r for reverse).
  
        
        Eg 3: Find out number of generator programs created :--
	    
	    For the generator executables, we need to use -g option (for showing
            generator files) with -b option to give path to build directory. The
            command will be:
        
            $ ./bb.py -i -g -b $BUILD -s $SOURCE make.log.
        
        
        Eg 4: Find dependency of cc1 upto 3 levels  which are present only 
              in one of the three stages and not in others :--


            For finding  differences in depedency among  the stages you have to 
            write the  expression for the stage in the interactive mode. For eg.
            if we want dependency  that only occurs  in first stage, expression 
            would be:
        
            1 and not 2 and not 3 and not p.