We hope you have already checked the installation prerequisites and know where to find the suitable C++ compiler.

1. Unpack the downloaded file:

       tar xfj polymake-VERSION.tar.bz2

   It will create a directory tree polymake-VERSION . Change into it:

       cd polymake-VERSION

2. Now the most straightforward way to build everything is to try your luck and type in:

       make
       make install

   In the most fortunate case the installation script will ask you exactly one question: where to install `polymake`. You can agree with the default proposal /usr/local/polymake (but note that on many Linux systems only the superuser may install new files there), or type in a path of your choice. Expressions like ~, ~user, or $env_variable are interpreted exactly as a bash or csh would do.
   If everything has successfully finished, proceed with the step 4 below. Note for impatient: the compile stage can be very long: as of now, the C++ programs with deeply nested templates (and such is polymake) are compiled very slowly and with huge memory consumption.
3. If you want to perform some fine-tuning, you can run the configuration step explicitly:

       make configure
       make
       make install

   In this case you have to answer a couple more questions. First of all, you can choose between a single-architecture and a multi-architecture installation. The latter choice makes sense in a heterogeneous network consisting of computers of various architectures. It stipulates a shared location for architecture-independent files (perl modules, rules, etc.) and separate directories for binary files.
   You may also choose an alternative location for the HTML documentation, where your local WWW server prefers to see its documents.
   Further you can specify the location of the C++ compiler, its optimization level (the default -O3 is rather optimistic), and whatever additional compiler and linker flags you might consider useful. For example, specifying an exact type of your CPU, such as -mcpu=ultrasparc or -march=athlon, can significantly accelerate the rational arithmetic which takes the main part of the computation time in `polymake`.
   The supported C++ compilers are listed here. Since different compilers have different command line syntax, the configuration script tries to choose the right one based on the compiler program name. Currently it assumes GNU if the compiler program path ends with g++ or c++ (with optional version suffix), Intel C++ by icc or ecc, and Comeau by como. You are free to modify the configuration script if this does not match your installation.
   If you are going to develop your own polymake clients, you will need a bit more to be installed: the library implementing the client-server communication, the sources of, and the documentation to the Template Library. It is accomplished with an additional command make install-devel .
   If you have chosen the multi-architecture installation, you must now log in on a computer of the next architecture. Then you run make to compile the binaries and make install-bin to put them to the right place. make install would indeed do it, too, but it would unnecessarily overwrite the shared files already installed in the first architecture step. For the same reason, the client development environment should be installed with make install-devel-bin .
4. Now you should customize your startup files so that the `polymake` script and the client programs can be found by your command shell. In a single architecture case the following appendix on the PATH variable would suffice:

       :InstallTop/bin

   In the multi-architecture case you might need to tinker up your startup files a bit in order that the correct architecture-dependent directory gets included in the PATH:

       :InstallArch/bin

   when you log in on different hosts.
5. Run `polymake --help` and watch for the warnings about lacking external packages. Download and install those you are interested in. First of all, some visualization software, preferably JavaView.
   By the way, if you install JavaView prior to `polymake`, then the configuration script gets a chance to find it and to prepare the Java components to work properly from the very beginning.
   If you install an external package later on, don't forget to run `polymake --reconfigure` to enable the corresponding interface.
6. Try to run some examples from the Application Tutorials. If you get output similar to the cited one, congratulations! you have managed to install `polymake`. Enjoy it!
7. Visit our news page from time to time. So you can see what has appeared newly or what bugs has been fixed - `polymake` evolves slowly but steadily.

## Potential sources of trouble

- wrong compiler and/or options
  Despite of numerous warnings scattered over the installation instruction you might have got a wrong C++ compiler, which is not ANSI C++ conforming enough to cope with `polymake` sources. Please consult the list of supported versions.
  Some RedHat and SuSE Linux releases are shipped with a non-standard `gcc` version, modified specially for the distribution. These custom `gcc`'s are easy to discover, as they report something like:

      > gcc --version
      gcc (GCC) 3.3 20030226 (prerelease) (SuSE Linux)

  Some of them are OK, other stem from non-official snapshots and are severely broken. If you encounter troubles, say, `gcc` crashes with internal compiler error or tries to occupy a Gigabyte of RAM, you are better advised to give up with it and install `gcc 3.4.x` from official sources (or let your sysadmin do it for you).
  If you are really short of availabe RAM, you can consider to lower the optimization level. However, be prepared for noticeably worse performance on large jobs. You can also selectively change the optimization level for individual clients in the files `apps/APP_NAME/src/Makefile.src` . The standard `gcc` in MacOS X 10 needs this especially often.
  To change the compiler and linker options, rerun `make configure` or just manually edit the file `build/conf.make` . If you decide to change the compiler on the half way, be sure to remove all produced binaries by `make clean` . With `make distclean` you can restore the initial state of the source tree, as if just unpacked from the tarball.
- `ar` crash
  This is an often occuring Solaris-specific problem. The `ar` utility shipped with several Solaris releases is broken, and does not seem to be better with the time. It can't cope with long global symbol names (so called mangled names) produced by the C++ compiler. To fix this, use the `ar` implementation from the GNU binutils collection. Either specify it explicitly: `make AR=path_to_GNU_ar` , or reorder your `PATH` so that the broken `/usr/ccs/bin/ar` get shadowed by the GNU clone.
- GMP library not found
  Beginning with version 1.3, polymake uses the GMP library. If its most recent version is already installed at your site and it can be found with default compiler settings, it will be used. Otherwise you should specify its location by means of `-I` and `-L` compiler flags in the configuration step or let the configuration script compile GMP from the sources packed together with the polymake.
  One frequent cause of failure by the detection of the GMP is a non-standard location of its shared library, libgmp.so.version . Make sure it resides in a directory included in the standard search path of the dynamic linker. This can be achieved by various means, such as setting the `LD_LIBRARY_PATH` environment variable (`DYLD_LIBRARY_PATH` in MacOS X), using Solaris `crle`, or Linux `ldconfig` utility. Since the dynamic linking process is platform-dependent to a very large extent, we aren't able to give you detailed advices about it here. Please ask your local system administrator for assistance.
  Another source of trouble can be architecture mismatch between GMP installed at your site and polymake binaries. For example, on a UltraSPARC machine running under Solaris 7 or later in 64-bit mode, GMP auto-configuration chooses the 64-bit mode too. `gcc`, it its turn, may choose to produce 32-bit binaries per default. Then they can't link with GMP library. Similar problem can arise on other architectures allowing dual running modes, such as Linux on an AMD64 platform, SGI IRIX, or IBM AIX. At any rate, you have to specify an ABI=32|64 GMP configuration option and/or compile polymake for the 64-bit target architecture using `-m64` gcc option (both for compiler and linker.)
- `polymake` does not run after perl upgrade
  For the sake of efficiency, `polymake` contains several small perl extension modules, so called XS-modules. They are written in C, as they have to access perl internal data structures directly. This makes them dependent on the perl implementation to the very high extent. Therefore they must be recompiled after each upgrade of the perl interpreter. Some nice day we will introduce a script performing this automatically, in the meanwhile you will have to do it by hand.
  But this is not that difficult. There is a special make target install-perlx. Even if you have deleted the unpacked sources and compiled binaries after the initial `polymake` installation, you have to repeat the configuration step only:

      make configure
      make install-perlx

  Indeed, you have to provide exactly the same answers about the installation target locations as you did during the initial installation.