Alien Arena Developer Reference

(Suggestion: Start with the Autotools Mythbuster.)

The user-writeable data and configuration directory is, by default, $HOME/.local/share/cor-games. The program honors the XDG_DATA_HOME environment variable. See:

http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html

For development testing, the user-writeable directory may be temporarily changed by running like this:

The botinfo resource subdirectory is moved to the data1 directory. There are user-writeable botinfo directories in the game subdirectories. So there is, potentially, an arena/botinfo and a tactical/botinfo in $XDG_DATA_HOME/cor-games.

The shared data installation directory is specified in the build by defining a COR_DATADIR preprocessor symbol. The default is /usr/local/share/alienarena.

(Included here for reference.)

Previous versions had support for configurable DATADIR and LIBDIR installation paths. However, the implementation was not complete; due largely to the file system organization inherited from the Quake source. The installation procedure now uses configure arguments for determining installation paths.

Linux distributions install the game in the /usr hierarchy in conformance with Unix file system standards. The /usr hierarchy requires root privileges for writing, of course. While the game already had support for a user writeable directory, .codered/, in the users home directory, it did not implement a place to write bot information. Therefore, support for a botinfo directory in the user’s home directory was added.

To simplify the installation and to avoid the complications of using a shared library, the game module shared library, game.so, is now a static library. As a result, the LIBDIR installation variable is eliminated. Internally, the interface to the game module retains the dynamic link structure. Thus, it is still possible, in theory, to have a dynamic game.so that overrides the statically linked version. This is not tested nor supported in version 7.50.

Two new functions were added to the server/game interface for file system access. The location of game data files depends on how the game is installed. The code should not make assumptions about the base path since it might be affected by "prefix" and "datadir" configuration options. The game module will now determine all file paths using those functions (eliminating problems where the code assumed the legacy Quake style file system). The additional functions make it possible to place a botinfo directory, in user-writeable file space. The two new functions supply the full filesystem path when given a relative path. The functions are FullPath() and FullWritePath(). They are declared in game/game.h and qcommon/qcommon.h. They are defined in qcommon/files.c.

The name of the stand-alone dedicated server was changed from crded to crx-ded. The purpose was to make it simple to change the name of the executable files using the standard built-in configure option.

(Included here for reference.)

With the 7.60 release, the dedicated server name was updated to alienarena-ded.

Install the free Apache (formerly Tigris) Subversion client using your package manager. Or download it from the website at http://subversion.apache.org/ .

To download Alien Arena from the SVN Repository:

For example:

These are Autotools-related files that are manually edited:

Some Autotools files are just copied without change:

The Alien Arena Autotools build uses Maintainer Mode. The upside of this is that the end user does not need the Autotools programs and can run the well-known ./configure, make, sudo make install procedure. The downside is that if configure is run without --enable-maintainer-mode, some of the generated files will not be updated.

The Generated Files are:

The Generated Files need to be regenerated when any of following occur:

Note There are other intermediate files generated by Autotools. Refer to Autotools documentation.

The Autotools packages are:

To avoid confusion, developers committing to the repository should all be using the same versions of these packages.

The autoconf-archive is an evolving set of macros maintained on the GNU website. We use a few of these. The file names are normally prefixed with ax_ and the macros prefixed with AX_. Each file has a serial number in a comment. Care should be take not to commit an earlier version of a .m4 file into the SVN m4 subdirectory. If a file we use is updated in the archive, update it in the repository.

After adding new AX_ macros to configure.ac, the .m4 file needs to be added to the m4 subdirectory. This is done with the following command.

Source files are modified in the source/Makefile.am file. Modify the source in the applicable *_SOURCE lists. Header (.h) files must be included, because the list is used to generate the tarball.

Certain files may appear in several lists. For example, 'alienarena_SOURCES, alienarena-ded_SOURCES and libgame_a_SOURCES all have qcommon/qfiles.h.

There is a set of subdirectory Makefile.am files that contain lists of game resources. These are invoked recursively during the make install and make distcheck procedures. They contain only those resources that are to be included in the distribution tarball.

The downside is that these files needs to be kept up-to-date with additions and deletions. The advantage is that the install program handles the copying of game resources. For make uninstall it handles deletion of what make install installed.

To make modifications, find the appropriate Makefile.am and add, delete or modify the file entry. Makefile syntax requires that there be no trailing spaces after the \. Each entry should be preceeded by one TAB character. The files are listed in (mostly) alphabetical order.

Formerly, the game resource list was a monolithic file (game_data.am). With version 7.60 the number of resources exceeded the command line length limit.

The details of changing the system library settings are way beyond the scope of this document. Some knowledge of autoconf and automake is required.

For common system libraries, there may be a helpful .m4 macro available. These may be part of autoconf (AC_*), or they may be extensions from the Autoconf Archive (AX_*).

There are various clean options, besides the usual, that remove more than object files. Some useful ones are:

Following any changes changes to configure.ac files or Makefile.am files, or after make maintainer-clean do:

The --force and --install options to autoreconf are not usually needed. Run autoreconf --help for descriptions. The --install option copies files to m4/ and config/.

For source code only updates, all that is needed are:

After a make distclean, do:

When game assets are modified it is usually a good idea to remove the existing assets installed by the last make install. Do this with:

If this is done after doing an SVN update and regenerating the installation Makefiles, it may not delete old files. So, it is a good idea to check that the installation directories are cleared. One way to do that:

There are variations for the configure and make install commands, of course. See below for configure options and compiler options.

The make command runs faster with a multicore CPU if you add the -jN option where N is the number of cores plus one.

Run some tests and, if all this goes well, commit the changed files to the repository. The svn status command will show which files were modified.

If you want to commit only a subset of the changed files, the SVN changelist command is your friend.

Verify that your versions of autoconf, automake, and autoconf-archive are current.

The 7.66 release uses autoconf 2.69 and automake 1.14. If more than one dev is committing autotool related changes to SVN, it will be less confusing if all are using the same versions.

As of 2015-01, the "7.66.1" SVN development version is using automake 1.13.4 (because that’s my distro’s default, that’s why.).

Verify that the version number in configure.ac is correct.

See the Maintainer’s Guide above. Verify that all Autotools-related files are up-to-date.

Export from the SVN trunk to a directory for the distribution build.

Verify that the files in config/ and m4/ subdirectories are current. One way to do this is to rename the config/ and m4/ directories and then run:

Compare the files in the new config/ and m4/ with the previous ones. If they match, proceed. If not, then the files in SVN need to be updated. The cleanest thing to do would be to update SVN and do a new export.

As of 2015-01, the only files in m4/ are manually copied. But, in the future it may contain libtool files that are updated by the commands above.

Run this command to build and verify the distribution package:

If this succeeds, the alienarena-<version>.tar.gz has been created.

In a test directory, extract the distribution archive. Run the configure, make, make install sequence. Use the --prefix configure option to install into a test directory.

To test the dedicated server only build, create a subdirectory and build with an alternative test directory. In the subdirectory, configure is invoked with ../configure.

An example for testing distribution package generation:

For release, separate source and data archives should be generated in addition to the monolithic archive. This is primarily for the convenience of distro packagers. Distros normally use separate source and data packages; possibly, because the licenses for the source and data are different.

For the source-only package:

For the data1-only package, in the data1 directory:

This script uses several SVN export commands to retrieve the subset of files needed for the release tarball. It then invokes make distcheck to build the tarballs. Run the script in a RELEASE directory.

The following commands generate the checksums and then run a diff to check for possibly missing files. This compares the repository directories with what is in the tarball. Since, not all repository files are distributed, this requires knowing what files are not supposed to be in the tarball. (But, we are not too picky about putting "extra" stuff in the tarball.)

In the RELEASE directory:

The Script: