********* David Bergman - July 10th, 2006 **********
*						   *
* The purpose of this document is to demonstrate   *
* how to compile a program in Aszgard.             *
*						   *
* It is based on adding the file into the existing *
* suite of demos.  Once a method for creating a    *
* new suite and setting up that directory is       *
* established, a new text document will be written *
****************************************************



**********A newer way of compiling ****************
As of August 3rd, 2006, we have discovered a new method of compiling in aszgard.  This involves the /user folder.

1) The easiest way to compile a new .cpp file in aszgard would be to make a copy of the aszgard/user/szg-cubecake folder.  Name it foo and make the path aszgard/user/foo

2) Then go into foo/build/makefiles/ and edit Makefile.my_app.  Either make this your personalized makefile or feel free to just change all the reference to szg-cubecake to foo.  Don't forget to delete all of the OBJ dependencies if you don't actually need any of them.

3) Put your foo.cpp into /foo/src/

4) Go into foo/ and type make.  Provided it compiles properly, the executable will appear in /build/(your OS folder)/ as foo.exe.



***** The older way of doing things **********

For any existing .c/.cpp file that you wish to compile in Aszgard, you should folow these steps:

1) Add the source file (.c or .cpp) to aszgard\szg\src\demo\(program name)\
-  For instance, the path to atp.c would now be aszgard\szg\src\demo\atp\atp.c
-  This would also be the place to put any custom files that the program looks for.

2) Add the name of the program to the Makefile (located in:  aszgard\szg\build)

-  Find the two lines that say DEMODIRS = .... and DEMOFAST = ...
-  DEMODIRS is the list of programs that compile when you type make demo  (Slow since it compiles all programs).
-  DEMOFAST is the list of programs that compile when you type make fast  (faster since it only compiles a few programs).
-  I suggest adding your program to DEMOFAST while you are testing it and then adding it to DEMODIRS once it works.
-  The line currently looks like DEMOFAST=ribbons atlantis.  I suggest changing it to DEMOFAST = atp, if for instance, the name of your .c file is atp.c.
-  The way to add a program to compile with the rest of the suite would be changing "DEMODIRS=ribbons atlantis coaster hspace cosmos cubes parade schprel" to "DEMODIRS=ribbons atlantis coaster hspace cosmos cubes parade schprel atp" with atp appended to the end of the list.


3) Each new source will need its own make file.
-  These are located in aszgard/szg/build/make/demo
-  The naming convention of these make files are "Makefile.(program name)"
-  If you already use an existing make file for your program, copy it into this folder and rename it "Makefile.(program name)"
-  For instance, atp.c would be associated with Makefile.atp.
-  If you do not have a make file for your program, Makefile.cosmos is a generic one and should work for any single source file program by just replacing any instance of "cosmos" in Makefile.cosmos with (program name).
-  For instance, cosmos$(EXE): would be replaced with atp$(EXE):
-  There should be five instances that need to be replaced.

4) Each source file will need a pointer to its make file
-  These are located in aszgard/szg/build/linux
                        "               "/mips
                        "               "/win32             /demo/(name of program)
                        "               "/mips4
                        "               "/darwin

-  On windows machines, only the win32 directory is relavent.  So I will use that as an example.
-  aszgard/szg/build/win32/demo/(program name)/     needs to include:
a) a CVIGNORE file
  -  The CVIGNORE file can just be copied from any of the other programs' folders.
b) a Makefile
  -  The Makefile file can be copied from any of the other program's folders.
  -  However, the line "include ../../../make/demo/Makefile.cubes" needs to be changed to "include ../../../make/demo/Makefile.(program name)".
  -  For atp, for instance, this would be "include ../../../make/demo/Makefile.atp"



****************************************************
To compile in Aszgard, go to aszgard/szg/build.

-  type make fast  (provided you added the name of your program to DEMOFAST.  make demo if you added it to DEMODIRS)
-  fix any errors that show up in the compile log
-  type !(program name).
-  !atp, for instance, will launch ATP.