Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Documentation and notes for perl's ExtUtils::MakeMaker

branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.pod

This document is meant to provides notes, thoughts, comments, and expositions on ExtUtils::MakeMaker, referred to henceforth as 'EU::MM'.

This is not meant to be an extensive documentation of EU::MM, nor do I claim that everything in this document is accurate.

If you have experience with EU::MM and find something wrong, or think something is missing, please use one of the github pull requests (or better yet, start an 'issues' thread) for the topic.

The immediate goals here are the following

  • Gather ideas about EU::MM's capabilities. What it can do, and what other simple helper modules (e.g. Devel::CheckLib) may be used to complement its functionality.
  • Gather ideas about EU::MM boilerplate which may be abstracted in a future API.

    This API would not be a facility for performing any kind of magic.

    This point is very important. There are sufficient modules and systems designed for automation, if the task is simple enough to fit into a cookie-cutter project.

    EU::MM (and even any wrapper APIs) will always be a relatively low-level mechanism for perfoming the gory details of compiling source code and linking them in a portable manner.

To understand EU::MM's featureset, one must understand the very basics of make(1).

Specifically, EU::MM generates make targets which are dependencies of your XS module, and rules for (I) building those dependencies and (II) linking your XS module against those dependencies.

For most simple XS modules, there are no direct external dependencies, and therefore the task is as simple as compiling the source code into simple objects and linking them together in a large shared object, loadable by DynaLoader without further dependencies.

For the more complex modules, this involves building other dependent objects which are either submodules or third-party dependencies and/or linking against them.

Some of these 'features' are not products of EU::MM itself, but possibly that of Config. In any event we present them as 'haves' for EU::MM.

EU::MM knows about the compiler directives and flags used to build Perl itself. If your perl lives in a 'user-defined' installation directory (e.g. /usr/local/, /usr/pkg, /opt/local) etc, then it will know about include directories located therein.

EU::MM also knows how to properly generate object code suitable for linking as a shared object (via $Config{cccdlflags}).

Perl knows about environment variables and linker directives needed to link shared objects from arbitrary locations. This is done via ExtUtils::Liblist. This can even figure out the exact name of the shared object.

In addition, it knows the proper way to link to a shared object, which extension to use for shared objects, and other goodies.

It can even do the equivalent of RPATH for you, with some caveats (see below).

EU::MM knows how to change into a child directory, touch a file, create a file, remove a directory, and even execute random snippets of Perl code. The output for all of these features are Makefile fragments which end up going into your Makefile.

EU::MM makes use of these features internally, but the interface facing the user is lacking

EU::MM has native support for building sub or extension projects. It does this in a very interesting way, actually requireing or doing the child Makefile.PLs.

This offers the advantage of letting a child Makefile alter or give extra parameters to the parent Makefile, while isolating the logic between different directories.

The ability to control which files are ultimately installed with your distribution. This goes against the naive assumption that everything in lib will be blindly copied over to perl's final module installation directory.

While there is no 'native' support for this, it is perfectly possible to add alternate extension directories (similar to File::ShareDir) to place non-xs and non-perl data.

Contrary to popular opinion, EU::MM allows you to place your C source code in non-top-level directories.

In addition, a helper module, Devel::CheckLib (not included with EU::MM but easily embeddable into your distribution) allows for ./configure-like features such as AC_TRY_LINK, AC_TRY_RUN and the like.

This is how you meet the very mature, stable, but horribly kludgy undocumented interface of EU::MM

TBC

Something went wrong with that request. Please try again.