NAME

       Module::Install::XSUtil - Utility functions for XS modules

VERSION

       This document describes Module::Install::XSUtil version 0.45.

SYNOPSIS

           # in Makefile.PL
           use inc::Module::Install;

           # Enables C compiler warnings
           cc_warnings;

           # Uses ppport.h
           # No need to include it. It's created here.
           use_ppport 3.19;

           # Sets C pre-processor macros.
           cc_define q{-DUSE_SOME_FEATURE=42};

           # Sets paths for header files
           cc_include_paths 'include'; # all the header files are in include/

           # Sets paths for source files
           cc_src_paths 'src'; # all the XS and C source files are in src/

           # Installs header files
           install_headers; # all the header files in @cc_include_paths

DESCRIPTION

       Module::Install::XSUtil provides a set of utilities to setup distributions which include
       or depend on XS module.

       See XS::MRO::Compat and Method::Cumulative for example.

FUNCTIONS

   cc_available
       Returns true if a C compiler is available. YOU DO NOT NEED TO CALL THIS FUNCTION YOURSELF:
       it will be called for you when this module is initialized, and your Makefile.PL process
       will exit with 0 status.  Only explicitly call if you need to do some esoteric handling
       when no compiler is available (for example, when you have a pure perl alternative)

   c99_available
       Returns true if a C compiler is available and it supports C99 features.

   want_xs ?$default
       Returns true if the user asked for the XS version or pure perl version of the module.

       Will return true if "--xs" is explicitly specified as the argument to Makefile.PL, and
       false if "--pp" is specified. If neither is explicitly specified, will return the value
       specified by $default. If you do not specify the value of $default, then it will be true.

   use_ppport ?$version
       Creates ppport.h using "Devel::PPPort::WriteFile()".

       This command calls "configure_requires 'Devel::PPPort' => $version" and adds
       "-DUSE_PPPORT" to "MakeMaker"'s "DEFINE".

   use_xshelper ?-clean|-realclean
       Create sxshelper.h, which is a helper header file to include EXTERN.h, perl.h, XSUB.h and
       ppport.h, and defines some portability stuff which are not supported by ppport.h.

       Optional argument "-clean" and "-realclean" set "clean_files" or "realclean_files" to the
       generated file xshelper.h respectably.

       This command includes "use_ppport".

   cc_warnings
       Enables C compiler warnings.

   cc_define @macros
       Sets "cpp" macros as compiler options.

   cc_src_paths @source_paths
       Sets source file directories which include *.xs or *.c.

   cc_include_paths @include_paths
       Sets include paths for a C compiler.

   cc_inc_paths @include_paths;
       This was an alias to "cc_include_paths", but from 0.42, this is
       "Module::Install::Compiler::cc_inc_paths", which replaces the EUMM's "INC" parameter.

       Don't use this function. Use "cc_include_paths" instead.

   cc_libs @libs
       Sets "MakeMaker"'s "LIBS". If a name starts "-", it will be interpreted as is.  Otherwise
       prefixed "-l".

       e.g.:

           cc_libs -lfoo;
           cc_libs  'foo'; # ditto.
           cc_libs qw(-L/path/to/libs foo bar); # with library paths

   cc_assert_lib %args
       Checks if the given C library is installed via Devel::CheckLib.  Takes exactly what
       Devel::CheckLib takes. Note that you must pass the path names explicitly.

   requires_c99
       Tells the build system to use C99 features.

   requires_cplusplus
       Tells the build system to use C++ language.

   install_headers ?@header_files
       Declares providing header files, extracts functions from these header files, and adds
       these functions to "MakeMaker"'s "FUNCLIST".

       If @header_files are omitted, all the header files in include paths will be installed.

   cc_append_to_inc @include_paths
       Low level API.

   cc_append_to_libs @libraries
       Low level API.

   cc_append_to_ccflags @ccflags
       Low level API.

   cc_append_to_funclist @funclist
       Low level API.

OPTIONS

       Under the control of this module, Makefile.PL accepts "-g" option, which sets
       "MakeMaker"'s "OPTIMIE" "-g" (or something like). It will disable optimization and enable
       some debugging features.

DEPENDENCIES

       Perl 5.5.3 or later.

NOTE

       In Makefile.PL, you might want to use "author_requires", which is provided by
       "Module::Install::AuthorReauires", in order to tell co-developers that they need to
       install this plugin.

           author_requires 'Module::Install::XSUtil';

BUGS

       No bugs have been reported.

       Please report any bugs or feature requests to the author.

ACKNOWLEDGEMENT

       Thanks to Taro Nishino for the test reports.

       Tanks to lestrrat for the suggestions and patches.

AUTHOR

       Goro Fuji (gfx) <gfuji(at)cpan.org>.

SEE ALSO

       ExtUtils::Depends.

       Module::Install.

       Module::Install::CheckLib.

       Devel::CheckLib.

       ExtUtils::MakeMaker.

LICENSE AND COPYRIGHT

       Copyright (c) 2009-2010, Goro Fuji (gfx). All rights reserved.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.