.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Makefile::Parser::GmakeDB 3pm"
.TH Makefile::Parser::GmakeDB 3pm "2011-10-01" "perl v5.12.4" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Makefile::Parser::GmakeDB \- GNU makefile parser using GNU make's database dump
.SH "VERSION"
.IX Header "VERSION"
This document describes Makefile::Parser::GmakeDB 0.215 released on 18 August 2011.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use Makefile::Parser::GmakeDB;
\&    my $db_listing = \`make \-\-print\-data\-base \-pqRrs \-f Makefile\`;
\&    my $ast = Makefile::Parser::GmakeDB\->parse(\e$db_listing);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module serves as a parser for \s-1GNU\s0 makefiles. However, it does not parse
user's original makefile directly. Instead it uses Makefile::DOM to parse
the \*(L"data base output listing\*(R" produced by \s-1GNU\s0 make (via its
\&\f(CW\*(C`\-\-print\-data\-base\*(C'\fR option). So essentially it reuses the C
implementation of \s-1GNU\s0 make.
.PP
This parser has been tested as a component of the pgmake-db utility and has successfully passed 51% of \s-1GNU\s0 make 3.81's official test suite.
.PP
The result of the parser is a makefile \s-1AST\s0 defined by Makefile::AST.
.PP
The \*(L"data base output listing\*(R" generated by \f(CW\*(C`make \-\-print\-data\-base\*(C'\fR is a detailed listing for \s-1GNU\s0 make's internal data structures, which is essentially the \s-1AST\s0 used by \f(CW\*(C`make\*(C'\fR. According to \s-1GNU\s0 make's current maintainer, Paul Smith, this feature is provided primarily for debugging the user's own makefiles, and it also helps the \s-1GNU\s0 make developer team to diagnose the flaws in make itself. Incidentally this output is conformed to the \s-1GNU\s0 makefile syntax, and a lot of important information is provided in the form of makefile comments. Therefore, my GmakeDB parser is able to reuse the Makefile::DOM module to parse this output listing.
.PP
The data base output from \s-1GNU\s0 make can be divided into several clearly-separated segments. They're file header, \*(L"Variables\*(R", \*(L"Files\*(R", \*(L"\s-1VPATH\s0 Search Paths\*(R", as well as the last resource stats information.
.PP
The contents of these segments are mostly obvious. The Files segment may deserve some explanation. It is the place for explicit rules.
.PP
Now let's take the Variables segment as an example to demonstrate the format of the data base listing:
.PP
.Vb 1
\&    # Variables
\&
\&    # automatic
\&    <D = $(patsubst %/,%,$(dir $<))
\&    # automatic
\&    ?F = $(notdir $?)
\&    # environment
\&    DESKTOP_SESSION = default
\&    # automatic
\&    ?D = $(patsubst %/,%,$(dir $?))
\&    # environment
\&    GTK_RC_FILES = /etc/gtk/gtkrc:/home/agentz/.gtkrc\-1.2\-gnome2
\&    # environment
\&    ...
.Ve
.PP
It's shown that the flavor and origin of the makefile variables are given in the previous line as comments. Hence feeding this back into \s-1GNU\s0 make again makes little sense.
.PP
Similarly, the Files segment for explicit rules also puts big amount of the important information into makefile comments:
.PP
.Vb 1
\&    # Files
\&
\&    # Not a target:
\&    bar.c:
\&    #  Implicit rule search has not been done.
\&    #  Modification time never checked.
\&    #  File has not been updated.
\&
\&    all: foo.o bar.o
\&    #  Implicit rule search has been done.
\&    #  File does not exist.
\&    #  File has not been updated.
\&    # variable set hash\-table stats:
\&    # Load=0/32=0%, Rehash=0, Collisions=0/0=0%
\&
\&    foo.o: foo.c
\&    #  Implicit rule search has not been done.
\&    #  Implicit/static pattern stem: \`foo\*(Aq
\&    #  File does not exist.
\&    #  File has not been updated.
\&    # variable set hash\-table stats:
\&    # Load=0/32=0%, Rehash=0, Collisions=0/0=0%
\&    #  commands to execute (from \`ex2.mk\*(Aq, line 8):
\&        $(CC) \-c $(CFLAGS) $< \-o $@
\&    ...
.Ve
.PP
From the previous two data base listing snippets, it's not hard to see that the variable references in rule commands and recursively-expanded variables's values are not expanded.
.PP
Experiments have shown that \s-1GNU\s0 make will do implicit rule search for the first rule that needs to, but no more. This behavior means testing our own implicit rule searching algorithm requires specifying at least two goals that require matching.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
.IP "\s-1GNU\s0 make 3.81" 4
.IX Item "GNU make 3.81"
At least the \fImake\fR executable of \s-1GNU\s0 make 3.81 is required to work with this module.
.IP "Makefile::DOM" 4
.IX Item "Makefile::DOM"
.SH "BUGS"
.IX Header "BUGS"
.PD 0
.IP "\(bu" 4
.PD
\&\s-1GNU\s0 make does not escape meta characters appeared in rule targets and prerequisites in its data base listing. Examples are \f(CW\*(C`:\*(C'\fR, \f(CW\*(C`\e\*(C'\fR, and \f(CW\*(C`#\*(C'\fR. This bug has been reported to the \s-1GNU\s0 make team as \f(CW\*(C`Savannah bug #20067\*(C'\fR.
.Sp
This bug has not yet been fixed on the \f(CW\*(C`make\*(C'\fR side, so I have to work around this issue by preprocessing the data base listing in the makesimple script.
.IP "\(bu" 4
The data base listing produced by \s-1GNU\s0 make lacks the information regarding the \f(CW\*(C`export\*(C'\fR and \f(CW\*(C`unexport\*(C'\fR directives. It gives rise to the lack of information in the resulting \s-1AST\s0 structures constructed by this module. Hence the current \s-1AST\s0 and runtime do not implement the \f(CW\*(C`export\*(C'\fR and \f(CW\*(C`unexport\*(C'\fR directives.
.Sp
To make it even worse, there's no known way to work around it.
.Sp
I've already reported this issue to the \s-1GNU\s0 make team as Savannah bug #20069.
.SH "CODE REPOSITORY"
.IX Header "CODE REPOSITORY"
For the very latest version of this script, check out the source from
.PP
http://github.com/agentzh/makefile\-parser\-pm <http://github.com/agentzh/makefile-parser-pm>.
.PP
There is anonymous access to all.
.SH "AUTHOR"
.IX Header "AUTHOR"
Zhang \*(L"agentzh\*(R" Yichun \f(CW\*(C`<agentzh@gmail.com>\*(C'\fR
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (c) 2005\-2008 by Zhang \*(L"agentzh\*(R" Yichun (agentzh).
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Makefile::AST, Makefile::AST::Evaluator, Makefile::DOM,
makesimple, pgmake-db.