Usage of emonic

Installation

There are two ways of installing Emonic: via an update site or via a download from Sourceforge.

Download via update site

Add one of the following update sites to your Eclipse update configuration (Menu: Help->Software updates->Find and Install)

AdressLocation
http://emonic.sourceforge.net/updatesite/internap/site.xmlSan Jose, CA - North America
http://emonic.sourceforge.net/updatesite/nchc/site.xmlTainan, Taiwan - Asia
http://emonic.sourceforge.net/updatesite/ovh/site.xmlParis, France - Europe

Download from Sourceforge

Alternativly, you can get the plug-in as a zip and simply unzip it:

  • get the plug-in as zip file from Sourceforge (the file named emonic_VERSION.zip)
  • copy it in the root folder of your Eclipse installation
  • unzip it

You may also want to investigate alternate methods described on this external website about managing your Eclipse environment.

Adapting the preferences of Emonic

There are 2 preference pages: One for the preferences of the c#-Editor and one for the build mechanism.

  • Select "preferences..." in the "Windows"-Menue
  • Open the Preference Page for the c#-editor or the build prefs
  • c#-Preferences:
    • Emonic can build new c#-files and correct indentation. In the emonic c#-edtor You use the tab to indent the code. Insert in "Editor: Tabspace" how many spaces the code source will be indented.
    • The emonic editor is able to make command completion. If You want to use it check the "Editor: Use completion"-Button
    • All possible completions which are not part of the c#-source-code You write have to be evaluated by the .net-reflection-mechanism. For this purpose emonic comes with a tool "emonicinformator". If You want to use this, enable "Editor: Use Completion with Emonic Informator" and set the field cli-explorer: informator command to the command to start the emonic informator. The default locaton of this tool is ECLIPSE_INSTDIR/plugins/org.emonic.base_VERSION/net/emonicinformator.exe. So for exemple, if You use eclipse with mono, have the Plug-In-Version 0.1.2 and Your ECLIPSE-Home is /usr/local/eclipse the command would be: mono /usr/local/eclipse/plugins/org.emonic.base_0.1.2/net/emonicinformator.exe
  • Build-Preferences:
    • If You want that emonic is able to build Your sources with nant add the command to start nant.

Work with .Net 2.0

You can use Emonic to work with the .NET 2.0 framework (either Mono or Microsoft .NET). NAnt's build mechanism allows you to choose which version the framework the build should use. Just select the desired one in the New .NET Project Creation wizard. As Ant does not have this ability, you will have to use NAnt for this projects.

To get the correct command line completions, use the emonic informator that is compiled against .NET 2.0, i.e. write in your Emonic preferences something like "mono /path/to/emonicinformator-2.0.exe".

Since .net-3.0 adds only some libraries to .net-2.0, this preferences should work for .net-3.0 as well as for .net 2.0.

Switching to the Emonic perspective

Emonic provides a perspective with the most relevant views (Navigator, outline, editor, problems). You can select it via "Window - Open Perspective - other".

Creating a new Emonic project

When You start to work, You will want to create a new emonic project. For this purpose You start the emonic-project-wizard under "new/project/New Emonic Project". The first page of the wizard allows you to set the name of the project, its source and output folders, and the build mechanism and settings. The second page determines what happens with newly generated sourcefiles (See Screen Shot ). It works close together with the C# Class/Interface Creation Wizards and keeps the settings which have to be made for all new generated C# files (the settings made in the C# Class/Interface Creation Wizards can vary from file to file).

  • In each file created via the wizards, the copyright comment will be inserted. If you don't want to have copyright statements in your files just leave this empty.
  • When you generate a C# file via the wizards, it will contain the namespace declaration set as the default namespace.
  • The files created with the wizards will be added to the build file
  • The project will be built via the mechanism selected in "Build mechanism":
    • Use "ant" if You want to use "ant" for compiling. 
      • Advantage of Ant: It comes with the Eclipse SDK so you have it on your machine
      • Take care: Some Linux distributions come with Ant packages which cannot handle the C# target
    • Use "nant" if You want to use "nant" for compiling.
      • Advantage of NAnt: Made for .net
      • Advantage of NAnt: faster than Ant
      • Advantage of NAnt: You can determine the compilation target (mono 1.0, mono-2.0, .net-1.0, .net-2.0 as a setting in the build file or as a parameter)
      • NAnt is NOT distributed with Emonic or with Eclipse. You have to download it from the NAnt homepage, install it separately and then configure it like in "Adapting preferences" described
    • Use "none" if you want to manage the build process yourself manually without tool support from Emonic.
  • After the creation of the project You can change these settings under "project/preferences/CodeGeneration"

The last page of the wizard is the standard eclipse project references page. Emonic does not use the results of at the moment. However, in a later version we can use this mechanism to allow the connection between various .NET projects (like: One project uses the result files of a other; since the projects are referenced, we copy the referenced files in the result dir of the project and set the .net-preferences..... but that is music of the future).

Adding C# files to the project

After you set up your project, you would want to add the source files of your program to the proejct. When you add a source file, you want to determine what happens to it at the time you build your project. For that reason, Emonic provides C# Class/Interface Creation Wizards. You find it under "File/New/other/.NET/New C# Class/Interface". You have to specify the name of the file and the container where it is saved. Ant and NAnt organize their work in "targets", simplified said to groups of Code-Files compiled together to one assembly. If You have existing targets where You can add the files You can do this via activating "Add the new file to the existing target" and selecting the name of that target. If You don't have a target yet You have to create a new:

  • Activate for this the check box "Insert new target"
  • Give the target a name in "Target name"
  • If Your compilation needs references to existing .net-assemblies add them in "References"
  • If You want to define something during the compilation, add this in "defines"
  • Set the warning level, the debug and the optimize switches to Your requirements
  • Choose what kind of target You want to create

Adding existing CSharp-Files to the build / removing c#-files from the build

Existing C#-files can be added to the build by the command "Add to build" and removed by "remove from build" file. This commands are available via the context menus of the package explorer, the navigator and the c#-editor. After choosing "add to build file" You get a dialog quite similar to the one of the "new C#-File" - wizard described in the former chapter. Look there how to handle it. In this way, You can also add the c#-file to more than one target. If You choose "remove from build" You get a dialog from which of the target You want to remove the file. Select the right one and press OK.


Editing C# files

The C# editor is configured to associate itself with any files with a .cs file extension. The editor provides support for:

  • Syntax highlighting.
  • Code completion: Press ctr-space to see possible completions relevant to the code that you are typing (might be a bit slow the first time). Check the preferences to enable it.   
  • Toggle comment: If you want to comment out a block of code, select the block in the editor and select "source->toggle comment" in the context menu or press 'Ctrl+/'
  • Correct indentation: To correct the indentation to the indentation deep selected in the preferences select the block You want to correct and select "source->Correct Indentation" in the context menu or press 'Ctrl+I'
  • Quick outline: Use 'Ctrl+O' to bring up an outline of the file you are currently editing.

The navigation in C# files is supported via the Outline View. Click a item in this view to jump to the definition of this item in the editor.


Manipulating the build process

Building the project

 Ensure that the emonic auto builder is switched on (See Auto Builder). If You have switched on "Project/Build automaticlly" a build is triggered each time You save a c#-file. If this switch isn't activated, You have to compile the project via "Project/build all" by hand. You can see the messages of the build in the "Console" - view If there are errors/warnings during the build, this messages are inserted in the "Problem" view and  marked with markers in the editor.

This sounds quite simple, but works only, if all components are set up right. So, what to do if this does not work? It is very important to understand how this plugin works: It adds the c#-files You created in the build file and compiles it via the commands You set up in "windows/preferences/emonicpreferences"

  • Check the build mechanism and build file You choose. You can find it under "Project/Properties/Code Generation". The buildfilename is in the next points referenced as "BUILDFILE".
  • Get the command for the chosen bild mechanism in "windows/preferences/emonicpreferences". Ths command is in the next points referenced as "CMD"
  • Check wether the project compiles via command line: Open a shell under Unix or a cmd-Window under windows and go to the project directory. Start the build by hand via "CMD -f BUILDFILE" for a ant build or "CMD -f:BUILDFILE" for nant. Look at the error messages You get.
  • Set up Your nant/ant so that they work. In the case of ant for example: Support for .net is only a "optional task". In the default distribution of ant  this task is activated by default. However, some linux distributions come with ant-versions with deactivated .net-support. You have to deinstall this version and install one with .net-support to get the build file translated. There might be more problems like shown in this example.... 
  • Check Your build file wether it looks like it should. Compare the syntax of the file to the syntax published at the documentation of ant or nant. Correct the syntax if necessary.

Running the application

You can run the applications via Run/Run.../.NET. To do so, you can:

  • Configure your runtime environment: Select Window/Preferences/.Net/Installed Frameworks. Add the framework(s) that you are using by specifying its installation directory. Hint for Mono users on a UNIX-based system: This is the PREFIX of the build, e.g. /usr or /usr/local.
  • Create a launch configuration under Run/Run.../.Net-Application
  • Start it