Linux - Using Monodevelop

To develop with AgateLib on Linux, first you must have Mono installed. You can download Mono from the Mono-Project web site. This includes MonoDevelop, the C# IDE for Linux. Many Linux distributions include a version of mono in their repositories. Check with your distribution to see what package you need to install to get Mono and MonoDevelop. You also need Mono's WinForms implementation.

OpenSUSE 11.1: zypper install mono-complete

Download

Once you have a working copy of Mono, you should download AgateLib version 0.2.5 from the SourceForge site. Extract it to a folder, say ~/Agate.

Creating a Project

Note: These instructions were written for an older version of MonoDevelop. They should still be valid but there may be minor differences.

In MonoDevelop, create a new project (Shift+Ctrl+N) and name it TestAgate. You should be able to pick any language you like, but be sure to pick an Empty Project underneath it. Picking a language other than C# may make the instructions that follow a little different, so you may want to start with C# until you get familiar with how to setup a new project.

Setting the runtime

In order to use AgateLib effectively, you need to be using the .NET 2.0 stack. To make this change, look in the Solution window on the left hand side. There will be a tree there with Solution TestAgate and TestAgate under it. Expand them both. Right click the project (titled TestAgate) and choose Options. In the new window that comes up, underneath General there will be Runtime Options. Click that, and on the right hand side, make sure the runtime version to 2.0 and click Ok.

Adding AgateLib references

Once you have a new project created, look in the Solution window on the left hand side. so that you see the references folder. Right click that folder, and choose Edit References. Pick the tab that is titled .Net Assembly. At the top you will see a file browser. Pick the folder that you extracted AgateLib to, and select all DLL files there. Click Add and then OK to add the references to your project.

Adding Source Code

Now back in the Solution window, we need to add a source code file. Right click on your project (named TestAgate), go down to Add and choose New File.... MonoDevelop will give you several choices on what to add here. You want to click the General category on the left hand side, and then choose Empty File on the right hand side. Name this file TestAgate.cs and click New.

Copy and paste the following code into the TestAgate.cs file.

  1. using System;
  2. using System.Collections.Generic;
  3. using AgateLib;
  4. using AgateLib.DisplayLib;
  5. using AgateLib.Geometry;
  6.  
  7. namespace TestAgateLib
  8. {
  9.     class HelloWorldProgram
  10.     {
  11.         /// <summary>
  12.         /// The main entry point for the application.
  13.         /// </summary>
  14.         [STAThread]
  15.         static void Main(string[] args)
  16.         {
  17.             using (AgateSetup setup = new AgateSetup(args))
  18.             {
  19.                 // initialize AgateLib.
  20.                 setup.InitializeAll();
  21.  
  22.                 // if something bad happened, bail out.
  23.                 if (setup.WasCanceled)
  24.                     return;
  25.  
  26.                 // Create a window with resolution 640x480 and title "Hello World"
  27.                 DisplayWindow wind = DisplayWindow.CreateWindowed("Hello World", 640, 480);
  28.  
  29.                 // Run the program while the window is open.
  30.                 while (Display.CurrentWindow.IsClosed == false)
  31.                 {
  32.                     // Display.BeginFrame must be called at the start of every frame,
  33.                     // before rendering takes place.
  34.                     Display.BeginFrame();
  35.  
  36.                     // Clears the display to a nice color.
  37.                     Display.Clear(Color.DarkGreen);
  38.  
  39.                     // End frame must be called after all drawing is finished.
  40.                     Display.EndFrame();
  41.                    
  42.                     // KeepAlive processes events.
  43.                     Core.KeepAlive();
  44.                 }
  45.             }          
  46.         }
  47.     }
  48. }

Now build and run the application by pressing the F5 key. If you did everything right, then the application should crash with an unhandled exception! Unfortunately, there's one more important step, which should be handled by MonoDevelop but isn't.

== Copying DLL config files ==

If you look inside the directory where you extracted AgateLib (ie. ~/Agate), you should see a file OpenTK.OpenGL.dll.config and a Linux folder. The config file must be manually copied to the same directory as the executable that is produced by the Mono compiler. The Linux folder contains other files that components of AgateLib depend on that are specific to Linux. At the moment, this is only the FMOD library. To use FMOD, these files must also be copied to the same directory as your executable. So open up a terminal window and execute the following two commands:

cp ~/Agate/*.config ~/Projects/TestAgate/TestAgate/bin/Debug
cp ~/Agate/Linux/* ~/Projects/TestAgate/TestAgate/bin/Debug

Note: You may have to change the above lines depending on choices you made previously. If you changed the name of your project from TestAgate, you will have to use your project name. If you didn't choose to make a separate directory for the solution, the target directory structure will be something like ~/Projects/ProjectName/bin/Debug. Also, if you extracted AgateLib to a different directory than ~/Agate, you will need to change that.

Now if you go back to MonoDevelop and push F5 to build and run your project, you should have a window with a "Hello World" title with a green background. Congratulations, you have just written your first application using AgateLib!