1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
==================
README-DEVELOPER
==================
:Author: z-man
.. contents::
This file is intended as a guide to developers. It is a constant work in
progress.
If you want to become a developer, you should register at the `Armagetron
Advanced Forum`_. Just tell us that you want to join and what your skills are.
We can always use another hand.
.. _Armagetron Advanced Forum: http://forums.armagetronad.net
The information here is for the Unix side of development, Windows developers
just need to read README-Subversion to get going.
Flags and Settings only developers need to know about
=====================================================
The general rule of developing solid software is that as many bugs as possible
are found during development. To faciliate this, the configure script
understands some options for developers. They are triggered by giving the
shell variables ``DEBUGLEVEL`` and ``CODELEVEL`` to numeric values. The tables
below defines the possible settings. Every setting includes all the effects of
the previous settings.
``DEBUGLEVEL``: determines the level of debugging checks
0
No debugging. If no further CXXFLAG is set, this enables the -Os
optimization flag.
1
Disables optimizations and enables debugging symbols.
2
Enables tASSERT assertions and other things that do not eat away too much
CPU time.
3
Enables the leak-finding memory manager.
4
Enables extensive consistency checks. This slows down the system
considerably, but it is still playable.
5
Enables full memory management debugging. Slows down things to a crawl.
``CODELEVEL``: determines the level of compiler checks for sensible code
0
No checks.
1
Enables ``-Wall`` compiler flag.
2
Enables various other warnings that are not too restrictive.
3
Enables all warnings that sound good in theory.
4
Enables ``-Werror``.
z-man feels that developers should use at least ``DEBUGLEVEL=3`` in daily
operation. Higher debug levels should be used when bugs are hard to find
otherwise. Likewise, ``CODELEVEL=2`` should be the default for developers and
the code should compile without warnings. (Hint: also setting
``CXXFLAGS=-Werror`` helps not to miss any warning by mistake) Warning options
activated by ``CODELEVEL=2`` that turn out to be too restrictive should be
reported to the forum, they are negotiable.
How to run and debug
======================
Use ``make debug`` to create debugging files: a symbolic link to the
executable from the build directory and ``.gdbinit`` setting a default
breakpoint. You can then use ``gdb armagetronad(-dedicated)`` to start the
game in the debugger.
Use ``make run`` to run the game from within the build directory; it should
automatically gather its data files from the source and build directory. In
this mode of operation, variable files are stored inside the build directory
in the var/ subfolder.
Source code reformatting
========================
There exist three source code reformatting targets for different needs:
make rebeautify
For developers who are happy with the project code formatting settings. It
enforces them and touches the time-stamps of changed files.
make beatuify-personal and make beautify
Apply your personal formatting rules (from ~/.astylerc) and the project
defaults without updating the timestamps for those who want to switch
between two styles without full rebuilds in between.
Checks
======
Build system integrity checks:
make installcheck
installs the game in a local directory tree (._inst), tests its basic
operation and uninstalls it, checking whether there are leftover files.
make devcheck
runs beautification and "make installcheck".
make distcheck
(provided by automake) builds a distributable source tarball and checks
whether "make (dist)clean" and various installations work correctly. It
makes a full rebuild and is time consuming.
make fullcheck
runs all of the above.
z-man's advice: Before committing your work to Subversion, please run at least
``make devcheck``, it only takes some seconds. Run ``make fullcheck`` when you
have made changes to the build system.
|