Makefile::Parser

SYNTAX SUPPORTED

The current parser implementation has been trying to support a common feature set of both MS NMAKE and GNU make. In the future, different formats of Makefiles will be handled by individual subclasses such as Makefile::Parser::Gmake.

Variable Definition

    MIN_T_FILES = $(PAT_COVER_FILES) t\optest.t t\my_perl.exe.t t\types.cod.t \
        t\catln.t t\exe2hex.t t\hex2bin.t t\bin2hex.t t\bin2asm.t t\ndisasmi.t \
        t\Idu.t t\pat_tree.t t\state_mac.t t\Idu-Util.t t\cidu.t \
        t\opname.t t\error.t t\operand.t t\01disasm.t t\02disasm.t t\03disasm.t \
        t\disasm_cover.t t\ndisasm.t
    T_FILES = t\main.cod.t t\bin2hex.exe.t t\hex2bin.exe.t $(MIN_T_FILES)
    DIRFILESEP = ^\
    

"Simply expanded" variables' definition syntax in GUN make is also supported:

    FOO := blah blah blah
    

which is considered invalid in Win32 NMake. "Recursively expanded" variables are currently treated as "simply expanded" variables.

Variable redefinition can be handled as well:

    CC = cl
    %.obj : %.c
        $(CC) /nologo /c $<
    CC = gcc
    %.o : %.c
        $(CC) -c $<
    

Variable expansion syntax

    ${abc}
    

is accepted, whereas Win32 NMAKE will complain about it.

Currently, environment variables defined in the command-line are not imported.

I have no idea what default value should be assigned to built-in variables like $(MAKE) and $(CC). Currently they will be left untouched if they're not set explicitly in the Makefile.

Due to the current implementation, expansion of unrecognized built-in variables and variables not previously defined by Makefile will NOT be performed. This behavior is different from any practical make tools, but is reasonable at this early stage of this parser.

Explicit Rules

    $(CIDU_DLL) : C\idu.obj C\idu.def
        link /dll /nologo /debug /out:$@ /def:C\idu.def C\idu.obj
    $(CIDU_LIB) : $(CIDU_DLL)
    C\idu.obj : C\idu.c C\idu.h
        cd C
        cl /nologo /c /I . idu.c
        cd ..
    smoke : all pat_cover t\pat_cover.t \
            t/pat_cover.ast.ast
        perl util\run-smoke.pl . smoke.html
        perl txt2html.pl t\*.t t\*.ast
    clean:
        copy t\pat_cover.ast.ast.html ..\ /Y
        $(RM_F) encoding.html encoding.pod state_mac.xml encoding.ast \
            pat_tree.ast state_mac.ast \
            main.cod pat_cover.pod pat_cover.html types.cod \
            hex2bin.exe hex2bin.obj
    

Special variable $@ will be expanded using its value in the context.

Implicit Rules

Substitution References

    objects = foo.o bar.o baz.o
    sources = $(objects:.o=.c)  # foo.c bar.c baz.c
    

Functions

Currently the following GNU make makefile builtin functions are supported:

Commands after ';'

    all : ; echo 'hello, world!'
    

Special variable $@ will be expanded using its value in the context.

For the list of features which will be added very soon, take a look at the "TODO" section.

METHODS

"$obj = Makefile::Parser->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()"

"$obj->parse($Makefile_name)"

"$obj->parse($Makefile_name, { var => value, ... })"

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.

You can also pass a hash reference to specify initial variables and their values. Note that these variables are treated as "defaults" so assignments in the makefile have higher priority.

"$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 Make.

"@vars = $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.

"@targets = $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.

"@roots = $obj->roots()"

The "roots" method returns the "root targets" in Makefile. The targets which there are 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 counter-intuitive. That's because there are some other targets depend on clean, test, or both.

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

PACKAGE VARIABLES

$Makefile::Parser::Strict

When this variable is set to true, the parser will sense syntax errors and semantic errors in the Makefile. Default off.

$Makefile::Parser::Debug

When this variable is set to true, the parser will enter Debug Mode. This variable is not supposed to be used directly by the user.

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.

"@prereqs = $obj->prereqs()"

You can get the list of prerequisites (or dependencies) for the current target. If no dependency is specified in the Makefile for the target, an empty list will be returned.

"@prereqs = $obj->depends()"

Alias to the "prereqs" method. This method is only preserved for the sake of backward-compatibility. Please use "prereqs" instead.

"$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.