Create a new directory on your PC that's ready for the Cygwin downloads:

C:\>mkdir cygwin
C:\>cd cygwin
C:\cygwin>

Download the setup program. Instead of downloading a single massive tarball, we chose to download setup.exe, a sort of traffic-cop program designed to direct the rest of the installation proper, in a manner conceptually similar to the Perl configure program. We got hold of setup.exe from this URL:

http://www.cygwin.com/setup.exe

Run the setup program. Once we had downloaded setup.exe, we ran the program by double-clicking it inside the C:\cygwin directory in Windows Explorer. The first screen we saw is shown on the left in Figure 2-5.

We then pressed Next->, taking us to the screen on the right in Figure 2-5, which provided a range of three options. We decided to download our required packages from the Internet, and then install them later — you may prefer to install directly from the Internet. Choose the approach that suits you best.

We then moved progressively through the screens in Figure 2-6, choosing Internet Explorer IE5 settings, to overcome any potential proxy difficulties. As before, you may prefer alternative options.

The next stage was the pop-up list of Cygwin mirrors, shown on the left side in Figure 2-7. All the Cygwin packages, shortly to be downloaded, come from one of these mirrors.

Figure 2-5. First steps — Setting up Cygwin

Figure 2-6. Determining download locations and options

Figure 2-7. Choosing download packages

After we chose a convenient mirror, the main package selection screen appeared. Note that the setup.exe program will already have worked out the absolute base set of packages you need to get Cygwin up and running. The rest are optional. To get a real development environment going, we need more than the economy model cup-holder allocation of one for the driver. We need swing-out tables, portable showers, and a whole army of oil-damped cup-holders, all over the vehicle!

Click on the Category name tags of the main package selection screen shown in Figure 2-7. These include Admin, Archive, Base, Database, and Devel. Go ahead. Open them all up. In the early days, Cygwin used to be a single download, but it took 3.9812 eons to bring back the whole caboodle over a home Internet connection. A single rogue disconnection could lose the entire shooting match, forcing you to start all over again. Thankfully, the various bits and pieces of Cygwin are now available as separate items.

The packages we recommend you choose for a minimalist Perl-based development environment are detailed in Table 2-1. In compiling this list, we've tried to identify what's truly necessary and what's nice to have, balancing both against the restrictions of bandwidth. The safest bet, if you have both the time to spare and the hard disk capacity available, is to simply get everything. (If you don't have time or space for that now, though, you can always pick up the missed packages later on. Cygwin's setup.exe program is clever enough to determine what you've already got, and what you need. In addition, it will even flag the latest versions of programs as they become available on the Cygwin home site.)

Table 2-1. Cygwin packages for Perl development

Category	Packages required
Base	All
Devel	All
Editors	vim -- vi Improved (not that we're die-hard vi fanatics, but we do need a text editor)
Graphics	All (for possible use with DBD::Chart and other Perl-based graphics packages that rely on these libraries)
Interpreters	Perl (fairly essential, this one)
Libs	All (although in a crunch you may want to come back later for the OpenGL, OpenSSL, and Tcl/Tk libraries; make sure you do get all the Win32 libraries)

To save further time and hard disk space, you may want to avoid selecting the source code options until you need to dig down into programs of interest later on.

Once you've selected what you want, click on Next-> on the main packages selection screen in Figure 2-7, and let the download begin. At this point, you may need to go to your Win32 Start bar at the bottom of the screen in order to bring up the minimized Cygwin progress window — it may have disappeared behind all your other windows. Cygwin's setup.exe will now weave its gold and silvery magic, while we go for a nice hot cup of tea, or some other alkaloid-based stimulant.

Once we're back, and Cygwin has done its stuff, we just need to do a little housekeeping. Those who downloaded the packages, rather than installing directly, will have to rerun the first stages of the setup.exe process. This time, we install from locally supplied packages instead of downloading from the Internet. Installation should then take place, as shown in Figure 2-8.

At some point, you should also have been asked if you wanted Cygwin to be added to the Start menu and a Cygwin shortcut placed on the desktop, as in the center screen of Figure 2-8. Once these options are installed, use either route to bring up a Cygwin shell window. For good measure, check to see if Perl has been installed as expected. You can do this with the following command:

$ perl -v

Perl should now be confirmed as available under Cygwin, and we should have a full GNU-like development environment for compiling both DBI and DBD::Oracle.

Download the latest Perl DBI and DBD::Oracle tarballs to C:\cygwin from:

http://www.cpan.org/authors/id/TIMB

Now unpack the DBI tarball (once again, we used Version 1.20):

$ gzip -d DBI-1.20.tar.gz
$ tar xvf DBI-1.20.tar
$ cd DBI-1.20

Next, compile DBI:

$ make

You may get a few warnings with make under Cygwin, but everything should still be OK, as the DBI.dll file should get compiled as necessary. The final part of the output should look something like this:

...
cp dbish blib/script/dbish
/usr/bin/perl -I/usr/lib/perl5/5.6.1/cygwin-multi 
-I/usr/lib/perl5/5.6.1 -MExtUt
ils::MakeMaker -e "MY->fixin(shift)" blib/script/dbish
Manifying blib/man3/DBI.ProxyServer.3
Manifying blib/man3/DBD.Proxy.3
Manifying blib/man3/DBI.Format.3
Manifying blib/man1/dbish.1
Manifying blib/man3/DBI.Shell.3
Manifying blib/man3/DBI.3
Manifying blib/man3/DBI.FAQ.3
Manifying blib/man3/Bundle.DBI.3
Manifying blib/man3/Win32.DBIODBC.3
Manifying blib/man1/dbiproxy.1
Manifying blib/man3/DBI.W32ODBC.3
Manifying blib/man3/DBI.DBD.3
  
$

Now test and install:

$ make test
$ make install
...
Writing /usr/lib/perl5/site_perl/5.6.1/cygwin-multi/auto/DBI/.packlist
Appending installation info to /usr/lib/perl5/5.6.1/cygwin-multi/perllocal.pod
  
$

We're done!

Unpack as usual:

$ cd C:/cygwin
$ gzip -d DBD-Oracle-1.12.tar.gz
$ tar xvf DBD-Oracle-1.12.tar
$ cd DBD-Oracle-1.12

Read through some important README information, particularly the README.wingcc file:^[7]

^[7] Those new to the vi editor can read some great help pages at http://www.vim.org/html/quickref.html and http://www.vim.org/html/help.html.

$ vi README README.win32 README.wingcc

Create the liboci.a file, as instructed in README.wingcc, and place it somewhere such that Cygwin's make compilation utilities can find it later on, such as /usr/local/lib. We did this via the following steps:

$ cd C:/cygwin/DBD-Oracle-1.12
$ dlltool --input-def oci.def --output-lib liboci.a
$ ls -la liboci.a
-rw-r--r--    1 andyd None       260806 Dec 28 14:40 liboci.a
$ mv liboci.a /usr/local/lib

The required definitions archive is now available for other compilation tools, such as make, to view. Before beginning compilation, however, make sure that you can access all of the required Oracle client libraries, especially for the make test step. Change values where appropriate:

$ ORACLE_HOME=C:/ORANT
$ export ORACLE_HOME
$ ORACLE_SID=orcl
$ export ORACLE_SID
$ ORACLE_USERID=scott/tiger@orcl
$ export ORACLE_USERID

Because ActivePerl is the usual Win32 environment for DBI, Cygwin compilation can sometimes lag slightly behind other more typical Unix-style operating systems. For instance, the latest flavor of DBD::Oracle available at the time we carried out this installation was DBD-Oracle-1.12. This had slightly altered an older part of the Makefile.PL file from DBD::Oracle 1.08, a version we knew would compile without problems. The old code in Makefile.PL from DBD::Oracle 1.08 was:

die qq{  The $ORACLE_ENV environment variable value ($OH) is not valid.
  It must be set to hold the path to an Oracle installation directory
  on this machine (or a compatible archtecture).
  See the README.clients file for more information.
  ABORTED!
} unless -d $OH;

This had become updated to:

die qq{  The $ORACLE_ENV environment variable value ($OH) is not valid.
  It must be set to hold the path to an Oracle installation directory
  on this machine (or a compatible archtecture).
  See the README.clients file for more information.
  ABORTED!
} unless (($os eq 'VMS') ? -d $OH : -d "$OH/lib/.");

Notice the more complex unless condition. Although the rest of our Cygwin compilation will look for important locations, such as /lib, under $ORACLE_HOME/OCI80, the code shown previously prechecks its location directly under $ORACLE_HOME, where it will fail to find it under certain Oracle versions. It then aborts the build operation. (This is version-specific however, and anything after Oracle8i Version 8.1.5 seems to revert back to the Unix-style directory structures.)

You'll probably have no problems of your own. This is just an example of the kind of thing you have to look out for, especially if you use earlier versions of Oracle.

To get around this problem, we commented out the previous section in Makefile.PL and set it to this:

#die qq{  The $ORACLE_ENV environment variable value ($OH) is not valid.
#  It must be set to hold the path to an Oracle installation directory
#  on this machine (or a compatible archtecture).
#  See the README.clients file for more information.
#  ABORTED!
#} unless (($os eq 'VMS') ? -d $OH : -d "$OH/lib/.");

OK, this hack lacks splendor, but it does remove an immediate problem, and we're confident that it doesn't create other problems elsewhere. You may have your own little niggles to solve too, but ice-cool code warrior perseverance will see you through.

We can now begin the compilation run:

$ perl Makefile.PL

This produces rather "interesting" output:

Using DBI 1.20 installed in 
/usr/lib/perl5/site_perl/5.6.1/cygwin-multi/auto/DBI
  
 Configuring DBD::Oracle ...
  
>>>     Remember to actually *READ* the README file!
        Especially if you have any problems.
  
Using Oracle in C:/ORANT
Can't stat C:/ORANT/rdbms: No such file or directory
I can't find the header files I need in your Oracle installation.
You probably need to install some more Oracle components.
I'll keep going, but the compile will probably fail.
See README.clients for more information.
Found OCI80 directory
Using OCI directory 'OCI80'
Using liboci.a  (did you build it?)
System: perl5.006001 cygwin_nt-4.0 loreley 1.3.2(0.3932) 
2001-05-20 23:28 i686 unknown
Compiler:   gcc -O2 -DPERL_USE_SAFE_PUTENV -fno-strict-aliasing 
-I/usr/local/inc
lude
Linker:     /usr/bin/ld
Sysliblist:
  
Warning: If you have problems you may need to rebuild perl with 
-Uusemymalloc.
Checking if your kit is complete...
Looks good
LD_RUN_PATH=/usr/local/lib
Using DBD::Oracle 1.12.
Using DBI 1.20 installed in 
/usr/lib/perl5/site_perl/5.6.1/cygwin-multi/auto/DBI
Writing Makefile for DBD::Oracle
  
***  If you have problems...
     read all the log printed above, and the README 
     and README.help files.
     (Of course, you have read README by now anyway, haven't you?)

At first, this looks a little ugly, especially the fact that C:/ORANT/rdbms does not exist! Did we cause this with our hack? No, the preceding is absolutely fine and to be expected. We can ignore the C:/ORANT/rdbms problem — the compilation will later find everything it needs under C:/ORANT/OCI80/include. These kinds of warnings are only here because of the strange hybrid nature of a Unix-style Cygwin running on a Win32 box, with its own particular complexities.

We're now ready for compilation, with make — though did you also notice that reminder about liboci.a? Note also that the LD_RUN_PATH is set to /usr/local/lib. This is where we should have placed liboci.a. Now let's go for the compilation:

$ make

Again, we'll get more warnings than is usual under Unix, but as long as the liboci.a file is in /usr/local/lib (or possibly /usr/lib, if this should fail to work), there should be no real worries, and the correct Oracle.dll file should be produced. It is possible, however, that you might encounter OCI8 problems because the latest Oracle client libraries may be unavailable. For example, if you get errors saying that certain OCI definitions are undeclared (such as OCI_HTYPE_ and OCI_DTYPE_ values), you should check to see if they're declared in oci.h, which should be under the following directory:

$ORACLE_HOME/OCI80/include

If they're undeclared, you'll have two choices. You can either get more up-to-date Oracle client libraries or go back a step and run the following commands, which allow you to use the older Oracle7-style OCI libraries:

$ make clean
$ perl Makefile.PL -8
$ make

If the rogue definitions are declared in oci.h, you may need to check that the generated Makefile is including the appropriate C header file directories. More debug details should be available within the online DBD::Oracle documentation, which comes with the tarball.

Once we've got everything ship shape, we can then run the two final installation instructions:

$ make test
$ make install

We should then be able to run the program in Example 2-2, which is illustrated in Figure 2-9. We ran it with the following command:

$ perl cygwinDBI.pl

Figure 2-9. Perl DBI running under Cygwin

Example 2-2. Running DBI under Cygwin — cygwinDBI.pl

#!perl -w
  
use strict;
use DBI;
  
my $dbh = DBI->connect('DBI:Oracle:orcl', 'scott', 'tiger',
                       {RaiseError => 1, AutoCommit => 0} );
my $msg =
   $dbh->selectrow_array(
      "SELECT SYSDATE || ' Hello Cygwin DBI! :-)' message FROM DUAL"
                        );
# Lets have some formatting fun! :-)
  
my $msg_len = length( $msg );
$underline = '=' x ($msg_len + 6);
  
print "\n", $underline, "\n",
"|| ", ' ' x $msg_len, " ||", "\n",
"|| ", $msg, " ||", "\n",
"|| ", ' ' x $msg_len, " ||", "\n",
$underline, "\n\n";
  
$dbh->disconnect;

To further investigate some of the formatting operations shown in Example 2-2, try the following command to see the Perl online documentation (and see Appendix A for a full description of perldoc):

$ perldoc perlop

Now that Perl is well and truly on board, we're ready to sail out from the Perl havens and head towards an open sea of exploration and destiny. In the next few chapters, we'll examine a variety of Perl modules that extend the combined power of Perl and Oracle.