libwww-perl Installation Information ==================================== # $Id: INSTALL.txt,v 0.15 1994/09/21 01:23:18 fielding Exp $ See the files README.html and Artistic.txt for licensing and distribution info. See the file LWP_Changes.pl for a complete list of changes and version history. The latest version of libwww-perl can always be found at: http://www.ics.uci.edu/WebSoft/libwww-perl/ or by anonymous ftp from ftp://liege.ics.uci.edu/pub/arcadia/libwww-perl/ ========================================================================== Installation instructions: 1. Get the libwww-perl package from the distribution site (above). Normally, it will be in the form of a compressed unix tar file. If it has not already been decompressed by your WWW client, then do one of: % uncompress libwww-perl-V.vv.tar.Z % gunzip libwww-perl-V.vv.tar.gz depending on which compressed version you downloaded. "V.vv" should be replaced with the library version number, e.g. "0.40". 2. Move the resulting libwww-perl-V.vv.tar file to the directory above where you want to install libwww-perl, cd to that directory, and do % tar xvf libwww-perl-V.vv.tar to create the directory ./libwww-perl-V.vv containing the following: Artistic.txt -- the Artistic License governing redistribution of the libwww-perl package. INSTALL.txt -- this file LWP_Changes.pl -- the list of known problems and version information. Makefile -- a Makefile for automating the initial configuration. RCS/ -- the complete RCS repository, including all versions. README.html -- primary source of information about libwww-perl get -- a simple program for performing WWW GET requests from the command-line. The name of the program determines what request method to be used (i.e. create a link to it called "head" and you have a program that does HEAD requests). This program demonstrates the power and simplicity of the libwww-perl interface. hostname.pl -- a library for determining the fully qualified domain name for the host running libwww-perl. mime.types -- the standard MIME content-types and default filename extensions in the same format as that used by NCSA httpd_1.3 and many WWW clients. sys_socket_ph.c - A simple C program for displaying your system's symbolic values normally found in sys/socket.ph. testbot -- a simple program for testing the wwwbot.pl package. testdates -- a simple program for testing the wwwdates.pl package. testescapes -- a program for testing wwwurl'escape and unescape. testlinks -- a simple program for testing HTML link extraction and combinations of GET and HEAD requests. www.pl -- the primary entry point for WWW requests -- give it any absolute URL and a request method and it will try to perform the method using the URL's protocol scheme (or a proxy). wwwbot.pl -- a package for implementing the robot exclusion protocol. wwwdates.pl -- a package of library utilities for reading, manipulating, and writing dates as they are formatted by most World-Wide Web software and protocols. wwwerror.pl -- a package for defining and generating error messages for requests which did not make it outside the client program. wwwfile.pl -- a package for performing local file requests (URLs of the form file://localhost/*) and returning a response as if it came from an HTTP server. wwwhtml.pl -- a package of library utilities for reading and manipulating HTML documents. wwwhttp.pl -- a package for performing HTTP requests (URLs of the form http:*). wwwmailcap.pl -- a package of library utilities for handling MIME mailcap files and executing viewers by content-type. wwwmime.pl -- a package of library utilities for handling MIME content-types and message headers. wwwurl.pl -- a package of library utilities for parsing, composing, manipulating, and canonicalizing Uniform Resource Locators (URLs) as they are used by the World-Wide Web software and protocols. 3. Edit the Makefile to match your system configuration. All you should need to change is the value of PERLBIN -- the full pathname of your perl interpreter. Then, perform the command % make If the full pathname of your perl interpreter is not "/usr/public/bin/perl", you should also perform the command: % make config 4. Set the LIBWWW_PERL environment variable to point to the libwww-perl directory, e.g. % setenv LIBWWW_PERL /usr/local/lib/libwww-perl-V.vv This allows clients like "get" to place the libwww-perl on their @INC path and also allows wwwmime.pl to find the standard mime.types file. 5. That's it. You should now be able to run get, HEAD and POST, as well as the other library test* programs. See the usage info and the FAQ list below for more information. ========================================================================== Usage: See the "get" and test* programs for examples of how to interface with libwww-perl. More documentation will be available later. The "get" program is a production-quality WWW client, useful for performing quick downloads from HTTP servers, translating FILE directories to HTML, and testing request/response headers on HTTP servers. usage: get [-heqd] [-b BaseURL] [-t Timeout] [-i IMS_date] [-c ContentType] [URL ...] GET/0.5 -- A program for sending GET requests for World-Wide Web URLs Options: [DEFAULT] -h Help -- just display this message and quit. -e Display the request and response headers to STDERR. [STDOUT] -q Don't display the request and response headers. -d Don't display the content (useful for debugging servers). -b Start with the given Base URL. [file://localhost/co/ub/fielding/public/www/lwp/libwww-perl/] -t Start with the given Timeout value (in seconds) [30] -i Add the If-Modified-Since header (an HTTP date) to GET requests. -c Use the given MIME Content-type for POST, PUT, and CHECKIN requests. [application/x-www-form-urlencoded] URL ... Perform the GET request on each URL listed. If no URLs are listed on the command-line, the program enters an interactive mode. The following commands are available interactively: base=BaseURL -- changes the current Base URL to that given. tout=NNNN -- sets the current Timeout value (in seconds). ims=IMS_date -- sets the If-Modified-Since header value. URL -- performs the request on the given URL. Here's a nice way to download information AND see the response headers: % get -e http://www.ics.uci.edu/WWWdocs/papers/rfc1630.txt > rfc1630.txt And, since the method used is equal to the program's name (uppercased), you can use symbolic links to create other useful programs, e.g. % echo "tick=sunw" | POST http://www.secapl.com/cgi-bin/qs Give it a try. I have only tested the GET, HEAD, and POST methods, but all the others are supported as well (though they may not be supported by any server). ========================================================================== Frequently Asked Questions 1. Why doesn't libwww-perl support FTP, Gopher, WAIS, ... ? Because you haven't written the interface yet ;-) Seriously, though, all you need to do to add a new protocol to the library is to copy an existing one (e.g. "cp wwwhttp.pl wwwftp.pl") and define the contents of the %AllowedMethods array and the scheme's request function (e.g. wwwftp'request()), and then include a "require" statement in the main program that uses it. That's it -- determination of whether or not a protocol module exists is made dynamically by &www'request(). 2. How do I contribute my changes to the standard distribution? First, you should join the mailing list by sending a subscribe request, including your name and preferred e-mail address, to . You will be sent a welcome message when you are placed on the list. To see what the list looks like, see the Hypermail Archive of it at: After that, send a mail message describing your changes or suggestions to and we can all talk about them. If you have RCS (or CVS), you can use the included RCS repository to keep track of your changes and merge them with later distributions. You are also free to send changes to others by mail or news (or even disk), just as long as you don't claim they are part of the "standard distribution" of libwww-perl. 3. Help, I have encountered a bug and I don't know what to do... First, look at the hypertext archive (the URL above) to see if a similar problem has already been discussed on the mailing list. If not, send a message to the mailing list which describes the problem and symptoms, etc. Above all, be sure to mention what platform you are running on, since most of the problems discovered so far have been platform-specific. Finally, if you solve a problem, be sure to send the solution to the mailing list as well. 4. Undefined subroutine "main'_BSD" called at /usr/local/lib/perl/sys/socket.ph Arrgh! This has been the big problem so far with SVR4 and mach-based system installs. What you need to do is create a sys/socket.ph file for your perl standard library which is valid for your system. Normally, you can just run the "h2ph" command (part of the perl distribution) to set up the files, but some SVR4 and mach-based systems use extra symbols which can't be found by h2ph. So, you need to do one (or more) of the following: A. Comment out the lines in sys/socket.ph that generate errors (they are rarely needed in any case). B. Add your own definitions to the sys/socket.ph, e.g. eval 'sub BSD { 0; }'; You may have to guess the correct value, or do a grep on /usr/include/sys/*.h to find the exact definition. C. Create your own canned socket.ph file via the included C program sys_socket_ph.c -- compile and run it using the commands: % make socket % sys_socket_ph > my_socket.ph and then edit "wwwhttp.pl" (in the libwww-perl stuff) to replace the require "sys/socket.ph" with require "my_socket.ph"; Depending on the vagaries of your system, at least one of the above fixes should work. ========================================================================== Have fun, ......Roy Fielding ICS Grad Student, University of California, Irvine USA