Introduction
Wesnoth is a very large fantasy turn based
role playing game written in C++. The most recent stable version of this game
is Wesnoth 1.8.6. The compressed
wesnoth-1.8.6.tar file may be downloaded from
this site and then
expanded in order to recover the source code, but be warned that this is a
540Mbyte compressed file, and may take considerable time to download. A
somewhat smaller 302Mbyte
wesnoth-1.8.6.tar.bz2
can be downloaded in order to obtain source, if you have no need to build
wesnoth.
If you intend to perform all of the steps involved in extracting facts from
WESNOTH you will need to complete the following steps on a linux
machine since asx will only currently run on such machines.
Alternatively, and much more simply you can take advantage of the fact that
this exercise has already been done for you and download the large
56Mbyte wesnoth.1.8.6.ta fact extraction graph
which includes references to templated functions, or the much smaller
4.3Mbyte wesnoth.1.8.6.small.ta which
does not. You will probably find the much smaller fact extraction much
easier to extract a high level architecture from.
WESNOTH fact extraction steps
The following are all of the steps needed to perform fact extraction, given
that one starts with nothing.
- Create a suitable directory to work in.
- Download the latest version of WESNOTH from
http://sourceforge.net/projects/wesnoth/files/.
Currently the latest version is wesnoth-1.8.6.tar.bz2
- Decompress wesnoth-1.8.6.tar.bz2 using bunzip2 wesnoth-1.8.6.tar.bz2.
- Alternatively obtaining a copy of this
decompressed file from swag:~ijdavis/wesnoth-1.8.6.tar.
- Decompress wesnoth-1.8.6.tar using tar xvf wesnoth-1.8.6.tar.
- Change into the directory wesnoth-1.8.6
- Read the INSTALL file
- Run ./autogen.sh
- Run ./configure
As long as configure fails due to missing files, you will need to install stuff.
I had to install
- apt-get install libsdl-image1.2
- apt-get install libsdl1.2debian-all
- apt-get install libsdl-ttf2.0-0
- apt-get install libsdl-ttf2.0-dev
- apt-get install libsdl-image1.2-dev
- apt-get install libsdl-mixer1.2
- apt-get install libsdl-mixer1.2-dev
- apt-get install libsdl-net1.2
- apt-get install libsdl-net1.2-dev
- apt-get install lua5.1
- apt-get install liblua5.1-0-dev
- apt-get install libboost-dev
- apt-get install libboost-iostreams1.40.0
- apt-get install libboost-iostreams1.40-dev
- Create shell scripts for gcc, g++ and if desired as
that capture the
information about how WESNOTH is built as described in the
asx webpage.
This will as a subtask involve installing of echoargs. These shell scripts
and echoargs can alternatively be obtained from swag:~ijdavis/bin, and
then be suitably modified to direct output to a file you may write to.
- Perform superficial tests to validate that your wrapping shell scripts
that act as front ends to gcc, g++ and asm work.
- Make sure the log you are going to capture the build history into is
absent or empty before each fact extraction.
- cd src
- Build WESNOTH by issuing the command make wesnoth in the src
directory and check that the build completed successfully. You might wish
to capture the output from the build process itself by using the script
command.
Note that if you issue make in the wesnoth-1.8.6 directory you will build
all the components of WESNOTH including the wesnoth executable. The
resulting history, from which fact extraction is obtained will cause
fact extraction to reflect the totality of the wesnoth code, rather
than as presumed intended just the wesnoth executable.
- Immediately rename the build log captured by the scripts that override
the normal build process to history.wesnoth.1.8.6, (or other suitable name)
so as to ensure that no further compilations are incorrectly appended to it.
- Check the log captured from the
build process, and remove any parts of the build process not deemed relevant
to the fact extraction.
- Download, compile and install asx, or
obtain a copy of asx from "swag:~ijdavis/bin/asx".
- Set the asx environment variables appropriately. I used
- ASX_IGNORE="o;a;so;v" to avoid extracting facts about variable usage
which would have added clutter to the landscape, and made it more difficult to
load the graph into lsedits available memory. The smaller extraction used
ASX_IGNORE="o;a;so;v;t" to also omit references to templated functions.
- ASX_UNLINK=no because I wanted to preserve the assembler files
from which facts were actually extracted.
- ASX_SILENT=yes because I didn't need verbose output from asx.
- ASX_FORCE=
- Run asx < history.wesnoth.1.8.6 > wesnoth.1.8.6.ta.
- Check the start of the output in wesnoth.1.8.6.ta for correctness, and that
the final line indicates end of output was reached.
- If you don't already have Sun's java installed on your machine download and install it from www.java.sun.
- Download and build lsedit.
- If running lsedit on a unix machine using X-Windows you may need to
set the environment variable DISPLAY=":0.0" and then export DISPLAY, and/or
use other magic in order to have LSEdit paint correctly in the display
window.
- To view the facts extracted I use the java command:
"c:\program files\Java\jdk1.6.0_12\bin\java.exe" -Xms1024M -Xmx1024M -XX:PermSize=512M -XX:MaxPermSize=512M -classpath . LandscapeEditorFrame -l simplex ..\data\wesnoth.1.8.6.ta
Note that the facts extracted from Wesnoth are very large, and it is difficult
to apriori make any reasonable guess as to how much permanent memory and
heap memory java will require to both permit the call graph to be visualised
and suitably manipulated. The above sizing which allocates 512Mbytes of
memory to the permanent memory space and 1Gbyte of memory to the heap is
(given the size of the lsedit executable itself) approaching the maximum
memory that can be used by a single program on a 32 bit machine. If you
are working on machines with only a limited amount of main memory you
may find it more difficult to suitably configure memory, and may not be able
to successfully load wesnoth.1.8.6.ta into lsedit under any memory
configuration possible on your machine.
.
-
If you also wish to use the bunch clusterer you will need to extend the class
path above to be -classpath .;bunch.jar to include the bunch libraries.
You will also need to build the associated java program clue.
Viewing source code
It is possible to view the source code associated with fact extraction using
LSEdit. Ideally when viewing the extracted facts source code will be located
on the same path that it was found at when performing fact extraction. This
can normally be achieved by creating the approriate directories and
placing the source code appropriately. However, if this is not possible,
change the named location of the
root directory by clicking on this root directory in lsedit, pressing 'a'
and then alter the file field appropriately. Note that enter is required
following change of a value to commit that change. You can check that the
value has been changed by closing the attribute dialog box and then
reopening it.
To open source code once this has been done from either an edge or a node
that has file/lineno information in its attributes, go to options
in the menu bar, and then Specify command. There are a number of
example ways of opening up software to visualise source code (you are
welcome to submit others for inclusion in the list of examples). Basically
the top white line names the command to be executed, and each of the lines
in the grey box specify a single parameter to this command. At run time
$(X) gets changed into the value of the X attribute in the object which
is selected when one invokes the command. Note that one can have more
than one command by changing the hot key name in the right hand bottom
corner any of (h, f4-f10). If any of the examples work for you just
press set to use it. Otherwise choose the best example and then change
the values in the dialog after pressing set appropriately.
Grok and JGrok
If you wish to manipulate the facts extracted you may use either
grok or
jgrok. Note that grok is more stable but runs only
on linux platforms. JGrok should work on any machine that supports Sun
Java.
Contact information
For more information on fact extraction please contact us at
.
|