[doc] update README and INSTALL

also add tests/README with some testing notes

Author: gstrauss

INSTALL

@@ -3,25 +3,22 @@
 Installation
 ============
 
-:author: Jan Kneschke
-:Date: $Date: $
-:Revision: $Revision: $
 
-Installation
-------------
+Quick Installation
+------------------
 
-Get the source from
+Get lighttpd source from
 
 https://www.lighttpd.net/download/
 
 unpack it by ::
 
-  $ gzip -cd lighttpd-1.x.x.tar.gz | tar xf -
+  $ tar xvJf lighttpd-1.4.xx.tar.xz
 
 compile and install it with ::
 
-  $ cd lighttpd-1.x.x
-  $ ./configure
+  $ cd lighttpd-1.4.xx
+  $ ./configure -C
   $ make
   $ su -
   # make install
@@ -31,6 +28,140 @@ take look at the configfile in ./doc/lighttpd.conf,
 make your own copy of that file and modify it for your needs.
 
 
+Online documentation
+--------------------
+https://redmine.lighttpd.net/projects/lighttpd/wiki/Devel
+https://redmine.lighttpd.net/projects/lighttpd/wiki/DevelSubversion
+https://redmine.lighttpd.net/projects/lighttpd/wiki/InstallFromSource
+
+
+Custom Installation
+-------------------
+
+required packages ::
+
+  autoconf
+  automake
+  libtool
+  m4
+  pcre
+  pcre-devel
+  pkg-config
+
+optional packages for optional features ::
+
+  bzip2-devel         # bzip2      ./configure --with-bzip2
+  bzip2-libs
+  cyrus-sasl          # SASL       ./configure --with-sasl
+  cyrus-sasl-devel
+  gamin               # FAM        ./configure --with-fam
+  gamin-devel
+  gdbm                # GDBM       ./configure --with-gdbm
+  gdbm-devel
+  GeoIP-devel         # GeoIP      ./configure --with-geoip
+  GeoIP
+  gnutls              # GnuTLS     ./configure --with-gnutls
+  gnutls-devel
+  krb5-devel          # Kerberos5  ./configure --with-krb5
+  krb5-libs
+  libattr             # xattr      ./configure --with-attr
+  libattr-devel
+  libbrotli           # brotli     ./configure --with-brotli
+  brotli-devel
+  libdbi              # DBI        ./configure --with-dbi
+  libdbi-devel
+  libdbi-dbd-mysql
+  libdbi-dbd-pgsql
+  libdbi-dbd-sqlite
+  libmaxminddb        # MaxMindDB  ./configure --with-maxminddb
+  libmaxminddb-devel
+  libmemcached-devel  # Memcached  ./configure --with-memcache
+  libmemcached-libs
+  libpq               # Postgresql ./configure --with-pgsql
+  libpq-devel
+  libunwind           # libunwind  ./configure --with-libunwind
+  libuuid             # libuuid    ./configure --with-webdav-locks
+  libuuid-devel
+  libxml2             # libxml2    ./configure --with-webdav-props
+  libxml2-devel
+  libxml2-static
+  lua                 # Lua        ./configure --with-lua
+  lua-devel
+  mariadb-devel       # MariaDB    ./configure --with-mysql
+  mariadb-libs
+  mbedtls             # mbedTLS    ./configure --with-mbedtls
+  mbedtls-devel
+  nettle              # Nettle     ./configure --with-nettle
+  nettle-devel
+  nss                 # NSS        ./configure --with-nss
+  nss-devel
+  openldap            # OpenLDAP   ./configure --with-ldap
+  openldap-devel
+  openssl-devel       # OpenSSL    ./configure --with-openssl
+  openssl-libs
+  pam                 # PAM        ./configure --with-pam
+  pam-devel
+  pcre                # PCRE       ./configure --with-pcre      # (default)
+  pcre-devel
+  sqlite              # SQLite     ./configure --with-webdav-props
+  sqlite-devel
+  valgrind            # valgrind   ./configure --with-valgrind
+  valgrind-devel
+  zlib                # zlib       ./configure --with-zlib
+  zlib-devel
+
+more options: ./configure --help
+
+re-run ./configure after installing packages
+
+compile and install it with ::
+
+  $ cd lighttpd-1.4.xx
+  $ ./autogen.sh        # detect/use newer versions of autotools (if present)
+  $ ./configure -C      # add --with-xxxxx custom flags
+  $ make
+  # sudo make install
+
+
+Running Tests
+-------------
+
+required packages to run test harness ::
+
+  (e.g. on Fedora 22, sudo dnf install ...)
+  (e.g. on Arch Linux, sudo pacman ... (with lowercased package names))
+
+  perl-CGI
+  perl-Digest
+  perl-Digest-MD5
+  perl-Encode-Locale
+  perl-HTML-Entities-Interpolate
+  perl-HTML-Parser
+  perl-HTML-Tagset
+  perl-HTTP-Date
+  perl-HTTP-Message
+  perl-IO-HTML
+  perl-LWP-MediaTypes
+  perl-Tie-Function
+  perl-TimeDate
+  php
+  php-cgi
+
+optional packages to run test harness ::
+
+  fcgi-devel
+
+  $ cd tests/ && make fcgi-auth fcgi-responder
+
+run test harness
+
+  $ make check
+
+run test harness with additional FastCGI tests (requires fcgi-devel package)
+
+  $ cd tests/ && make check-am
+
+
 static build using SCons
 ------------------------
 

README

@@ -37,21 +37,22 @@ Network
 Protocols
 `````````
 
-- HTTP/1.0 (http://www.ietf.org/rfc/rfc1945.txt)
-- HTTP/1.1 (http://www.ietf.org/rfc/rfc2616.txt)
-- HTTPS (provided by openssl)
-- CGI/1.1 (http://CGI-Spec.Golux.Com/)
+- HTTP/2   (https://tools.ietf.org/rfc/rfc7540.txt)
+- HTTP/1.1 (https://tools.ietf.org/rfc/rfc2616.txt)
+- HTTP/1.0 (https://tools.ietf.org/rfc/rfc1945.txt)
+- HTTPS (via one of openssl, BoringSSL, LibreSSL, mbedTLS, wolfSSL, GnuTLS, NSS)
+- CGI/1.1 (https://tools.ietf.org/html/rfc3875.txt)
 - FastCGI (http://www.fastcgi.com/devkit/doc/fcgi-spec.html)
 
 Advanced Features
 `````````````````
 
-- load-balanced FastCGI
+- load-balanced FastCGI, SCGI, reverse-proxy, socket proxy, websocket tunnel
   (one webserver distributes requests to multiple PHP-servers via FastCGI)
+- streaming FastCGI, SCGI, reverse-proxy, socket proxy, websocket tunnel
 - custom error pages (for Response-Code 400-599)
 - virtual hosts
 - directory listings
-- streaming CGI and FastCGI
 - URL-Rewriting
 - HTTP-Redirection
 - output-compression with transparent caching

tests/README

@@ -0,0 +1,82 @@
+Running tests
+-------------
+
+  $ make check
+
+If run from tests/ dir, tests will fail to run tests if lighttpd not built.
+If run from top level, 'make' will build lighttpd exectuable if not yet built,
+and then will run tests.
+
+
+Running individual tests programs
+---------------------------------
+
+prep
+  $ cd tests/
+  $ ./prepare.sh
+
+then, for any particular *.t such as request.t,
+  $ ./request.t
+or
+  $ VERBOSE=1 RUNTESTS=request ./run-tests.pl
+
+More information is output by tests with additional environment settings:
+  $ TRACE_HTTP=1     ./request.t
+
+See LightyTest.pm before trying TRACEME
+  $ less LightyTest.pm
+
+  $ TRACEME=strace   ./request.t   # output to file 'strace'
+  $ TRACEME=truss    ./request.t   # output to file 'strace'
+  $ TRACEME=gdb      ./request.t   # not for interactive debugging (see below)
+  $ TRACEME=valgrind ./request.t
+
+To reduce noise from valgrind --show-leak-kinds=all (or =reachable), avoid FAM.
+Use server.stat-cache-engine = "simple" (not server.stat-cache-engine = "fam")
+in lighttpd.conf.  (FAM creates /usr/libexec/gam_server as child process.)
+
+
+Running lighttpd server with a config from tests/*.conf
+-------------------------------------------------------
+
+Each *.t loads the lighttpd server with one or more config files.
+See each *.t for which config file is used, e.g. tests/lighttpd.conf
+
+To run a specific config
+  repo=$PWD      # from root of src repository
+  cd tests/
+  ./prepare.sh
+  PERL=/usr/bin/perl PHP=/usr/bin/php-cgi SRCDIR=$repo/tests \
+    $repo/src/lighttpd -D -f lighttpd.conf -m $repo/src/.libs
+
+The PERL, PHP, and SRCDIR environment variables are set by LightyTest.pm
+when 'make check' is run.  PERL and PHP can be set to paths to perl and php,
+e.g. export PERL=/usr/bin/perl PHP=/usr/bin/php-cgi
+
+To run a specific config under gdb
+  repo=$PWD      # from root of src repository
+  cd tests/
+  ./prepare.sh
+  PERL=/usr/bin/perl PHP=/usr/bin/php-cgi SRCDIR=$repo/tests repo=$repo \
+    gdb $repo/src/lighttpd
+
+  (gdb) set args -D -f lighttpd.conf -m $repo/src/.libs
+  (gdb) start
+  (gdb) ...
+
+
+Hints and tips
+--------------
+Q: What do I do if tests fail with:
+     bind: Address already in use at LightyTest.pm line 429.
+A: It is likely that something else on the machine is already using the port
+   that tests are trying to use to run a backend.  Try exiting out of your web
+   browser and then run the tests again.  (root can use 'netstat' or 'ss' to
+   find out which process is using the port.)
+
+
+Additional documentation
+------------------------
+https://redmine.lighttpd.net/projects/lighttpd/wiki/RunningUnitTests
+https://redmine.lighttpd.net/projects/lighttpd/wiki/HowToReportABug
+https://redmine.lighttpd.net/projects/lighttpd/wiki/DebugVariables