Techwizz/Gobligine
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
Gobligine/doc/development.html
jsalmon3 a26b5da183 Updated docs
2003-02-05 00:35:02 +00:00

541 lines
20 KiB
HTML
Raw Blame History

<HTML><HEAD>
<!--
---- $Id$
---- (c) Copyright 2001-2003 by Lutz Sammer
---- FreeCraft 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.
---- FreeCraft 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.
-->
<TITLE>Development for FreeCraft Version 1.18</TITLE>
</HEAD>
<BODY>
<H1>Development for FreeCraft Version 1.18</H1>
<HR><PRE WIDTH=80>
___________ _________ _____ __
\_ _____/______ ____ ____ \_ ___ \____________ _/ ____\/ |_
| __) \_ __ \_/ __ \_/ __ \/ \ \/\_ __ \__ \\ __\\ __|
| \ | | \/\ ___/\ ___/\ \____| | \// __ \| | | |
\___ / |__| \___ >\___ >\______ /|__| (____ /__| |__|
\/ \/ \/ \/ \/
______________________ ______________________
T H E W A R B E G I N S
FreeCraft - A free fantasy real time strategy game engine
</PRE>
<P><B>(C) Copyright 1998-2003 by The FreeCraft Project. Distributed under the
<A HREF="gpl.html">"GNU General Public License"</A></B>
<HR>
This file should give you some information to help to develop FreeCraft.<P>
If you make bigger changes please always extend the copyright with your name.<P>
<H2>Mailing list</H2>
If you want to develop for FreeCraft you should join the development mailing
list.<P>
<A HREF="http://www.geocrawler.com/redir-sf.php3?list=freecraft-hackers">FreeCraft development Archives</A><P>
<A HREF="http://lists.sourceforge.net/mailman/listinfo/freecraft-hackers">Subscribe FreeCraft development</A><P>
<H2>IRC - Internet Relay Chat</H2>
You can try to meet other FreeCraft developers and users on IRC:
<A HREF="http://www.openprojects.net/">OPN</A> OpenProjects Network, channel
#FreeCraft.
<H2>Bugs and tasks</H2>
You can find known bugs here:<P>
<A HREF="http://sourceforge.net/tracker/?group_id=1965&atid=101965">FreeCraft real-time strategy game engine - Tracker - Bugs</A><P>
And the planned tasks here:<P>
<A HREF="http://sourceforge.net/pm/task.php?group_project_id=1539&group_id=1965&func=browse">FreeCraft real-time strategy game engine - Tasks</A><P>
Before doing some work, please ask on the mailing list, whether anybody else is
doing the same thing and write what you plan to do to avoid that someone else
starts the same work.
<H2>Compiling, tools, and libraries</H2>
<H3>Installing CVS client</H3>
If you want to help develop, it is the best that you use CVS. To do so, first
you need CVS for your system.<P>
You find all information about CVS on <A HREF="http://www.sourceforge.net/">
SourceForge</A>.<P>
<UL>
<LI><A HREF="http://sourceforge.net/docman/display_doc.php?docid=763&group_id=1">
Sourceforge: CVS HOWTO</A><P>
CVS on SF - rookie should read it. General, should read it, <B>*too*.</B>
<LI><A HREF="http://sourceforge.net/docman/display_doc.php?docid=767&group_id=1">
Win32/CVS/SSH HowTo</A><P>
A "quick & dirty" guide
<LI><A HREF="http://sourceforge.net/docman/display_doc.php?docid=769&group_id=1">
Win32/CVS/SSH addendum for WinCVS</A><P>
Read after the Win32 Guide & Howto
<LI><A HREF="http://sourceforge.net/docman/display_doc.php?docid=770&group_id=1">
SourceForge setup tool for CVS/SSH/Win32</A><P>
There's a tool to help
<LI>Linux<P>
Install CVS, CVS-BOOK, and if you like, a CVS GUI.
<P>
In Debian: apt-get install cvs; apt-get install cvsbook; apt-get install lincvs
</UL>
<H3>Getting FreeCraft from CVS</H3>
<H4>There are four modules in CVS repository.</H4>
<UL>
<LI>freecraft - The FreeCraft engine source<P>
All you need to use with the original WC2 CD. The sources is licenced
under the terms of the GPL (GNU General Public License).
<B>This module is needed for development.</B>
<LI>fcsp - The FreeCraft Sound Project<P>
<B>This module will be removed.</B><P>
A collection of free sounds and music, GPL (GNU General Public License)
prefered. But each file can have its own license, so please read.
<LI>fcgp - The FreeCraft Graphic Project<P>
<B>This module will be removed.</B><P>
A collection of free graphics, animations and models, GPL
(GNU General Public License) prefered. But each file can have its own
license, so please read.
<LI>Planned: fcmp - The FreeCraft Media Project<P>
This will be the replacement of FcSP and FcGP.<P>
A collection of free media (free sounds, music, videos, graphics,
animations and models), GPL (GNU General Public License) prefered.
But each file can have its own license, so please read.
<LI>crafted - The FreeCraft Map Editor<P>
A map editor for FreeCraft. This project has just started and also needs
more developers.
</UL>
<H4>How do I access to these modules?</H4>
<H5>Anonymous CVS Access</H5>
This is for all user/developer/designer without account on SourceForge.<P>
Make somewhere a directory FreeCraft. Enter this directory.<P>
cvs -d:pserver:anonymous@cvs.freecraft.sourceforge.net:/cvsroot/freecraft login<BR>
<I>"When prompted for a password for anonymous, simply press the Enter key."</I><BR>
cvs -z3 -d:pserver:anonymous@cvs.freecraft.sourceforge.net:/cvsroot/freecraft co freecraft<BR>
cvs -z3 -d:pserver:anonymous@cvs.freecraft.sourceforge.net:/cvsroot/freecraft co crafted<BR>
cvs -z3 -d:pserver:anonymous@cvs.freecraft.sourceforge.net:/cvsroot/freecraft co fcgp<BR>
cvs -z3 -d:pserver:anonymous@cvs.freecraft.sourceforge.net:/cvsroot/freecraft co fcsp<P>
You will now have the directories freecraft, crafted, fcpg and fcsp.<P>
In the future, only go into any directory and enter "cvs -q update -d" to update to
the latest version.<P>
<H5>Developer CVS Access via SSH</H5>
Only project developers can access the CVS tree via this method. Substitute
<I>developername</I> with the proper values. Enter your site password when
prompted.<P>
export CVS_RSH=ssh<BR>
cvs -z3 -d:ext:<I>developername</I>@cvs.freecraft.sourceforge.net:/cvsroot/freecraft co freecraft<BR>
cvs -z3 -d:ext:<I>developername</I>@cvs.freecraft.sourceforge.net:/cvsroot/freecraft co crafted<BR>
cvs -z3 -d:ext:<I>developername</I>@cvs.freecraft.sourceforge.net:/cvsroot/freecraft co fcgp<BR>
cvs -z3 -d:ext:<I>developername</I>@cvs.freecraft.sourceforge.net:/cvsroot/freecraft co fcsp<P>
You will now have the directories freecraft, crafted, fcpg and fcsp.<P>
In the future only go into any directory and enter "cvs -q update -d" to get
the latest version. You'll be prompted to enter your ssh password.<P>
<H3>Getting FreeCraft without CVS</H3>
Please note CVS is always a little newer and it is easier for you to keep
up to date. But you find regular snapshots of the FreeCraft source here:
<UL>
<LI><A HREF="http://freecraft.sourceforge.net/snapshots/">HTTP sourceforge</A>
<LI><A HREF="http://freecraft.net/snapshots/">HTTP freecraft</A>
</UL>
<H3>Linux(tm)</H3>
To build FreeCraft with Linux you will need the following packages. The
following list refers mainly to Debian packages. You'll have to figure out
the corresponding packages in your particular distribution.
<UL>
<LI>gcc - The GNU C compiler<P>
gcc-2.95 preferred. Old gcc 2.96 can't compile FreeCraft. gcc 3.0 produce
many wrong! warnings.
<LI>libc6-dev - GNU C Library: Development Libraries and Header Files<P>
Contains the symlinks, headers, and object files needed to compile and link
programs which use the standard C library.
<LI>libpng2-dev - PNG library - development<P>
libpng is a library implementing an interface for reading and writing PNG
(Portable Network Graphics) format files.
<LI>zlib-dev - compression library - development<P>
zlib is a library implementing the deflate compression method found in gzip
and pkzip. This package includes the development support files.
<LI>xlibs-dev - X Window System client library development files<P>
xlibs-dev provides static versions of the libraries provided in xlibs, as
well as several libraries that do not exist in shared object form for
various reasons (such as the fact that their API's have not stabilized, or
that they are deprecated). Include files and manual pages are also
provided.
<LI>libsdl1.2-dev - Development files for Simple DirectMedia Layer<P>
Very simply, SDL is a library that allows you portable low level access to
a video framebuffer, audio output, mouse, and keyboard.<P>
This package contains the files needed to compile and link programs which
use SDL.<P>
If not included in your distribution you can get it
<A HREF="http://www.libsdl.org">here</A>.
</UL>
<H3>MacOS(tm)</H3>
To build FreeCraft with MacOS you will need the following packages.
<UL>
<UL>
<LI>gcc - The GNU C compiler<P>
gcc-2.95 preferred. Old gcc 2.96 can't compile FreeCraft. gcc 3.0 produce
many wrong! warnings.
<LI>If you have MacOS, can you please write this section. And send it us as
patch.
<LI>You can run ./setup which should work on MacOS/Darwin.
<LI>Or extract the project builder archive "contrib/macosx.tgz", this should
work on MacOS X.
</UL>
<LI>libpng2-dev - PNG library - development<P>
libpng is a library implementing an interface for reading and writing PNG
(Portable Network Graphics) format files.
<LI>zlib-dev - compression library - development<P>
zlib is a library implementing the deflate compression method found in gzip
and pkzip. This package includes the development support files.
<LI>libsdl1.2-dev - Development files for Simple DirectMedia Layer<P>
Very simply, SDL is a library that allows you portable low level access to
a video framebuffer, audio output, mouse, and keyboard.<P>
This package contains the files needed to compile and link programs which
use SDL.<P>
If not included in your distribution you can get it
<A HREF="http://www.libsdl.org">here</A>.
</UL>
<H3>Windows(tm)</H3>
You need a C compiler for Windows. Get <B>one</B> of the following.
<UL>
<LI>VC++<P>
In order to compile FreeCraft with VC++ follow these instructions:
<UL>
<LI>Extract the VC++ project and workspace files from
freecraft\contrib\msvc.zip into the root freecraft directory.
<LI><a href="http://freecraft.sourceforge.net/snapshots/msvc-libs.zip">
Download</a> the VC++ libraries and extract them into the root
freecraft directory.
<LI>Copy freecraft\contrib\freecraft.ico to freecraft\src.
<LI>You should now be able to compile freecraft.
</UL>
<P><LI><A HREF="http://sources.redhat.com/cygwin/">cygwin</A><P>
The Cygwin tools are ports of the popular GNU development tools and
utilities for Windows. They function by using the Cygwin library which
provides a UNIX-like API on top of the Win32 API.
<P><LI><A HREF="http://www.mingw.org">MinGW</A><P>
MinGW is a collection of header files and import libraries that allow one
to use GCC and produce native Win32 programs that do not rely on any
3rd-party DLLs.<P>
<UL>
<LI><B>CROSSCOMPILE ONLY</B>: <A HREF="http://www.libsdl.org/Xmingw32/">
http://www.libsdl.org/Xmingw32/</A><P>
Informations how to use MingGW and libSDL for cross development and
native development.<P>
<LI><A HREF="http://www.libsdl.org/Xmingw32/mingw32.zip">
http://www.libsdl.org/Xmingw32/mingw32.zip</A><P>
Compiler package for Windows, built by Sam Lantinga.<P>
<LI><A HREF="http://prdownloads.sourceforge.net/freecraft/freecraft-compiler-020322.zip">
http://prdownloads.sourceforge.net/freecraft/freecraft-compiler-020322.zip
</A><P>
My build is based on the above. Contains SDL 1.2.4, libpng, zlib.
libbz2 and libzzip. Install this, download the newest FreeCraft
source and start FreeCraft development under Windows. Come on!<P>
<B>If unclear, please download only this.</B>
</UL>
</UL>
<H3>Windows CE(tm) / PocketPc(tm)</H3>
You need a C compiler for this platform.<P>
<UL>
<LI>eMbedded Visual C++ 3.0<P>
You can download or order it <A HREF="http://www.microsoft.com/mobile/downloads/emvt30.asp">
here</A>.
<LI>CE support for Visual C++ or Visual Studio<P>
This isn't supported yet. If you know the links and how to use, please
publish this.
</UL>
You need the following libs for WinCE.
<UL>
<LI>libpng<P>
Required, you can download a ready and compiled development version here:
<A HREF="http://freecraft.net/snapshots/lpngce108a.zip">lpngce108a.zip</A>
or <A HREF="http://www.tenik.co.jp/~adachi/wince/index.htm">author site</A>
<LI>zlib<P>
Required, you can download a ready and compiled development version here:
<A HREF="http://freecraft.net/snapshots/zlibce12.zip">zlibce12.zip</A>
or <A HREF="http://www.tenik.co.jp/~adachi/wince/index.htm">author site</A>
<LI>libsdl<P>
Required, or you should write a new WinCE hardware driver for FreeCraft. You
will find information about SDL on the
<A HREF="http://www.libsdl.org">libSDL home</A> and you can download it
<A HREF="http://www.libsdl.org/download-1.2.html">here</A> and
<A HREF="http://www.libsdl.org/cvs/WinCE-SDL.zip">workbench and project</A>.
<LI>bz2lib<P>
Not required and no WinCE version found.
<LI>zziplib<P>
Not required and no WinCE version found.
</UL>
Now you need the
<A HREF="http://freecraft.sourceforge.net/snapshots/FreeCraft%20CE.vcp.gz">
emVC++ project</A> and
<A HREF="http://freecraft.sourceforge.net/snapshots/FreeCraft%20CE.vcw.gz">
emVC++ workbench</A> for FreeCraft.<P>
With the sources from CVS, you can continue working.<BR>
<B>Note: WinCE isn't supported yet.</B>
<H2>Make and makefiles</H2>
<I>Remember the first time you must start ./setup <B>or</B> copy
Rules.make.orig to Rules.make and edit it.</I><P>
Type 'make help' to get an overview what all could be made.<P>
'make depend'<P>
and then<P>
'make'<P>
is all you need, most times.<P>
<H2>C code documentation</H2>
See below: you can use always the source code documentation.<P>
I have prepared some extra documentation:<P>
<UL>
<LI><A HREF="datadir.html">FreeCraft data directory description.</A>
</UL>
<H2>Source code documentation</H2>
Valery Shchedrin has introduced tagged source documentation. I continue to
use them.<P>
<H3>This programs are required</H3>
You need one these programs to generate source code documentation.
<UL>
<LI><A HREF="http://www.stack.nl/~dimitri/doxygen/download.html">DoxyGen</A>
or <A HREF="http://www.doxygen.org">DoxyGen</A>
<LI><A HREF="http://www.zib.de/Visual/software/doc++/index.html">DOC++</A>
</UL>
<H3>Generate documentation from source code</H3>
Please compile and install one of the above programs.
With these commands you produce the documentation:
<UL>
<LI><EM>make doc</EM> If you use DoxyGen.
<LI><EM>make doc++</EM> If you use DOC++.
</UL>
<H3>Tags used in source code</H3>
I use the doc++ tags:<P>
/** ... */<P>
Multi line source code documentation.<P>
/// ... <P>
Single line source code documentation.<P>
//@{ or /*@{*/<P>
Start grouping.<P>
//@} or /*@}*/<P>
End grouping.<P>
<UL>
<LI>@name
<BR>Name of file or group.
<LI>@param
<BR>Describes function/macro parameter
<LI>@return
<BR>Describes function return
<LI>@see
<BR>Links to other section
</UL>
<P>
Please read the documentation of the programs.
<H2>Empty C prototype file</H2>
<PRE>
// ___________ _________ _____ __
// \_ _____/______ ____ ____ \_ ___ \____________ _/ ____\/ |_
// | __) \_ __ \_/ __ \_/ __ \/ \ \/\_ __ \__ \\ __\\ __|
// | \ | | \/\ ___/\ ___/\ \____| | \// __ \| | | |
// \___ / |__| \___ >\___ >\______ /|__| (____ /__| |__|
// \/ \/ \/ \/ \/
// ______________________ ______________________
// T H E W A R B E G I N S
// FreeCraft - A free fantasy real time strategy game engine
//
/**@name {filename}.c - {One line description of this file} */
//
// (c) Copyright 2003 by {insert your name here}
//
// FreeCraft 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.
//
// FreeCraft 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.
//
// $Id$
//@{
/*----------------------------------------------------------------------------
-- Includes
----------------------------------------------------------------------------*/
#include &lt;stdio.h&gt;
#include "freecraft.h"
// More game includes.
/*----------------------------------------------------------------------------
-- Variables
----------------------------------------------------------------------------*/
// Global and local variables of this module.
/*----------------------------------------------------------------------------
-- Functions
----------------------------------------------------------------------------*/
// Local and global functions of this module.
//@}
</PRE>
<H2>Coding style</H2>
You can use your own coding style in your own modules.
If you fix in other modules, please imitate the coding style of the old coder.
<P>I suggest: <A HREF="/usr/src/linux/Documentation/CodingStyle">
(Linux kernel coding style) </A>
<UL>
<LI>Write ANSI C.
<LI>Use 8 spaces tabulators.
<LI>Use 4 spaces indentation levels.
<LI>No line should be longer than 78 characters.
<LI>Use C++ comments for to end of line comments.
<LI>Use { } also for one statement blocks.
</UL>
<H2>Sending a patch</H2>
Now you made something, how this should be included into the main distribution?
<P>
Follow the following steps:<P>
<UL>
<LI>cvs -q update -d
<LI>cvs -q diff -u &gt; your-nickname.diff
<LI>upload it to <A HREF="http://sourceforge.net/tracker/?func=add&group_id=1965&atid=301965">patch tracker on sourceforge</A>
</UL>
<H2>Building FcGP (outdated see FcMP)</H2>
You always need the newest tarball from FcGP, because not all files are already
imported into CVS.<P>
<UL>
<LI>Download the fcgp tarball from <A HREF="http://FreeCraft.Net/snapshots/">snapshots</A>.
<LI>Get module from CVS. See above for instructions.
<LI>Unpack fcgp tarball. <I>tar vxzf fcgp-010801.tar.gz</I>
<LI>Move data directory into FcGP-CVS directory. <I>mv fcgp-010801 fcgp</I>
<LI>Enter CVS directory. <I>cd fcgp</I>
<LI>Update data tree. <I>make</I>
<LI>Test it. <I>../freecraft/freecraft</I>
</UL>
<H2>Building FcSP (outdated see FcMP)</H2>
You need FcGP, without this FcSP can't be used. Follow the above instructions.
<P>
<UL>
<LI>Get module from CVS. See above for instructions.
<LI>Link data directory from FcSP to FcGP. <I>ln -s fcgp/data fcsp/data</I>
<LI>Enter CVS directory. <I>cd fcgp</I>
<LI>Build data tree. <I>make</I>
<LI>Test it. <I>../freecraft/freecraft</I>
</UL>
<H2>Building FcMP</H2>
The new FcMP (FreeCraft Media Project) isn't yet available from CVS. You
can only download it as complete archive. Download it, extract it, copy
the binary freecraft(.exe) into the top directory and start it.
<H2>Building CraftED from CVS</H2>
CraftED uses autoconf and configure. To build from CVS use.<P>
./autogen.sh<BR>
make<BR>
./src/crafted<P>
<I>Note: the first time you must enter your path to the FcMP/original data
directory.</I> For more documentation please look into the docs directory.
<H2>Building CraftED from tarball</H2>
CraftED uses autoconf and configure. To build from tarball distribution use.<P>
./configure<BR>
make<BR>
./src/crafted<P>
<I>Note: the first time you must enter your path to the FcMP/original data
directory.</I> For more documentation please look into the docs directory.
<HR>
All trademarks and copyrights on this page are owned by their respective owners.
<ADDRESS><A HREF="http://freecraft.org">The FreeCraft Project</A>
</ADDRESS></BODY></HTML>
Reference in a new issue View git blame Copy permalink