Introduction

If you intend to perform all of the steps involved in extracting facts from FREECIV 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 3.8Mbyte freeciv-2.3.2.ta fact extraction graph.

FREECIV fact extraction steps

The following are all of the steps needed to perform fact extraction, given that one starts with nothing.

1. Create a suitable directory to work in.
2. Download the latest version of FREECIV from http://freeciv.wikia.com/wiki/Main_Page. To do this click on [SOURCE CODE 2.3.2 31st Mar 2012].
   Currently the latest version is freeciv-2.3.2.tar.bz2
3. Decompress freeciv-2.3.2.tar.bz2 using bunzip2 freeciv-2.3.2.tar.bz2.
4. Decompress freeciv-2.3.2.tar using tar xvf freeciv-2.3.2.tar
5. Create a target directory in your home directory named freeciv
6. Change into the directory freeciv-2.3.2
7. Read any relevant documentation in this directory
8. ./configure --prefix=/<homedir>/freeciv
9. Create shell scripts for gcc and g++ that capture the information about how FREECIV 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.
10. Perform superficial tests to validate that your wrapping shell scripts that act as front ends to gcc, g++ and asm work.
11. Make sure the log you are going to capture the build history into is absent or empty before each fact extraction. Eg. rm ../history
12. make
13. Build FREECIV by issuing the command make 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 this will build all the components of FREECIV including the freeciv executable. The resulting history, from which fact extraction is obtained will cause fact extraction to reflect the totality of the freeciv code, rather than as presumed intended just the freeciv executable. If this is deemed to be undesirable you will have to parameterise the make command to instruct it to only build what you deem relevant
14. Immediately rename the build log captured by the scripts that override the normal build process so as to ensure that no further compilations are incorrectly appended to it. Eg. mv ../history ../history.freeciv.
15. Check the log captured from the build process, and remove any parts of the build process not deemed relevant to the subsequent fact extraction.
16. Download, compile and install asx, or obtain a copy of asx from "swag:~ijdavis/bin/asx".
17. Set the asx environment variables appropriately. I used
    • ASX_IGNORE="o;a;so;v;t";export ASX_IGNORE 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.
    • ASX_UNLINK=no; export ASX_UNLINK because I wanted to preserve the assembler files from which facts were actually extracted.
    • ASX_SILENT=no; export ASX_SILENT because I wanted verbose output from asx to tell me how it was progressing.
    • ASX_FORCE=; export ASX_FORCE
    • ASX_SKIP=no; export ASX_SKIP

18. Run asx < history.freeciv.2.3.2 > freeciv.2.3.2.ta.
19. Check the start of the output in freeciv.2.3.2.ta for correctness, and that the final line indicates end of output was reached.
20. If you don't already have Sun's java installed on your machine download and install it from www.java.sun.
21. Download and build lsedit.
22. 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.
23. 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\freeciv.2.3.2.ta

    Note that the facts extracted from Freeciv are 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 freeciv.2.3.2.ta into lsedit under any memory configuration possible on your machine. .

24. 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