1Makefile::Parser(3) User Contributed Perl Documentation Makefile::Parser(3)
2
6 Makefile::Parser - A simple parser for Makefiles
7
9 This document describes Makefile::Parser 0.211 released on March 16,
10 2008.
11
13 use Makefile::Parser;
14 $parser = Makefile::Parser->new;
16 # equivalent to ->parse('Makefile');
18 $parser->parse or
19 die Makefile::Parser->error;
20 # get last value assigned to the specified variable 'CC':
22 print $parser->var('CC');
23 # get all the variable names defined in the Makefile:
25 @vars = $parser->vars;
26 print join(' ', sort @vars);
27 @roots = $parser->roots; # Get all the "root targets"
29 print $roots[0]->name;
30 @tars = $parser->targets; # Get all the targets
32 $tar = join("\n", $tars[0]->commands);
33 # get the default target, say, the first target
35 # defined in Makefile:
36 $tar = $parser->target;
37 $tar = $parser->target('install');
39 # get the name of the target, say, 'install' here:
40 print $tar->name;
41 # get the dependencies for the target 'install':
43 @depends = $tar->depends;
44 # access the shell command used to build the current target.
46 @cmds = $tar->commands;
47 # parse another file using the same Parser object:
49 $parser->parse('Makefile.old') or
50 die Makefile::Parser->error;
51 # get the target who is specified by variable EXE_FILE
53 $tar = $parser->target($parser->var('EXE_FILE'));
54
56 This is a simple parser for Makefiles. At this very early stage, the
57 parser only supports a limited set of features, so it may not recognize
58 most of the advanced features provided by certain make tools like GNU
59 make. Its initial purpose is to provide basic support for another
60 module named Makefile::GraphViz, which is aimed to render the building
61 process specified by a Makefile using the amazing GraphViz library. The
62 Make module is not satisfactory for this purpose, so I decided to build
63 one of my own.
64 WARNING!!! This stuff is highly experimental and is currently at pre-
66 alpha stage, so production use is strongly discouraged. Right now it's
67 just a toy for parsing trivial makefiles.
68 IMPORTANT!!! If you're looking for something more serious for parsing
70 GNU makefiles, please see Makefile::Parser::GmakeDB instead. The
71 GmakeDB parser has passed 51% of GNU make's official test suite as of
72 this writing.
73 If you're looking for something that can parse makefiles losslessly,
75 take a look at the Makefile::DOM module which may fit your needs.
76 SYNTAX SUPPORTED
78 The current parser implementation has been trying to support a common
79 feature set of both MS NMAKE and GNU make. In the future, different
80 formats of Makefiles will be handled by individual subclasses such as
81 Makefile::Parser::Gmake.
82 Variable Definition
84 MIN_T_FILES = $(PAT_COVER_FILES) t\optest.t t\my_perl.exe.t t\types.cod.t \
85 t\catln.t t\exe2hex.t t\hex2bin.t t\bin2hex.t t\bin2asm.t t\ndisasmi.t \
86 t\Idu.t t\pat_tree.t t\state_mac.t t\Idu-Util.t t\cidu.t \
87 t\opname.t t\error.t t\operand.t t\01disasm.t t\02disasm.t t\03disasm.t \
88 t\disasm_cover.t t\ndisasm.t
89 T_FILES = t\main.cod.t t\bin2hex.exe.t t\hex2bin.exe.t $(MIN_T_FILES)
90 DIRFILESEP = ^\
91 "Simply expanded" variables' definition sytax in GUN make is also
93 supported:
94 FOO := blah blah blah
96 which is considered invalid in Win32 NMake. "Recursively expanded"
98 variables are currently treated as "simply expanded" variables.
99 Variable redefinition can be handled as well:
101 CC = cl
103 %.obj : %.c
105 $(CC) /nologo /c $<
106 CC = gcc
108 %.o : %.c
110 $(CC) -c $<
111 Variable expansion sytax
113 ${abc}
115 is accepted, whereas Win32 NMAKE will complain about it.
117 Currently, environment variables defined in the command-line are
119 not imported.
120 I have no idea what default value should be assigned to built-in
122 variables like $(MAKE) and $(CC). Currently they will be left
123 untouched if they're not set explicitly in the Makefile.
124 Due to the current implementation, expansion of unrecognized built-
126 in varaibles and variables not previously defined by Makefile will
127 NOT be performed. This behavior is different from any practial make
128 tools, but is reasonable at this early stage of this parser.
129 Explicit Rules
131 $(CIDU_DLL) : C\idu.obj C\idu.def
132 link /dll /nologo /debug /out:$@ /def:C\idu.def C\idu.obj
133 $(CIDU_LIB) : $(CIDU_DLL)
135 C\idu.obj : C\idu.c C\idu.h
137 cd C
138 cl /nologo /c /I . idu.c
139 cd ..
140 smoke : all pat_cover t\pat_cover.t \
142 t/pat_cover.ast.ast
143 perl util\run-smoke.pl . smoke.html
144 perl txt2html.pl t\*.t t\*.ast
145 clean:
147 copy t\pat_cover.ast.ast.html ..\ /Y
148 $(RM_F) encoding.html encoding.pod state_mac.xml encoding.ast \
149 pat_tree.ast state_mac.ast \
150 main.cod pat_cover.pod pat_cover.html types.cod \
151 hex2bin.exe hex2bin.obj
152 Specital variable $@ will be expanded using its value in the
154 context.
155 Implicit Rules
157 Pattern Rules
158 %.obj : %.asm
159 masm /t $<;
160 %.exe : %.obj
162 link /BATCH /NOLOGO $<;
163 The special varaibles $< and $* will be expanded according to
165 the context.
166 Old-Fashioned Suffix Rules
168 Currently only double-suffix rules are supported:
169 .SUFFIXES: .obj .asm .exe
171 .asm.obj :
173 masm /t $<
174 .obj.exe :
176 link /nologo $<
177 At this moment, .SUFFIXES is a no-op. So any suffix-like things
179 will be treated as suffixes, excluding the following example:
180 .c.o: foo.h
182 $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@ $<
183 In suffix rules, no prerequisites are allowed according to most
185 make tools.
186 Substitution References
188 objects = foo.o bar.o baz.o
189 sources = $(objects:.o=.c) # foo.c bar.c baz.c
190 Functions
192 Currently the following GNU make makefile builtin functions are
193 supported:
194 " $(subst from,to,text) "
196 " $(patsubst pattern,replacement,text) "
197 " $(strip string) "
198 " $(findstring find,text) "
199 " $(filter pattern...,text) "
200 " $(filter-out pattern...,text) "
201 " $(sort list) "
202 " $(word n,text) "
203 " $(words text) "
204 " $(wordlist s,e,text) "
205 " $(firstword names...) "
206 " $(lastword names...) "
207 " $(dir names...) "
208 " $(notdir names...) "
209 " $(suffix names...) "
210 " $(basename names...) "
211 " $(addsuffix suffix,names...) "
212 " $(addprefix prefix,names...) "
213 " $(join list1,list2) "
214 " $(wildcard pattern...) "
215 " $(realpath names...) "
216 " $(abspath names...) "
217 " $(if condition,then-part[,else-part]) "
218 " $(or condition1[,condition2[,condition3...]]) "
219 " $(and condition1[,condition2[,condition3...]]) "
220 " $(foreach var,list,text) "
221 " $(error argument...) "
222 " $(warning argument...) "
223 " $(info argument...) "
224 " $(shell cmd...) "
225 Please consult the GNU make Manual for details and also take a look
227 at the following file for some use cases:
228 http://svn.openfoundry.org/mdom/branches/gmake/t/gmake/sanity/func-refs.t
230 <http://svn.openfoundry.org/mdom/branches/gmake/t/gmake/sanity/func-
231 refs.t>
232 Commands after ';'
234 all : ; echo 'hello, world!'
235 Specital variable $@ will be expanded using its value in the
237 context.
238 For the list of features which will be added very soon, take a look at
240 the "TODO" section.
241
243 This class provides the main interface to the Makefile parser.
244 METHODS
246 "$obj = Makefile::Parser->new()"
247 It's the constructor for the Parser class. You may provide the path
248 of your Makefile as the argument which . It is worth mentioning
249 that the constructor will not call ->parse method internally, so
250 please remember calling ->parse after you construct the parser
251 object.
252 "$obj->parse()"
254 "$obj->parse($Makefile_name)"
255 "$obj->parse($Makefile_name, { var => value, ... })"
256 This method parse the specified Makefile (default to 'Makefile').
257 When an error occurs during the parsing procedure, "parse" will
259 return undef. Otherwise, a reference to Parser object itself is
260 returned. It is recommended to check the return value every time
261 you call this method. The detailed error info can be obtained by
262 calling the "error" method.
263 You can also pass a hash reference to specify initial variables and
265 their values. Note that these variables are treated as "defaults"
266 so assignments in the makefile have higher priority.
267 "$obj->error()"
269 It returns the error info set by the most recent failing operation,
270 such as a parsing failure.
271 "$obj->var($variable_name)"
273 The var method returns the value of the given variable. Since the
274 value of variables can be reset multiple times in the Makefile, so
275 what you get is always the last value set to the variable. It's
276 worth noting that variable reassignment can be handled
277 appropriately during parsing since the whole parsing process is a
278 one-pass operation compared to the multiple-pass strategy used by
279 the CPAN module Make.
280 "@vars = $obj->vars"
282 This will return all the variables defined in the Makefile. The
283 order may be quite different from the order they appear in the
284 Makefile.
285 "$obj->target($target_name)"
287 This method returns a Makefile::Target object with the name
288 specified. It will returns undef if the rules for the given target
289 is not described in the Makefile. It is worth noting that only
290 targets with a definition body will be considered as a target here.
291 When $target_name is omitted, this method will return the default
293 target, say, the first target defined in Makefile, to the user.
294 This can be handy if you try to build a make tool on top of this
295 module.
296 It is important not to send something like "$(MY_LIB)" as the
298 target name. Only raw values are acceptable. If you really want to
299 do something like this, please use the following code:
300 my $tar = $parser->target($parser->var('MY_LIB'));
302 but this code will break if you have reassigned values to variable
304 MY_LIB in your Makefile.
305 "@targets = $obj->targets()"
307 This returns all the targets in Makefile. The order can be
308 completely different from the order they appear in Makefile. So the
309 following code will not work if you want to get the default target
310 (the first target):
311 @tars = $parser->targets;
313 print $tars[0];
314 Please use the following syntax instead:
316 print $parser->target;
318 The type of the returned list is an array of Makefile::Target
320 objects.
321 "@roots = $obj->roots()"
323 The "roots" method returns the "root targets" in Makefile. The
324 targets which there're no other targets depends on are called the
325 root targets. For example, install, uninstall, and veryclean are
326 all root targets in the Makefile generated by the
327 ExtUtils::MakeMaker module. On the other hand, clean and test are
328 not, which may be somewhat counterintuitive. That's because
329 there're some other targets depend on clean, test, or both.
330 The type of the returned list is an array of Makefile::Target
332 objects.
333 PACKAGE VARIABLES
335 $Makefile::Parser::Strict
336 When this variable is set to true, the parser will sense syntax
337 errors and semantic errors in the Makefile. Default off.
338 $Makefile::Parser::Debug
340 When this variable is set to true, the parser will enter Debug
341 Mode. This variable is not supposed to be used directly by the
342 user.
343
345 post_parse
346 Iterate the Makefile AST to apply implicit rules in the following
347 form:
348 %.o : %.c
350 $(CC) -c $<
351 solve_imp($depend)
353 Solve implicit rules as many as possible using one target name that
354 appears in other target's dependency list.
355
357 This class overloads the "" operator so its instances can be
358 automatically converted to strings using their names.
359 METHODS
361 "$class->new($target_name, $colon_type)"
362 This is the constructor for class Makefile::Target. The first
363 argument is the target name which can't be a Makefile variable, the
364 second one is a single colon or a double colon which is used by the
365 rule definition in Makefile.
366 This method is usually called internally by the Makefile::Parser
368 class. It doesn't make much sense to me if the user has a need to
369 call it manually.
370 "$obj->name()"
372 It will return the name of the current Target object.
373 "@prereqs = $obj->prereqs()"
375 You can get the list of prerequisites (or dependencies) for the
376 current target. If no dependency is specified in the Makefile for
377 the target, an empty list will be returned.
378 "@prereqs = $obj->depends()"
380 Alias to the "prereqs" method. This method is only preserved for
381 the sake of backward-compatibility. Please use "prereqs" instead.
382 "$obj->commands()"
384 This method returns a list of shell commands used to build the
385 current target. If no shell commands is given in the Makefile, an
386 empty array will be returned.
387
389 For the very latest version of this module, check out the source from
390 http://svn.openfoundry.org/makefileparser/branches/gmake-db
391 <http://svn.openfoundry.org/makefileparser/branches/gmake-db>. There is
392 anonymous access to all.
393
395 The following syntax will be implemented soon:
396 · Add support the remaining GNU make makefile builtin functions:
398 "origin", "value", "call", "flavor", and "eval".
400 · Add support for recursively-expanded variables.
402 · Implement rules with multiple targets
404 · Serious support for "Recursively expanded" variables in GUN make
406 · Comments that span multiple lines via trailing backslash
408 · Lines that don't contain just comments
410 · Literal "#" escaped by a leading backslash
412 · The include directive
414 · Look for 'GNUmakefile' and 'makefile' automatically
416 · MAKEFILES Variable
418 · MAKEFILE_LIST Variable
420 · .VARIABLES Variable
422
424 Please feel free to report bugs or send your wish-list to
425 http://rt.cpan.org/NoAuth/Bugs.html?Dist=Makefile-Parser
426 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Makefile-Parser>.
427
429 plmake, makesimple, Makefile::Parser::GmakeDB, Makefile::GraphViz,
430 Make.
431
433 Agent Zhang, "<agentzh@yahoo.cn>"
434
436 Copyright (c) 2005-2008 by Agent Zhang (agentzh).
437 This library is free software; you can redistribute it and/or modify it
439 under the same terms as Perl itself.
440perl v5.12.0 2008-03-16 Makefile::Parser(3)