$Id: compile-mathsim.html 502 2011-08-18 19:02:42Z perseant $

Getting and Building MATH

These are instructions on how to get the source code and documentation for MATHSim and MATHView (and, to some extent, MATHFlow) from the PARVAC SVN revision control repository, assuming you are running some version of Windows.

What is presented here is a very brief overview of the Subversion revision control system, the Microsoft Visual Studio IDE, and the WiX installer builder. See Further Reading at the bottom for more information on these systems.

Prerequisites

To get the source code from the repository, you will need TortoiseSVN. To compile MATHSim, you will need the Visual Studio 2010 IDE. To compile MATHView, you will need NetBeans IDE. To build the MATHSim installer, you will need WiX 3.5.

These packages can be acquired from the following sources:

TortoiseSVN: http://tortoisesvn.net/downloads.html
Visual Studio 2010 (IDE): http://www.microsoft.com/express/Downloads/#2010-Visual-CS
WiX: http://wix.codeplex.com/releases/view/60102 (choose "Wix35.msi").
NetBeans (IDE): http://netbeans.org/

After installing these four software packages, you should reboot your computer.

Check Out a Copy of the Repository

The source code and documentation are located in a Subversion repository on svn.parvac.washington.edu. To communicate with this server, we use the TortoiseSVN client software.

Before we can do anything else, however, we must first obtain a "checked out copy" of one of the folders that the server maintains.

Right-click on the desktop (or in any folder you like, really) and pull down to "SVN Checkout...".
For "URL of repository", type in our repository URL: svn+ssh://svn.parvac.washington.edu/home/svnroot/sharpc
Press OK. You will be prompted for a login and password, perhaps as many as three times. This doesn't mean that you typed it wrong the first time, only that it needs it again for whatever reason.
You should see a window listing all the files that were checked out; and the new folder what will have appeared on your desktop should have a green check mark on it. I'm going to call this folder sharpc.

Once this procedure has been completed, TortoiseSVN will remember what server it should talk to about the folder sharpc, if and when you decide to update its contents from the server, or if you have made changes to it that you think should be reflected on the server.

Update an Existing Copy of the Repository

If at some later time you want to update the files you have checked out to the newest revisions in the repository, right-click on the sharpc folder, and select "SVN Update". Once again you will be prompted for a login and password, and you will see a list of files that have been updated and/or checked out afresh.

Building MATHSim

Double-click on the MSEI.sln file, contained in sharpc\MSEI. This should open the solution in Visual Studio.
You will see several projects listed in the right-hand sidebar. Find the project titled MATHSim. If it is listed in bold-face, that indicates that that is the startup project. If it is not listed as the startup project, right-click on it, and pull down to Set as Startup Project.
Press F6, or select Build Solution from the Debug menu.

Once MATHSim has built successfully, Visual Studio will also call WiX to create an installer. The resulting installer resides at sharpc\MSEI\MATHVisualSimulator\WiX\MathVS-Setup.msi.

Running MATHSim from Inside Visual Studio

After a successful build, you will be able to run MATHSim by pressing F5, or by selecting Start Debugging from the Debug menu. Note that MATHSim will run several times more slowly in this environment than it will once it has been installed.

Building MATHView

Gephi/MATHView is written in Java using the NetBeans platform, so the instructions for building it are somewhat different.

Open NetBeans from the All Programs menu.
From the File menu, select Open Project.
Navigate to sharpc and select MathView.
From the Projects window on the left, locate the Gephi 0.8 alpha project.
Right-click on Gephi 0.8 alpha and pull down to Clean and Build All.
To build a Zip file for distribution, right-click on Gephi 0.8 alpha and pull down to Package As, then Zip Distribution. (There is also an option for Installers; it doesn't work for me, but I haven't investigated why not very far.)
The generated zip file will be in the file system, in the sharpc\MathView\dist folder.

Running MATHView from inside NetBeans

To run Gephi/MATHView from within NetBeans, click on the green triangle ("Play") button on the top tool bar.

Building MATHFlow

The instructions for building MATHFlow are the same as for building MATHSim, except for the location of the solution file. MATHFlow's solution file is located at sharpc\MATH\Math.sln. The MATHFlow sources do not include an installer, and MATHFlow expects all of its constituent parts to reside in the C:\MATH directory, so running it from the Visual Studio debugger is also a bit more challenging.

Looking at the Change Log

It is sometimes useful to discover what the intended changes were for a given revision. To see these, right-click on the sharpc folder, and from within TortoiseSVN, select Show Log. You will be prompted for your password twice, and then a log will appear, showing what files were changed for each revision, and what the committer's comments were for that revision.

Glossary

Build: To build software is to create an executable (or more than one, as the case may be) from the source code. Sometimes, but not always, an installer will be built as part of the same build process.
Checkout: Files that are being maintained under revision control can be retrieved by checking them out; the analogy is that of a lending library. In concurrent revision control systems, such as Subversion, the user that checks out the source code does not at the same time obtain exclusive privileges over the checked out software; it is as though, instead of retrieving the original book from the library, you photocopied a book that was being held on reserve. The result of a checkout operation is a checked-out copy of the most current revision of the files stored in the repository.
Commit: When a user with a checked-out copy wishes to submit changes to the repository, he commits (or, colloquially, checks in) the changes to the repository. The result of this operation is that a new revision of the affected files is created, and the current revision number is increased. In Subversion, this means that the global revision number is increased by one.
Commit Log: Whenever a developer commits a change to the repository, he provides a summary of what changes were made. These summaries, along with a list of affected files, appear in the commit log, which can later be used to identify potential sources of observed regressions. The commit log is also often used by managers and other developers, who may wish to follow the progress of the code without having to read the code directly.
Conflict: When a user with local changes performs an update, it might happen that someone else has made changes to the same parts of the same files as the user himself. If the changes are far enough apart, Subversion will simply merge the changes together, but if they are right on top of one another, it doesn't know how to do that. In that case, it will mark the affected file(s) in conflict. Subversion will not allow files to be committed while in conflict. The user must address the conflicting source code, and then tell Subversion that the file(s) are no longer in conflict, before committing his changes. Since changes to binary files cannot be merged, concurrent changes to any binary files stored in the repository will always result in a conflict.
IDE (Integrated Development Environment): An application (or perhaps a collection of applications) that includes at least a source code editor and a compiler. For this project, our development environments are Microsoft Visual Studio and Oracle NetBeans.
Installer: An installer is a small application whose job it is to install software and inform the end user of the licensing conditions. The installer contains information about each part of the software to be installed and where it all should go on the end user's computer (subject, usually, to their preferences).
Local Changes: A common misconception about revision control is that any changes made to any local checked-out copy are automatically reflected in every other checked-out copy. Since a significant fraction of the development cycle involves code that does not even compile, let alone do what it is supposed to, no sane revision control software will work like this. Instead, individual developers work on one component to effect one change, and when their change is working well enough to share, they commit. Before they commit, of course, their checked-out copy differs from what is in the repository. These changes are known as local changes.
Regression: A feature which had previously worked as expected, but which no longer works after a software update, is known as a regression.
Repository: In revision control parlance, the repository is the central location of the files under revision control.
Revision Control: Revision control allows organizations (as well as individual developers) to have a historical view of source code. Past revisions can be retrieved, or compared against the present revision or against each other. For a single developer, this makes it possible to identify the source of regressions, and acts as a sort of instant backup system. In the case of multiple developers, it allows them all to work on the same code at the same time, with a minimum of fuss. (There is always, of course, some fuss when there are multiple developers.) For organizations, revision control allows the simultaneous existence of several released versions of a piece of software, so that updates can be released for both. Revision control also allows managers to keep track of what changes are being made to the source code by looking at the commit log, thus freeing managers from themselves having to read the source code.
Update: An update applies any changes that have been made to the repository since the last update, to the checked-out copy. If there are any local changes, the update will attempt to merge the changes, possibly resulting in a conflict.