perlxstut.1

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

However, for readability purposes, it is suggested that you indent \s-1CODE:\s0
one level and the lines following one more level.
.PP
Now we'll run "\f(CW\*(C`perl Makefile.PL\*(C'\fR".  This will create a real Makefile,
which make needs.  Its output looks something like:
.PP
.Vb 5
\&    % perl Makefile.PL
\&    Checking if your kit is complete...
\&    Looks good
\&    Writing Makefile for Mytest
\&    %
.Ve
.PP
Now, running make will produce output that looks something like this (some
long lines have been shortened for clarity and some extraneous lines have
been deleted):
.PP
.Vb 10
\&    % make
\&    cp lib/Mytest.pm blib/lib/Mytest.pm
\&    perl xsubpp  \-typemap typemap  Mytest.xs > Mytest.xsc && mv Mytest.xsc Mytest.c
\&    Please specify prototyping behavior for Mytest.xs (see perlxs manual)
\&    cc \-c     Mytest.c
\&    Running Mkbootstrap for Mytest ()
\&    chmod 644 Mytest.bs
\&    rm \-f blib/arch/auto/Mytest/Mytest.so
\&    cc  \-shared \-L/usr/local/lib Mytest.o  \-o blib/arch/auto/Mytest/Mytest.so   \e
\&                \e
\&
\&    chmod 755 blib/arch/auto/Mytest/Mytest.so
\&    cp Mytest.bs blib/arch/auto/Mytest/Mytest.bs
\&    chmod 644 blib/arch/auto/Mytest/Mytest.bs
\&    Manifying blib/man3/Mytest.3pm
\&    %
.Ve
.PP
You can safely ignore the line about \*(L"prototyping behavior\*(R" \- it is
explained in the section \*(L"The \s-1PROTOTYPES:\s0 Keyword\*(R" in perlxs.
.PP
If you are on a Win32 system, and the build process fails with linker
errors for functions in the C library, check if your Perl is configured
to use PerlCRT (running \fBperl \-V:libc\fR should show you if this is the
case).  If Perl is configured to use PerlCRT, you have to make sure
PerlCRT.lib is copied to the same location that msvcrt.lib lives in,
so that the compiler can find it on its own.  msvcrt.lib is usually
found in the Visual C compiler's lib directory (e.g. C:/DevStudio/VC/lib).
.PP
Perl has its own special way of easily writing test scripts, but for this
example only, we'll create our own test script.  Create a file called hello
that looks like this:
.PP
.Vb 1
\&    #! /opt/perl5/bin/perl
\&
\&    use ExtUtils::testlib;
\&
\&    use Mytest;
\&
\&    Mytest::hello();
.Ve
.PP
Now we make the script executable (\f(CW\*(C`chmod +x hello\*(C'\fR), run the script
and we should see the following output:
.PP
.Vb 3
\&    % ./hello
\&    Hello, world!
\&    %
.Ve
.Sh "\s-1EXAMPLE\s0 2"
.IX Subsection "EXAMPLE 2"
Now let's add to our extension a subroutine that will take a single numeric
argument as input and return 0 if the number is even or 1 if the number
is odd.
.PP
Add the following to the end of Mytest.xs:
.PP
.Vb 7
\&    int
\&    is_even(input)
\&            int input
\&        CODE:
\&            RETVAL = (input % 2 == 0);
\&        OUTPUT:
\&            RETVAL
.Ve
.PP
There does not need to be whitespace at the start of the "\f(CW\*(C`int input\*(C'\fR\*(L"
line, but it is useful for improving readability.  Placing a semi-colon at
the end of that line is also optional.  Any amount and kind of whitespace
may be placed between the \*(R"\f(CW\*(C`int\*(C'\fR\*(L" and \*(R"\f(CW\*(C`input\*(C'\fR".
.PP
Now re-run make to rebuild our new shared library.
.PP
Now perform the same steps as before, generating a Makefile from the
Makefile.PL file, and running make.
.PP
In order to test that our extension works, we now need to look at the
file Mytest.t.  This file is set up to imitate the same kind of testing
structure that Perl itself has.  Within the test script, you perform a
number of tests to confirm the behavior of the extension, printing \*(L"ok\*(R"
when the test is correct, \*(L"not ok\*(R" when it is not.
.PP
.Vb 2
\&    use Test::More tests => 4;
\&    BEGIN { use_ok(\*(AqMytest\*(Aq) };
\&
\&    #########################
\&
\&    # Insert your test code below, the Test::More module is use()ed here so read
\&    # its man page ( perldoc Test::More ) for help writing this test script.
\&
\&    is(&Mytest::is_even(0), 1);
\&    is(&Mytest::is_even(1), 0);
\&    is(&Mytest::is_even(2), 1);
.Ve
.PP
We will be calling the test script through the command "\f(CW\*(C`make test\*(C'\fR".  You
should see output that looks something like this:
.PP
.Vb 6
\&    %make test
\&    PERL_DL_NONLAZY=1 /usr/bin/perl "\-MExtUtils::Command::MM" "\-e" "test_harness(0, \*(Aqblib/lib\*(Aq, \*(Aqblib/arch\*(Aq)" t/*.t
\&    t/Mytest....ok
\&    All tests successful.
\&    Files=1, Tests=4,  0 wallclock secs ( 0.03 cusr +  0.00 csys =  0.03 CPU)
\&    %
.Ve
.Sh "What has gone on?"
.IX Subsection "What has gone on?"
The program h2xs is the starting point for creating extensions.  In later
examples we'll see how we can use h2xs to read header files and generate
templates to connect to C routines.
.PP
h2xs creates a number of files in the extension directory.  The file
Makefile.PL is a perl script which will generate a true Makefile to build
the extension.  We'll take a closer look at it later.
.PP
The .pm and .xs files contain the meat of the extension.  The .xs file holds
the C routines that make up the extension.  The .pm file contains routines
that tell Perl how to load your extension.
.PP
Generating the Makefile and running \f(CW\*(C`make\*(C'\fR created a directory called blib
(which stands for \*(L"build library\*(R") in the current working directory.  This
directory will contain the shared library that we will build.  Once we have
tested it, we can install it into its final location.
.PP
Invoking the test script via "\f(CW\*(C`make test\*(C'\fR" did something very important.
It invoked perl with all those \f(CW\*(C`\-I\*(C'\fR arguments so that it could find the
various files that are part of the extension.  It is \fIvery\fR important that
while you are still testing extensions that you use "\f(CW\*(C`make test\*(C'\fR\*(L".  If you
try to run the test script all by itself, you will get a fatal error.
Another reason it is important to use \*(R"\f(CW\*(C`make test\*(C'\fR\*(L" to run your test
script is that if you are testing an upgrade to an already-existing version,
using \*(R"\f(CW\*(C`make test\*(C'\fR" ensures that you will test your new extension, not the
already-existing version.
.PP
When Perl sees a \f(CW\*(C`use extension;\*(C'\fR, it searches for a file with the same name
as the \f(CW\*(C`use\*(C'\fR'd extension that has a .pm suffix.  If that file cannot be found,
Perl dies with a fatal error.  The default search path is contained in the
\&\f(CW@INC\fR array.
.PP
In our case, Mytest.pm tells perl that it will need the Exporter and Dynamic
Loader extensions.  It then sets the \f(CW@ISA\fR and \f(CW@EXPORT\fR arrays and the
\&\f(CW$VERSION\fR scalar; finally it tells perl to bootstrap the module.  Perl
will call its dynamic loader routine (if there is one) and load the shared
library.
.PP
The two arrays \f(CW@ISA\fR and \f(CW@EXPORT\fR are very important.  The \f(CW@ISA\fR
array contains a list of other packages in which to search for methods (or
subroutines) that do not exist in the current package.  This is usually
only important for object-oriented extensions (which we will talk about
much later), and so usually doesn't need to be modified.
.PP
The \f(CW@EXPORT\fR array tells Perl which of the extension's variables and
subroutines should be placed into the calling package's namespace.  Because
you don't know if the user has already used your variable and subroutine
names, it's vitally important to carefully select what to export.  Do \fInot\fR
export method or variable names \fIby default\fR without a good reason.
.PP
As a general rule, if the module is trying to be object-oriented then don't
export anything.  If it's just a collection of functions and variables, then
you can export them via another array, called \f(CW@EXPORT_OK\fR.  This array
does not automatically place its subroutine and variable names into the
namespace unless the user specifically requests that this be done.
.PP
See perlmod for more information.
.PP
The \f(CW$VERSION\fR variable is used to ensure that the .pm file and the shared
library are \*(L"in sync\*(R" with each other.  Any time you make changes to
the .pm or .xs files, you should increment the value of this variable.
.Sh "Writing good test scripts"
.IX Subsection "Writing good test scripts"
The importance of writing good test scripts cannot be over-emphasized.  You
should closely follow the \*(L"ok/not ok\*(R" style that Perl itself uses, so that
it is very easy and unambiguous to determine the outcome of each test case.
When you find and fix a bug, make sure you add a test case for it.
.PP
By running "\f(CW\*(C`make test\*(C'\fR\*(L", you ensure that your Mytest.t script runs and uses
the correct version of your extension.  If you have many test cases,
save your test files in the \*(R"t\*(L" directory and use the suffix \*(R".t\*(L".
When you run \*(R"\f(CW\*(C`make test\*(C'\fR", all of these test files will be executed.
.Sh "\s-1EXAMPLE\s0 3"
.IX Subsection "EXAMPLE 3"
Our third extension will take one argument as its input, round off that
value, and set the \fIargument\fR to the rounded value.
.PP
Add the following to the end of Mytest.xs:
.PP
.Vb 10
\&        void
\&        round(arg)
\&                double  arg
\&            CODE:
\&                if (arg > 0.0) {
\&                        arg = floor(arg + 0.5);
\&                } else if (arg < 0.0) {
\&                        arg = ceil(arg \- 0.5);
\&                } else {
\&                        arg = 0.0;
\&                }
\&            OUTPUT:
\&                arg
.Ve
.PP
Edit the Makefile.PL file so that the corresponding line looks like this:
.PP
.Vb 1
\&        \*(AqLIBS\*(Aq      => [\*(Aq\-lm\*(Aq],   # e.g., \*(Aq\-lm\*(Aq
.Ve
.PP
Generate the Makefile and run make.  Change the test number in Mytest.t to
\&\*(L"9\*(R" and add the following tests:
.PP
.Vb 5
\&        $i = \-1.5; &Mytest::round($i); is( $i, \-2.0 );
\&        $i = \-1.1; &Mytest::round($i); is( $i, \-1.0 );
\&        $i = 0.0; &Mytest::round($i);  is( $i,  0.0 );
\&        $i = 0.5; &Mytest::round($i);  is( $i,  1.0 );
\&        $i = 1.2; &Mytest::round($i);  is( $i,  1.0 );
.Ve
.PP
Running "\f(CW\*(C`make test\*(C'\fR" should now print out that all nine tests are okay.
.PP
Notice that in these new test cases, the argument passed to round was a
scalar variable.  You might be wondering if you can round a constant or
literal.  To see what happens, temporarily add the following line to Mytest.t:
.PP
.Vb 1
\&        &Mytest::round(3);
.Ve
.PP
Run "\f(CW\*(C`make test\*(C'\fR" and notice that Perl dies with a fatal error.  Perl won't
let you change the value of constants!
.Sh "What's new here?"
.IX Subsection "What's new here?"
.IP "\(bu" 4
We've made some changes to Makefile.PL.  In this case, we've specified an
extra library to be linked into the extension's shared library, the math
library libm in this case.  We'll talk later about how to write XSUBs that
can call every routine in a library.
.IP "\(bu" 4
The value of the function is not being passed back as the function's return
value, but by changing the value of the variable that was passed into the
function.  You might have guessed that when you saw that the return value
of round is of type \*(L"void\*(R".
.Sh "Input and Output Parameters"
.IX Subsection "Input and Output Parameters"
You specify the parameters that will be passed into the \s-1XSUB\s0 on the line(s)
after you declare the function's return value and name.  Each input parameter
line starts with optional whitespace, and may have an optional terminating
semicolon.
.PP
The list of output parameters occurs at the very end of the function, just
before after the \s-1OUTPUT:\s0 directive.  The use of \s-1RETVAL\s0 tells Perl that you
wish to send this value back as the return value of the \s-1XSUB\s0 function.  In
Example 3, we wanted the \*(L"return value\*(R" placed in the original variable
which we passed in, so we listed it (and not \s-1RETVAL\s0) in the \s-1OUTPUT:\s0 section.
.Sh "The \s-1XSUBPP\s0 Program"
.IX Subsection "The XSUBPP Program"
The \fBxsubpp\fR program takes the \s-1XS\s0 code in the .xs file and translates it into
C code, placing it in a file whose suffix is .c.  The C code created makes
heavy use of the C functions within Perl.
.Sh "The \s-1TYPEMAP\s0 file"
.IX Subsection "The TYPEMAP file"
The \fBxsubpp\fR program uses rules to convert from Perl's data types (scalar,
array, etc.) to C's data types (int, char, etc.).  These rules are stored
in the typemap file ($PERLLIB/ExtUtils/typemap).  This file is split into
three parts.
.PP
The first section maps various C data types to a name, which corresponds
somewhat with the various Perl types.  The second section contains C code
which \fBxsubpp\fR uses to handle input parameters.  The third section contains
C code which \fBxsubpp\fR uses to handle output parameters.
.PP
Let's take a look at a portion of the .c file created for our extension.
The file name is Mytest.c:
.PP
.Vb 10
\&        XS(XS_Mytest_round)
\&        {
\&            dXSARGS;
\&            if (items != 1)
\&                Perl_croak(aTHX_ "Usage: Mytest::round(arg)");
\&        PERL_UNUSED_VAR(cv); /* \-W */