~ubuntu-branches/ubuntu/edgy/gnome-games/edgy-proposed

===============================================================================
                             Gnome-Games
===============================================================================

Contents
--------

- Overview
- The Games
- Website
- License
- Mailing List
- Maintainers
- Bug Reports
- Requirements
- Building Gnome-Games
- Security Issues
- The Future

=========================================================================

!!! IMPORTANT !!!

Migrating from 2.8 to 2.10.

There is almost nothing you need to know, almost everything should
Just Work. The major source of problems will be in Same GNOME, which
has been completely rewritten. The theme format is different and
your old custom themes will not be recognised. Standard themes that
have been migrated may also look different. Anything else is a bug,
report it to http://bugzilla.gnome.org/. 

People with 64-bit machines need to ensure they have guile version
1.6.5 or later. This is to avoid a 64-bit bug in guile. The configure
scripts should detect this, but the test is a little dodgy and the
response is simply to not build aisleriot. If aisleriot is not being
built, check your version of guile.

========================================================================

Overview
--------

Gnome-games is a collection of simple, but addictive, games from the
GNOME desktop project. They represent many of the popular games and
include card games, puzzle games and arcade games. They are meant to
be the sort of game that can be played in five minutes or so. They are
also meant to be fun enough that you will play them again and
again. Of course we can't be held responsible for the time and
productivity lost while playing them.

The Games
---------

Here is a list of the games in this compilation along with a brief
description. The names in brackets are the program names you use from the
command line.

AisleRiot       A compilation of seventy different solitaire card games.
                (sol)

Ataxx           A disk-flipping game where players try and control the
                most disks. This is similar to Iagno, another game in
                this suite. (gataxx)

Blackjack       The casino card game without any need to actually pay
                your gambling debts. (blackjack)

Four-in-a-row   The classic game where each player tries to make a line
                of four disks before their opponent. There is a very
                popular version of this in the real world called
                Connect Four. (gnect)

Gnometris       That Russian game of fitting falling geometric
                shapes. Need I say more ? (gnometris)

Iagno           Gnome version of the popular Othello (R) disk flipping
                game. The goal is to control all the disks on the
                board by trapping your opponents disks between two of
                yours. (iagno)

Klotski         A series of sliding block puzzles. (gnotski)

Five or More    You move balls around the grid and try and form lines
                of the same colour to make them disappear. Unfortunately 
                more balls keep dropping in ... (glines)

Mahjongg        A tile-based solitaire game with an oriental
                flavor. Remove tiles in matching pairs from a pile to
                try and dismantle it. (mahjongg)

Mines           The popular logic puzzle minesweeper. Clear mines from
                a board using hints from squares you have already
                uncovered. (gnomine)

Nibbles         The "worm" game. You pilot a worm around a maze trying
                to collect diamonds. With each diamond your worm grows
                and navigation becomes ever more difficult. (gnibbles)

Robots          The classic BSD robots game where you have to avoid a
                hoard of robots who are trying to kill you. Mac users
                might remember a similar "daleks" game. (gnobots2)

Same GNOME      You start with a grid of stones of different
                colors. You can only remove stones where two or more
                of the same colour touch each other. The goal is to
                remove as many as possible. You score more points by
                removing them in bigger groups.

Stones          Mine through dirt and collect gems: but don't get
                squashed by the boulders. Also has a Sokoban mode.
                (gnome-stones)

Tali            Sort of poker with dice and less money. An ancient
                Roman game, this variant is similar to Yahtzee (R).
                (gtali)

Website
-------

Further information and screenshots can be found at:

http://www.gnome.org/projects/gnome-games/

developers should see

http://www.gnome.org/projects/gnome-games/contributing.html

License
-------

This is Free Software and there are no restrictions on your use and
enjoyment of it. In most countries copyright law would prevent you
from sharing these programs, either as is or in a modified
form. However we provide a license to allow you to modify and
redistribute this code. This is the GNU General Public License and it
can be found in the file COPYING. This allows you to do almost
anything you would like with this software, including selling
it. There are only two catches, firstly you can't restrict anyone else
from copying the code, you have to give them the same freedoms you
received (including access to the source code). Secondly, because the
code may have been modified and we have no idea what state it will be
in when it reaches you, we cannot provide a warranty. All the details
can be found in the file COPYING which should have accompanied this
software. If it didn't you can find a copy at

http://www.gnu.org/copyleft/gpl.html 

or write to the Free Software Foundation, Inc., 59 Temple Place, Suite
330, Boston, MA 02111-1307 USA

Mailing List
------------

Gnome-games has a mailing list at <games-list@gnome.org>. You can
subscribe to the list at:

 http://mail.gnome.org/mailman/listinfo/games-list

and browse the archives at:

 http://mail.gnome.org/archives/games-list/

The mailing list is for announcements and discussion about games
written for the GNOME environment. It is moderated and low volume.

Maintainers
-----------

The current maintainers are:

 Callum McKenzie <callum@physics.otago.ac.nz>.
 Jon McCann <mccann@jhu.edu> (blackjack).

While you can email them with suggestions and bug reports it is better
to use either the bug tracking system (see below) or the mailing
list. Even for suggestions the bug tracking system is better because
it ensures that there is an archive of the discussion and it is harder
for the maintainer to loose suggestions. For more general discussion,
policy issues and issues that many people will be interested in, the
mailing list is the best place.

Reporting Bugs
--------------

If you find any bugs in gnome-games, or even just have a suggestion
for an improvement to the games then please submit a bug report. There
are two ways to do this, either by using the web-based interface to
the GNOME bug tracking system at

http://bugs.gnome.org/simple-bug-guide.cgi

or use the bug reporting tool, which you can find under the Development
sub-menu of the GNOME menu. The bug reporting tool can also be launched
from the command line via the bug-buddy command.

If a game crashes then the bug reporting tool will be automatically
launched.

There is one problem with the standard bug reporting tools and
gnome-games. Because gnome-games uses setgid bit to give the programs
extra privileges the ordinary bug reporting tools don't do a complete
job because a stack trace cannot be made. Stack traces are very useful
in determining what went wrong. To get a proper stack trace with
gnome-games binaries then you should try and recreate your crash while
running as the root use, or, with the setgid bit temporarily removed
from the file. Both these require root privileges which you may not
have.

Contributing
------------

See the file HACKING and the webpages mentioned within for details
about contributing to gnome-games.

Requirements
------------

To compile these packages you need at least the baseline GNOME 2.10
development packages. You really, really, need GTK+ 2.6. You also need
gettext 0.12 or newer. If you are building from CVS then you also need
the CVS version of intltool.

In addition it is useful to have a working C++ compiler (e.g. g++,
part of the gcc suite) and the guile implementation of the Scheme
programming language version 1.6 or later
(http://www.gnu.org/software/guile/guile.html). If either of these is
missing then the games that rely on them will simply not be built.

The games that require additional packages are:
 guile scheme:  	AisleRiot
 C++:         		Blackjack, Gnometris            


Building Gnome-Games
--------------------

Gnome-games uses the GNU automake system and installation may be as
easy as:

$ ./configure
$ make install

Generic, but detailed, instructions can be found in the file INSTALL.

There are several gnome-games specific options you can pass to
configure. These security related options are:

--disable-setgid                Do not set the setgid bit on the
                                installed binaries.
--with-scores-group=group       If you are using setgid binaries, set
                                the group for the programs. The
                                default is games.
--with-scores-user=user         If you are using setgid binaries, set
                                the user for the programs. The default
                                is games.

For a discussion of the details behind these options and why you might
want to change them see the "Security" section. In general you will
not need to change any of them.

To select which games to compile use --enable-omitgames and
--enable-games. Each option takes a comma separated list of directory
names (not the screen-names of the games). "all" is also a valid
name. For example:

./configure  --enable-omitgames=gnometris,gnome-stones

would compile all the games except gnometris and gnome-stones.

./configure --enable-omitgames=all --enable-games=gnomine

would only build the gnomine game. The choice of the awkward phrase
"enable-omitgames" is due to a limitation in the autoconf tools which
doesn't allow us to supply an argument to --disable-games.

./configure --enable-games=none,gnomine

has the same effect. The names in the lists are applied in order.

If you want Zeroconf support you have two options. On most Unix and
Linux systems Howl is the library of choice and is automatically
detected. You may also use Apple's Bonjour library, but you have to
enable it explicitly.

The configure options for zeroconf support are:

 --disable-howl                   Disable Howl support 
 --enable-bonjour                 Enable Bonjour support
 --with-bonjour-includes=PREFIX   Specify where to find the Bonjour 
                                  header files
 --with-bonjour-libs=PREFIX       Specify where to find the Bonjour 
                                  libraries

Setting the library and include file directories explicitly should not
normally be necessary. Note that if you select Bonjour support on a
system with Howl installed and do not explicitly disable Howl then
Howl support will be disabled and a warning printed.

Use './configure --help' for a complete list of currently supported
options and environment variables.

If you are compiling gnome-games from CVS you should look at:

http://www.gnome.org/projects/gnome-games/contributing.html

Security Issues
---------------

It might seem a little strange that a collection of games needs to
talk about security issues, but it all stems from an attempt to avoid
cheating. To stop people writing arbitrary scores into the score file
without actually having played the game, the games are given special
privileges and the score files are set to be only writable by programs
with these privileges. In this case the privilege is being part of the
games group.

The potential problem comes when there are bugs in the games that
allow someone to get the program to do something else (like classic
buffer overruns). This gives the (supposedly) evil user a way to do
things with the same privileges as the game, but not necessarily the
things that were intended. This is generally considered to be bad.

There are two mitigating factors here:
a) The programs open the score files and drop privileges very shortly
   after they have been started. This severely reduces the scope for an
   exploitable to occur.
b) On most systems having the privileges of the games group should
   allow you to do no more than change high score files.

The problem is that in a) the probability is small, but not zero, and
in b) "most systems" is not "all systems". If you are using a
typical Linux distribution then you should have no problems. If you
don't have a typical system and the "games" group is somewhat more
special than a way of maintaining the high scores then you may need to
change things.

If you need to change things, here are your options:

1) Do not use setgid binaries. This means that high score tracking
won't work (although you can make the files world-writable and
therefore open to use/abuse by everyone). Use the --disable-setgid at
configuration time to do this.

2) Change the group used. Creating a new, unique, group for
gnome-games (e.g. gnomegames) is the best solution. You can change the
group (and user) used via the --with-scores-group and
--with-scores-user options to configure at compile time.

The Future
----------

The 2.10 release of gnome-games has been an incremental improvement
over 2.8. 2.12 will be a similar incremental improvement. Once again I
hope to concentrate on only a few games to bring them kicking and
screaming into the 21st century. The following goals are still
important in the long run:
 - Making it easier for individual players to introduce their own themes.
 - Scalability of the game graphics so that the game can be resized
   to suit the player, for examples of this see gnomine and gnotravex.
 - Networking. Iagno and Nibbles already does it, there are several
   other games with two-player options that are just begging to be 
   networked.
 - A new high scores back-end. This resolves some synchronization
   issues between libgnome and gnome-games.