             _________ __                 __
            /   _____//  |_____________ _/  |______     ____  __ __  ______
            \_____  \\   __\_  __ \__  \\   __\__  \   / ___\|  |  \/  ___/
            /        \|  |  |  | \// __ \|  |  / __ \_/ /_/  >  |  /\___ \
           /_______  /|__|  |__|  (____  /__| (____  /\___  /|____//____  >
                   \/                  \/          \//_____/            \/
        ______________________                           ______________________
                              T H E   W A R   B E G I N S
               Stratagus - A free fantasy real time strategy game engine

# Development for Stratagus

This file should give you some information to help with development of Stratagus.

## Bugs

You can find known bugs on the Launchpad pages for Stratagus.

## Building Stratagus

### Getting Stratagus from Launchpad Bazaar branches

#### How do I get the latest source code of Stratagus?

The instructions for accessing the source code are on the launchpad project page.

For example:

    bzr branch lp:stratagus

This is done only once. To update your working copy, go into the directory and type 'bzr pull'.

### Getting Stratagus without Bazaar

### Compiling Stratagus

You can find instructions for compiling Stratagus at install.html.
Since you already have a copy of the source, you may skip ahead to Installation Step 2.

## Source code documentation

Valery Shchedrin has introduced tagged source documentation for Stratagus.

You need DoxyGen to generate source code documentation.

Having DoxyGen installed, compile Stratagus with option ENABLE_DOC=ON
(e.g, inside build directory, run 'cmake -DENABLE_DOC=ON .. && make').

Source documents are initially generated inside the build directory, as done for binaries.

After installing stratagus (using 'make install') you can find all these html files in
share/doc/stratagus directory.

When installing Stratagus html these files are copied into PREFIX/share/stratagus/doc.
Doxygen documentation is copied into PREFIX/share/stratagus/doc/doxygen.

If you are viewing installed stratagus documentation, Doxygen documentation is here: doxygen/index.html

### Tags used in source code

We use the doc++ tags:

Multi line source code documentation:

/** ... */

Single line source code documentation:

/// ...

Start grouping:

//@{ or /*@{*/

End grouping:

//@} or /*@}*/

- @name
  Name of file or group.
- @param
  Describes function/macro parameter
- @return
  Describes function return
- @see
  Links to other section

Please read the doxygen/doc++ documentation.

## Empty C++ prototype file

    //       _________ __                 __
    //      /   _____//  |_____________ _/  |______     ____  __ __  ______
    //      \_____  \\   __\_  __ \__  \\   __\__  \   / ___\|  |  \/  ___/
    //      /        \|  |  |  | \// __ \|  |  / __ \_/ /_/  >  |  /\___ \
    //     /_______  /|__|  |__|  (____  /__| (____  /\___  /|____//____  >
    //             \/                  \/          \//_____/            \/
    //  ______________________                           ______________________
    //                        T H E   W A R   B E G I N S
    //  Stratagus - A free fantasy real time strategy game engine
    //
    /**@name {filename}.cpp	-	{One line description of this file} */
    //
    //  (c) Copyright {year} by {insert your name here}
    //
    //  This program is free software; you can redistribute it and/or modify
    //  it under the terms of the GNU General Public License as published by
    //  the Free Software Foundation; only version 2 of the License.
    //
    //  This program is distributed in the hope that it will be useful,
    //  but WITHOUT ANY WARRANTY; without even the implied warranty of
    //  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    //  GNU General Public License for more details.
    //
    //  You should have received a copy of the GNU General Public License
    //  along with this program; if not, write to the Free Software
    //  Foundation, Inc., 51 Franklin St, Fifth Floor,
    //  Boston, MA  02110-1301  USA
    //

    //@{

    #include <stdio.h>

    #include "stratagus.h"
    // More game includes.

    // Global and local variables of this module.

    // Local and global functions of this module.

    //@}

## Coding style

You can use your own coding style in your own modules. If you fix in other modules, please imitate the coding style of the original coder.

We suggest the Linux kernel coding style (also found online here).

- Write ANSI C++.
- All Tabs (Developers use 4 columns for a tab).
- No line should be longer than 78 characters.
- All comments should be on their own line.
- Use { } even for one statement blocks.

Coding Examples:

        // Example for statement with i incremented
        for (i = 0; i < sample->Length >> 1; ++i) {
            ...
        }

        // if statement with brackets and functions.
        if ((i = CLread(f, &chunk, sizeof(chunk))) != sizeof(chunk)) {
            ...
        }

        // function with variables defined.
        int function(int a, int b)
        {
            int x;
            int y;

            x = a;
            y = b;

            return 0;
        }

        // Example of a function
        static int CclLoadPud(lua_State* l)
        {
            const char* name;

            if (SaveGameLoading) {
                return 0;
            }

            if (lua_gettop(l) != 1) {
                LuaError(l, "incorrect argument");
            }
            name = LuaToString(l, 1);
            LoadPud(name, &TheMap);

            // FIXME: LoadPud should return an error
            return 0;
        }

NOTE: If you make big changes please always extend the copyright with your name, and always update the copyright year if required.

## Sending a patch

Use Stratagus launchpad bug tracker

(C) Copyright 1998-2012 by The Stratagus Project under the GNU General Public License.
All trademarks and copyrights on this page are owned by their respective owners.