.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" 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" '' . ds C` . ds C' '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. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" 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 "MAKEPP_EXTENDING 1" .TH MAKEPP_EXTENDING 1 "2014-09-11" "perl v5.20.0" "Makepp" .\" 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" makepp_extending \-\- How to extend makepp using Perl .SH "DESCRIPTION" .IX Header "DESCRIPTION" Makepp internally is flexible enough so that by writing a little bit of Perl code, you can add functions or do a number of other operations. .SS "General notes on writing Perl code to work with makepp" .IX Subsection "General notes on writing Perl code to work with makepp" Each makefile lives in its own package. Thus definitions in one makefile do not affect definitions in another makefile. A common set of functions including all the standard textual manipulation functions is imported into the package when it is created. .PP Makefile variables are stored as Perl scalars in that package. (There are exceptions to this: automatic variables and the default value of variables like \s-1CC\s0 are actually implemented as functions with no arguments. Target specific vars, command line vars and environment vars are not seen this way.) Thus any Perl code you write has access to all makefile variables. Global variables are stored in the \f(CW\*(C`Mpp::global\*(C'\fR package. See Makefile variables for the details. .PP Each of the statements (ifperl / ifmakeperl, perl / makeperl, sub / makesub), the functions (perl / makeperl, map / makemap) and the rule action (perl / makeperl) for writing Perl code directly in the makefile come in two flavours. The first is absolutely normal Perl, meaning you have to use the \f(CW\*(C`f_\*(C'\fR prefix as explained in the next section, if you want to call makepp functions. The second variant first passes the statement through Make-style variable expansion, meaning you have to double the \f(CW\*(C`$\*(C'\fRs you want Perl to see. .PP End handling is special because makepp's huge (depending on your build system) data structures would take several seconds to garbage collect with a normal exit. So we do a brute force exit. In the main process you can still have \&\f(CW\*(C`END\*(C'\fR blocks but if you have any global file handles they may not get flushed. But you should be using the modern lexical filehandles, which get closed properly when going out of scope. .PP In Perl code run directly as a rule action or via a command you define, it is the opposite. \f(CW\*(C`END\*(C'\fR blocks will not be run, but global filehandles get flushed for you. The \f(CW\*(C`DESTROY\*(C'\fR of global objects will never be run. .SS "Adding new textual functions" .IX Subsection "Adding new textual functions" You can add a new function to makepp's repertoire by simply defining a Perl subroutine of the same name but with a prefix of \f(CW\*(C`f_\*(C'\fR. For example: .PP .Vb 3 \& sub f_myfunc { \& my $argument = &arg; # Name the argument. \& my( undef, $mkfile, $mkfile_line ) = @_; # Name the arguments. \& \& ... do something here \& \& return $return_value; \& } \& \& XYZ := $(myfunc my func arguments) .Ve .PP If your function takes no arguments, there is nothing to do. If your function takes one argument, as in the example above, use the simple accessor \f(CW&arg\fR to obtain it. If you expect more arguments, you need the more complex accessor \f(CW\*(C`args\*(C'\fR described below. .PP These accessors processes the same three parameters that should be passed to any \f(CW\*(C`f_\*(C'\fR function, namely the function arguments, the makefile object and a line descriptor for messages. Therefore you can use the efficient \f(CW&arg\fR form in the first case. .PP The \f(CW&arg\fR accessor takes care of the following for you: If the arguments were already expanded (e.g. to find the name of the function in \&\f(CW\*(C`$(my$(function) arg)\*(C'\fR the arg is passed as a string and just returned. If the argument still needs expansion, this is the usual case, it is instead a reference to a string. The \f(CW&arg\fR accessor expands it for you, for which it needs the makefile object as its 2nd parameter. .PP If you expect more arguments, possibly in variable number, the job is performed by \f(CW\*(C`args\*(C'\fR. This accessor takes the same 3 parameters as arg, plus additional parameters: .IP "max: number of args (default 2): give ~0 (maxint) for endless" 4 .IX Item "max: number of args (default 2): give ~0 (maxint) for endless" .PD 0 .IP "min: number of args (default 0 if max is ~0, else same as max)" 4 .IX Item "min: number of args (default 0 if max is ~0, else same as max)" .IP "only_comma: don't eat space around commas, usual for non-filename" 4 .IX Item "only_comma: don't eat space around commas, usual for non-filename" .PD .PP At most max, but at least min commas present before expansion are used to split the arguments. Some examples from makepp's builtin functions: .PP .Vb 4 \& my( $prefix, $text ) = args $_[0], $_[1], $_[2], 2, 2, 1; # addprefix \& for my $cond ( args $_[0], undef, $_[2], ~0 ) ... # and, or \& my @args= args $_[0], $_[1], $_[2], ~0, 1, 1; # call \& my( $filters, $words ) = args $_[0], $_[1], $_[2]; # filter .Ve .PP The function should return a scalar string (not an array) which is then inserted into the text at that point. .PP If your function encounters an error, it should die using the usual Perl die statement. This will be trapped by makepp and an error message displaying the file name and the line number of the expression causing the error will be printed out. .PP There are essentially no limits on what the function can do; you can access the file, run shell commands, etc. .PP At present, expressions appearing in dependencies and in the rule actions are expanded once while expressions appearing in targets are expanded twice, so be careful if your function has side effects and is present in an expression for a target. .PP Note that the environment (in particular, the cwd) in which the function evaluates will not necessarily match the environment in which the rules from the Makefile in which the function was evaluated are executed. If this is a problem for you, then your function probably ought to look something like this: .PP .Vb 3 \& sub f_foo { \& ... \& chdir $makefile\->{CWD}; \& \& ... etc. \& } .Ve .SS "Putting functions into a Perl module" .IX Subsection "Putting functions into a Perl module" If you put functions into an include file, you will have one copy per Makeppfile which uses it. To avoid that, you can write them as a normal Perl module with an \f(CW\*(C`Exporter\*(C'\fR interface, and use that. This will load faster and save memory: .PP .Vb 4 \& perl { use mymodule } \& perl { \& use my::module; # put : on a new line so this is not parsed as a rule \& } .Ve .PP If you need any of the functions normally available in a Makefile (like the \&\f(CW\*(C`f_\*(C'\fR functions, \f(CW\*(C`arg\*(C'\fR or \f(CW\*(C`args\*(C'\fR), you must put this line into your module: .PP .Vb 1 \& use Mpp::Subs; .Ve .PP The drawback is that the module would be in a different package than a function directly appearing in a makefile. So you need to pass in everything as parameters, or construct names with Perl's \f(CW\*(C`caller\*(C'\fR function. .SS "Calling external Perl scripts" .IX Subsection "Calling external Perl scripts" If you call an external Perl script via \f(CW\*(C`system\*(C'\fR, or as a rule action, makepp will fork a new process (unless it's the last rule action) and fire off a brand new perl interpreter. There's nothing wrong with that, except that there's a more efficient way: .IP "&\fIcommand arguments...\fR" 4 .IX Item "&command arguments..." This can be a rule action. It will call a function \fIcommand\fR with a \f(CW\*(C`c_\*(C'\fR prefix, and pass it the remaining (optionally quoted makepp style \*(-- not exactly the same as Shell) arguments. If such a function cannot be found, this passes all strings to \f(CW\*(C`run\*(C'\fR. .Sp .Vb 1 \& sub c_mycmd { my @args = @_; ... } \& \& $(phony callcmd): \& &mycmd \*(Aqarg with space\*(Aq arg2 "arg3" # calls c_mycmd \& \& %.out: %.in \& &myscript \-o $(output) $(input) # calls external myscript .Ve .Sp You can write your commands within the framework of the builtins, allowing you to use the same standard options as they have, and the I/O handling they give. .Sp The block operator \f(CW\*(C`Mpp::Cmds::frame\*(C'\fR is followed by a single letter option list of the builtins (maximally \f(CW\*(C`qw(f i I o O r s)\*(C'\fR). Even if you specify your own option overriding one of these, you still give the single letter of the standard option. .Sp Each own option is specified as \f(CW\*(C`[qw(n name), \f(CI\e$ref\f(CW, \f(CIarg\f(CW, \f(CIsub\f(CW]\*(C'\fR. The first two elements are short and long name, followed by the variable reference and optionally by a boolean for whether to take an argument. Without an arg, the variable is incremented each time the option is given, else the option value is stored in it. .Sp .Vb 3 \& sub c_my_ocmd { # Typical output case \& local @ARGV = @_; \& Mpp::Cmds::frame { \& \& ... print something here with @ARGV, with options already automatically removed \& \& } \*(Aqf\*(Aq, qw(o O); \& } \& \& sub c_my_icmd { # Typical input case with 2 options \& local @ARGV = @_; \& my( $short, $long ); \& Mpp::Cmds::frame { \& \& ... do something here with <> \& \& } qw(i I r s), # s specifies only \-\-separator, not \-s \& [qw(s short), \e$short], # No option arg \-> $short == 1 \& [qw(l long), \e$long, 1, sub { warn "got arg $long"}]; \& } .Ve .Sp Here comes a simple command which upcases only the first character of each input record (equivalent to \f(CW\*(C`&sed \*(Aq$$_ = "\eu\eL$$_"\*(Aq\*(C'\fR): .Sp .Vb 6 \& sub c_uc { \& local @ARGV = @_; \& Mpp::Cmds::frame { \& print "\eu\eL$_" while <>; \& } \*(Aqf\*(Aq, qw(i I o O r s); \& } .Ve .Sp Within the block handled by frame, you can have nested blocks for performing critical operations, like opening other files. .Sp .Vb 1 \& Mpp::Cmds::perform { ... } \*(Aqmessage\*(Aq; .Ve .Sp This will output message with \f(CW\*(C`\-\-verbose\*(C'\fR (which every command accepts) iff the command is successfully run. But if the block evaluates as false, it dies with negated message. .IP "run \fIscript arguments...\fR" 4 .IX Item "run script arguments..." This is a normal Perl function you can use in any Perl context within your makefile. It is similar to the multi-argument form of system, but it runs the Perl script within the current process. For makepp statements, the perl function or your own functions that is the process running makepp. But for a rule that is the subprocess performing it. The script gets parsed as many times as it gets called, but you can put the real work into a lib, as pod2html does. This lib can then get used in the top level, so that it's already present: .Sp .Vb 1 \& perl { use mylib } # gets forked to all rules which needn\*(Aqt reparse it \& \& %.out: %.in \& makeperl { run qw\*(Aqmyscript \-o $(output) $(input)\*(Aq } .Ve .Sp If the script calls \f(CW\*(C`exit\*(C'\fR, closes standard file descriptors or relies on the system to clean up after it (open files, memory...), this can be a problem with \f(CW\*(C`run\*(C'\fR. If you call \f(CW\*(C`run\*(C'\fR within statements or the perl function, makepp can get disturbed or the cleanup only happens at the end of makepp. .Sp If you have one the aforementioned problems, run the script externally, i.e. as from the command line instead. Within a rule cleanup is less of a problem, especially not as the last action of a rule, since the rule subprocess will exit afterwards anyway, except on Windows. .SS "Writing your own signature methods" .IX Subsection "Writing your own signature methods" Sometimes you want makepp to compute a signature method using a different technique. For example, suppose you have a binary that depends on a shared library. Ordinarily, if you change the shared library, you don't have to relink executables that depend on it because the linking is done at run time. (However, it is possible that relinking the executable might be necessary, which is why I did not make this the default.) What you want makepp to do is to have the same signature for the shared library even if it changes. .PP This can be accomplished in several ways. The easiest way is to create your own new signature method (let's call it \*(L"shared_object\*(R"). You would use this signature method only on rules that link binaries, like this: .PP .Vb 3 \& myprogram : *.o lib1/lib1.so lib2/lib2.so \& : signature shared_object \& $(CC) $(inputs) \-o $(output) .Ve .PP Now we have to create the signature method. .PP All signature methods must be their own class, and the class must contain a few special items (see Mpp/Signature.pm in the distribution for details). The class's name must be prefixed with \f(CW\*(C`Mpp::Signature::\*(C'\fR, so in this case our class should be called \f(CW\*(C`Mpp::Signature::shared_object\*(C'\fR. We have to create a file called \fIshared_object.pm\fR and put it into a \&\fIMpp::Signature\fR directory somewhere in the Perl include path; the easiest place might be in the \fIMpp/Signature\fR directory in the makepp installation (e.g., \fI/usr/local/share/makepp/Mpp/Signature\fR or wherever you installed it). .PP For precise details about what has to go in this class, you should look carefully through the file \fIMpp/Signature.pm\fR and probably also \&\fIMpp/Signature/exact_match.pm\fR in the makepp distribution. But in our case, all we want to do is to make a very small change to an existing signature mechanism; if the file is a shared library, we want to have a constant signature, whereas if the file is anything else, we want to rely on makepp's normal signature mechanism. The best way to do this is to inherit from \f(CW\*(C`Mpp::Signature::c_compilation_md5\*(C'\fR, which is the signature method that is usually chosen when makepp recognizes a link command. .PP So the file \fIMpp/Signature/shared_object.pm\fR might contain the following: .PP .Vb 10 \& use strict; \& package Mpp::Signature::shared_object; \& use Mpp::Signature::c_compilation_md5; \& our @ISA = qw(Mpp::Signature::c_compilation_md5); # Indicate inheritance. \& our $shared_object = bless \e@ISA; # A piece of magic that helps makepp find \& # the subroutines for this method. All \& # signature methods must have one of these. \& # The value is not used, just any object. \& # Now here\*(Aqs the method that gets called when we need the signature of \& # any target or dependency for which this signature method is active: \& sub signature { \& my ($self, # This will be the same as $shared_object. \& $finfo) = @_; # A special structure that contains everything \& # makepp knows about this file. See \& # Mpp/File.pm for details. \& \& if ($finfo\->{NAME} =~ /\e.s[oa]$/) { # Does the file name end in .so or .sa? \& return $finfo\->file_exists ? \*(Aqexists\*(Aq : \*(Aq\*(Aq; \& # Always return the same signature if the file \& # exists. In this case, the signature is the \& # string "exists". \& } \& \& Mpp::Signature::c_compilation_md5::signature; \& # If the file didn\*(Aqt end in .so or .sa, \& # delegate to makepp\*(Aqs usual signature method. \& } .Ve .PP This file is provided as an example in the makepp distribution, with some additional comments. .PP Incidentally, why don't we make this the default? Well, there are times when changing a shared library will require a relinking of your program. If you ever change either the symbols that a shared library defines, or the symbols that it depends on other libraries for, a relink may sometimes be necessary. .PP Suppose, for example, that the shared library invokes some subroutines that your program provides. E.g., suppose you change the shared library so it now calls an external subroutine \f(CW\*(C`xyz()\*(C'\fR. Unless you use the \&\f(CW\*(C`\-E\*(C'\fR or \f(CW\*(C`\-\-export\-dynamic\*(C'\fR option to the linker (for \s-1GNU\s0 binutils; other linkers have different option names), the symbol \f(CW\*(C`xyz()\*(C'\fR may not be accessible to the run-time linker even if it exists in your program. .PP Even worse, suppose you defined \f(CW\*(C`xyz()\*(C'\fR in another library (call it \&\fIlibxyz\fR), like this: .PP .Vb 1 \& my_program: main.o lib1/lib1.so xyz/libxyz.a .Ve .PP Since \f(CW\*(C`libxyz\*(C'\fR is a \fI.a\fR file and not a \fI.so\fR file, then \f(CW\*(C`xyz()\*(C'\fR may not be pulled in correctly from \fIlibxyz.a\fR unless you relink your binary. .PP Mpp::Signature methods also control not only the string that is used to determine if a file has changed, but the algorithm that is used to compare the strings. For example, the signature method \f(CW\*(C`target_newer\*(C'\fR in the makepp distribution merely requires that the targets be newer than the dependencies, whereas the signature method \f(CW\*(C`exact_match\*(C'\fR (and everything that depends on it, such as \f(CW\*(C`md5\*(C'\fR and \f(CW\*(C`c_compilation_md5\*(C'\fR) requires that the file have the same signature as on the last build. .PP Here are some other kinds of signature methods that might be useful, to help you realize the possibilities. If general purpose enough, some of these may eventually be incorporated into makepp: .IP "\(bu" 4 A signature method for shared libraries that returns a checksum of all the exported symbols, and also all the symbols that it needs from other libraries. This solves the problem with the example above, and guarantees a correct link under all circumstances. An experimental attempt has been made to do this in the makepp distribution (see \&\fIMpp/Signature/shared_object.pm\fR), but it will only work with \s-1GNU\s0 binutils and \s-1ELF\s0 libraries at the moment. .IP "\(bu" 4 A signature method that ignores a date stamp written into a file. E.g., if you generate a \fI.c\fR file automatically using some program that insists on putting a string in like this: .Sp .Vb 1 \& static char * date_stamp = "Generated automatically on 01 Apr 2004 by nobody"; .Ve .Sp you could write a signature method that specifically ignores changes in date stamps. Thus if the date stamp is the only thing that has changed, makepp will not rebuild. .IP "\(bu" 4 A signature method that computes the signatures the normal way, but ignores the architecture dependence when deciding whether to rebuild. This could be useful for truly architecture-independent files; currently if you build on one architecture, makepp will insist on rebuilding even architecture-independent files when you switch to a different architecture. .IP "\(bu" 4 A signature method that knows how to ignore comments in latex files, as the \f(CW\*(C`c_compilation_md5\*(C'\fR method knows how to ignore comments in C files. .IP "\(bu" 4 A signature method for automatic documentation extraction that checksums only to the comments that a documentation extractor needs and ignores other changes to the source file. .SS "Unfinished" .IX Subsection "Unfinished" This document is not finished yet. It should cover how to write your own scanners for include files and things like that.