README

WHAT IS THIS?
-------------

This is the source distribution of the NaviServer, a versatile
multiprotocol (HTTP(S) et al) server written in C/Tcl.  It can
be easily extended in either language to create interesting
websites and services.

Contents
--------
    1. Introduction
    2. Documentation
    3. Compiling and installing
    4. Mailing lists


1. Introduction
---------------

NaviServer is maintained, enhanced, and distributed freely by the
open source community.  The home for NaviServer downloads and bug/patch
database is located on the SourceForge site:

    https://sourceforge.net/projects/naviserver

Source code is available from the GitHub site:

    https://github.com/orgs/naviserver-project/naviserver

Another resource is the Tcl wiki:

    https://wiki.tcl-lang.org/page/NaviServer

NaviServer is a freely available open source package.  See the file
"license.terms" for complete information.


2. Documentation
----------------

Documentation is available in the "doc" subdirectory. At this
point it is incomplete and is considered to be a work in progress.
Once done, it will be distributed in Unix nroff format (suitable
for viewing with Unix "man" command) and HTML format (suitable
for viewing with any HTML-compatible browser).

The latest development version is available online:

    https://naviserver.sourceforge.io/n/toc.html


3. Compiling and installing
---------------------------

NaviServer is known to compile and run on FreeBSD, Linux, Solaris,
macOS 10.2+ and Windows. To compile and install:


3a. Download, configure, build and install Tcl 8.5 or better

    You may use the version of Tcl already installed on your machine
    if it was built with threads enabled. The configure step below
    will complain if this is not the case.

    You can download the latest Tcl release from https://www.tcl-lang.org/
    and follow the instructions in the included README. You may install
    Tcl within the directory you intend to install the server
    (e.g., /usr/local/ns) or in some other location.

    NaviServer 4.99.* requires Tcl 8.5 or Tcl 8.6. NaviServer 5 will
    be compatible with Tcl 9 (when it is released).

    The following commands should work on a Unix-like operating system:

    $ gunzip < tcl8.6.13-src.tar.gz | tar xvf -
    $ cd tcl8.6.13/unix
    $ ./configure --prefix=/usr/local/ns --enable-threads --enable-symbols
    $ make install


3b. If you don't have GNU make (Linux make is GNU make), install
    it, as the server's makefiles require it.  If you're not sure
    if you have GNU make, try "make -v" to check.  You can get
    GNU make at https://www.gnu.org/


3c. Download, configure, build, and install NaviServer.

    Official releases:

        https://sourceforge.net/projects/naviserver/files/

    Latest development source code (Git repository):

        https://github.com/naviserver-project/naviserver/

    Note that the main branches on the Git repository are:
        - main (the latest development code)
        - release/4.99 (bug fixes for NaviServer 4.99.*)

    The following should work for official releases:

        $ gunzip < naviserver-4.99.25.tar.gz | tar xvf -
        $ cd naviserver-4.99.25
        $ ./configure --prefix=/usr/local/ns --with-tcl=/usr/local/ns/lib --enable-symbols
        $ make
        $ su -c 'make install'

    The configure script takes the following options:

    --with-tcl=/usr/local/ns/lib

        Path to library installation directory of Tcl where
        configure can find the tclConfig.sh script.  Without
        this option, configure will search around for
        tclConfig.sh, perhaps finding it in ../tcl8.6.13/unix.

    --with-zlib=/usr

        You will need the zlib compression library headers available.
        e.g. "yum install zlib-devel" for Fedora Linux. If the headers
        are not located in the usual places where the compiler looks,
        you can tell configure where to find them with the --with-zlib
        option.

    --enable-symbols

        Compile with debug symbols enabled. Recommended.

    --prefix=/usr/local/ns

        Set the installation directory for the server.  All
        program, man page, and runtime files (e.g., log
        files) will be installed or updated within this
        directory.


    To compile with Purify tool, set the variable $PURIFY to
    your Purify executable along with any options you desire, e.g.,

        make PURIFY="purify -cache-dir=/home/joe/my-cache-dir" install

    Alternatively, NaviServer can be installed directly from GitHub
    via the git version control system installed.  Git is
    available for most Linux distributions: e.g. "yum install git".
    For e.g. Windows binaries, see https://git-scm.com/downloads

    If you checked out the source directly from GitHub, replace
    "./configure" in the example above with "./autogen.sh" to get the
    initial makefiles created.

    You will need recent versions of autoconf and automake installed.
    You will need 'dtplite' which is part of 'tcllib' installed if you
    want to build the documentation.

    Checkouts from the source code repository have to generate
    the documentation from the sources as well via "make build-doc",
    otherwise, the call "make install" will complain.

    See: 'make help' for more help in the build process.


3d. Create and edit a configuration file (nsd.tcl, by convention)

    A couple of samples are provided to get you started:

    $ cd /usr/local/ns
    $ cp sample-config.tcl nsd.tcl
    $ vi nsd.tcl

    sample-config.tcl contains every possible configuration option and
    its default value. Remove the ones you don't need.

    simple-config.tcl contains a basic set of the important configuration
    options you are likely to need. Add to it as necessary.


3e. Try running the server in a shell window:

    $ cd /usr/local/ns
    $ ./bin/nsd -f -t conf/nsd.tcl

    The '-f' option runs the server in the foreground with important
    log messages directed to your terminal.


3f. To download and install additional modules:

    For tar releases of NaviServer, a compatible version of the modules
    is as well provided via SourceForge. In order to obtain a module
    named "nsfoo", get it from the modules tar file and install it
    like sketched below:

        $ gunzip < naviserver-4.99.25-modules.tar.gz | tar xvf -
        $ cd modules/nsfoo
        $ make install NAVISERVER=/usr/local/ns

    Alternatively, modules can be obtained from the code repository at
    GitHub via git. To get a module "nsfoo" via git

        $ git clone https://github.com/naviserver-project/nsfoo.git
        $ cd nsfoo
        $ make install NAVISERVER=/usr/local/ns

    See: https://github.com/orgs/naviserver-project/repositories
    for a full list of modules.


3g. To compile for Windows with Msys + Mingw

    Download: https://sourceforge.net/projects/mingw/files/

    The Msys + Mingw download above is the minimal environment needed
    to build NaviServer under Windows. It includes a shell environment and
    gcc.

    To install, you just download the zip file and extract the
    files into a directory. The README.TXT file describes how to launch
    the msys shell.

    You then run the configure script in the NaviServer directory. The
    Msys based configure/build process works just like the UNIX one.

    Example of building naviserver.exe:

    Run dos prompt or cmd.exe, assuming msys_mingw8.zip is unpacked in the
    root of drive c:

        c:>cd msys
        c:\msys> msys.bat

        $ cd /c/naviserver-4.99.25
        $ ./configure --prefix=c:/naviserver --with-tcl=c:/naviserver/lib
        $ make install

    The example above assumes Tcl is also built using mingw with prefix c:/naviserver

3h. To compile for Windows with MSVC

    Update the 'tcl_64' and 'tcllib_64' variables in Makefile.win32 in
    the top-level NaviServer directory. See also these settings in
    "include/Makefile.win32": 'HAVE_OPENSSL_EVP_H', 'openssl_64'.

    Run appropriate Microsoft build setup script.  E.g. one of these:
        "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat"
        "%ProgramFiles%\Microsoft SDKs\Windows\v7.1\Bin\SetEnv.Cmd" /Debug /x64 /win7

        nmake -f Makefile.win32

3i. Cross-compiling for Windows 64-bit (using gcc/mingw)

    The configure magic does not detect some settings for MINGW,
    they need to be specified explicitly:

        ./configure --host=x86_64-w64-mingw32 --enable-64-bit \
              --prefix=<path> --with-zlib=<path> --with-openssl=<path> --with-tcl=<path>/lib

        CFLAGS="-DHAVE_INET_PTON -DHAVE_INET_NTON -DHAVE_GETADDRINFO -D_WIN32_WINNT=0x600" \
              LDFLAGS="-static-libgcc" \
              make LIBLIBS="-Wl,-Bstatic -lpthread -Wl,-Bdynamic"

    The installation script does not expect the ".exe" extension; workaround:

        cp nsthread/nsthreadtest.exe nsthread/nsthreadtest
        cp nsd/nsd.exe nsd/nsd
        cp nsproxy/nsproxy.exe nsproxy/nsproxy
        make install


4. Mailing lists
----------------

There are mailing lists for NaviServer to discuss anything from
configuration, development, and future direction. To join visit:

    https://sourceforge.net/projects/naviserver

Thank you for your interest in NaviServer.  We hope you find it
useful and look forward to hearing from you on our mailing list.

-EOF-