trader/INSTALL

**************************************************************************
*                                                                        *
*              Star Traders: A Game of Interstellar Trading              *
*                 Copyright (C) 1990-2019, John Zaitseff                 *
*                                                                        *
**************************************************************************

Star Traders is written in  the C99 programming language and uses Autoconf
and Automake  to handle compilation  and installation.  Assuming  you have
the needed tools, all you should  need to do is run the following commands
from the source directory:

    ./configure
    make
    make install

The first two commands  may be run as an ordinary user;  the last may need
to be done as the system administrator (root).


Prerequisites
=============

Star Traders requires the  following components for successful compilation
and installation:

1.  A working C compiler  conforming to  ISO/IEC 9899:1999  (also known as
    C99).  Any recent version  of the GNU Compiler Collection (GCC) or the
    Clang LLVM Compiler is more than adequate.

2.  An operating system ideally conforming to  ISO/IEC 9945-1:2008 (POSIX)
    or to the Open Group Single UNIX Specification version 4 or later.  In
    short, any modern Unix or Unix-like system like Linux almost certainly
    qualifies.

    In actual fact, Star Traders uses the GNU Portability Library, so many
    older systems may also work without modification.

3.  A working X/Open Curses-compatible  library, such as Ncurses.  Ncurses
    is preferred  over system-native libraries, if  present.  Locales with
    multibyte character sequences (such as UTF-8) require a wide-character
    version of Curses, such as NcursesW, to work correctly.

4.  The GNU Gettext library, version 0.19.8 or later, to allow the game to
    use languages other than English;  this is also called Native Language
    Support.  If you do not have  this library (and do not wish to install
    it), you may pass "--disable-nls" to the configure script.

5.  The GNU libiconv library  for supporting multiple character encodings,
    if required by the GNU Gettext library.  This is not needed on systems
    with the  GNU C Library (glibc)  version 2.2 or later,  or on Mac OS X
    (now called macOS) 10.3 or newer.

6.  Development libraries and header files  for all of the above.  On many
    systems, these files are part of XXX-dev or XXX-devel packages.

7.  The GNU Perfect Hash Function Generator,  gperf.  This utility program
    may be required for parts of the GNU Portability Library.


Installation
============

The installation of Star Traders can be broken down into three main steps:
configuration, compilation and the installation proper.

The first step is configuring  the package for your compiler and operating
system environment.  As  Star Traders uses Autoconf and  Automake, all you
need to do in most cases is run "./configure" from the top-level directory
of the Star Traders source  tree.  The configure script understands all of
the usual Autoconf options; these  are explained in detail in the Autoconf
manual:

    https://www.gnu.org/software/autoconf/manual/autoconf.html#Running-configure-Scripts

This version of the configure script  understands the following additional
command line options:

    --disable-nls
                Don't use Native Language Support.  Star Traders will only
                show untranslated US English text and only accept US ASCII
                keyboard input.

    --with-libintl-prefix=DIR
                Find the GNU Gettext library  installed in the DIR/lib and
                DIR/include  directories.  This option  is needed  if your
                library is not installed in /usr/lib and /usr/include (or,
                more precisely, if the C compiler  cannot find the library
                ".so" or ".a" archive file using the standard "-l" command
                line parameter or the relevant header files using standard
                "#include" directives).

    --with-libiconv-prefix=DIR
                Find the GNU libiconv library installed in the DIR/lib and
                DIR/include directories.  This option is needed if the GNU
                Gettext library requires libiconv on your system, and that
                library is not installed in /usr/lib and /usr/include.

    --with-ncurses
                Force the use of Ncurses over the system's Curses library.
                In other words, do not search for  a native Curses library
                at all.

    --with-ncursesw
                Force the use of the NcursesW library  with wide-character
                support.  If NcursesW cannot be found, abort the configure
                script.

    --without-ncursesw
                Don't use  the NcursesW library.  This will prevent non-8-
                bit character encodings  like UTF-8 from working correctly
                and is thus not recommended.

    --without-ncurses
                Don't use the Ncurses library: use either NcursesW (unless
                "--without-ncursesw"  is also specified)  or  the system's
                normal Curses library.  This option is not recommended.

    --disable-assert
                Turn off all debugging assert() statements.

By default, configure uses  "/usr/local" as the top-level (prefix) install
directory.  You  can change this  by specifying "--prefix=DIR" to  use DIR
instead.  For example, you can use  a directory in your own home directory
by specifying something like:

    ./configure --prefix=$HOME/opt/trader

You may also specify certain configuration and/or compilation variables on
the command line to override  choices made by configure.  For example, you
can specify the compiler flags to use by passing the CFLAGS variable:

    ./configure CFLAGS="-g -O2 -Wall"

The  configure script  has many other options.   You may obtain  a list of
these by running:

    ./configure --help

You can also run configure  in a separate build-only directory tree.  This
feature requires GNU Make and allows you to keep the source code tree from
being modified by  the compilation process.  To use  this option, create a
separate build directory, then run  configure.  For example, if you placed
the Star Traders source code tree in $HOME/src/trader-7.13,  you could run
something like:

    mkdir $HOME/build/trader-build-7.13
    cd $HOME/build/trader-build-7.13
    $HOME/src/trader-7.13/configure

Once again, the Autoconf manual describes these options (and many others):

    https://www.gnu.org/software/autoconf/manual/autoconf.html#Running-configure-Scripts

Once the package  has been configured, you can type  "make" to compile it,
then "make install" to install  it.  You can specify the following command
lines, amongst others:

    make all
    make install
    make clean
    make distclean
    make uninstall

The command  "make all" does the  same thing as running  "make" by itself:
compile the package source code into an executable.

Running "make  install" copies the  executable program and  all associated
data  and  documentation  files  to  those  directories  specified  during
configuration.  If  any of these directories  require system administrator
access  privileges for writing,  you will  need to  run "make  install" as
system administrator (root).

If you like, you can specify the DESTDIR variable to copy all installation
files to a temporary location  before installing them later.  For example,
if the prefix directory is "/usr/local", typing:

    make install DESTDIR=/tmp/trader-install

will copy the final program "trader" to /tmp/trader-install/usr/local/bin,
the manual page to /tmp/trader-install/usr/local/share/man/man6 and so on.

The "make clean"  command will remove most build-generated  files, such as
object  files generated by  the compiler,  from the  source code  or build
directory.  Running "make distclean" will do the same, but will remove the
Makefiles  generated by configure  as well.   In other  words, if  you run
"make distclean", you will need to  rerun "configure" if you would like to
recompile Star Traders at a later date.

Finally, "make uninstall" will  remove the executable program "trader" and
associated  data and  documentation  files from  their final  installation
location.  This assumes, of course, that you have NOT run "make distclean"
to  remove the  Makefiles that  know the  path to  which those  files were
installed!


Tested Systems
==============

The following operating systems and compilers have been successfully test-
ed with this version of Star Traders:

+-------------------------+--------+-------+-------------------------+---+
| Linux distribution      | Arch   | Glibc | Compiler                | N |
+-------------------------+--------+-------+-------------------------+---+
| Debian GNU/Linux Sid    | x86_64 | 2.27  | GNU C Compiler 8.2.0    |   |
| Debian GNU/Linux Sid    | i686   | 2.27  | GNU C Compiler 8.2.0    |   |
| Debian GNU/Linux 9.5    | x86_64 | 2.24  | GNU C Compiler 6.3.0    |   |
| Ubuntu 18.04            | x86_64 | 2.27  | GNU C Compiler 7.3.0    |   |
| Ubuntu 18.04            | x86_64 | 2.27  | Clang (LLVM) 6.0.0      |   |
| Ubuntu 18.04            | x86_64 | 2.27  | Portland PGI C/C++ 18.5 |   |
| Fedora 28               | x86_64 | 2.27  | GNU C Compiler 8.1.1    |   |
| CentOS 7.5              | x86_64 | 2.17  | GNU C Compiler 4.8.5    |   |
| CentOS 6.10             | x86_64 | 2.12  | GNU C Compiler 4.4.7    |   |
| CentOS 6.10             | x86_64 | 2.12  | Portland PGI C/C++ 18.3 |   |
| CentOS 6.9              | x86_64 | 2.12  | Intel C/C++ 18.0.3      |   |
| OpenSUSE Leap 15.0      | x86_64 | 2.26  | GNU C Compiler 7.3.1    |   |
+-------------------------+--------+-------+-------------------------+---+

+-------------------------+--------+---------------------------------+---+
| Operating system        | Arch   | Compiler                        | N |
+-------------------------+--------+---------------------------------+---+
| FreeBSD 11.2            | x86_64 | Clang (LLVM) 6.0.0              | 1 |
| NetBSD 8.0              | x86_64 | GNU C Compiler 5.5.0            | 2 |
| macOS 10.13             | x86_64 | Apple Clang (LLVM) 9.1.0        | 3 |
| Solaris 11.3 (x86_64)   | i386   | GNU C Compiler 4.8.2            |   |
| Solaris 11.3 (x86_64)   | x86_64 | GNU C Compiler 4.8.2            | 4 |
| Solaris 11.3 (x86_64)   | i386   | Oracle Developer Studio 12.6    | 5 |
| Solaris 11.3 (x86_64)   | x86_64 | Oracle Developer Studio 12.6    | 6 |
| Cygwin 2.10.0 (Win7SP1) | i686   | GNU C Compiler 7.3.0            |   |
+-------------------------+--------+---------------------------------+---+

Notes:

1.  FreeBSD with the  gettext, gettext-runtime, gettext-tools and libiconv
    binary packages installed with "pkg", using:

        ./configure --with-libiconv-prefix=/usr/local \
                    --with-libintl-prefix=/usr/local

2.  NetBSD with the gettext, libiconv and ncursesw packages installed with
    "pkg_add", using:

        ./configure --with-libiconv-prefix=/usr/pkg  \
                    --with-libintl-prefix=/usr/pkg   \
                    --with-ncursesw --with-ncurses   \
                    CURSES_CFLAGS=-I/usr/pkg/include \
                    LDFLAGS=-L/usr/pkg/lib

3.  macOS with the gettext package installed with Homebrew, using:

        ./configure --with-libintl-prefix=/usr/local/opt/gettext

4.  Using "./configure CC='gcc -m64'" for 64-bit user-space.
5.  Using "./configure CC='/opt/developerstudio12.6/bin/cc'".
6.  Using "./configure CC='/opt/developerstudio12.6/bin/cc -m64'".

The following systems are known not to work at the current time; this list
is almost certainly not exhaustive:

+-------------------------+--------+---------------------------------+---+
| Operating system        | Arch   | Compiler                        | N |
+-------------------------+--------+---------------------------------+---+
| OpenBSD 6.3             | x86_64 | GNU C Compiler 4.2.1            | 1 |
| OpenBSD 6.3             | x86_64 | Clang (LLVM) 5.0.1              | 1 |
+-------------------------+--------+---------------------------------+---+

Notes:

1.  The OpenBSD C library does not include <monetary.h> nor its associated
    functions, particularly strfmon().


Git Repository
==============

You can always  download the latest version of Star Traders  directly from
the Git repository on the ZAP Group server:

    git clone git://git.zap.org.au/data/git/trader.git

Released versions of Star Traders include all scripts and files needed for
installation.  If you are cloning the source code from the Git repository,
however,  you will need to update these files yourself.  You will need the
following additional tools installed on your system to do so:

1.  Autoconf v2.69 or later (https://www.gnu.org/software/autoconf/)
2.  Automake v1.15 or later (https://www.gnu.org/software/automake/)
3.  pkg-config v0.9.0 or later (https://pkg-config.freedesktop.org/)
4.  GNU Portability Library (https://www.gnu.org/software/gnulib/)

The  GNU Portability Library  may  be installed  by retrieving  the latest
Gnulib source code from the Git repository:

    git clone git://git.savannah.gnu.org/gnulib.git

Once you have these tools, change to the Star Traders source code tree and
type:

    PATH=${PATH}:/path/to/gnulib-tool ./build-aux/bootstrap

where "/path/to/gnulib-tool"  is, of course, the  directory containing the
Gnulib "gnulib-tool" script.   You should be ready to  run "./configure &&
make && make install" now.


For Translators
===============

Thank you for even considering to translate  Star Traders into your native
language!  You may use  either  a released version of  Star Traders, or an
unreleased one,  as discussed  in the  Git Repository  section  above.  In
either case, you may find the following workflow useful.

First, run "./build-aux/bootstrap" if needed (only for unreleased versions
of Star Traders).

Next, configure and install Star Traders into your home directory:

    ./configure --prefix=$HOME/opt/trader
    make
    make install

If you are adding a new translation, add its GNU Gettext  language code to
the file po/LINGUAS, then create the template file for that language ("zz"
is used here):

    (cd po; msginit --locale=zz --width=132)

Now, modify the PO file  for your language using  your favourite editor or
translation tool.   Please note that  the generated PO file  has extensive
documentation in its translator comments.   If anything is unclear, please
feel free  to ask the author and maintainer; contact details are available
in the README file.

To test your PO file, compile and run Star Traders (replace "zz" with your
language code, of course):

    make && make -C po zz.gmo && make install
    LANGUAGE=zz $HOME/opt/trader/bin/trader

The "make -C po zz.gmo" forces  the rebuilding of the GMO output file; the
"LANGUAGE=zz" parameter sets the language of the messages to use.

This process of  editing and testing the PO file  can be done iteratively,
of course:  make a change, recompile, run the program  to see the changes,
repeat as needed.

Once you have finished your translation,  please submit the PO file to the
Translation Project.  The relevant web page for Star Traders is:

    https://translationproject.org/domain/trader.html

More information for translators is available at:

    https://translationproject.org/html/translators.html

To clean up your install directory, simply run:

    rm -fr $HOME/opt/trader

By the way,  as mentioned in the translator comments,  formatting the help
text is probably the most complicated and tedious part of translating Star
Traders.  The  author and maintainer  of this game  is more than  happy to
help you with this task: if you are able to provide a translation, even if
it is not  formatted correctly, the maintainer  will perform the necessary
adjustments for word-wrapping and justification.