initial man page attempt for testcurl.pl

3 files changed, 125 insertions, 5 deletions

diff --git a/tests/Makefile.am b/tests/Makefile.am
index 4aa1d1347..6a968adf9 100644
--- a/tests/Makefile.am
+++ b/tests/Makefile.am
@@ -22,7 +22,7 @@
 ###########################################################################
 EXTRA_DIST = ftpserver.pl httpserver.pl httpsserver.pl runtests.pl	\
  ftpsserver.pl getpart.pm FILEFORMAT README stunnel.pem memanalyze.pl	\
- testcurl.pl valgrind.pm
+ testcurl.pl valgrind.pm testcurl.1
 
 SUBDIRS = data server libtest
 
diff --git a/tests/testcurl.1 b/tests/testcurl.1
new file mode 100644
index 000000000..c9b4cbfb8
--- /dev/null
+++ b/tests/testcurl.1
@@ -0,0 +1,119 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2005, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" *
+.\" * This software is licensed as described in the file COPYING, which
+.\" * you should have received as part of this distribution. The terms
+.\" * are also available at http://curl.haxx.se/docs/copyright.html.
+.\" *
+.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+.\" * copies of the Software, and permit persons to whom the Software is
+.\" * furnished to do so, under the terms of the COPYING file.
+.\" *
+.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+.\" * KIND, either express or implied.
+.\" *
+.\" * $Id$
+.\" **************************************************************************
+.\"
+.TH testcurl.pl 1 "15 Mar 2005" "Curl 7.13.2" "testcurl"
+.SH NAME
+testcurl.pl \- (automatically) test curl
+.SH SYNOPSIS
+.B testcurl.pl [options] [dir] > output
+.SH DESCRIPTION
+\fItestcurl.pl\fP is the master script to use for automatic testing of curl
+off CVS or daily snapshots. It is written for the purpose of being run from a
+crontab job or similar at a regular interval. The output is suitable to be
+mailed to curl-autocompile@haxx.se to be dealt with automatically (make sure
+the subject includes the word "autobuild" as the mail gets silently discarded
+otherwise).  The most current build status (with a resonable backlog) will be
+published on the curl site, at http://curl.haxx.se/auto/
+
+\fIoptions\fP may be omitted. See \fI--setup\fP for what happens then.
+
+\fIdir\fP is a curl source dir, possibly a daily snapshot one. Using this will
+make testcurl.pl skip the 'buildconf' stage and thus it removes the dependency
+on automake, autoconf, libtool, GNU m4 and possibly a few other things.
+
+testcurl.pl will run 'buildconf' (or similar), run configure, build curl and
+libcurl in a separate build directory and then run 'make test' to test the
+fresh build.
+.SH OPTIONS
+.IP "--configure=[options]"
+Configure options passed to configure.
+.IP "--crosscompile"
+This is a crosscompile. Makes \fItestcurl.pl\fP skip a few things.
+.IP "--desc=[desc]"
+Description of your test system. Displayed on the build summary page on the
+weba site.
+.IP "--email=[email]"
+Set email address to report as. Displayed in the build logs on the site.
+.IP "--mktarball=[command]"
+Generic command to run after completed test.
+.IP "--name=[name]"
+Set name to report as. Displayed in the build summary on the site.
+.IP "--nocvsup"
+Don't update from CVS even though it is a CVS tree. Useful to still be able to
+test even though your network is down, or similar.
+.IP "--setup=[file name]"
+File name to read setup from (deprecated). The old style of providing info.
+If info is missing when testcurl.pl is started, it will prompt you and then
+store the info in a 'setup' file, which it will look for on each invoke. Use
+\fI--name\fP, \fI--emacs\fP, \fI--configure\fP and \fI--desc\fP instead.
+.IP "--target=[your os]"
+Specify your target environment. Recognized strings include 'vc', 'mingw32',
+\&'borland' and 'netware'.
+.SH "INITIAL SETUP"
+First you make a checkout from CVS (or you write a script that downloads daily
+snapshots automatically, find inspiration at
+http://curl.haxx.se/auto/autocurl.txt):
+
+.nf
+  $ mkdir daily-curl
+  $ cd daily-curl
+  $ cvs -d :pserver:anonymous@cool.haxx.se:/cvsroot/curl login
+    [enter return when prompted for password ]
+  $ cvs -d :pserver:anonymous@cool.haxx.se:/cvsroot/curl checkout curl
+.fi
+
+With the curl sources checked out, or downloaded, you can start testing right
+away. If you want to use \fItestcurl.pl\fP without command line arguments and
+to have it store and remember the config in its 'setup' file, then start it
+manually now and fill in the answers to the questions it prompts you for:
+
+.nf
+  $ ./curl/tests/testcurl.pl
+.fi
+
+Now you are ready to go. If you let the script run, it will perform a full
+cycle and spit out lots of output. Mail us that output as described above.
+.SH "CRONTAB EXAMPLE"
+The crontab could include something like this:
+
+.nf
+\# autobuild curl:
+0 4 * * * cd daily-curl && ./testit.sh
+.fi
+
+Where testit.sh is a shell script that could look similar to this:
+
+.nf
+mail="mail -s autobuild curl-autocompile@haxx.se"
+name="--name=whoami"
+email="--email=iamme@nowhere"
+desc='"--desc=supermachine Turbo 2000"'
+testprog="perl ./curl/tests/testcurl.pl $name $email $desc"
+opts1="--configure=--enable-debug"
+opts2="--configure=--enable-ipv6"
+
+# run first test 
+$testprog $opts1 | $mail
+
+# run second test
+$testprog $opts2 | $mail
diff --git a/tests/testcurl.pl b/tests/testcurl.pl
index 9fd0bab5a..826299dd0 100755
--- a/tests/testcurl.pl
+++ b/tests/testcurl.pl
@@ -28,10 +28,11 @@
 
 # testcurl.pl is the master script to use for automatic testing of CVS-curl.
 # This is written for the purpose of being run from a crontab job or similar
-# at a regular interval. The output will be suitable to be mailed automaticly
-# to "curl-autocompile@haxx.se" to be dealt with automatically.  The most
-# current build status (with a resonable backlog) will be published on the
-# curl site, at http://curl.haxx.se/auto/
+# at a regular interval. The output is suitable to be mailed to
+# curl-autocompile@haxx.se to be dealt with automatically (make sure the
+# subject includes the word "autobuild" as the mail gets silently discarded
+# otherwise).  The most current build status (with a resonable backlog) will
+# be published on the curl site, at http://curl.haxx.se/auto/
 
 # USAGE:
 # testcurl.pl [options] [curl-daily-name] > output