Prima::Make(3)

NAME
Prima::Make - module for automated Makefile creating

DESCRIPTION
Prima does not use standard "Make::MakeMaker" module for creating its Makefile, nor it encourages to use it for the build of Prima-dependent C modules, although this is possible. For such a module it is typical to use "Prima::Make" inside its "Makefile.PL", and use the methods that provide compilation and linking commands.

The module implements its own basic file operations, required for a typical installer: file copying, removing, creation of distributives etc. See init for details.

SYNOPSIS
   use Prima::Make;

   # check command line
   exit unless init( @ARGV );

   # object file extension
   my $o  = $Prima::Config::Config{objext};

   # store .pm files under /File directory
   setvar( 'INSTALL_LIB', $PREFIX . qd( "/File"));

   # compile command
   my $cc = cc_command_line( "a.c", "a.$o");

   # so / dll name
   my $dl = dl_name( "a" );

   # link command
   my $ld = ld_command_line( "a.c", "a.def", "a.$o");

   open F, "> Makefile";
   print F <<MAKE;
   a.$o: a.c
   \t$cc

   $dl: a.$o
   \t$ld

   clean:
   \t$^X Makefile.PL --rm a.$o $ld

   install:
   \t$^X Makefile.PL --cp $ld $INSTALL_DL a.pm $INSTALL_LIB
   \t$^X Makefile.PL --cpbin a.pl $INSTALL_BIN

   MAKE
   close F;

  API

  Methods

addlib LIBRARY
    Adds LIBRARY to list of libraries, stored in @LIBS.

canon_name FILENAME
    Converts FILENAME to a canonized form, by eliminating ".." up-references in the path.

cc_command_line C_FILE, O_FILE
    Returns suggested command for compilation of a C_FILE into output object O_FILE.

dl_name NAME
    Converts NAME without an extension into shared library / dll file name by adding the OS-dependant extension. Under OS2 NAME can be modified to overcome a problem that the system does not handle dll files with name longer than 8 letters. This is the reason why under OS/2 Prima dll file is named PrimaDI.dll .

dump_command SUB, COMMAND, @PARAMS
    Creates a line for executing COMMAND on set of PARAMS. This method is used to overcome a problem when PARAMS array is too long to be fit into the command line. The method calls SUB for each of PARAMS array scalars, and breaks the command line at each 20 parameters. SUB is an anonymous subroutine, as an only parameter receiving PARAMS array member and returns its value adapted for COMMAND.

env_true ENV_STRING
    Returns a boolean value, reflecting whether the evironment variable is a true value, ( e.g. "yes", 1, "on", "true" ) or not.

find_version MODULE
    Reads MODULE file and extracts its version without actual MODULE load via "use". If $VERSION string is found there, returns two integers - major and minor file version. Otherwise throws an exception.

generate_def DEF_FILE, LIBNAME, @EXPORTS
    Writes DEF_FILE used in linking of LIBNAME ( library or dll file ). DEF_FILE is used on Win32 and OS/2 to explicitly declare the list of exported names. These names are passed in @EXPORTS array.

    Does nothing under unix environment.

init @ARGV
    Checks the command line by parsing @ARGV array ( not @main::ARGV ). First, the checks are done if the module was invoked as an utility; such a call is constructed with a command, started with a double hyphen, for example, "--cp a.pm /perl/site/lib". The full list of commands and actions follows:

    --cp SOURCE, DEST, [ SOURCE, DEST, ... ]
        Copies SOURCE file to DEST. Can accept more than one pair.

    --cpbin SOURCE, DEST, [ SOURCE, DEST, ... ]
        Copies SOURCE file to DEST and modifies DEST so that it presents an executable script; during the operation, DEST can change both its extension and content. The method can accept more than one pair.

    --dist TYPE, DISTFILE
        Creates a distributive archive of the given TYPE, which is either "bin", "zip", or "tar". These correspond to binary archive, zip source archive, and tar source archive. In case of the binary archive, DISTFILE is combined with OS type string.

    --md PATH, [ PATH, ... ]
        Creates one or more PATH directories by calling "File::Path::mkpath", which can create a directory with more than one level at a time.

    --rm FILE, [ FILE, ... ]
        Unlinks one or more FILEs.

    If none of the options found, it is assumed that module is called for generation of "Makefile". The command line is parsed to see if it contains overridden variables. This allows the user to add, for example, paths to include and library files, select installation directories, compiling and debugging switches etc.

    The list of the user-overrideable variables is described in Variables below.

find_cdeps C_FILE, DEPENDENCIES, INCLUDES
    Scans C_FILE for the eventual dependencies of local include files. DEPENDENCIES and INCLUDES are hash references, used for global dependency accounting. DEPENDENCIES keys are C files, and its values are arrays of include files. INCLUDES keys are include files, and values are always 1. All dependencies are also cached internally, so successive calls to same C or include file do not result in file scan.

    The method does not handle conditional defines.

find_file FILENAME, PATH
    Recursively searches for FILENAME in PATH; returns two scalars - the full name and success flag.

ld_command_line DL_FILE, DEF_FILE, @O_FILES
    Returns suggested command for linking of set of object files O_FILES, with an eventual DEF_FILE into DL_FILE shared library / dll file. The name of DL_FILE is returned by "dl_name".

qd PATH
    Returns PATH with standard directory separator "/" mapped to the OS-default one.

quoted_split STRING
    Splits STRING by separate spaces, preserving the double-quoted text. Returns array of split text chunks.

setvar VARIABLE, @DEFAULT
    Sets the internal VARIABLE. If the command line contains user-preferred settings, these are used. Otherwise, DEFAULT parameters are used. The operations allowed are assignment ( "DEBUG=1" ) and concatenation ( "INCPATH+=/usr/local/include").

  Variables
The variables influence many aspects of Makefile generation. The user can tune the build process by passing variables in the command line, which are parsed in "init".

$DEBUG
    Boolean; if 1, the commands for preserving debugging symbols are emitted by "cc_command_line" and "ld_command_line".

@INCPATH
    Set of include files paths.

$INSTALL_BIN
    Installation directory for executable scripts.

$INSTALL_DL
    Installation directory for shared objects / dll files.

$INSTALL_EXAMPLES
    Installation directory for example executable scripts.

$INSTALL_LIB
    Installation directory for perl modules and include files.

@LIBPATH
    Set of library files paths.

@LIBS
    Set of library files used for linking.

$PREFIX
    An installation prefix path, under which the installed files will be copied.

$Unix, $Win32, $OS2
    Boolean flags for fast check if the current OS type is unix, win32, or os2. For extended info use $^O variable.

BUGS
The module is very experimental. Many features simply were not realized, for example, documentation in pod and man files.

AUTHOR
Dmitry Karasik, <dmitry@karasik.eu.org>.

SEE ALSO
Prima, gencls, IPA ( http://www.prima.eu.org/IPA ).