1Makefile::Parser::GmakeUDsBe(r3)Contributed Perl DocumenMtaakteifoinle::Parser::GmakeDB(3)
2
3
4

NAME

6       Makefile::Parser::GmakeDB - GNU makefile parser using GNU make's
7       database dump
8

VERSION

10       This document describes Makefile::Parser::GmakeDB 0.216 released on 18
11       November 2014.
12

SYNOPSIS

14           use Makefile::Parser::GmakeDB;
15           my $db_listing = `make --print-data-base -pqRrs -f Makefile`;
16           my $ast = Makefile::Parser::GmakeDB->parse(\$db_listing);
17

DESCRIPTION

19       This module serves as a parser for GNU makefiles. However, it does not
20       parse user's original makefile directly. Instead it uses Makefile::DOM
21       to parse the "data base output listing" produced by GNU make (via its
22       "--print-data-base" option). So essentially it reuses the C
23       implementation of GNU make.
24
25       This parser has been tested as a component of the pgmake-db utility and
26       has successfully passed 51% of GNU make 3.81's official test suite.
27
28       The result of the parser is a makefile AST defined by Makefile::AST.
29
30       The "data base output listing" generated by "make --print-data-base" is
31       a detailed listing for GNU make's internal data structures, which is
32       essentially the AST used by "make". According to GNU make's current
33       maintainer, Paul Smith, this feature is provided primarily for debuging
34       the user's own makefiles, and it also helps the GNU make developer team
35       to diagnose the flaws in make itself. Incidentally this output is
36       conformed to the GNU makefile syntax, and a lot of important
37       information is provided in the form of makefile comments. Therefore, my
38       GmakeDB parser is able to reuse the Makefile::DOM module to parse this
39       output listing.
40
41       The data base output from GNU make can be divided into several clearly-
42       separated segments. They're file header, "Variables", "Files", "VPATH
43       Search Paths", as well as the last resource stats information.
44
45       The contents of these segments are mostly obvious. The Files segment
46       may deserve some explanation. It is the place for explict rules.
47
48       Now let's take the Variables segment as an  example to demonstrate the
49       format of the data base listing:
50
51           # Variables
52
53           # automatic
54           <D = $(patsubst %/,%,$(dir $<))
55           # automatic
56           ?F = $(notdir $?)
57           # environment
58           DESKTOP_SESSION = default
59           # automatic
60           ?D = $(patsubst %/,%,$(dir $?))
61           # environment
62           GTK_RC_FILES = /etc/gtk/gtkrc:/home/agentz/.gtkrc-1.2-gnome2
63           # environment
64           ...
65
66       It's shown that the flavor and origin of the makefile variables are
67       given in the previous line as comments. Hence feeding this back into
68       GNU make again makes little sense.
69
70       Similarly, the Files segment for explicit rules also puts big amount of
71       the important information into makefile comments:
72
73           # Files
74
75           # Not a target:
76           bar.c:
77           #  Implicit rule search has not been done.
78           #  Modification time never checked.
79           #  File has not been updated.
80
81           all: foo.o bar.o
82           #  Implicit rule search has been done.
83           #  File does not exist.
84           #  File has not been updated.
85           # variable set hash-table stats:
86           # Load=0/32=0%, Rehash=0, Collisions=0/0=0%
87
88           foo.o: foo.c
89           #  Implicit rule search has not been done.
90           #  Implicit/static pattern stem: `foo'
91           #  File does not exist.
92           #  File has not been updated.
93           # variable set hash-table stats:
94           # Load=0/32=0%, Rehash=0, Collisions=0/0=0%
95           #  commands to execute (from `ex2.mk', line 8):
96               $(CC) -c $(CFLAGS) $< -o $@
97           ...
98
99       From the previous two data base listing snippets, it's not hard to see
100       that the variable references in rule commands and recursively-expanded
101       variables's values are not expanded.
102
103       Experiments have shown that GNU make will do implicit rule search for
104       the first rule that needs to, but no more. This behavior means testing
105       our own implicit rule searching algorithm requires specifying at least
106       two goals that require matching.
107

DEPENDENCIES

109       GNU make 3.81
110           At least the make executable of GNU make 3.81 is required to work
111           with this module.
112
113       Makefile::DOM
114

BUGS

116       •   GNU make does not escape meta characters appeared in rule targes
117           and prerequisites in its data base listing. Examples are ":", "\",
118           and "#". This bug has been reported to the GNU make team as
119           "Savannah bug #20067".
120
121           This bug has not yet been fixed on the "make" side, so I have to
122           work around this issue by preprocessing the data base listing in
123           the makesimple script.
124
125       •   The data base listing produced by GNU make lacks the information
126           regarding the "export" and "unexport" directives. It gives rise to
127           the lack of information in the resulting AST structures constructed
128           by this module. Hence the current AST and runtime do not implement
129           the "export" and "unexport" directives.
130
131           To make it even worse, there's no known way to work around it.
132
133           I've already reported this issue to the GNU make team as Savannah
134           bug #20069.
135

CODE REPOSITORY

137       For the very latest version of this script, check out the source from
138
139       <http://github.com/agentzh/makefile-parser-pm>.
140
141       There is anonymous access to all.
142

AUTHOR

144       Zhang "agentzh" Yichun "<agentzh@gmail.com>"
145
147       Copyright (c) 2005-2008 by Zhang "agentzh" Yichun (agentzh).
148
149       This library is free software; you can redistribute it and/or modify it
150       under the same terms as Perl itself.
151

SEE ALSO

153       Makefile::AST, Makefile::AST::Evaluator, Makefile::DOM, makesimple,
154       pgmake-db.
155
156
157
158perl v5.38.0                      2023-07-20      Makefile::Parser::GmakeDB(3)
Impressum