.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Module::Install::XSUtil 3pm"
.TH Module::Install::XSUtil 3pm "2014-01-30" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Module::Install::XSUtil \- Utility functions for XS modules
.SH "VERSION"
.IX Header "VERSION"
This document describes Module::Install::XSUtil version 0.45.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    # in Makefile.PL
\&    use inc::Module::Install;
\&
\&    # Enables C compiler warnings
\&    cc_warnings;
\&
\&    # Uses ppport.h
\&    # No need to include it. It\*(Aqs 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 \*(Aqinclude\*(Aq; # all the header files are in include/
\&
\&    # Sets paths for source files
\&    cc_src_paths \*(Aqsrc\*(Aq; # all the XS and C source files are in src/
\&
\&    # Installs header files
\&    install_headers; # all the header files in @cc_include_paths
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Module::Install::XSUtil provides a set of utilities to setup distributions
which include or depend on \s-1XS\s0 module.
.PP
See XS::MRO::Compat and Method::Cumulative for example.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "cc_available"
.IX Subsection "cc_available"
Returns true if a C compiler is available. \s-1YOU DO NOT NEED TO CALL
THIS FUNCTION YOURSELF:\s0 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)
.SS "c99_available"
.IX Subsection "c99_available"
Returns true if a C compiler is available and it supports C99 features.
.SS "want_xs ?$default"
.IX Subsection "want_xs ?$default"
Returns true if the user asked for the \s-1XS\s0 version or pure perl version of the
module.
.PP
Will return true if \f(CW\*(C`\-\-xs\*(C'\fR is explicitly specified as the argument to
\&\fIMakefile.PL\fR, and false if \f(CW\*(C`\-\-pp\*(C'\fR is specified. If neither is explicitly
specified, will return the value specified by \f(CW$default\fR. If you do not
specify the value of \f(CW$default\fR, then it will be true.
.SS "use_ppport ?$version"
.IX Subsection "use_ppport ?$version"
Creates \fIppport.h\fR using \f(CW\*(C`Devel::PPPort::WriteFile()\*(C'\fR.
.PP
This command calls \f(CW\*(C`configure_requires \*(AqDevel::PPPort\*(Aq => $version\*(C'\fR
and adds \f(CW\*(C`\-DUSE_PPPORT\*(C'\fR to \f(CW\*(C`MakeMaker\*(C'\fR's \f(CW\*(C`DEFINE\*(C'\fR.
.SS "use_xshelper ?\-clean|\-realclean"
.IX Subsection "use_xshelper ?-clean|-realclean"
Create s\fIxshelper.h\fR, which is a helper header file to include
\&\fI\s-1EXTERN\s0.h\fR, \fIperl.h\fR, \fI\s-1XSUB\s0.h\fR and \fIppport.h\fR, and defines
some portability stuff which are not supported by \fIppport.h\fR.
.PP
Optional argument \f(CW\*(C`\-clean\*(C'\fR and \f(CW\*(C`\-realclean\*(C'\fR set \f(CW\*(C`clean_files\*(C'\fR
or \f(CW\*(C`realclean_files\*(C'\fR to the generated file \fIxshelper.h\fR respectably.
.PP
This command includes \f(CW\*(C`use_ppport\*(C'\fR.
.SS "cc_warnings"
.IX Subsection "cc_warnings"
Enables C compiler warnings.
.ie n .SS "cc_define @macros"
.el .SS "cc_define \f(CW@macros\fP"
.IX Subsection "cc_define @macros"
Sets \f(CW\*(C`cpp\*(C'\fR macros as compiler options.
.ie n .SS "cc_src_paths @source_paths"
.el .SS "cc_src_paths \f(CW@source_paths\fP"
.IX Subsection "cc_src_paths @source_paths"
Sets source file directories which include \fI*.xs\fR or \fI*.c\fR.
.ie n .SS "cc_include_paths @include_paths"
.el .SS "cc_include_paths \f(CW@include_paths\fP"
.IX Subsection "cc_include_paths @include_paths"
Sets include paths for a C compiler.
.ie n .SS "cc_inc_paths @include_paths;"
.el .SS "cc_inc_paths \f(CW@include_paths\fP;"
.IX Subsection "cc_inc_paths @include_paths;"
This \fBwas\fR an alias to \f(CW\*(C`cc_include_paths\*(C'\fR, but from 0.42,
this is \f(CW\*(C`Module::Install::Compiler::cc_inc_paths\*(C'\fR, which
replaces the \s-1EUMM\s0's \f(CW\*(C`INC\*(C'\fR parameter.
.PP
Don't use this function. Use \f(CW\*(C`cc_include_paths\*(C'\fR instead.
.ie n .SS "cc_libs @libs"
.el .SS "cc_libs \f(CW@libs\fP"
.IX Subsection "cc_libs @libs"
Sets \f(CW\*(C`MakeMaker\*(C'\fR's \f(CW\*(C`LIBS\*(C'\fR. If a name starts \f(CW\*(C`\-\*(C'\fR, it will be interpreted as is.
Otherwise prefixed \f(CW\*(C`\-l\*(C'\fR.
.PP
e.g.:
.PP
.Vb 3
\&    cc_libs \-lfoo;
\&    cc_libs  \*(Aqfoo\*(Aq; # ditto.
\&    cc_libs qw(\-L/path/to/libs foo bar); # with library paths
.Ve
.ie n .SS "cc_assert_lib %args"
.el .SS "cc_assert_lib \f(CW%args\fP"
.IX Subsection "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.
.SS "requires_c99"
.IX Subsection "requires_c99"
Tells the build system to use C99 features.
.SS "requires_cplusplus"
.IX Subsection "requires_cplusplus"
Tells the build system to use \*(C+ language.
.SS "install_headers ?@header_files"
.IX Subsection "install_headers ?@header_files"
Declares providing header files, extracts functions from these header files,
and adds these functions to \f(CW\*(C`MakeMaker\*(C'\fR's \f(CW\*(C`FUNCLIST\*(C'\fR.
.PP
If \fI\f(CI@header_files\fI\fR are omitted, all the header files in \fBinclude paths\fR will
be installed.
.ie n .SS "cc_append_to_inc @include_paths"
.el .SS "cc_append_to_inc \f(CW@include_paths\fP"
.IX Subsection "cc_append_to_inc @include_paths"
Low level \s-1API.\s0
.ie n .SS "cc_append_to_libs @libraries"
.el .SS "cc_append_to_libs \f(CW@libraries\fP"
.IX Subsection "cc_append_to_libs @libraries"
Low level \s-1API.\s0
.ie n .SS "cc_append_to_ccflags @ccflags"
.el .SS "cc_append_to_ccflags \f(CW@ccflags\fP"
.IX Subsection "cc_append_to_ccflags @ccflags"
Low level \s-1API.\s0
.ie n .SS "cc_append_to_funclist @funclist"
.el .SS "cc_append_to_funclist \f(CW@funclist\fP"
.IX Subsection "cc_append_to_funclist @funclist"
Low level \s-1API.\s0
.SH "OPTIONS"
.IX Header "OPTIONS"
Under the control of this module, \fIMakefile.PL\fR accepts \f(CW\*(C`\-g\*(C'\fR option, which
sets \f(CW\*(C`MakeMaker\*(C'\fR's \f(CW\*(C`OPTIMIE\*(C'\fR \f(CW\*(C`\-g\*(C'\fR (or something like). It will disable
optimization and enable some debugging features.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
Perl 5.5.3 or later.
.SH "NOTE"
.IX Header "NOTE"
In \fIMakefile.PL\fR, you might want to use \f(CW\*(C`author_requires\*(C'\fR, which is
provided by \f(CW\*(C`Module::Install::AuthorReauires\*(C'\fR, in order to tell co-developers
that they need to install this plugin.
.PP
.Vb 1
\&    author_requires \*(AqModule::Install::XSUtil\*(Aq;
.Ve
.SH "BUGS"
.IX Header "BUGS"
No bugs have been reported.
.PP
Please report any bugs or feature requests to the author.
.SH "ACKNOWLEDGEMENT"
.IX Header "ACKNOWLEDGEMENT"
Thanks to Taro Nishino for the test reports.
.PP
Tanks to lestrrat for the suggestions and patches.
.SH "AUTHOR"
.IX Header "AUTHOR"
Goro Fuji (gfx) <gfuji(at)cpan.org>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
ExtUtils::Depends.
.PP
Module::Install.
.PP
Module::Install::CheckLib.
.PP
Devel::CheckLib.
.PP
ExtUtils::MakeMaker.
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright (c) 2009\-2010, Goro Fuji (gfx). All rights reserved.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.