The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
makepp-1.19
River stage zero No dependents
5 ++
/ makepp_statements

NAME

makepp_statements -- Various statements in a makefile

DESCRIPTION

A statement is any line beginning with a word which does not have a : in it. (A colon implies that the line is a rule.) For example, these are statements:

    include extra_rules.mk
    load_makefile subdir

Makepp has a number of builtin statements which you may occasionally need to use.

Note that wherever you see an underscore, you may also use a dash, because makepp converts dashes to underscores in statement names.

include

This inserts the contents of another makefile into the current makefile. It can be useful if you have boilerplate files with a number of rules or variables, and each directory only needs to make a few modifications. The include statement also used to be commonly used in traditional makes in conjunction with automatic include file scanners, but this is no longer necessary with makepp.

include first considers the current directory, then the parent of the current directory, then its parent, etc. It stops considering directories when it reaches the root of the file system or when the file system device ID changes. (This means that it will not find files located in other NFS mounts. This is to prevent problems with network file systems or automounters and dead servers.) If it does not find a file of the given name by the time its search is stopped, then it looks in the makepp dadta directory (/usr/local/share/makepp if you installed makepp in /usr/local) for one of the include files that comes with makepp.

If you want to include a template file in every makefile in a whole directory hierarchy, you can place your makefile template at the top directory. The makefiles do not have to know exactly where they are in the hierarchy; each makefile can contain a line like this:

    include standard_definitions.mk

instead of something more complicated, like this:

    include ../../../standard_definitions.mk  # Is this the right number of ..?

You can specify as many files as you want, and variables are allowed:

    include file1 file2 file3 $(other_include_files)
_include

A minor variant on include, the _include statement includes the file if it exists but doesn't generate a fatal error if it does not. The _include statement used to be important for include file scanning with GNU make, but is seldom useful for makepp. (Makepp will not try to make the file and then reread it, unlike GNU make.)

load_makefile
    load_makefile /some/directory/somewhere/Makefile
    load_makefile subdir
    load_makefile VAR1=value1 VAR2=value2 subdir

This statement causes makepp to cd to the directory containing the makefile and load its rules into makepp's internal database. If you specify just a directory instead of a makefile, load_makefile looks for Makeppfile, makefile, or Makefile in that directory.

Any variables you specify with the syntax VAR=value (or VAR="value1 value2") are passed to the loaded makefiles. They override any settings in those makefiles, just as if you had typed them on the command line.

Using load_makefile is different from the command

    include dir/makefile

in two ways. First, load_makefile does not transfer any variables from the top-level makefile into the subordinate makefile; each makefile exists in its own namespace. The subordinate makefile cannot influence the variables in the top-level makefile in any way.

Second, each build command is tagged with the directory of the makefile that it came from. When makepp executes a rule from a different makefile, it first cd's to the directory containing that makefile before executing the command. Makefiles which are seen with the include statement are actually treated as part of the makefile that included them, and therefore their rules are not tagged with a different directory.

You usually do not have to load a makefile explicitly, unless it has an unusual name, or it has targets which are not contained in the same directory as the makefile itself, or you have disabled implicit makefile loading. By default, if makepp is trying to build a file and doesn't have a rule to build it, or if it is evaluating a wildcarded filename in a directory, it will automatically attempt to load a makefile from that directory. See "Tips for multiple directories" in makepp_cookbook for info on building with multiple directories.

You cannot use load_makefile to load several makefiles that apply to the same directory. Use include for several pieces of the makefile that apply to the same directory, and load_makefile for makefiles that apply to different directories.

no_implicit_load

This statement turns off implicit loading of makefiles from a set of directories. This can be useful if you want to load makefiles automatically from most directories, but there are some directories which for various reasons you do not want makepp to attempt to update. (E.g., maybe the directory has a makefile for some other version of make which makepp does not understand.) For example,

    no_implicit_load dir1 dir2/*

The above statement will turn off implicit loading for makefiles in dir1 <b>and all of its subdirectories</b>. It will also turn of implicit makefile loading for all subdirectories of dir2 (and all of their subdirectories), but not for dir2 itself.

You may use wildcards in the statement. Non-directory files that match the wildcard are ignored. You can also use functions to further specify the directories that you are interested in, e.g.,

    no_implicit_load $(filter-out dir1 dir2, *)

will turn off implicit loading for all subdirectories except dir1 and dir2 and their subdirectories.

perl_begin

This statement introduces a block of code which is interpreted verbatim by perl. It can be useful for defining functions, but you can do this more concisely with the sub statement. A block of perl code in your makefile can be useful to perform actions that are easier in perl than with makepp functions and rules.

The remainder of the line following the perl_begin statement is ignored. All text up until a line that begins at the left margin with perl_end is sent verbatim to the perl interpreter.

One example that I use this for is to make directories that might not necessarily exist. It's common in makefiles to put all the .o files in a subdirectory (e.g., a directory with a name i386, or sparc, or something that depends on the machine type). But what if the directory does not exist yet? You can make each .o file depend on the subdirectory, and put a rule in to build the subdirectory. But it's a lot easier just to do this:

   OBJDIR := $(ARCH)               # Where we put .o files.
   perl_begin
   -d $OBJDIR or mkdir $OBJDIR;    # Make sure the directory exists.
   perl_end

This way, every time the makefile is run, the subdirectory will be created if it does not exist.

Some operations are better expressed in terms of regular expressions than makepp's text functions. For example,

    perl_begin
    if ($ARCH =~ /^i[56]86/) {
      $CFLAGS = '-O6 -malign-double';   # On intel machines > 486, there
                                        # is a substantial speed penalty
                                        # for doubles that aren't quadword 
                                        # aligned.
    } else {
      $CFLAGS = '-O6';
    }
    perl_end
    
    %.o: %.c
        $(CC) $(CFLAGS) -c $(input) -o $(output)

Any make variable can be accessed directly as a perl scalar. In this case, we've set the value of CFLAGS differently based on a regular expression match on the architecture flags.

As a final example, some pieces of information are easier to access directly from perl than from makepp. For example, you can access all of the configuration information that perl knows about your system, including how to build shared libraries, etc. (Type perldoc Config if you want to see what configuration information perl has available.)

    perl_begin
    
    use Config;
    
    $ARCH = $Config{'archname'};    # Use perl's knowledge of the architecture.
    $CC = $Config{'cc'};            # Use the same C compiler as perl did.
    $SHARED_OBJ_CFLAGS = $Config{'cccdlflags'};
                                # Flags needed to compile objects which will
                                # go into a shared library.
    $SHARED_OBJ_LDFLAGS = $Config{'ccdlflags'} . " " . $Config{'lddlflags'};
                                # Linker flags to make a shared library.
    $SHARED_CC_LINK = $Config{'ld'}; # Command to produce shared libraries.
    
    $SHARED_EXTENSION = $Config{'dlext'}; # Extension of shared libraries.
    perl_end
    
    %.o: %.c
        $(CC) $(CFLAGS) $(SHARED_OBJ_CFLAGS) -c $(input) -o $(output)
    
    libmylib.$(DLEXT): *.o
        $(SHARED_CC_LINK) $(inputs) -o $(output) $(SHARED_OBJ_LDFLAGS)

Note how we define a bunch of variables in the perl block, and then we use them afterwards in the rest of the makefile. You can use the full power of the perl interpreter to set your variables in arbitrarily complicated ways. You can run shell commands from your perl code, access a database, or whatever you want.

repository
    repository dirname
    repostiory destdir=srcdir

Specifies one or more repository directories. The first repository specified has precedence over the others if the same file exists in multiple repositories and there is no build command for it. See makepp_repositories for more details about repositories.

If you specify just a directory after repository, its contents are linked into the current directory. You can link its contents into any arbitrary place in the file system by specifying the location before an equals sign, e.g,

    repository subdir1/subdir2=/users/joe/joes_nifty_library

You should put the repository statement near the top of your makefile, before any rules that may need to use it.

signature
    signature exact_match
    signature target_newer
    signature md5
    signature c_compilation_md5
    signature default

Overrides the default signature method for all rules following the signature statement. This overrides the signature method specified on the command line with -m or --signature-method, but does not override signature methods specified with the :signature rule modifier.

Specify signature default to return to makepp's default, either the builtin default or the default specified on the command line.

For more information about signature methods, see makepp_signatures.

sub

This statement provides a way to define a perl subroutine inside your makefile. The syntax is identical to that of the perl sub statement, except that the closing brace must be at the left margin.

A perl subroutine is invoked whenever a statement is seen, or when an expression like $(name words) is seen. For example, suppose that for some reason you need to load the contents of a file into a make variable. (You could do this by saying $(shell cat filename) but it's possible to do it without ever invoking the shell.) This can be done by placing the following into your makefile:

    sub f_file_contents {
      my ($filename) = @_;              # Name the arguments.
      my $file_contents;
      open FILE, $filename || die "$!\n";
      my $line;
      while (defined($line = &lt;FILE&gt;)) {  # Read another line.
        $file_contents .= $line;
      }
      close FILE;
    
      return $file_contents;
    }

Now, with this function defined, you can write

    X = $(file_contents filename)

and the variable $(X) will contain the contents of the given file.

See makepp_extending for more details and examples.

ifeq
ifneq
    ifeq ($(STR1),$(STR2))
       makefile lines if true
    else
       makefile lines if false
    endif

If the two strings match exactly (except for leading or trailing whitespace), then the first set of lines is used; otherwise the second is used. The else clause is optional.

There are several different acceptable syntaxes for the ifeq and ifneq statements:

    ifeq string1, string2
    ifeq "string1", "string2"
    ifeq 'string1', 'string2'
    ifeq string1, string2

are all equivalent.

ifeq and its friends ifneq, ifdef, and ifndef are primarily useful when you have to build a program under several different conditions. For example,

    BUILD_TYPE := debug    # "debug" or "production"

    ifeq ($(BUILD_TYPE), debug)
     CFLAGS := -g
    else
     CFLAGS := -O2
    endif

    program : *.o
        $(CC) $(CFLAGS) $(inputs) -o $(output) $(LIBS)
    ifeq ($(BUILD_TYPE), production)
        strip $(output)
    endif

    %.o : %.c
        $(CC) $(CFLAGS) -c $(input) -o $(output)

If this is a production build, all files are compiled with the -O2 option instead of the -g option. Furthermore, the program strip is run on the resulting binary (in case you happened to link with some libraries that were compiled in debug mode).

The ifeq and related conditional statements are unique in that they may occur in the middle of rule actions, as in the above example, without disrupting the rule.

Sometimes it is easier to use the $(if ) function instead of a ifeq statement; see the $(if ) function for details.

ifdef
ifndef

These statements work analogously to the ifeq and ifneq statements, except that they test whether a variable is defined or not. A variable is defined if:

  • It was given a value with an assignment earlier in the makefile. See makepp_variables for details.

  • It was given a value as a perl variable in a perl_begin block.

  • The variable is present in the environment.

  • The variable is present on the command line, e.g., to invoke your makefile, you typed

        makepp CFLAGS=-O2

For example,

    ifndef CFLAGS
      CFLAGS := -g
    endif

In this case, CFLAGS is set to -g only if it wasn't already defined. Note that this statement could just as easily have been written using the ?= assignment, like this:

    CFLAGS ?= -g

AUTHOR

Gary Holt (holt-makepp@gholt.net)