Installation Instructions for PCC2
===================================

  Content of this file:
  - 1. Installing from Source
    . 1.1 Unix
    . 1.2 Windows
  - 2. Installing from Binary Distributions
    . 2.1 Windows
    . 2.2 Linux
  - 3. Configuring
    . 3.1 Manual installation

  For links to the required packages, see README.


1. Installing from Source
--------------------------

1.1 Unix
.........

  PCC2 can be installed on unixoid systems. So far, the following
  systems have been tried with various PCC2 versions:

  - SuSE 5.1 (libc5)
  - Debian 3.0 (libc6)
  - Debian 8 (libc6)
  - OpenSuSE 10.1 and 11.4 (libc6)
  - Ubuntu 10.4 (libc6)
  - Ubuntu 14.4 (libc6)
  - Mac OS X 10.6 for x64
  - Solaris 2.7 on Sparc


1.1.1 Prerequisites

  You need the following source code packages:

  - PCC2 source code (pcc2-YYYYMMDD.tar.gz). Unpack into a directory
    of your choice.

  - Additional source code (cpluslib-YYYYMMDD.tar.gz). Unpack into the
    pcc-v2 directory just created, or one level above.

  - (optional) the Makefile Generator (proj-YYYYMMDD.tar.gz) if you
    intend to modify PCC2.


  You need the following external libraries. You can build them from
  source or use binary packages. You need the development packages,
  too, of course (header files).

  - SDL 1.2.x. SDL is a cross-platform graphics library. You'll need
    both the library binary (.so) and the development headers, so your
    best bet is to compile from source. To check whether your SDL
    installation is okay, type `sdl-config --version'.

    You can probably get away with a lower SDL version (if it is 1.1.5
    or newer), but currently the PCC2 configure script rejects these.
    SDL2 is not supported.

    SDL requires a supported thread package (pthreads) and, if you
    want to use SDL under X, thread-safe X libraries. On Linux, it can
    also use SVGAlib and the console framebuffer, these probably need
    special configuration options for SDL (i.e. libvga is not used by
    default). Without a thread package, it might compile but it did not
    work on my system.

    I'm using assorted SDL versions between 1.2.1 and 1.2.15 for
    development.

  - SDL_image 1.2.x or higher, which in turn requires libjpeg, libpng
    and zlib. Currently, SDL_image isn't strictly mandatory; you can
    get away without it by converting all PNG/JPG images to BMP.

  - the PHost development kit, PDK, is required to build the FLAK
    server (host add-on).

  - zlib. This library is ubiquitous, therefore compilation without
    it is not supported.


  You need the following programs:

  - a decent C++ compiler. Probably, anything above g++ 3 is ok.
    C++1x is not required.

  - Perl

  - Make

  - optional: xsltproc to generate the HTML documentation

  - optional: msgmerge/xgettext (from the gettext package) to update
    the translations


1.1.2 Building

  Step 1: Invoke ./configure. This is GNU configure and accepts all
  the options you know and love. If you want to build with FLAK, you
  probably have to tell it the path to the PDK, as in
      ./configure --with-pdk=/path/to/pdk

  Other useful options:

  --prefix=/dir/name
    Target directory for installation.

  --disable-inplace
    Disable in-place execution. By default, PCC2 has its build
    directory compiled in to find its resources when run without
    installation; with this option, the build directory does not
    appear in the binaries, but you have to install PCC2 before trying
    it. Use this if you're building packages.

  CC=gcc-4.3
  CXX=g++-4.3
  CFLAGS=-W
  CXXFLAGS=-W
    Force a particular compiler version and/or options. Note that when
    you specify only a C compiler, our configure tries to infer the
    corresponding C++ compiler automatically.


  Step 2: Invoke make. This will build a few binaries.


  Step 3: Try it. Unless you used '--disable-inplace', you can run
  the binaries straight off the build directory:

  - "./un-trn /path/to/player9.trn" to decompile a turn file

  - "./playvcr /path/to/vcr9.dat" to play a VCR. Note that, if you
    use libvga, "playvcr" must be run as root for graphics to work.

  - "./pcc-v2 /path/to 9" to start the client on a game.


1.1.3 Installing

  Install everything using "make install". You probably want to be
  root to do that to be able to install files with proper permissions.
  If you are not root, do "make install INSTALL_FLAGS=--no-chown".

  This will create a file "INSTALL.log" containing all installed
  files. You can use that to uninstall later.


1.1.4 Making a Debian Package

  Since beta 13, PCC2 comes with files needed to build a Debian
  package. To do this, run "make deb" as root after building the
  package.

  If you want to make a package, you'll probably want to configure
  PCC2 as "./configure --prefix=/opt/pcc2 --disable-inplace".


1.2 Windows
............

  PCC2 can be built on Windows using MinGW (Minimalist GNU for Windows).
  This is my primary target for Windows.

  PCC2 can also be built with Visual Studio 2005 (VC8) from the command
  line (I do not maintain .vcproj files for the GUI).

  It used to be possible to build PCC2 using Borland C++ 5.5. All releases
  up to beta 7 were built this way. However, this compiler has not seen
  updates for ages, and other free compilers now abound, so Borland support
  has been removed in 2.0 (and was probably not working for a long time
  before that).


1.2.1 Prerequisites

  You need the following source code packages:

  - PCC2 source code (pcc2-YYYYMMDD.tar.gz). Unpack into a directory
    of your choice. Most Windows archivers can unpack .tar.gz files.

  - Additional source code (cpluslib-YYYYMMDD.tar.gz). Unpack into the
    pcc-v2 directory just created.

  - (optional) the Makefile Generator (proj-YYYYMMDD.tar.gz) if you
    intend to modify PCC2.


  You need the following external libraries. You can build them from
  source or use binary packages. You need the development packages,
  too, of course (header files).

  - SDL 1.2.x.

  - SDL_image 1.2.x.

  - the PHost development kit, PDK, is required to build the FLAK server
    (host add-on). It must have been built using the same compiler that
    you'll be using to build PCC2.

  - zlib.


  You need the following programs:

  - the compiler.

  - Perl (from Cygwin or ActiveState), should be on your %path%.

  - (optional) the NullSoft Install System (NSIS) to build the
    installer.


1.2.2 Building using MinGW

  Step 1: Configure. Open a command prompt and 'cd' into the PCC2
  directory. Type "config mingw" to prepare the source code. Edit
  "acdefs.mak" and "acdefs.h" according to your needs. You probably use
  different paths than I do.

  Likewise, edit "installer/prepare2.pl" and fill in the correct paths
  in the "Path name configuration" section.


  Step 2: Compile it by invoking "make -f Makefile.min" ("make" is
  MinGW's or Cygwin's version).


1.2.3 Building using VC8

  Step 1: Configure. Open a "Microsoft Visual Studio 2005 Command
  Prompt" (this is a custom version of the regular command prompt, set
  up with correct environment variables, provided by Visual Studio).
  'cd' into the PCC2 directory. Type "config vc8" to prepare the source
  code. Edit "acdefs.mak" and "acdefs.h" according to your needs. You
  probably use different paths than I do.

  Likewise, edit "installer/prepare2.pl" and fill in the correct paths
  in the "Path name configuration" section.


  Step 2: Compile it by invoking "nmake -f Makefile.vc8" ("nmake" is
  Microsoft's MAKE variant).

  Note that VC8 by default does not implement integral class member
  constants correctly. Although it can be configured to do so using
  "/Za", that switch also makes it refuse to compile <windows.h>. You
  will therefore see a number of "duplicate symbol" warnings during
  the linking process. I expect those to be harmless.


1.2.4 Installing

  Unless you have the SDL DLLs on your %path%, you cannot run PCC2 without
  installing it first, which will arrange the .exe and .dll files in the
  same directory so they find each other.

  Change into the "installer" directory. Invoke
    perl prepare2.pl install target_dir_name
  to create a runnable installation in "target_dir_name". The .exe
  files in that directory can directly be run. Zipping that directory
  gives my "pcc2-win32-YYYYMMDD.zip" distribution.

  Invoke "make PCC2-Installer.exe" in that directory to build the
  installer.


2. Installing from Binary Distributions
----------------------------------------

2.1 Windows
............

  I usually also provide the Win32 version in the form of an
  installable binary package. It comes in two forms:

  - a self-installing .exe file. Start it, pick the components and
    target directory, and be happy. This will also install Winplan
    integration for the VCR and will automatically use Winplan's
    pictures. It will also install start menu entries and an
    uninstallation program.

  - a ZIP file. You can unzip it into a directory of your choice. Use
    this if you don't trust my installer: PCC2 needs no registry
    entries to work. However, it will of course not automatically
    configure pictures. See chapter 3, Configuring, for how to do
    that. To uninstall, just delete the directory created by
    unzipping.


2.2 Linux
..........

  When possible, I'm preparing a i386 Debian package for PCC2,
  containing the whole program suite. This package can be installed
  directly on Debian-based distributions, including the Ubuntus.

  You need to have the packages libsdl1.2debian, libsdl-image1.2, and
  libstdc++5 installed (graphics libraries, and g++ 3.3 runtime
  libraries). Use your distribution's package management system to
  install them, or a command like this:
    sudo apt-get install libsdl1.2debian libsdl-image1.2 libstdc++5

  You can install the package by typing a command like this
    sudo dpkg -i pcc2_1.99.13_i386.deb
  into a Terminal/command prompt window. Substitute the correct file
  name, of course.

  I do not currently have a good way to automatically configure pictures.
  Create a text file ~/.pcc2/cc-res.cfg, and point it to some pictures; see
  section 3 below.

  Please remember that Linux is most of the times case-sensitive. PCC2
  will only find game files spelled in lower-case (e.g. "player9.rst",
  "hullspec.dat"). Some people use cute names such as "Player9.RST" or
  "HullSpec.Dat"; you have to demote them before PCC2 can use them.
  Alternatively, store your game files on a FAT partition (or on a USB
  thumb drive, which defaults to FAT, too). Those are not case
  sensitive, and also allow easy access from Windows.


3. Configuring
---------------

  PCC2 does not include many pictures. Unless you have used the
  installer to tell PCC2 about your copy of Winplan, you must manually
  tell PCC2 where to find pictures.

  The easiest way is to install an artwork plugin from
  <http://phost.de/~stefan/plugins/>.

  Download the *.c2z file and then use the plugin manager (F5 from PCC2's
  or PlayVCR's game selection screen) or the c2plugin tool to install the
  plugin:
     c2plugin add path/to/file.c2z
  This will install the artwork for your user account. If you have used
  the Windows installer, just opening the *.c2z file (double-click) will
  install it.


3.1 Manual installation
........................

  Manual installation is still supported.

  To install pictures for your user account, create a text file
  "cc-res.cfg" in your user profile directory; to install for all users on
  your computer, create it in PCC2's resource directory.

  Unix:
  - user profile: ~/.pcc2/ (e.g. /home/user/.pcc2/)
  - resources: /usr/local/share/planets/resource/

  Windows:
  - user profile: %APPDATA%\PCC2 (e.g. C:\Users\myself\AppData\PCC2)
  - resources: C:\Programs\PCC2\resource

  cc-res.cfg must be a plain-text file, so use Notepad or Edit or any other
  text editor to create it, not a word-processor. This file contains
  "resource specifications", one per line.

  - if you have a PCC 1.x picture pack ("cc.res" or "cc256.res"), you
    place a line like this in cc-res.cfg:
        d:\path\pcc1\cc.res
        /home/myself/pcc1/cc.res
    (just the complete file name)

  - if you have a Winplan picture pack (a "bmp" folder containing
    files named "vplXXX.bmp"), you place a line like this in
    cc-res.cfg:
        wp:d:\path\to\bmp
        wp:/media/c/plan1/bmp
    (directory name preceded by "wp:")

  - if you have a Winplan VCR picture pack ("wpvcr.dll" file), you
    place a line like this in cc-res.cfg:
        wpvcr:d:\path\to\wpvcr.dll
        wpvcr:/media/c/plan1/vpvcr.dll



-end-
