The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Zoidberg-0.41
River stage zero No dependents
/ Makefile

NAME

Makefile - yet another approach to Makefile.PL

SYNOPSIS

in Makefile.PL

  require 'm/Makefile.pm';
  import Makefile qw/get_version_from/;

  my %config = (
    'default_target' => 'compile',
    'manifest' => 'MANIFEST',
    'fake_targets' => [qw/all/],
    'depends' => {
        'all' => [qw/compile test install/],
    },
    'vars' => {
        'PREFIX' => '/usr/local',
        'TEST_VERBOSE' => 0,
        'CONFIG' => '/etc',
        'INSTALLDIRS' => 'site',
    },
    'include' => {
        'NAME'          => 'My_perl_extension',
        'VERSION'       => get_version_from('lib/My_perl_extension.pm'),
        'AUTHOR'        => 'N. Nescio <NN@incognita.net>',
        'PREREQ_PM'     => { 'Data::Dumper' => '1.0', 'Storable' => '0.5' },
    },
  );

  my $make = Make->new(\%config);
  $make->check_manifest;
  $make->write_makefile;

in for example m/targets/test.pl

  require 'm/Makefile.pm';
  import Makefile qw/path_copy rmdir_force/;

  my $make = Makefile->new;

  use Test::Harness;
  $Test::Harness::verbose = $make->{vars}{TEST_VERBOSE};

  # run tests etc ...

DESCRIPTION

This module is yet another approach to the make process for packages of perl files. It does as little as possible in the makefile itself but rather links make targets to perl scripts.

By default the scripts are in a directory m/targets. These scripts can be of a general/reusable kind but also can contain package specific code. The scripts also can use this module to get their configuration vars.

One can add make targets by simply adding scripts or directories to the target directory.

Files and directories starting with a '.' are ignored. For obvious reasons targets called 'CVS'will also be ignored. Also it is not wise to call a target 'Makefile' or something alike.

Since Makefile.pm relies on @ARGV one should not touch @ARGV in a target script or at least do require 'm/Makefile.pm'; first.

Since the module itself just glues scripts in the Makefile, it can also be used for all kind of packages other then perl extensions.

This module is not intended for permanent installation, it should be included in the package, by default as m/Makefile.pm.

EXPORT

None by default

All routines marked as "non oo method" are in @EXPORT_OK . These exports can be used by target script for some standard functionality.

CONFIG

The config hash contains the following keys. These can be set before writing the makefile and can be accessed in the target scripts as attributes of the Makefile object.

It is adviced to do something like %config = ( 'file' = $ENV{PWD}.'/file', );> in Makefile.PL to make sure target scripts even find the meta files after doing chdir or something similar.

conf_file

Makefile.pm's config file, defaults to 'm/config.pd', if you choose an other config file you should also modify all target scripts form Makefile-new> to Makefile-new({ 'conf_file' => 'my_conf_file'})>

makefile

The name of the created makefile, defaults to 'Makefile'.

target_dir

Dir to scan for targets, defaults to 'm/targets'. All files and dirs in this dir will be regarded as make targets except dirs called 'CVS'.

default_target

Supply to target to be executed when make is run without args, defaults to 'all'.

manifest

Name of your manifest file, defaults to 'MANIFEST'. Most of my target scripts rely heavely on the manifest to be correct.

fake_targets

Array ref of target names without scripts asociated to them. In combination with "depends" used to bundle targets.

depends

Hash ref with target names as keys and arra refs as values. Array contains names of targets the key target depends on. Can be used to bundle targets.

vars

Vars should be a hash ref with of the form { var_name = default_value, }>. Values should always be strings. Var names will be translated to all caps - to acces them from targets scripts use this last form. The var "VERBOSE" is special.

Vars can be commandline args to make like: make test TEST_VERBOSE=1 and the defaults can be set both from the Makefile.PL (in the config hash) and as commandline args to Makefile.PL like: perl Makefile.PL test_verbose=1, perl Makefile.PL --test_verbose="1" or perl Makefile.PL TEST_VERBOSE=1.

include

Hash ref with package information. Used for several purposes and will be included in the Makefile as comment. For example CPAN reads dependencies from these comments.

At least provide: 'NAME', 'VERSION', 'AUTHOR' and 'PREREQ_PM' to provide package data.

The first 3 take a string, PREREQ_PM takes a hash ref with module names as keys and version numbers as values. PREREQ_PM specifies the dependencies.

Modelled after ExtUtils::MakeMaker vars.

help

Hash ref, has target names as keys and a string as value, this string is used by the print_help method.

help_postamble

String to be printed as part of the help text with print_help.

tools

Hash ref that tells Makefile.pm which interpreter to use for which extension. Also these create vars in the Makefile that can be overloaded with commandline args.

Entries have their var name as key (like vars this is set to caps) and as value an array consisting of the interpreter binary location and a array of possible file extensions. This will asociate these extensions with the given interpreter and allows you to supply alternate interpreter locations as commandline arguments.

This hash defaults to { 'PERL' = [ $Config{perl5}, ['pl', 'PL', 'pm'] ], 'SHELL' => [ $Config{sh}, ['sh'] ], }>

METHODS

new(\%config)

Simple constructor, takes config hashref. If no config is supplyed tries to read the default config file and/or uses default config.

Most likely one only supplies config from the Makefile.PL.

pd_read($file)

Eval $file and return $VAR1 .

pd_write($file, \%hash)

Print hash to file with Data::Dumper .

check_manifest()

Check for missing files, prints errors and returns bit.

manifest()

Reads the manifest and returns a array filenames.

check_dep()

Check for missing dependencies, prints errors and returns bit.

write_makefile()

Print makefile. This does _not_ create something like a Makefile.old -- if you want this do it yourself from Makefile.PL . Also this method writes a fresh config file used as a bypass around the Makefile :]

compare_version($v1, $v2) [non oo method]

Returns 0 if $v1 eq $v2, 1 if $v1 < $v2 and -1 if $v1 > $v2. Used to compare required versions to installed versions.

get_version($class_name) [non oo method]

Get version of an installed module.

get_version_from($file) [non oo method]

Get version declared in file. This uses the same regex as ExtUtils::MakeMaker uses for "VERSION_FROM" this is: /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/ . See docs MM for more details.

check_mtime($from, $to) [non oo method]

If this method returns true one can assume that the file $to doesn't need updating from $from ( think make(1) ).

make_dir($dir) [non oo method]

Create all directories in the path of $dir.

path_copy($from, $to) [non oo method]

Copy file $from to file $to, create directories if needed.

file_copy($from, $to) [non oo method]

Copy file $from to file $to, create directories if needed.

rmdir_force($dir) [non oo method]

Like rm -fr dir, used to rm non-empty dir trees. Use with care.

dir_copy($from, $to, $make) [non oo method]

Copy contents of dir $from to dir $to. If $make is set true files will only be copied if check_mtime failes.

LIMITATIONS

I do not intend to develope this module to maturity, as long as it works for my package I'm happy. (But if anyone feels like doing so ...)

I'm not sure it scales right. But this is up to your specific configuration.

It doesn't have all the fancy features like XS support, this should be implemented in target scripts, the module is just glue. On the other hand standard routines could be put in the module. Write your own fancy script or use MakeMaker instead.

It depends on other modules, see "DEPENDS" . Also the scripts use other packages like Pod::Man. This might be a problem in some situations.

I have no idea about the portability to other platforms, but one can just patch the scripts. At least it should use File::Spec but it doesn't.

DEPENDS

 Carp
 Config
 Exporter
 Strorable
 Data::Dumper

HISTORY

This module was born as part of the zoidberg project out of a personal itch with MakeMaker. Features where selected upon the needs of this project. See the Zoidberg for an extensive example.

"You all _do_ write docs, don't you?" - Schwern on Yapc::Europe::2002

AUTHOR

Jaap Karssenberg || Pardus [Larus] <j.g.karssenberg@student.utwente.nl>

Copyright (c) 2002 Jaap G Karssenberg. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Example: Zoidberg, http://zoidberg.sf.net

Related: ExtUtils::MakeMaker, CPAN::MakeMaker, Module::Build, CPAN, http://www.gnu.org/manual/make