1Makefile::Parser(3)   User Contributed Perl Documentation  Makefile::Parser(3)
2
3
4

NAME

6       Makefile::Parser - A simple parser for Makefiles
7

VERSION

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

SYNOPSIS

13         use Makefile::Parser;
14
15         $parser = Makefile::Parser->new;
16
17         # equivalent to ->parse('Makefile');
18         $parser->parse or
19             die Makefile::Parser->error;
20
21         # get last value assigned to the specified variable 'CC':
22         print $parser->var('CC');
23
24         # get all the variable names defined in the Makefile:
25         @vars = $parser->vars;
26         print join(' ', sort @vars);
27
28         @roots = $parser->roots; # Get all the "root targets"
29         print $roots[0]->name;
30
31         @tars = $parser->targets;  # Get all the targets
32         $tar = join("\n", $tars[0]->commands);
33
34         # get the default target, say, the first target
35         # defined in Makefile:
36         $tar = $parser->target;
37
38         $tar = $parser->target('install');
39         # get the name of the target, say, 'install' here:
40         print $tar->name;
41
42         # get the dependencies for the target 'install':
43         @depends = $tar->depends;
44
45         # access the shell command used to build the current target.
46         @cmds = $tar->commands;
47
48         # parse another file using the same Parser object:
49         $parser->parse('Makefile.old') or
50           die Makefile::Parser->error;
51
52         # get the target who is specified by variable EXE_FILE
53         $tar = $parser->target($parser->var('EXE_FILE'));
54

DESCRIPTION

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
65       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
69       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
74       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
77   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
83       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
92           "Simply expanded" variables' definition sytax in GUN make is also
93           supported:
94
95               FOO := blah blah blah
96
97           which is considered invalid in Win32 NMake. "Recursively expanded"
98           variables are currently treated as "simply expanded" variables.
99
100           Variable redefinition can be handled as well:
101
102               CC = cl
103
104               %.obj : %.c
105                   $(CC) /nologo /c $<
106
107               CC = gcc
108
109               %.o : %.c
110                   $(CC) -c $<
111
112           Variable expansion sytax
113
114               ${abc}
115
116           is accepted, whereas Win32 NMAKE will complain about it.
117
118           Currently, environment variables defined in the command-line are
119           not imported.
120
121           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
125           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
130       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
134               $(CIDU_LIB) : $(CIDU_DLL)
135
136               C\idu.obj : C\idu.c C\idu.h
137                   cd C
138                   cl /nologo /c /I . idu.c
139                   cd ..
140
141               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
146               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
153           Specital variable $@ will be expanded using its value in the
154           context.
155
156       Implicit Rules
157           Pattern Rules
158                   %.obj : %.asm
159                       masm /t $<;
160
161                   %.exe : %.obj
162                       link /BATCH /NOLOGO $<;
163
164               The special varaibles $< and $* will be expanded according to
165               the context.
166
167           Old-Fashioned Suffix Rules
168               Currently only double-suffix rules are supported:
169
170                   .SUFFIXES: .obj .asm .exe
171
172                   .asm.obj :
173                       masm /t $<
174
175                   .obj.exe :
176                       link /nologo $<
177
178               At this moment, .SUFFIXES is a no-op. So any suffix-like things
179               will be treated as suffixes, excluding the following example:
180
181                   .c.o: foo.h
182                           $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@ $<
183
184               In suffix rules, no prerequisites are allowed according to most
185               make tools.
186
187       Substitution References
188               objects = foo.o bar.o baz.o
189               sources = $(objects:.o=.c)  # foo.c bar.c baz.c
190
191       Functions
192           Currently the following GNU make makefile builtin functions are
193           supported:
194
195           " $(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
226           Please consult the GNU make Manual for details and also take a look
227           at the following file for some use cases:
228
229           <http://github.com/agentzh/makefile-dom-pm/tree/master/t/gmake/sanity/func-refs.t>
230
231       Commands after ';'
232               all : ; echo 'hello, world!'
233
234           Specital variable $@ will be expanded using its value in the
235           context.
236
237       For the list of features which will be added very soon, take a look at
238       the "TODO" section.
239

The Makefile::Parser Class

241       This class provides the main interface to the Makefile parser.
242
243   METHODS
244       "$obj = Makefile::Parser->new()"
245           It's the constructor for the Parser class. You may provide the path
246           of your Makefile as the argument which . It is worth mentioning
247           that the constructor will not call ->parse method internally, so
248           please remember calling ->parse after you construct the parser
249           object.
250
251       "$obj->parse()"
252       "$obj->parse($Makefile_name)"
253       "$obj->parse($Makefile_name, { var => value, ... })"
254           This method parse the specified Makefile (default to 'Makefile').
255
256           When an error occurs during the parsing procedure, "parse" will
257           return undef. Otherwise, a reference to Parser object itself is
258           returned.  It is recommended to check the return value every time
259           you call this method. The detailed error info can be obtained by
260           calling the "error" method.
261
262           You can also pass a hash reference to specify initial variables and
263           their values. Note that these variables are treated as "defaults"
264           so assignments in the makefile have higher priority.
265
266       "$obj->error()"
267           It returns the error info set by the most recent failing operation,
268           such as a parsing failure.
269
270       "$obj->var($variable_name)"
271           The var method returns the value of the given variable. Since the
272           value of variables can be reset multiple times in the Makefile, so
273           what you get is always the last value set to the variable. It's
274           worth noting that variable reassignment can be handled
275           appropriately during parsing since the whole parsing process is a
276           one-pass operation compared to the multiple-pass strategy used by
277           the CPAN module Make.
278
279       "@vars = $obj->vars"
280           This will return all the variables defined in the Makefile. The
281           order may be quite different from the order they appear in the
282           Makefile.
283
284       "$obj->target($target_name)"
285           This method returns a Makefile::Target object with the name
286           specified.  It will returns undef if the rules for the given target
287           is not described in the Makefile. It is worth noting that only
288           targets with a definition body will be considered as a target here.
289
290           When $target_name is omitted, this method will return the default
291           target, say, the first target defined in Makefile, to the user.
292           This can be handy if you try to build a make tool on top of this
293           module.
294
295           It is important not to send something like "$(MY_LIB)" as the
296           target name.  Only raw values are acceptable. If you really want to
297           do something like this, please use the following code:
298
299               my $tar = $parser->target($parser->var('MY_LIB'));
300
301           but this code will break if you have reassigned values to variable
302           MY_LIB in your Makefile.
303
304       "@targets = $obj->targets()"
305           This returns all the targets in Makefile. The order can be
306           completely different from the order they appear in Makefile. So the
307           following code will not work if you want to get the default target
308           (the first target):
309
310               @tars = $parser->targets;
311               print $tars[0];
312
313           Please use the following syntax instead:
314
315               print $parser->target;
316
317           The type of the returned list is an array of Makefile::Target
318           objects.
319
320       "@roots = $obj->roots()"
321           The "roots" method returns the "root targets" in Makefile. The
322           targets which there're no other targets depends on are called the
323           root targets.  For example, install, uninstall, and veryclean are
324           all root targets in the Makefile generated by the
325           ExtUtils::MakeMaker module. On the other hand, clean and test are
326           not, which may be somewhat counterintuitive. That's because
327           there're some other targets depend on clean, test, or both.
328
329           The type of the returned list is an array of Makefile::Target
330           objects.
331
332   PACKAGE VARIABLES
333       $Makefile::Parser::Strict
334           When this variable is set to true, the parser will sense syntax
335           errors and semantic errors in the Makefile. Default off.
336
337       $Makefile::Parser::Debug
338           When this variable is set to true, the parser will enter Debug
339           Mode. This variable is not supposed to be used directly by the
340           user.
341

INTERNAL METHODS

343       post_parse
344           Iterate the Makefile AST to apply implicit rules in the following
345           form:
346
347               %.o : %.c
348                   $(CC) -c $<
349
350       solve_imp($depend)
351           Solve implicit rules as many as possible using one target name that
352           appears in other target's dependency list.
353

The Makefile::Target Class

355       This class overloads the "" operator so its instances can be
356       automatically converted to strings using their names.
357
358   METHODS
359       "$class->new($target_name, $colon_type)"
360           This is the constructor for class Makefile::Target. The first
361           argument is the target name which can't be a Makefile variable, the
362           second one is a single colon or a double colon which is used by the
363           rule definition in Makefile.
364
365           This method is usually called internally by the Makefile::Parser
366           class. It doesn't make much sense to me if the user has a need to
367           call it manually.
368
369       "$obj->name()"
370           It will return the name of the current Target object.
371
372       "@prereqs = $obj->prereqs()"
373           You can get the list of prerequisites (or dependencies) for the
374           current target.  If no dependency is specified in the Makefile for
375           the target, an empty list will be returned.
376
377       "@prereqs = $obj->depends()"
378           Alias to the "prereqs" method. This method is only preserved for
379           the sake of backward-compatibility. Please use "prereqs" instead.
380
381       "$obj->commands()"
382           This method returns a list of shell commands used to build the
383           current target.  If no shell commands is given in the Makefile, an
384           empty array will be returned.
385

CODE REPOSITORY

387       For the very latest version of this module, check out the source from
388       <http://github.com/agentzh/makefile-parser-pm>. There is anonymous
389       access to all.
390

TODO

392       The following syntax will be implemented soon:
393
394       •   Add support the remaining GNU make makefile builtin functions:
395
396           "origin", "value", "call", "flavor", and "eval".
397
398       •   Add support for recursively-expanded variables.
399
400       •   Implement rules with multiple targets
401
402       •   Serious support for "Recursively expanded" variables in GUN make
403
404       •   Comments that span multiple lines via trailing backslash
405
406       •   Lines that don't contain just comments
407
408       •   Literal "#" escaped by a leading backslash
409
410       •   The include directive
411
412       •   Look for 'GNUmakefile' and 'makefile' automatically
413
414       •   MAKEFILES Variable
415
416       •   MAKEFILE_LIST Variable
417
418       •   .VARIABLES Variable
419

BUGS

421       Please feel free to report bugs or send your wish-list to
422       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Makefile-Parser>.
423

SEE ALSO

425       plmake, makesimple, Makefile::Parser::GmakeDB, Makefile::GraphViz,
426       Make.
427

AUTHOR

429       Zhang "agentzh" Yichun, "<agentzh@gmail.com>"
430
432       Copyright (c) 2005-2011 by Zhang "agentzh" Yichun (章亦春).
433
434       This library is free software; you can redistribute it and/or modify it
435       under the same terms as Perl itself.
436
437
438
439perl v5.34.0                      2022-01-21               Makefile::Parser(3)
Impressum