dbd.html

perl教程

access to the C functions you write that will, in turn, call down onto
your database software.</p>
<p>The Driver.h header is a stylized header that ensures you can access the
necessary Perl and DBI macros, types, and function declarations.</p>
<p>The dbdimp.h is used to specify which functions have been implemented by
your driver.</p>
<p>The dbdimp.c file is where you write the C code that does the real work
of translating between Perl-ish data types and what the database expects
to use and return.</p>
<p>There are some (mainly small, but very important) differences between
the contents of Makefile.PL and Driver.pm for pure Perl and C/XS
drivers, so those files are described both in the section on creating a
pure Perl driver and in the section on creating a C/XS driver.</p>
<p>Obviously, you can add extra source code files to the list.</p>
<p>
</p>
<h2><a name="requirements_on_a_driver_and_driver_writer">Requirements on a driver and driver writer</a></h2>
<p>To be remotely useful, your driver must be implemented in a format that
allows it to be distributed via CPAN, the Comprehensive Perl Archive
Network (http://www.cpan.org/ and <a href="http://search.cpan.org).">http://search.cpan.org).</a>
Of course, it is easier if you do not have to meet this criterion, but
you will not be able to ask for much help if you do not do so, and
no-one is likely to want to install your module if they have to learn a
new installation mechanism.</p>
<p>
</p>
<hr />
<h1><a name="creating_a_pure_perl_driver">CREATING A PURE PERL DRIVER</a></h1>
<p>Writing a pure Perl driver is surprisingly simple. However, there are
some problems you should be aware of. The best option is of course
picking up an existing driver and carefully modifying one method
after the other.</p>
<p>Also look carefully at DBD::AnyData and DBD::Template.</p>
<p>As an example we take a look at the <em>DBD::File</em> driver, a driver for
accessing plain files as tables, which is part of the <em>DBD::CSV</em>
package.
In what follows I assume the name <code>Driver</code> for your new package and the
prefix 'drv_'.
The minimal set of files we have to implement are <em>Makefile.PL</em>,
<em>README</em>, <em>MANIFEST</em> and <em>Driver.pm</em>.</p>
<p>
</p>
<h2><a name="pure_perl_version_of_makefile_pl">Pure Perl version of Makefile.PL</a></h2>
<p>You typically start with writing <a href="#item_makefile_2epl"><code>Makefile.PL</code></a>, a Makefile generator.
The contents of this file are described in detail in the
<code>ExtUtils::MakeMaker</code> man pages.
It is definitely a good idea if you start reading them.
At least you should know about the variables <em>CONFIGURE</em>, <em>DEFINED</em>,
<em>PM</em>, <em>DIR</em>, <em>EXE_FILES</em>, <em>INC</em>, <em>LIBS</em>, <em>LINKTYPE</em>, <em>NAME</em>,
<em>OPTIMIZE</em>, <em>PL_FILES</em>, <em>VERSION</em>, <em>VERSION_FROM</em>, <em>clean</em>,
<em>depend</em>, <em>realclean</em> from the <code>ExtUtils::MakeMaker</code> man page: These
are used in almost any Makefile.PL.
Additionally read the section on <em>Overriding MakeMaker Methods</em> and the
descriptions of the <em>distcheck</em>, <em>disttest</em> and <em>dist</em> targets: They
will definitely be useful for you.</p>
<p>Of special importance for DBI drivers is the <em>postamble</em> method from
the <code>ExtUtils::MM_Unix</code> man page.
And, for Emacs users, I recommend the <em>libscan</em> method, which removes
Emacs backup files (file names which end with a tilde '~') from lists of
files.</p>
<p>Now an example, I use the word <code>Driver</code> wherever you should insert
your driver's name:</p>
<pre>
  <span class="comment"># -*- perl -*-</span>
</pre>
<pre>
  <span class="keyword">use</span> <span class="variable">DBI</span> <span class="number">1.03</span><span class="operator">;</span>
  <span class="keyword">use</span> <span class="variable">DBI::DBD</span><span class="operator">;</span>
  <span class="keyword">use</span> <span class="variable">ExtUtils::MakeMaker</span><span class="operator">;</span>
</pre>
<pre>
  <span class="variable">WriteMakefile</span><span class="operator">(</span>
      <span class="variable">dbd_edit_mm_attribs</span><span class="operator">(</span> <span class="operator">{</span>
          <span class="string">'NAME'</span>         <span class="operator">=&gt;</span> <span class="string">'DBD::Driver'</span><span class="operator">,</span>
          <span class="string">'VERSION_FROM'</span> <span class="operator">=&gt;</span> <span class="string">'Driver.pm'</span><span class="operator">,</span>
          <span class="string">'INC'</span>          <span class="operator">=&gt;</span> <span class="variable">$DBI_INC_DIR</span><span class="operator">,</span>
          <span class="string">'dist'</span>         <span class="operator">=&gt;</span> <span class="operator">{</span> <span class="string">'SUFFIX'</span>   <span class="operator">=&gt;</span> <span class="string">'.gz'</span><span class="operator">,</span>
                              <span class="string">'COMPRESS'</span> <span class="operator">=&gt;</span> <span class="string">'gzip -9f'</span> <span class="operator">}</span><span class="operator">,</span>
          <span class="string">'realclean'</span>    <span class="operator">=&gt;</span> <span class="operator">{</span> <span class="string">FILES</span> <span class="operator">=&gt;</span> <span class="string">'*.xsi'</span> <span class="operator">}</span><span class="operator">,</span>
      <span class="operator">}</span><span class="operator">,</span>
      <span class="operator">{</span> <span class="string">create_pp_tests</span> <span class="operator">=&gt;</span> <span class="number">1</span><span class="operator">}</span><span class="operator">)</span>
  <span class="operator">);</span>
</pre>
<pre>
  <span class="keyword">package</span> <span class="variable">MY</span><span class="operator">;</span>
  <span class="keyword">sub</span><span class="variable"> postamble </span><span class="operator">{</span> <span class="keyword">return</span> <span class="variable">main::dbd_postamble</span><span class="operator">(</span><span class="variable">@_</span><span class="operator">);</span> <span class="operator">}</span>
  <span class="keyword">sub</span><span class="variable"> libscan </span><span class="operator">{</span>
      <span class="keyword">my</span> <span class="operator">(</span><span class="variable">$self</span><span class="operator">,</span> <span class="variable">$path</span><span class="operator">)</span> <span class="operator">=</span> <span class="variable">@_</span><span class="operator">;</span>
      <span class="operator">(</span><span class="variable">$path</span> <span class="operator">=~</span> <span class="regex">m/\~$/</span><span class="operator">)</span> <span class="operator">?</span> <span class="keyword">undef</span> <span class="operator">:</span> <span class="variable">$path</span><span class="operator">;</span>
  <span class="operator">}</span>
</pre>
<p>Note the calls to <code>dbd_edit_mm_attribs</code>() and <code>dbd_postamble</code>().
The second hash reference in the call to <code>dbd_edit_mm_attribs</code>
(containing <code>create_pp_tests</code>) is optional; you should not use it
unless your driver is a pure Perl driver (that is, it does not use C and
XS code).
Therefore, the call to <code>dbd_edit_mm_attribs</code> is not relevant for C/XS
drivers and may be omitted; simply use the (single) hash reference
containing NAME etc as the only argument to <code>WriteMakefile</code>().
Note that the <code>dbd_edit_mm_attribs</code> code will fail if you do not have a
<code>t</code> sub-directory containing at least one test case.
All drivers must use <code>dbd_postamble</code> or risk running into problems.</p>
<p>Note the specification of VERSION_FROM; the named file (Driver.pm) will
be scanned for the first line that looks like an assignment to $VERSION,
and the subsequent text will be used to determine the version number.
Note the commentary in <a href="../../lib/ExtUtils/MakeMaker.html">the ExtUtils::MakeMaker manpage</a> on the subject of
correctly formatted version numbers.</p>
<p>If your driver depends upon external software (it usually will), you
will need to add code to ensure that your environment is workable before
the call to <code>WriteMakefile</code>().
A full-fledged Makefile.PL can be quite large (for example, the files
for DBD::Oracle and DBD::Informix are both over 1000 lines long, and the
Informix one uses - and creates - auxilliary modules too).</p>
<p>See also <a href="../../lib/ExtUtils/MakeMaker.html">the ExtUtils::MakeMaker manpage</a> and <a href="../../lib/ExtUtils/MM_Unix.html">the ExtUtils::MM_Unix manpage</a>.
Consider using <a href="../../CPAN/MakeMaker.html">the CPAN::MakeMaker manpage</a> in place of ExtUtils::MakeMaker.</p>
<p>
</p>
<h2><a name="readme">README</a></h2>
<p>The README file should describe what the driver is for, the
pre-requisites for the build process, the actual build process, how to
report errors, and who to report them to.
Users will find ways of breaking the driver build and test process which
you would never even have dreamed to be possible in your worst
nightmares.
Therefore, you need to write this document defensively, precisely and
concisely.
Also, it is in your interests to ensure that your tests work as widely
as possible.
As always, use the README from one of the established drivers as a basis
for your own; the version in DBD::Informix is worth a look as it has
been quite successful in heading off problems.</p>
<ul>
<li>
<p>Note that users will have versions of Perl and DBI that are both older
and newer than you expected, but this will seldom cause much trouble.
When it does, it will be because you are using features of DBI that are
not supported in the version they are using.</p>
</li>
<li>
<p>Note that users will have versions of the database software that are
both older and newer than you expected.
You will save yourself time in the long run if you can identify the
range of versions which have been tested and warn about versions which
are not known to be OK.</p>
</li>
<li>
<p>Note that many people trying to install your driver will not be experts
in the database software.</p>
</li>
<li>
<p>Note that many people trying to install your driver will not be experts
in C or Perl.</p>
</li>
</ul>
<p>
</p>
<h2><a name="manifest">MANIFEST</a></h2>
<p>The MANIFEST will be used by the Makefile's dist target to build the
distribution tar file that is uploaded to CPAN. It should list every
file that you want to include in your distribution, one per line.</p>
<p>
</p>
<h2><a name="lib_bundle_dbd_driver_pm">lib/Bundle/DBD/Driver.pm</a></h2>
<p>The CPAN module provides an extremely powerful bundle mechanism that
allows you to specify pre-requisites for your driver.
The primary pre-requisite is Bundle::DBI; you may want or need to add
some more.
With the bundle set up correctly, the user can type:</p>
<pre>
        perl -MCPAN -e 'install Bundle::DBD::Driver'</pre>
<p>and Perl will download, compile, test and install all the Perl modules
needed to build your driver.</p>
<p>A suitable skeleton for this file is shown below.
The prerequisite modules are listed in the <code>CONTENTS</code> section, with the
official name of the module followed by a dash and an informal name or
description.
Listing Bundle::DBI as the main pre-requisite simplifies life.
Don't forget to list your driver.
Note that unless the DBMS is itself a Perl module, you cannot list it as
a pre-requisite in this file.
You should keep the version of the bundle the same as the version of
your driver.
You should add configuration management, copyright, and licencing
information at the top.</p>
<pre>
  <span class="keyword">package</span> <span class="variable">Bundle::DBD::Driver</span><span class="operator">;</span>
</pre>
<pre>
  <span class="variable">$VERSION</span> <span class="operator">=</span> <span class="string">'0.01'</span><span class="operator">;</span>
</pre>
<pre>
  <span class="number">1</span><span class="operator">;</span>
</pre>
<pre>
  __END__</pre>
<pre>
  =head1 NAME</pre>
<pre>
  Bundle::DBD::Driver - A bundle to install all DBD::Driver related modules</pre>
<pre>
  =head1 SYNOPSIS</pre>
<pre>
  C&lt;perl -MCPAN -e 'install Bundle::DBD::Driver'&gt;</pre>
<pre>
  =head1 CONTENTS</pre>
<pre>
  Bundle::DBI  - Bundle for DBI by TIMB (Tim Bunce)</pre>
<pre>
  DBD::Driver  - DBD::Driver by YOU (Your Name)</pre>
<pre>
  =head1 DESCRIPTION</pre>
<pre>