Subversion Repository

From Hero of Allacrost

Revision as of 10:49, 27 July 2008 by MindFlayer (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This page contains information for accessing the code in the Allacrost Subversion (SVN) repository. Below covers the primary SVN client usage for each major operating system that Allacrost runs on.

Contents

Subversion Usage Policies

Note: This section is primarily written for the Allacrost development staff.

We have a few policies in place with regards to using the official Allacrost SVN at SourceForge. The reason for these policies is to keep the repository looking clean and to avoid clobbering someone else's commits.


  • Do not commit code that does not compile, or has enough serious bugs that the game can not be run!
  • If you are planning to add a new file (or directory) to the repository, you must give the programming team advanced notice (at least a few days) and get a majority approval for the file to be added.
  • The same policy above applies for removal of files or directories.
  • Do not commit code that is strictly for testing purposes. Small test functions inside existing code is okay, but a file that consists only of code for testing is not acceptable. Use the FTP if you must share such test code.
  • Every commit should be followed up with a post in the stickied Subversion Commit Log thread in the Programming forum.
  • In general, every developer has a set of files that they are the primary owner of. Do not make major changes to another owner's files without first notifying them. Small bug fixes to others files, however, are okay to make (but you should still notify the owner of the bug you fixed).
  • If, with your commit, you have been given permission to add or remove files, it is your responsibility to update the project files.
  • If you violate these policies, you may have your SVN access priveledges temporarily suspended.

Subversion on Linux

For users/players

So, you want to take a look at the current development tree? Well all you have to do is checkout the code. It's quite simple really. But first you need to install Subversion. There's the command line version, and there's GUI frontends. Which one you choose is up to you.

Command-line

Just open up a terminal and type the following at a command prompt:

svn co https://allacrost.svn.sourceforge.net/svnroot/allacrost/trunk local_dir_name

where local_dir_name is the local directory on your machine where Subversion will put the Allacrost top-level directory.

GUI frontends

Not yet familiar with any...


For developers

We will start here by assuming you've already checked out a working copy of Allacrost. The following will show how to commit changes you've made to the code, how to get previous revisions of files, and other miscellaneous things you can do.

Command-line

Note: All following commands should be done from the top-level working Allacrost directory, unless otherwise mentioned.


Adding files

You've created some new files and want to add them to the tree? No problem:

svn add file_name

If you'd like to add an entire directory to the repository:

svn add dir_name
Note: You will have to commit these changes before they will show up in the main repository.


Deleting files

Deleting a file is as simple as adding one:

svn delete file_name
Note: You will have to commit these changes before they will show up in the main repository.


Committing changes

Saving the changes you've made to your local working copy of the tree to the main repository is called "committing the changes", and is done like so:

svn update
svn commit -m "message goes in here"

The update command is used to make sure you have the latest updates in your tree before committing your changes. This is done to make sure you don't clobber any new changes that may have occurred to the main repository while you were doing your coding. The message is used to describe what changes have been made.


Revisioning

Note: If you're not familiar with Subversion's revisioning system, get up to speed, as it's quite different from CVS.

Let's say the current revision for the tree is 100, and you want to revert back to revision 99. The following command will do the trick:

svn update -r 99

What if you only wanted a certain directory to be reverted?

svn update -r 99 src/video

It's elementary, my dear Watson, to see that reverting one single file becomes something like so:

svn update -r 99 src/video/video.cpp


More help

More detailed help on any svn command can be done like so:

svn help command

An example would be

svn help update

Don't forget about the SVN RedBook and the quintessential

man svn

GUI frontends

Not yet familiar with any...

Subversion on Windows

Probably the easiest way to use Subversion on Windows platforms is to install TortoiseSVN which integrates seamlessly with the Windows Explorer.

Click here for the download section, then download the latest .msi file. After the installation, open up Windows Explorer and create a new folder for Allacrost. After that, right-click to see all the TortoiseSVN commands. Choose SVN Checkout...

Subversion on OS X

To use subversion on MacOSX, a subversion client must be downloaded. You can download a recent build here. With this build, the same commands can be used as above from Terminal.app. Note that Mac OS X Leopard (10.5.x) comes with SVN already installed. For a frontend, svnX is highly recommended.

Build Files

Hero of Allacrost uses the GNU Autotools suite to efficiently handle all types of systems/OSes. This currently includes GNU Autoconf, for configuring the source code correctly for each type of machine, GNU Autoheader, for generating a config file containing items defined on the system, and GNU Automake (and aclocal), for generating machine specific Makefiles.

The GNU Autotools suite has certain files associated with it in the repository. This section attempts to explain which files are associated with each step the GNU Autotools process, what those files contain, and which files to modify when need be.

Note: This section is intended for developers wishing to modify the build setup. It is not required for a regular install!!


GNU Autoconf

Files in the repository affected by GNU Autoconf are configure.ac and configure. GNU Autoconf will use configure.ac as an input file to produce the configure script by running the following command:

autoconf

So, if configure.ac is modified and committed to the repository, configure must be regenerated and committed also!! configure.ac specifies, among other things, libraries the game requires to run, as well as compiler flags. When any of these requires modification, configure.ac is where the changes should be made.

This is what configure.ac looks like:

File: configure.ac
dnl                                               -*- Autoconf -*-
dnl Process this file with autoconf to produce a configure script.

AC_PREREQ(2.59)
AC_INIT(Hero of Allacrost, 0.1, bugs@allacrost.org, allacrost)
AC_CONFIG_SRCDIR([src/main.cpp])
AC_CONFIG_HEADER([config.h])
AM_INIT_AUTOMAKE

dnl Checks for programs.
AC_PROG_CXX
AC_PROG_CC
AC_PROG_INSTALL
CXXFLAGS="-Werror -Wall"

dnl Check for map editor and Qt.
AC_MSG_CHECKING(whether to enable usage of map editor)
editor_default="no"
AC_ARG_ENABLE(editor, [--enable-editor=[no/yes] will build the map editor [default=no]],
    , enable_editor=$editor_default)
if test "x$enable_editor" = "xyes"; then
    AC_MSG_RESULT(yes)
    gw_CHECK_QT
else
    AC_MSG_RESULT(no)
fi
AM_CONDITIONAL([COND_EDITOR], [test "$enable_editor" = yes])

dnl Check for libraries.
AC_CHECK_LIB([openal], [alGetError], [], \
	[echo "You need to install the OpenAL library."
	 exit -1])
AC_CHECK_LIB([alut], [alutInit], [], \
   [echo "You need to install the ALUT library."
    exit -1])
AC_CHECK_LIB([vorbisfile], [ov_open], [], \
   [echo "You need to install the ALUT library."
    exit -1])
AC_CHECK_LIB([GL], [glEnable], [], \
	[echo "You need to install the GL library."
	 exit -1])
AC_CHECK_LIB([GLU], [gluBuild2DMipmaps], [], \
	[echo "You need to install the GLU library."
	 exit -1])
AC_CHECK_LIB([IL], [ilInit], [], \
	[echo "You need to install the IL library."
	 exit -1])
AC_CHECK_LIB([ILUT], [iluInit], [], \
	[echo "You need to install the ILU library."
	 exit -1])
AC_CHECK_LIB([SDL], [SDL_InitSubSystem], [], \
	[echo "You need to install the SDL library."
	 exit -1])
AC_CHECK_LIB([SDL_ttf], [TTF_Init], [], \
	[echo "You need to install the SDL_ttf library."
	 exit -1])
AC_CHECK_LIB([lua50], [lua_open], [], \
	[AC_CHECK_LIB([lua], [lua_open], [], \
		[echo "You need to install the lua library."
		 exit -1])])
AC_CHECK_LIB([lualib50], [luaopen_table], [], \
	[AC_CHECK_LIB([lualib], [luaopen_table], [], \
		[echo "You need to install the lualib library."
		 exit -1])])
AC_CHECK_LIB([m], [log], [], \
	[echo "You need to install the math library."
	 exit -1])
#AC_CHECK_LIB([X11], [main], [], \
#	[echo
#	 echo "**********"
#	 echo "You need to install the X11 library (comes with XFree or Xorg)" \
#	 	  "in order to use the Map Editor."
#	 echo "**********"
#	 echo])
#AC_CHECK_LIB([Xext], [main], [], \
#	[echo
#	 echo "**********"
#	 echo "You need to install the Xext library in order to use the Map Editor."
#	 echo "**********"
#	 echo])

dnl Checks for header files.
AC_HEADER_STDC
AC_CHECK_HEADERS([stdlib.h string.h])

dnl Checks for typedefs, structures, and compiler characteristics.
AC_HEADER_STDBOOL
AC_C_CONST
AC_C_INLINE

dnl Checks for library functions.
AC_CHECK_FUNCS([atexit sqrt])

AC_CONFIG_FILES([Makefile])
dnl				 src/Makefile
dnl				 src/map_editor/Makefile])
										  
AC_OUTPUT

echo ""
echo "Now type 'make'."
echo ""


The compiler flags are on the line starting with CXXFLAGS. Add or delete flags there.

Adding extra library dependencies is a little harder, but not much. Just copy one of the AC_CHECK_LIB invocations and modify it to suit your needs. The first parameter is the library itself, the second parameter is a function in the library, the third parameter (not used here) is for extra functionality when the check is successful, and the last parameter is used when the check is unsuccessful. So, our use of AC_CHECK_LIB is to check for a function in the library which it belongs, stopping with an error if not found.


GNU Autoheader

GNU Automake

External Links

http://svnbook.red-bean.com/ A free, online book detailing everything you need to know about subversion.

http://tortoisesvn.tigris.org/ A GPL-licensed, easy-to-use version control system using Subversion. Integrates automatically with the Windows Explorer.

Personal tools