Readme-save.txt
---------------

It is often useful to save "snapshots" of your model/program
(and associated files), e.g., to have the extact version
as it was when you ran a set of experiments, or to have a version
you can go back to after you make some changes that
introduced bugs you can't find, or that you just don't want.

One way to do this is to use a program like cvs (Concurrent Version System).
From the man page:
    CVS is a version control system, which allows you to keep old  versions
    of  files  (usually  source  code),  keep  a  log of who, when, and why
    changes occurred, etc., like RCS or SCCS. 
It provides ways for users to "check out" files, change them, then 
"check in" those files.   There are facililities to lock files so
only one person can check them out at a time, and to merge changes
made concurrently by different users to the same files.
Thus cvs is one of a number of version control systems available on
linux/unix and other systems.   You can "man cvs" and/or get
O'reilly or other introductory books to learn how to use these.

A simpler approach involves using the "jar" program, a tool to
archive sets of files into a single "archive" file.  jar is like tar,
a famous linux/unix program, except jar has features especially useful
for archiving java files.

In the build.xml file used with the programs in /appl/repast/Demos-3
we have provided a "save" option which uses jar to produce
date-time stamped jar archive files.   To use it for a given project
(e.g., below in one called AntFoodEA/) just enter:

   ant save

You will see something like:

   Building jar: /users/rlr/RePast/Demos-3/AntFoodEA/Saves/AntFoodEA-050208-0728.jar
   The jarfile is in Saves/AntFoodEA-050208-0728.jar

You will see there is then a directory Saves/ and it will have the new
archive file in it:

badger-AntFoodEA$ ll Saves
total 36
-rw-r--r--    1 rlr      car         35599 Feb  8 07:28 AntFoodEA-050208-0728.jar

If you do ant save later, it will produce a new archive, with the appropriate
date/time in the file name.
You can see all the files in a given archive file with a command like:

badger-AntFoodEA$ jar tvf Saves/AntFoodEA-050208-0728.jar 
     0 Tue Feb 08 07:28:42 EST 2005 META-INF/
   103 Tue Feb 08 07:28:40 EST 2005 META-INF/MANIFEST.MF
     0 Wed Feb 02 00:08:06 EST 2005 dat/
     0 Wed Feb 02 00:08:06 EST 2005 src/
     0 Wed Feb 02 00:18:04 EST 2005 src/AntFoodEA/
   432 Wed Feb 02 00:29:32 EST 2005 Readme.txt
  9838 Wed Feb 02 00:08:08 EST 2005 build.xml
  8667 Wed Feb 02 00:18:04 EST 2005 src/AntFoodEA/AntFoodEA.java
  4169 Wed Feb 02 00:15:16 EST 2005 src/AntFoodEA/BatchModel.java
  4166 Wed Feb 02 00:08:06 EST 2005 src/AntFoodEA/BatchModel.java.bak
  2413 Wed Feb 02 00:17:16 EST 2005 src/AntFoodEA/Bug.java
  2404 Wed Feb 02 00:08:06 EST 2005 src/AntFoodEA/Bug.java.bak
  5488 Wed Feb 02 00:17:36 EST 2005 src/AntFoodEA/GUIModel.java
  5481 Wed Feb 02 00:08:06 EST 2005 src/AntFoodEA/GUIModel.java.bak
  8646 Wed Feb 02 00:08:06 EST 2005 src/AntFoodEA/Min2D.java.bak
 32109 Wed Feb 02 00:08:08 EST 2005 src/AntFoodEA/ModelParameters.java
 32110 Wed Feb 02 00:08:06 EST 2005 src/AntFoodEA/ModelParameters.java.bak

The parameters on the jar file are
  t - list the files in the archive
  v - verbose format
  f Saves/AntFoodEA-050208-0728.jar  -- the archive file to use

The first column show file sizes, then is the date/time of last change.

Suppose you want to recover one files from a particular jar file,
so you can compare it to the current contents of that same file.
One way to do this:

0. Make sure you are in your project directory 
   (the one that contains src/ classes/ Saves/ and so on).

1. See what archives you have:
      ll Saves
   Suppose you have:
      35599 Feb  8 07:28 AntFoodEA-050208-0728.jar
      37233 Feb  8 07:52 AntFoodEA-050208-0752.jar
   and you want to extract files from the second one.

1. Create a directory into which you can un-archive your file(s):
      mkdir AntFoodEA-050208-0752
   You can name that directory anything you want, but i find it is
   useful to name it with the name-date-time part of the archive file.

2. cd into that new directory, and extract the files from the archive:

      cd AntFoodEA-050208-0752
      jar xvf ../Saves/AntFoodEA-050208-0752.jar

3. You can use the ll command to see what was extracted:

      ll
      ll src/AntFoodEA

   and so on.

4. Compare the extracted Bug.java file to the one in your
   current directory.  Recall, your current version is in the directory
   "above" (..) from the directory with the extract (AntFoodEA-050208-0752).
   So you can do this to compare the extract to the current:

      diff src/AntFoodEA/Bug.java  ../src/AntFoodEA/Bug.java

   You will see a listing of differences between the files like this:

       59a60,61
       >               // here is the new line!!
       >

   Basically it says that the current file has the new lines shown there
   added after line 59.
   Do "man diff" to see all the details about using the diff command.
  
Note you can also just extract single files from the archive, if you 
just want to look at one file from a previous version.  For example
in this case we could have used this command in step #2 above:

    jar xvf ../Saves/AntFoodEA-050208-0752.jar src/AntFoodEA/Bug.java

The output from that command would look like this:

   created: src/
   created: src/AntFoodEA/
  inflated: src/AntFoodEA/Bug.java

indicating that that one file was extracted, and that the path
of directories down to it was created as well.

You can read more about the jar command with
   man jar

-----------------------------------------------------------------------------

How do you control what gets saved by the "save" option in the build.xml?

If you edit the build.xml file, you will find lines like these:

<target name="save"
 depends="getDate, getTime"
 description="create a save jar in ${saveDir}/${projectName}-${today}-${timenow}.jar">
    <jar jarfile="${saveDir}/${projectName}-${today}-${timenow}.jar"
    basedir="."
    includes="${srcDir}/**, dat/**, *.txt, build.xml"/>
 <echo message="The jarfile is in ${saveDir}/${projectName}-${today}-${timenow}.jar"/>
</target>

What gets saved is everything in the "basedir" that matches file patterns
specified int he includes= line.  In this case:

   basedir="."  -- i.e., the directory with the build.xml file in it

   includes= 
      ${srcDir}/**  save all files in ${srcDir} which is defined earlier in 
                    this build.xml file to be "src":
                      <property name="srcDir" value="src"/>
      dat/**        save all files in the dat/ directory
      *.txt         save all files in basedir (.) that end in ".txt" .
      build.xml     save the build.xml file itself

Thus you could have it save files that end in *.ctrl by changing the includes= 
line like this:

   includes="${srcDir}/**, dat/**, *.txt, *.ctrl, build.xml"/>
                                         ^^^^^^^^
where the ^^^ indicates the new part.

Note the ** means save every file in the named directory and recursively,
all files in subdirectories, etc.