perl the complete reference second edition phần 8 doc

Chapter 24: Cross-Platform Migration Traps 835 FINE-TUNING APPLICATIONS Note that the actual test must be done within the BEGIN block so that it is executed at compile rather than run time; then, by the time compilation reaches the use subs pragma, the contents of @functions has already been populated with the required information. The definition for chown is then placed into the MyBuiltin package, which is defined just like any other: package MyBuiltin; require Exporter; @ISA = qw/Exporter/; @EXPORT = (); @EXPORT_OK = qw/chown/; sub chown { print "Changed mode!"; return 1; } The contents of @EXPORT should be empty, since you don’t want to import anything as standard. The value of @EXPORT_OK contains the list of built-in functions that you want to support and overload, if necessary. Thus, when you call use MyBuiltin with a list of unsupported built-in functions, you import your own list of replacements. In this example, a simple print statement is used to show that the overloading is working. In an actual case, you’ll probably want to put some real functionality into the functions you want to overload. If you are testing a lot of functions, you will need to use loops and references to test the functions you want to overload: BEGIN { @subtest = qw/chown exec/; foreach $function (@subtest) { eval { &$function }; push @functions,$function if $@; } } It’s not possible in this to optimize the loop by placing the foreach loop within the eval block, since you’re using each eval invocation to test the existence of each function. This is a performance hit, but the overall process improves compatibility, and it’s one of the trade-offs examined at the beginning of the chapter. This page intentionally left blank. Chapter 25 Distributing Modules and Applications 837 Copyright 2001 The McGraw-Hill Companies, Inc. Click Here for Terms of Use. O nce you’ve written your Perl module or application, there are a few more steps you need to follow before it can finally be unleashed on the public. Although there’s no fixed route to this process, it will probably go something like this: ■ Debug and optimize the module or application ■ Optionally compile the script into a stand-alone application or library ■ Document the script and update the comments to reflect any changes ■ Ensure cross-platform compatibility, providing you want to support multiple platforms We’ve actually covered all these stages in the past chapters in this section, but there is one final stage—that of packaging up and making your module or application for distribution to the rest of the world. In this last chapter, we’re going to concentrate purely on the process behind packaging up your module or application for distribution. The core of this process centers around the ExtUtils::MakeMaker module and Perl makefiles. These are essentially the same as normal makefiles as used by make, but are parsed by the MakeMaker utility into the real thing, substituting the correct directories, command names, and other information to allow easy installation of your module or application. We’ll also look at some examples of using Perl makefiles, how to package a module up for distribution to CPAN, and how to package up modules for use with the ActiveState Perl Package Manager (PPM) format. Perl Makefiles and ExtUtils::MakeMaker We looked at the use of Perl makefiles in Chapter 20, when we set up and built an extension. The makefile system is an integral part of the XS extension system, and a makefile is automatically built for you when you use the h2xs utility. Although its primary use is for building and installing modules and extensions, it can actually be used for practically any installation that requires some form of automatic process. The Perl makefile is, like many other parts of the Perl environment, just a Perl script. It uses a module, ExtUtils::MakeMaker, and a configuration supplied in the form of a hash to work out how to build and install the different elements of a package. When the script executes, it loads the ExtUtils::MakeMaker module, determines the local configuration parameters, such as the location of the active Perl binary, the library directories, and other information, and then builds a makefile that can be used in combination with the standard make command to actually extract, compile (if necessary), and install the module or application into its correct location. In this section, we’re going to look at how the ExtUtils::MakeMaker module works and how to configure the system for your own uses above and beyond the default files produced by h2xs. 838 Perl: The Complete Reference FINE-TUNING APPLICATIONS Chapter 25: Distributing Modules and Applications 839 The ExtUtils::MakeMaker module actually splits the task of makefile generation into several subroutines, and the overall configuration that is used with these subroutines is infinitely configurable. In each case, the subroutines provided by the module return the text that is required to be written to the makefile. The whole system is object oriented, and the production of individual files within the MakeMaker system is possible at all levels. Each file created is treated as a single object, and therefore a single MakeMaker configuration can generate a number of makefiles both for the original target and for subdirectories and their targets. Perl Makefiles and CPAN To the untrained eye, it might appear that the CPAN module and the MakeMaker module are closely linked, since we can use CPAN to download and automatically install these modules for us. In fact, the two items are relatively independent. The MakeMaker tool works just as well if used “manually” at the command line—it still produces a makefile that needs to be parsed by make before it does anything. The CPAN module knows the required sequence of downloading, extracting, running the MakeMaker tool, and then running make—if it wasn’t for the ease of use provided by MakeMaker, CPAN would be difficult to write because the process would be different for each module. If you want to supply your module to CPAN, then check www.cpan.org for the precise submission details. You’ll need to package up your source files and the Makefile.PL script using tar and gzip. If you want to support the module under Windows, then check the “Packing for PPM/VPM” section later in this chapter. For more information on CPAN, see Chapter 2, Appendix B, and Web Appendix B. Perl Makefiles and PPM The Perl Package Manager (PPM) and the Visual Package Manager (VPM) are part of ActivePerl and the Perl Developer’s Kit, respectively. These work in a similar way to CPAN, downloading an extension or application automatically from a central repository and then installing the extension for you. However, unlike CPAN, extensions supplied through PPM are precompiled and ready to install, rather than requiring the usual make step. ActivePerl was, up until Perl 5.6, a Windows-only solution, but since the 5.6 release, other versions are now available for a number of Linux and Unix platforms. The main advantage of PPM over CPAN is that it doesn’t require the end-user to have access to a compiler and development environment to install the extension. See Chapter 2 for more information on how to use PPM, and see the “Packing for PPM/VPM” section later in this chapter. Extension Building and Installation Overview Most of this process will be familiar; we’ve seen a lot of it already in Chapter 20. However, the build and installation process is slightly more complex than the examples we have already seen. You should already be aware that the extension uses the AutoLoader module to decide which function should be included. The AutoLoader module is actually capable of a number of different operations. Depending on the context and requirements, it can do one of the following: ■ Perform the function itself; the caller will never know that the AutoLoader has been used. ■ Create the function on the fly using an eval statement. ■ Use the system function to launch an external program of the same name. ■ Dynamically load a library using the DynaLoader module. It is the last option that is used to load an external C library extension. The AutoSplit module is used to separate the original Perl module file into separate files, one per function, and a mapping within the split file then tells DynaLoader which library to load in order to implement the function. This loading mechanism requires a bootstrap file and an autoload file, which are both used to select the correct library location for the function, based on the library that was built and the split module. The whole system uses a specialized structure within the Perl module directory that accounts for both site and architecture differences. The entire process for the makefile produced by MakeMaker (under Solaris) is shown here. Entries taken from the StatVFS module we saw in Chapter 20 are used for reference: 1. A directory structure is created within the extensions directory that will hold the files produced during the build process before they are installed: mkdir blib mkdir blib/lib mkdir blib/arch mkdir blib/arch/auto mkdir blib/arch/auto/StatVFS mkdir blib/lib/auto mkdir blib/lib/auto/StatVFS mkdir blib/man3 cp StatVFS.pm blib/lib/StatVFS.pm 2. The module is split into individual functions. Each function is placed into the auto/StatVFS directory: AutoSplitting blib/lib/StatVFS.pm (blib/lib/auto/StatVFS) 840 Perl: The Complete Reference TEAMFLY Team-Fly ® 3. The XS file is parsed by xsubpp, producing the C file that contains the necessary functions: /usr/bin/perl -I/usr/local/lib/perl5/5.00553/sun4-solaris -I/usr/local/lib/perl5/5.00553 /usr/local/lib/perl5/5.00553/ExtUtils/xsubpp -typemap /usr/local/lib/perl5/5.00553/ExtUtils/typemap StatVFS.xs >xstmp.c && mv xstmp.c StatVFS.c 4. The source code is compiled into object format: gcc -B/usr/ccs/bin/ -c -I/usr/local/include -DDEBUGGING -O -DVERSION=\"0.01\" -DXS_VERSION=\"0.01\" -fPIC -I/usr/local/lib/perl5/5.00553/sun4-solaris/CORE StatVFS.c 5. The bootstrap code required for DynaLoader is produced. The StatVFS.bs file contains the necessary information to enable DynaLoader to relate the Perl call to the C function: Running Mkbootstrap for StatVFS () chmod 644 StatVFS.bs 6. The library file is generated in its dynamic format: LD_RUN_PATH="" gcc -B/usr/ccs/bin/ -o blib/arch/auto/StatVFS/StatVFS.so -G -L/usr/local/lib StatVFS.o 7. The library and the bootstrap code are copied into the correct location ready for installation, and the file modes are set to their correct values: chmod 755 blib/arch/auto/StatVFS/StatVFS.so cp StatVFS.bs blib/arch/auto/StatVFS/StatVFS.bs chmod 644 blib/arch/auto/StatVFS/StatVFS.bs 8. The POD format documentation in the Perl module is extracted and converted into a man page, ready for installation: Manifying blib/man3/StatVFS.3 The main process is now finished. The installation process just copies the structure below the blib directory into the site- or architecture-specific directories within the Perl library directory. At this point, if you want to test the module, you can use the make test command. The test files will need to include the just-built version of the library. See the blib pragma in Chapter 19 for more information on this. FINE-TUNING APPLICATIONS Chapter 25: Distributing Modules and Applications 841 The actual installation process has its tricks too. The following sample is a continuation of the StatVFS module example. 1. The files are copied to the specified installation directory. This is defined as a whole by the PREFIX option and individually with the INSTALL* options. Installing /usr/local/lib/perl5/site_perl/5.00553/sun4- solaris/auto/StatVFS/StatVFS.so Installing /usr/local/lib/perl5/site_perl/5.00553/sun4- solaris/auto/StatVFS/StatVFS.bs Files found in blib/arch -> Installing files in blib/lib into architecture dependent library tree! Installing /usr/local/lib/perl5/site_perl/5.00553/sun4- solaris/auto/StatVFS/autosplit.ix Installing /usr/local/lib/perl5/site_perl/5.00553/sun4-solaris/ StatVFS.pm Installing /usr/local/lib/perl5/5.00553/man/man3/StatVFS.3 2. A list of the files installed during the installation process is written in a special file, called .packlist in the module’s AutoLoader directory. The actual location will depend on whether you have installed an architecture or site version. See the INSTALLDIRS option later in the chapter. Writing /usr/local/lib/perl5/site_perl/5.00553/sun4- solaris/auto/StatVFS/.packlist 3. The installation information, including the configuration details, is written to a general file that can later be consulted (preferably via a POD file viewer) to study which packages and extensions have been installed and when. This can also be a helpful starting point for tracing problems when a script or module suddenly stops working. Appending installation info to /usr/local/lib/perl5/5.00553/sun4- solaris/perllocal.pod The rest of this chapter is devoted to describing the configurable parameters to the MakeMaker module. We’ll also take the opportunity to look at some of the other modules that are used by the MakeMaker module to do its work. MakeMaker Overview The basic use of the MakeMaker module is very simple. The synopsis for the module is use ExtUtils::MakeMaker; WriteMakefile( ATTRIBUTE => VALUE [, ] ); 842 Perl: The Complete Reference FINE-TUNING APPLICATIONS The basic method of operation is to create a simple file that imports the module and then calls the WriteMakefile function. You need to specify at least one attribute to the function, which is the name of the module. For example, to create the makefile for building the StatVFS module we created in Chapter 20, you could get away with as little as the following in Makefile.PL: use ExtUtils::MakeMaker; WriteMakefile('NAME' => 'StatVFS'); When run through a Perl interpreter, like this, $ perl Makefile.PL it automatically produces a makefile capable of building and installing the extension. It accounts for the location of all the necessary libraries and include files, and it selects the correct C compiler and definitions in order to ensure that the extension is compiled properly. This information is selected from the information produced at build time and is specific to the platform on which you use the MakeMaker file. Thus, the Perl makefile is completely platform independent. Any platform on which you can build Perl should be able to produce a suitable makefile for the platform for building an extension. The resulting makefile produced is, of course, platform- and build-specific, even though the original Makefile.PL file is completely platform independent. It’s the MakeMaker module that provides the platform-independent information required to build the module. The resulting makefile is big—751 lines long. It is too long, and completely pointless, to reproduce here. The point about MakeMaker is that it hides all the complexity of the makefile production from the user and just ensures that the file produced should work on whatever platform Perl is installed on. Start with h2xs It doesn’t matter what sort of module, extension, or application you are dealing with— it’s almost certainly easier to create the makefile using h2xs. The h2xs tool is actually designed to convert a header file into a suitable set of stub XS extensions ready for integrating into Perl. However, it can also be used to create a simple MakeMaker template. The command line options for the tool are shown in Table 25-1. If you want just to create a dummy MakeMaker template, then you should use $ h2xs -f -n MyModule -X Writing MyModule/MyModule.pm Writing MyModule/Makefile.PL Writing MyModule/test.pl Writing MyModule/Changes Writing MyModule/MANIFEST Chapter 25: Distributing Modules and Applications 843 Note that it creates most of the files that you need, including a blank module, test script, MANIFEST file (which lists the files that make up your module), and the MakeMaker template in Makefile.PL. The default template looks like this: use ExtUtils::MakeMaker; # See lib/ExtUtils/MakeMaker.pm for details of how to influence # the contents of the Makefile that is written. WriteMakefile( 'NAME' => 'MyModule', 'VERSION_FROM' => 'MyModule.pm', # finds $VERSION 'PREREQ_PM' => {}, # e.g., Module::Name => 1.1 ); 844 Perl: The Complete Reference Option Description -A Omit the autoloading definitions (implies the -c option). -F Additional flags for C preprocessor (used with -x). -O Allow overwriting of a preexisting extension directory. -P Omit the stub POD section. -X Omit the XS portion. -c Omit the constant() function and specialized AUTOLOAD from the XS file. -d Turn on debugging messages. -f Force creation of the extension. -n Specify a name to use for the extension—defaults to a title case version of the header file’s base name. -p Specify a string that will be removed from the start of the C functions when they are reproduced as Perl functions. -s Create subroutines for specified macros. -v Specify a version number for this extension. -x Autogenerate XSUBs using C::Scan. Table 25-1. Command Line Options for h2xs [...]... executed by the miniperl binary created during a Perl build PERLMAINCC A string defining the program to use for compiling the perlmain.c file The default is to use the value of $(CC) PERL_ ARCHLIB PERL_ LIB A string defining the libraries to be used for building the Perl binary A string specifying the directory containing the Perl library PERL_ MALLOC_OK Should be set to true if you are happy to have the extension... precompiled version of the module, rather than its raw source FINE-TUNING APPLICATIONS $ make dist 86 4 Perl: The Complete Reference You need to develop the Perl makefile and the options and other tricks you use with MakeMaker as normal, build it on your target platform, and then produce a separate file, the PPD, which contains all of the information about the module required by the PPM system There is, of course,... Applications 86 3 You can see here the Perl code to install links for GET, HEAD, and POST The $Config{"lns"} is the name of the link command determined by Perl during the build process, and the rest is just a foreach loop that first deletes and then creates the link The links are made in the blib/script directory and will be copied into the final script directory (/usr/local/bin) during the installation... incorporated into the new static Perl binary However, if you specify a list of specific options in INCLUDE_EXT, then only the extensions listed will be included in the final binary The DynaLoader extension (if supported) will always be included in the binary If you specify an empty array, only the current extension (and DynaLoader) will be included 84 8 Perl: The Complete Reference INSTALLHTMLPRIVLIBDIR The directory... created—Makefile.aperl, although the exact name is system dependent This contains the definitions for building a new Perl binary 3 The new makefile is used to produce the new binary, first by creating a new file with a modified main() function, and then by linking the resulting object file with the main Perl library and the extension library The new Perl binary is created within the current directory... installed over the existing binary using $ make -f Makefile.aperl inst _perl The final binary actually includes all the extensions specified in the INST_ARCHLIB, SITELIBEXP, and PERL_ ARCHLIB options defined within the main MakeMaker definition You can create a Perl binary with a different file name by defining the value of MAP_TARGET in the Perl makefile The best way to do this is on the command line,... Chapter 25: Distributing Modules and Applications 84 7 FIRST_MAKEFILE A string defining the name of the makefile to be produced for the MAP_TARGET—defaults to the value of the MAKEFILE option FULLPERL H A string defining the name of the Perl binary able to run this extension A reference to an array of the header files within the extension distribution HTMLLIBPODS Reference to a hash of pm and pod files to... file and then zip them using gzip The name of the resultant file will be based on the NAME and VERSION options in the Perl makefile Packing for PPM/VPM The Perl Package Manager is actually very similar to the CPAN module, and it provides a way for users of the ActivePerl distribution to download and install modules precompiled for a number of platforms, but primarily the Windows series This is the only... including, the installation process Other default targets are shown in Table 25-2 Other targets deserving special mention are covered in the following sections FINE-TUNING APPLICATIONS ExtUtils::MakeMaker::WriteEmptyMakefile(); 85 4 Perl: The Complete Reference Target Description test Runs the defined test script(s) testdb Runs the defined test script(s) within the Perl debugger install Installs the extension,... support dynamic loading, and in these and other situations you may wish to create your own statically linked Perl executable that includes the new extension If this is the case, you can use a special target, perl, to the makefile produced by the MakeMaker module The operation is then slightly different from the normal build process: 1 The extension is recompiled into a static rather than a dynamic library . the name of the makefile to be produced for the MAP_TARGET—defaults to the value of the MAKEFILE option FULLPERL A string defining the name of the Perl binary able to run this extension H A reference. INSTALLHTMLPRIVLIBDIR during a make install. 84 8 Perl: The Complete Reference INST_HTMLSCRIPTDIR The directory that will hold the HTML documents during build time; they will be copied from here into INSTALLHTMLSCRIPTDIR. building the Perl binary. PERL_ LIB A string specifying the directory containing the Perl library. PERL_ MALLOC_OK Should be set to true if you are happy to have the extension built using the Perl