Makefile::Parser - A Simple Parser for Makefiles

METHODS

The Makefile::Target Class

METHODS

EXPORT
CODE COVERAGE
BUGS
SEE ALSO
AUTHOR
COPYRIGHT AND LICENSE

NAME

Makefile::Parser - A Simple Parser for Makefiles

SYNOPSIS

  use Makefile::Parser;

  # Equivalent to ->new('Makefile');
  $parser = Makefile::Parser->new or
      die Makefile::Parser->error;

  # Get last value assigned to the specified variable 'CC':
  print $parser->var('CC');

  # Get all the variable names defined in the Makefile:
  @vars = $parser->vars;
  print join(' ', sort @vars);

  @roots = $parser->roots; # Get all the "root targets"
  print $roots[0]->name;

  @tars = $parser->targets;  # Get all the targets
  $tar = join("\n", $tars[0]->commands);

  # Get the default target, say, the first target defined in Makefile:
  $tar = $parser->target;

  $tar = $parser->target('install');
  # Get the name of the target, say, 'install' here:
  print $tar->name;

  # Get the dependencies for the target 'install':
  @depends = $tar->depends;

  # Access the shell command used to build the current target.
  @cmds = $tar->commands;

  # Parse another file using the same Parser object:
  $parser->parse('Makefile.old') or
    die Makefile::Parser->error;

  # Get the target who is specified by variable EXE_FILE
  $tar = $parser->target($parser->var('EXE_FILE'));

DESCRIPTION

This is a parser for Makefiles. At this very early stage, the parser only supports a very limited set of features, so it may not do what you expected. Currently its main purpose is to provide basic support for another module named the Makefile::GraphViz manpage, which is aimed to render the building processes specified by a Makefile using the amazing GraphViz library. The the Make manpage module is not satisfactory for this purpose, so I decided to build one of my own.

IMPORTANT! This stuff is highly experimental and is currently at ALPHA stage, so production use is strongly discouraged. Anyway, I have the plan to improve this stuff unfailingly.

The Makefile::Parser Class

This class provide the interface to the Makefile parser.

METHODS

$class->new()

It's the constructor for the Parser class. You may provide the path of your Makefile as the argument which . It is worth mentioning that the constructor will not call ->parse method internally, so please remember calling ->parse after you construct the parser object.

$obj->parse(Makefile-name)

This method parse the specified Makefile (default to 'Makefile').

When an error occurs during the parsing procedure, ->parse will return undef. Otherwise, a reference to Parser object itself is returned. It is recommended to check the return value every time you call this method. The detailed error info can be obtained by calling the ->error method.

$obj->error

It returns the error info set by the most recent failing operation, such as a parsing failure.

$obj->var($variable_name)

The var method returns the value of the given variable. Since the value of variables can be reset multiple times in the Makefile, so what you get is always the last value set to the variable. It's worth noting that variable reassignment can be handled appropriately during parsing since the whole parsing process is a one-pass operation compared to the multiple-pass strategy used by the CPAN module the Make manpage.

$obj->vars

This will return all the variables defined in the Makefile. The order may be quite different from the order they appear in the Makefile.

$obj->target($target_name)

This method returns a Makefile::Target object with the name specified. It will returns undef if the rules for the given target is not described in the Makefile. It is worth noting that only targets with a definition body will be considered as a target here.

When $target_name is omitted, this method will return the default target, say, the first target defined in Makefile, to the user. This can be handy if you try to build a make tool on top of this module.

It is important not to send something like ``$(MY_LIB)'' as the target name. Only raw values are acceptable. If you really want to do something like this, please use the following code:

    my $tar = $parser->target($parser->var('MY_LIB'));

but this code will break if you have reassigned values to variable MY_LIB in your Makefile.

$obj->targets

This returns all the targets in Makefile. The order can be completely different from the order they appear in Makefile. So the following code will not work if you want to get the default target (the first target):

    @tars = $parser->targets;
    print $tars[0];

Please use the following syntax instead:

    print $parser->target;

The type of the returned list is an array of Makefile::Target objects.

$obj->roots

The ->roots method returns the ``root targets'' in Makefile. The targets which there're no other targets depends on are called the root targets. For example, install, uninstall, and veryclean are all root targets in the Makefile generated by the ExtUtils::MakeMaker module. On the other hand, clean and test are not, which may be somewhat counterintuitive. That's because there're some other targets depend on clean, test, or both.

The type of the returned list is an array of Makefile::Target objects.

The Makefile::Target Class

This class overloads the ``'' operator so its instances can be automatically converted to strings using their names.

METHODS

$class->new($target_name, $colon_type)

This is the constructor for class Makefile::Target. The first argument is the target name which can't be a Makefile variable, the second one is a single colon or a double colon which is used by the rule definition in Makefile.

This method is usually called internally by the Makefile::Parser class. It doesn't make much sense to me if the user has a need to call it manually.

$obj->name

It will return the name of the current Target object.

$obj->depends

You can get the list dependencies for the current target. If no dependencies are specified in the Makefile for the target, an empty array will be returned.

$obj->commands

This method returns a list of shell commands used to build the current target. If no shell commands is given in the Makefile, an empty array will be returned.

EXPORT

None by default.

CODE COVERAGE

I use the Devel::Cover manpage to test the code coverage of my tests, below is the the Devel::Cover manpage report on this module test suite.

    ---------------------------- ------ ------ ------ ------ ------ ------ ------
    File                           stmt   bran   cond    sub    pod   time  total
    ---------------------------- ------ ------ ------ ------ ------ ------ ------
    blib/lib/Makefile/Parser.pm   100.0   95.5   87.1  100.0  100.0  100.0   97.3
    Total                         100.0   95.5   87.1  100.0  100.0  100.0   97.3
    ---------------------------- ------ ------ ------ ------ ------ ------ ------

BUGS

Please feel free to report bugs or send your wish-list to http://rt.cpan.org/NoAuth/Bugs.html.

AUTHOR

Agent Zhang, <agent2002@126.com>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Makefile::Parser - A Simple Parser for Makefiles