webperimental: killstack decides stack protects.
[freeciv.git] / INSTALL
1 ===================
2 Installing Freeciv:
3 ===================
5 This file describes how to compile and install Freeciv. Last time we
6 made sure this file is up to date was 16-Jul-06.
7 Last minor update was 02-May-17.
9 There may be a localized version of this file in the ./doc directory,
10 named INSTALL.<locale> (e.g., INSTALL.de).
12 This document contains sections and subsections as follows:
13      0. Prerequisites:
14      1. Prerequisites for the clients:
15           1a. Prerequisites for the Gtk3 client:
16           1b. Prerequisites for the Gtk3.22 client:
17           1c. Prerequisites for the SDL2 client:
18           1d. Prerequisites for the Qt client:
19      2. Generating Makefiles
20           2a. Generating the Makefile for svn versions:
21           2b. Generating the Makefile for release versions:
22      3. Compiling Freeciv:
23      4. Installation:
24      5. Native Language Support:
25      6. Readline Support:
26      7. Reinier's Solaris Installation Notes:
27      8. Reinier's libXpm Solaris Installation Notes:
28      9. Mac OS X and Darwin notes:
29     10. Debian GNU/Linux notes:
30     11. Windows notes:
33 0. Prerequisites:
34 =================
36 Freeciv has a number of prerequisites.  Note, that apart from the first
37 prerequisite, the Freeciv configuration process is smart enough to work
38 out whether your system is suitable.  If in doubt, just try it.
40  - Unix (or similar)
42    The Unix operating system, a work-alike such as Linux or FreeBSD,
43    or some OS that provides a very Unix-like personality or mode, like
44    EMX under OS/2 or the Cygnus Cygwin toolkit under Windows.
45    (See http://sourceware.cygnus.com/cygwin/).  Support for
46    BSD-style TCP/IP sockets is essential, as is a Bourne-shell
47    compatible shell, such as GNU "bash".  (Most Unixes fit the bill...)
49  - An ANSI C compiler.
51    Freeciv is written in very portable (almost) ANSI C.  Both 32- and 64-
52    bit machines are supported.  You cannot use a "K&R C" compiler, or
53    a C++ compiler.
55    Development of Freeciv is primarily done with "gcc", the GNU
56    project's excellent C compiler.  Releases can be compiled with gcc
57    or most other compilers (such as the unbundled Solaris C compiler).
58    Note that there have been reports that gcc with -O3 miscompiled
59    freeciv.
61  - A "make" program.
63    Freeciv developers generally use "gmake", the GNU make program.
65    Officially released versions of Freeciv are designed to have
66    makefiles which work with most make programs.
68    You can check if you have GNU make installed on your system by
69    typing:
71     % make -v                   [and if this doesn't work, try "gmake -v"]
73    The output should include "GNU Make" somewhere.
75  - libtool version 2.2 or better
77  - libcurl version 7.15.4 or better
79    Libcurl takes care of http communication with the metaserver, and
80    file transfers of modpack installers
82    http://curl.haxx.se/
84  - libicu
86    Libicu helps handling UTF-8 texts
88    http://site.icu-project.org/
90  - libsqlite3
92    http://www.sqlite.org/
94 The svn version has additional requirements. A release version
95 contains the generated files.
97  - The programs from GNU gettext version 0.15 or better
99    Especial the xgettext program is required to create the *.gmo
100    files which aren't included in the svn tree.
102  - GNU autoconf version 2.65 or better
104    Autoconf is required to create configure from configure.ac.
106  - GNU automake version 1.11.3 or better
108    Automake is required to create the various Makefile.in from
109    Makefile.am.
111 1. Prerequisites for the clients:
112 =================================
114 The Freeciv client comes in the following forms:
115 * Gtk+ 2.0 widget library ("Gtk+ 2.0").
116 * Gtk+ 3.0 widget library ("Gtk+ 3.0").
117 * Gtk+ 3.0 widget library, version 3.22 ("Gtk+ 3.22")
118 * SDL2
119 * Qt
121 These forms have different prerequisites, explained separately below.
123 Your system will need to satisfy at least one of these sets of prerequisites.
125 Note that most Linux systems have separate library packages for "runtime" 
126 library support and for development support (for compiling programs 
127 which use those libraries).  To compile Freeciv on such systems you 
128 will need to have the appropriate "development" packages installed.
131 1a. Prerequisites for the Gtk+ 3.0 client:
132 ==========================================
134  - "pkg-config".
136    "pkg-config" is a system for managing library compile/link flags that
137    works with automake and autoconf. You may obtain it at:
139       http://pkgconfig.freedesktop.org/releases/pkg-config-0.28.tar.gz
141  - The "Glib" utility library.
143    The "Glib" utility library provides non-graphical functions used by the
144    "Gdk" and "Gtk+" libraries, like hash tables, single linked lists, etc.
146    Freeciv requires a version of "Glib" greater or equal to 2.36
148    If the Freeciv configure process tells you that you don't have the
149    Glib library installed, then it may be obtained from here:
151      http://ftp.gnome.org/pub/gnome/sources/glib/2.36/glib-2.36.1.tar.xz
153  - The "Atk" accessibility library.
155    The "Atk" library provides a set of interfaces for accessibility.
156    It allows people with disabilities to utilize all the functionality
157    provided by Gtk+ apps. You may obtain it at:
159      http://ftp.gnome.org/pub/gnome/sources/atk/2.8/atk-2.8.0.tar.xz
161  - The "Pango" text layout and rendering library.
163    "Pango" is library for layout and rendering of text, with an emphasis
164    on internationalization. You may obtain it at:
166      http://ftp.gnome.org/pub/gnome/sources/pango/1.34/pango-1.34.0.tar.xz
168  - The "Gdk-Pixbuf" image loading/saving library
170    "Gdk-Pixbuf" used to be part of "Gtk+" itself, but is now separate
171    project. It may be obtained from:
173      http://ftp.gnome.org/pub/gnome/sources/gdk-pixbuf/2.28/gdk-pixbuf-2.28.1.tar.xz
175  - The "Gtk+" widget library.
177    The "Gtk+" widget library was designed for the GIMP graphics program.
178    Since then it has gained popularity as an easy to program, free toolkit.
180    The "Gtk+" library comes with one companion libraries:
182      "Gdk":
183        Provides an abstraction layer over X-Windows/LinuxFB/Win32 to implement
184        basic drawing functions, windows, clipping, etc.
186    Freeciv requires a version of "Gtk+" greater or equal to 3.10.0.
188    If the Freeciv configure process tells you that you don't have the
189    Gtk+ library installed, then it may be obtained from here:
191      http://ftp.gnome.org/pub/gnome/sources/gtk+/3.12/gtk+-3.12.2.tar.xz
193    "Gtk+" depends on the "Glib", "Atk", "Gdk-Pixbuf", and "Pango" libraries.
195 If you are going to make these yourself, build and install them in the
196 following order: pkg-config, Glib, Atk, Pango, Gdk-Pixbuf, Gtk+.
198 1b. Prerequisites for the Gtk+ 3.22 client:
199 ==========================================
201  - "pkg-config".
203    "pkg-config" is a system for managing library compile/link flags that
204    works with automake and autoconf. You may obtain it at:
206       http://pkgconfig.freedesktop.org/releases/pkg-config-0.29.1.tar.gz
208  - The "Glib" utility library.
210    The "Glib" utility library provides non-graphical functions used by the
211    "Gdk" and "Gtk+" libraries, like hash tables, single linked lists, etc.
213    Freeciv requires a version of "Glib" greater or equal to 2.50
215    If the Freeciv configure process tells you that you don't have the
216    Glib library installed, then it may be obtained from here:
218      http://ftp.gnome.org/pub/gnome/sources/glib/2.50/glib-2.50.1.tar.xz
220  - The "Atk" accessibility library.
222    The "Atk" library provides a set of interfaces for accessibility.
223    It allows people with disabilities to utilize all the functionality
224    provided by Gtk+ apps. You may obtain it at:
226      http://ftp.gnome.org/pub/gnome/sources/atk/2.22/atk-2.22.0.tar.xz
228  - The "Pango" text layout and rendering library.
230    "Pango" is library for layout and rendering of text, with an emphasis
231    on internationalization. You may obtain it at:
233      http://ftp.gnome.org/pub/gnome/sources/pango/1.40/pango-1.40.3.tar.xz
235  - The "Gdk-Pixbuf" image loading/saving library
237    "Gdk-Pixbuf" used to be part of "Gtk+" itself, but is now separate
238    project. It may be obtained from:
240      http://ftp.gnome.org/pub/gnome/sources/gdk-pixbuf/2.36/gdk-pixbuf-2.36.0.tar.xz
242  - The "Gtk+" widget library.
244    The "Gtk+" widget library was designed for the GIMP graphics program.
245    Since then it has gained popularity as an easy to program, free toolkit.
247    "Gtk+ 3.22" is the default client. If you don't specify any client with
248    "--enable-client" to configure, you will get "Gtk+ 3.22" client.
250    The "Gtk+" library comes with one companion libraries:
252      "Gdk":
253        Provides an abstraction layer over X-Windows/LinuxFB/Win32 to implement
254        basic drawing functions, windows, clipping, etc.
256    Freeciv requires a version of "Gtk+" greater or equal to 3.22.0.
258    If the Freeciv configure process tells you that you don't have the
259    Gtk+ library installed, then it may be obtained from here:
261      http://ftp.gnome.org/pub/gnome/sources/gtk+/3.22/gtk+-3.22.12.tar.xz
263    "Gtk+" depends on the "Glib", "Atk", "Gdk-Pixbuf", and "Pango" libraries.
265 If you are going to make these yourself, build and install them in the
266 following order: pkg-config, Glib, Atk, Pango, Gdk-Pixbuf, Gtk+.
268 1c. Prerequisites for the SDL2 client:
269 =====================================
271  - The "SDL2" library.
273    "Simple DirectMedia Layer is a cross-platform multimedia library designed
274     to provide low level access to audio, keyboard, mouse, joystick, 3D hardware
275     via OpenGL, and 2D video framebuffer." (http://www.libsdl.org)
277    These features make it a good choice for portable games. You may obtain it
278    at:
280    http://www.libsdl.org/release/SDL2-2.0.3.tar.gz
282    To compile the client using the "SDL2" library add "--enable-client=sdl2"
283    to the Freeciv configure script.  See the section below for more 
284    information about the configure script.
286  - The "SDL2_image" library.
288    This library loads the PNG images (with the help of libpng) and converts
289    them to "SDL surfaces" that can be handled by the "SDL" library. You may
290    obtain it at:
292    http://www.libsdl.org/projects/SDL_image/release/SDL2_image-2.0.1.tar.gz
294  - The "SDL2_gfx" library.
296    http://www.ferzkopp.net/Software/SDL2_gfx/SDL2_gfx-1.0.3.tar.gz
298  - The "SDL2_ttf" library.
300    http://www.libsdl.org/projects/SDL_ttf/release/SDL2_ttf-2.0.14.tar.gz
302  - The "freetype" library.
304    This library helps to render text for the SDL2 client, using an externally
305    provided TrueType font. You may obtain it at:
307    http://download.savannah.gnu.org/releases/freetype/freetype-2.7.1.tar.bz2
309 1d. Prerequisites for the Qt client:
310 ====================================
312  - C++ compiler.
314    Qt-client is written in C++, so you need appropriate compiler.
315    In Freeciv development, g++ has been used.
317  - Qt5Core, Qt5Gui, and Qt5Widgets libraries and headers
320 2. Generating Makefiles
321 =======================
322 This section contains two parts, one for generating makefiles from svn
323 versions and one for generating makefiles from release versions.
325 2a. Generating the Makefile for svn versions:
326 =============================================
328 This step is only needed for svn versions.
330 To create the makefile just type
332  % ./autogen.sh
334 This will create the configure script and will run it. All parameters
335 of autogen.sh are passed to configure. Read the next section about the
336 parameters which can be passed to configure.
338 2b. Generating the Makefile for release versions:
339 =================================================
341 Before you compile Freeciv, you must generate a Makefile.  This makefile
342 is configured to suit the features available on your machine.
344 This configuration is done using the GNU "configure" script.
346 To use "configure", "cd" into the top directory containing the Freeciv
347 files, and type:
349  % ./configure
351 This script will then attempt to determine the relevant features (and
352 misfeatures!!) of your system.  It should print a page or two of
353 diagnostics about your machine, then stop gracefully.
355 If you'd like help on the various options supported by the configure
356 script, try the --help option, like this:
358  % ./configure --help
360 By default the configure script will choose the Gtk+ client if the 
361 required libraries are found. If you prefer to override this default,
362 you can give configure the "--enable-client=sdl2" option.
364 If you want to change the compiler options, set the CFLAGS environment
365 variable in your shell before running "configure".  For example:
367  % CFLAGS="-O -g -pipe" ./configure   [for people using Bourne shell or bash]
371  % setenv CFLAGS "-O -g -pipe"
372  % ./configure                        [for people using C shell or tcsh]
374 If you're tracking down a "core dump", we suggest that you use
375 a value of "-g" for CFLAGS.
377 When you install Freeciv (later), the game components will be copied into
378 subdirectories of /usr/local by default.  If you would like to use some
379 other installation prefix besides /usr/local, you should specify it now:
381  % ./configure --prefix=/opt/freeciv
383 If for some reason using "configure" gives you trouble, follow these steps:
385   - Read the prerequisites section carefully, to determine if your
386     system meets all the requirements.
388   - If the problem is with "gettext", please read the Native Language
389     Support section, below, for possible work-arounds.
391   - Let us know, so that we can fix it for the next release!!
393     Send mail to the freeciv-dev mailing list, telling us what you did,
394     and what the result is.  It would be helpful to include the output
395     of the configure script, and the contents of the "config.status",
396     "config.cache" and "config.log" files, which are generated by the
397     configure script.
399     You can find out about the freeciv-dev mailing list on our web
400     site, at http://www.freeciv.org/
403 3. Compiling Freeciv:
404 =====================
406 If all has gone well previous to this point, then compiling Freeciv
407 should be as easy as typing "make" (or preferably, "gmake").
409 If you have problems, read the file BUGS, and follow the advice 
410 carefully.  If the problem is with "gettext", please read the Native
411 Language Support section, below, for possible work-arounds.
413 After compilation, the important results are:
415   - The "client/freeciv-<GUI>" and "server/freeciv-server" binaries.
416   - The "data/" directory, which contains the graphics and scenarios.
417   - The "translations/" directory, which contains the localization files.
418   - The "fcgui" and "fcser" scripts.
420 It's perfectly feasible to play Freeciv in this directory, without
421 installing it.  If you do this, the "fcgui" and "fcser" scripts may be
422 useful, although they are not as necessary as they used to be.
424 See the README file for more information.
426 (However you cannot use Internationalization when playing Freeciv from
427 the source directory; you must install Freeciv for that.)
430 4. Installation:
431 ================
433 Installing Freeciv involves installing the components mentioned in the
434 Compiling Freeciv section.  These need to be copied to a directory such
435 as /usr/local (the default), /usr/games, /usr/games/freeciv,
436 /usr/local/freeciv, or some other suitable directory.
438 Typing "make install" should install everything correctly on your machine.
439 You may like to use the --prefix=DIR configure option (see the Generating
440 the Makefile section) to ensure the files get placed where you want.
442 When the Freeciv client and Freeciv server are run they both need to 
443 find some files from the "data" directory.  By default freeciv looks
444 in the following directories, in order, for any data files: the current 
445 directory; the "data" subdirectory of the current directory; the 
446 subdirectory ".freeciv" in the user's home directory; and the directory
447 where the files are placed by running "make install".  You can override
448 this search patch by setting the FREECIV_DATA_PATH environment variable, to
449 a single directory or a list of directories separated by colons.
451 For example:
453   % setenv FREECIV_DATA_PATH "/usr/games/freeciv/data:./data"
454   (for users of csh, tcsh, etc.)
456   % FREECIV_DATA_PATH="/usr/games/freeciv/data:./data"; export FREECIV_DATA_PATH
457   (for users of sh, bash, ksh, zsh, etc.)
459 Also, note that you generally must install Freeciv if you wish to use
460 its Native Language Support.  See the README file for more information.
463 5. Native Language Support:
464 ===========================
466 Freeciv uses the "gettext" system for Native Language Support.
468 If you experience problems with gettext in either configuring or compiling
469 Freeciv, there are a few work-arounds you can try:
471 1. If you don't need Native Language Support, disable it using the
472    "--disable-nls" ./configure option:
474       % ./configure --disable-nls
475       % make
477 2. You can try to install the latest version of GNU gettext.
478    It may be obtained from here:
480       ftp://ftp.gnu.org/pub/gnu/gettext/gettext-0.19.2.tar.xz
483 6. Readline Support:
484 ====================
486 Freeciv has optional support for the readline library.
488 Readline support is what makes the server command line behave sensibly,
489 making it possible to
490  - Use the backspace key.
491  - Use the cursor to move back and forth on the line you have written.
492  - Use TAB completion of commands and command arguments. Ie, when you
493    push tab the server will finish the word for you if there is only one
494    possible choice.
495  - Use the up and down cursor to scroll through the history of previously
496    entered commands.
497  - etc.
499 The configure script will check if you have the readline library correctly
500 installed. If so it will automatically set up the makefiles so that readline
501 is compiled into the server. If not then it will just silently configure
502 without readline support.
503 You can force configure to include readline or die trying by giving
504 configure the --with-readline option:
506  % ./configure --with-readline
508 Some linux distributions (and possibly other operating systems) have
509 readline version 4 incorrectly installed, so that readline is not
510 set up to declare it's dynamic dependencies. In that case configure
511 will try to guess which extra libs it should link against and add them.
512 The configure script will give a warning if it had to add extra libs
513 to make readline work. This should be harmless, and is just meant as
514 a reminder to the folks who distribute readline. :)
516 7. Reinier's Solaris Installation Notes:
517 ========================================
519 Solaris (2.5 and up) has its own version of X in /usr/openwin, its own
520 version of make in /usr/ccs/bin/make, and its own compiler (to be purchased
521 separately) which, if you have it, is available in /opt/SUNWspro/bin.
522 Solaris does not provide any of the stuff required for imlib, gdk and gtk,
523 either, which is required to build the GTK+ client.  However, with some
524 patience, everything can be compiled without problems.
526 Make sure your environment variables, especially $PATH and $LD_LIBRARY_PATH,
527 and the ./configure options do not point to an inconsistent set of software,
528 and compiling will be fine.
530 You can set up your $PATH and ./configure to use only GNU
531 tools.  Furthermore, Freeciv is known to compile with MIT X, and with
532 certain combinations of GNU and Sun tools.  The exact recipes depend on your
533 local installation.
536 8. Reinier's libXpm Solaris Installation Notes:
537 ===============================================
539 When I was root on my Solaris system, I *still* didn't want to install
540 third-party software as root.  It's bad practice.
542 Unfortunately, the libXpm installation procedure assumes installation
543 in /usr/openwin, which is owned by root.  But it's not all that hard to
544 get around that.
546 Caveats:
548  - Make sure /usr/ucb/install is in your $PATH before /usr/bin/install,
549    otherwise 'make install' will break with strange error messages.
551  - The destination you want to install to can be specified with $DESTDIR;
552    however, installation will actually take place in $DESTDIR/$OPENWINDIR,
553    so the additional $OPENWINDIR subdir must be stripped afterwards
554    (changing the value of $OPENWINHOME doesn't work).
556 The Procedure:
558  - Get the source from somewhere, untar it, cd into the source directory,
559    and issue:
561      % setenv MYXPMDEST /usr/local   # or wherever you want to install it
562      % xmkmf; make Makefiles includes depend; make
563      % setenv PATH /usr/local/bin:/usr/ucb:$PATH
564      % make DESTDIR=$MYXPMDEST install
565      % make DESTDIR=$MYXPMDEST install.man
566      % cd $MYXPMDEST; mv ./$OPENWINHOME/* .; rm -rf ./$OPENWINHOME
568    (If you use sh, bash, ksh, zsh, etc., the "setenv"s above should be:
569      % MYXPMDEST=/usr/local; export MYXPMDEST
570      % PATH=/usr/local/bin:/usr/ucb:$PATH
571    .)
573  - You can now configure Freeciv with
575      % ./configure --with-xpm-prefix=$MYXPMDEST
577    which will add the proper -I/-L/-R options to the compile and link
578    commands.
581 9. Mac OS X and Darwin notes:
582 =============================
584 Apple's version of GCC uses precompiled headers that does not support
585 vararg macros (a GCC extension).  This causes GCC to fail when
586 compiling Freeciv since the compiler is otherwise (mostly)
587 indistinguishable from vanilla GCC.  So instead of the usual
589   % ./configure <...>
591 you should use either
593  Bourne shell:
594    $ CC="gcc -no-cpp-precomp" ./configure <...>
598  C shell:
599    % env CC="gcc -no-cpp-precomp" ./configure <...>
601 depending on whether your shell is a Bourne or C shell variant.  (If
602 in doubt, just try both to see which one will work.)
604 Replace <...> with whatever additional arguments you want to give to
605 configure.
608 10. Debian GNU/Linux notes:
609 ===========================
611 To compile freeciv on a debian system you need the following packages:
613  Common requirements:
614    gcc
615    libc6-dev
616    libreadline4-dev
617    zlib1g-dev
618    xlib6g-dev
620 If you need to run aclocal (if you don't know what aclocal is then you
621 don't need it) you also need to install imlib-dev to get the
622 AM_PATH_GDK_IMLIB macro. It is a bug in debian that this macro isn't
623 in gdk-imlib-dev, and it will hopefully be fixed in future debian
624 releases.
626 11. Windows notes:
627 ==================
629 Windows version of Freeciv can be built either with MinGW or Cygwin.
630 Official Windows binaries are built with MinGW, and they are self-contained
631 packages. For using Cygwin version, you need Cygwin environment installed.
633 Build instructions for MinGW versions are documented on top of file
634 win32/installer/Makefile
636 Cygwin specific installation notes can be found in doc/INSTALL.Cygwin.
638 ** END **