/ 
mpp-9
/ Scanner

NAME

Scanner - Base class for makepp file scanners

SYNOPSIS

use Scanner;
our @ISA = qw/Scanner/;
sub xscan_file {
  my $self=shift;
  my ($cp, $tag, $finfo, $conditional, $fh)=@_;
  while(<$fh>) {
    # ...
  }
}

DESCRIPTION

Scanner is a base class for makepp(1) file scanners. It supports both conditional scanning and unconditional scanning.

The scanner for a particular language should derive from this class. An object of this type is normally instantiated by an object of type CommandParser.

If unconditional scanning is used, then every include statement is considered active. This has the advantage that scanning is simpler, and that include directives are easily cached. However, it has the disadvantage of possibly creating incorrect dependencies. For example, in C the following lines should not affect the dependencies:

#if 0
# include "foo.h"
#endif

Also, the following should imply a dependency on foo.h, which should itself be scanned:

#define NAME "foo.h"
#include NAME

The reason that the include directives cannot easily be cached in conditional scanning is that the same file might include different things depending on what preceded it and what was defined on the command line. For the same reason, it is not possible to scan include files for the same translation in parallel if conditional scanning is employed (although that isn't done with unconditional scanning either right now).

METHODS

new

my $scanner = Scanner->new($rule, $dir, $conditional);

Returns a new Scanner for rule $rule. $dir is the directory name (relative to the CWD of $rule's Makefile) in which files are to be interpretted. $conditional is TRUE if conditional scanning is to be used, FALSE if not, and undef if it is to be determined from the rule options. The subclass may override this method, and may have different parameters.

add_include_dir

$scanner->add_include_dir($tag, $path);

Add directory $path (relative to $self->{DIR}) to the include path for tag $tag. Tags can be anything you want, as long as they are lowercase, for example "user" and "sys" for the C double-quote include path and angle-bracket include path, respectively.

An undefined $path represents the directory in which the file containing the include directive resides.

add_include_suffix

$scanner->add_include_suffix($tag, $suffix);

Append $suffix to the list of suffixes to append to the string naming the file to be included (i.e. the $name parameter of the include() method). The list starts as an empty array, but it defaults to ("") if a file is sought before any suffix is added. Directory search order takes precedence over suffix search order. [This is used by VCS, as well as a number of other Verilog-related tools.]

should_find

$scanner->should_find($tag);

Add include path tag $tag to the list of tags that should generate a warning if the requested file is not found. Not calling this is useful, for example, for C angle-bracket includes, wherein it is likely that the file won't be found because we don't know the entire standard system include path. It is assumed that files included from the system include path would not be included with double quotes, to avoid false warnings.

info_string

$scanner->info_string( $hashref );

Sets the build_info_string name associated with includes using the $tag include path to $name. For example, in C, "user" maps to "INCLUDES" and "sys" maps to "SYSTEM_INCLUDES".

NOTE: If you assign an info_string to any tag, then you need to assign info_string's to all the tags, or else the tags that aren't assigned will be ignored when the cached includes are used.

dont_scan

$scanner->dont_scan($finfo, $absname);

Returns 1 if the file $finfo should be scanned. $absname, if defined, must be $finfo's absolute filename.

Files that shouldn't be scanned typically include the system include files, as well as any files that are in a directory that can't be written by the current user. It is assumed that such files don't include other files that change between clean builds. This makes scanning go faster, and reduces the amount of "noise" emitted by makepp.

scan_file

$scanner->scan_file($command_parser, $tag, $name);

Check for cached dependencies of the file given by $name (relative to the current directory). If they are found, then add them to the dependency list, and either scan them recursively, or add them to the list of dependencies to scan later. Otherwise, delegate to $self->xscan_file().

Before this method returns sucessfully, all of the files that are included (possibly recursively) by the file will have been scanned.

The return value is TRUE on success, FALSE if any files to be scanned failed to build, or if scanning failed.

continue_scanning

$scanner->continue_scanning($command_parser);

Scan pending files. This is useful if include() is called after the last scan_file() call. Returns TRUE if and only if any files were scanned. Returns undef if and only if a file to be scanned failed to build, or if scanning failed.

xscan_file

$scanner->xscan_file($command_parser, $tag, $finfo, $conditional, $fh);

The derived class should define this to scan file handle $fh and report implicit dependencies by calling the include method.

If $conditional is FALSE, then the following methods may not be called:

push_scope
pop_scope

Also, is_active() is guaranteed to return TRUE, and include() is guaranteed not to call scan_file() recursively.

$fh is a file handle that is intially opened for reading at the beginning of the file to be scanned.

This method should be called only from scan_file() and not directly, because otherwise you have to check for cached includes yourself. Implemented by classes which inherit from this.

A FALSE return value is interpreted as a scanning failure.

find

$scanner->find($tag, $name, $src_dir);

Returns the FileInfo object associated with the location where $name is found, or undef if $name is not found. $tag is the include path tag, and $src is the source FileInfo, if any, or the source directory FileInfo.

add_dependency

$scanner->add_dependency($command_parser, $tag, $name, $src);

Similar to find, except that a dependency is added if the file is found. This is a simple dependency, as opposed to meta dependencies, which are created by calling include() or scan_file().

include

$scanner->include($command_parser, $tag, $name, $src);

Signals that an include file whose name is $name and whose type is $tag was requested, but only if $self->{ACTIVE} is TRUE. If the file is found, then a dependency is added to $self->rule and the FileInfo object of the file is returned. Otherwise, 1 is returned if the file is not found, or undef is returned if there was an error generating it or some other nested include file.

Whether this returns immediately or calls $self->xscan_file() recursively is not guaranteed. Currently, it is if and only if $self->{CONDITIONAL} is TRUE.

Whether this sets the build_info_string INCLUDE's of $name is not guaranteed. Currently, it does if and only if $self->{CONDITIONAL} is FALSE.

rule

my $rule=$scanner->rule;

Returns the rule object.

dir

my $dir=$scanner->dir;

Returns the dir name.

get_file_info

my $finfo=$scanner->get_file_info($name);

Returns the FileInfo object associated with $name relative to dir().

get_context

my $context=$scanner->get_context;

Returns a scalar representing the current scanning context, i.e. the variable settings and enclosing scopes. The format of this scalar is not guaranteed, but you can pass it to reset().

reset

$scanner->reset;
$scanner->reset($context);

Denotes the beginning of a new translation unit. Reset all variables, and sets $self->{ACTIVE} to TRUE. A Scanner object is guaranteed to be in the reset state on return from new(). If $context (from get_context()) is specified, then reset to that context instead of clearing everything.

set_var

$scanner->set_var($name, $value);

Sets the variable whose name in $name to $value, but only if $self->{ACTIVE} is TRUE.

get_var

my $value=$scanner->get_var($name);

Returns the value of the variable whose name is $name.

push_scope

$scanner->push_scope($act);

Push a new scope, and set $self->{ACTIVE} to $act if $self->{ACTIVE} is TRUE. A scope is typically introduced when a preprocessor conditional (e.g. #ifdef) is encountered, and the scope is inactive if its conditional evaluated false.

pop_scope

$scanner->pop_scope;

Reverse the most recent push_scope(). A scope is typically closed when a preprocessor conditional is terminated (e.g. with #endif). Returns $self->{ACTIVE} before popping.

is_active

my $act=$scanner->is_active;

Returns $self->{ACTIVE}. The current scope is active if and only if all enclosing scopes are active.

FUTURE WORK

One way to cache the scanning of include files with conditional scanning in force is to generate a rendition of the source file that has only the preprocessor directives in it, and scan that instead. That file can be kept up-to-date using makepp in the usual way (more or less). Then the amount of I/O required for scanning is then much less when the source file hasn't been modified. It may or may not be practical to store this in the build info structure.