View source for Installing New Modules with Eclipse

Creating your first module can often be an intimidating process when you don't exactly know what you're doing. The following tutorial will guide you step by step on how to create an ASSS module using the [http://www.eclipse.org/cdt/ CDT] (C/C++ Development Tools) Integrated Development Environment (IDE) for [http://www.eclipse.org/ Eclipse] on the Windows operating system. Users already familiar with [[Installing New Modules#With Dev C++|Dev-C++]] will note several similarities between the two. You can obtain the most recent version of Eclipse CDT [http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/galileor here]. (Note: you may also need to install MinGW, which can be downloaded from [http://sourceforge.net/projects/mingw/files/ here]. Choose ''Automated MinGW Installer'', then download ''MinGW-5.1.4.exe'')

== Step 1 ==
Once you have completely unpacked Eclipse, start up the program, and specify a workspace (a popup should automatically ask you for this). You can safely ignore the initial welcome screen and go straight to creating your first project. To do that, go to ''File'' > ''New'' > ''C Project''.

[[Image:Eclipse_01.png|300px]]

A new screen should now appear. Give your project a name, and then click the ''<u>N</u>ext'' button.

[[Image:Eclipse_02.png|300px]]

Deselect the ''Debug'' option, it isn't necessary for the following tutorial, and then press ''Finish''.

[[Image:Eclipse_03.png]]

Assuming everything went ok, your project should look something like this:

[[Image:Eclipse_04.png|300px]]

== Step 2 ==
[[Image:Eclipse_05.png|300px]]

The next step will be to create new files to add in your project. To do this, go into ''File'' > ''New'' > ''Source File''. A new window will now show up. From here, you can now give your source (.c) file a name. Press the ''Finish'' button once you're done.

[[Image:Eclipse_06.png|300px]]

If you don't already have a module in mind, copy and paste the following (as used throughout the rest of this tutorial):
<pre>
#include "asss.h"

//Interfaces
local Imodman *mm;
local Icmdman *cmd;
local Ichat *chat;

local void Shout(const char *command, const char *params, Player *p, const Target *target)
{
    chat->SendMessage(arena, "Hamburger!");
}

EXPORT int MM_hamburger(int action, Imodman *mm_, Arena *arena)
{
    if (action == MM_LOAD)
    {
        mm = mm_;

        chat = mm->GetInterface(I_CHAT, arena);
        cmd = mm->GetInterface(I_CMDMAN, arena);

        if (!chat || !cmd)
            return MM_FAIL;
        else
        {
            cmd->AddCommand("hamburger", ShoutHamburger, ALLARENAS, NONE);

            return MM_OK;
        }
    }
    else if (action == MM_UNLOAD)
    {
        cmd->RemoveCommand("hamburger", ShoutHamburger, ALLARENAS);

        mm->ReleaseInterface(cmd);
        mm->ReleaseInterface(chat);

        return MM_OK;
    }
    return MM_OK;
}
</pre>
[[Image:Eclipse_07.png|300px]]

You'll also need to add the file ''util.c'' into your project, which you can find in your ASSS folder under ''/src/main''. Either open util.c using an external program, or through Eclipse via ''File'' > ''Open File...'' Repeating the same process as from the beginning of Step 2, copy and paste the source of util.c into your project (keep the name the same).

[[Image:Eclipse_08.png|300px]]

== Step 3 ==
Even though you've created a project and added files, you're still not ready to build your module. You should notice that your main source file will be full of question marks; don't panic, this simply means that Eclipse isn't configured properly yet, and doesn't know what to do with your source. To configure your project, click on ''Project'' > ''Properties'' in the menu.

[[Image:Eclipse_09.png]]

Navigate your way under ''C/C++ Build'' > ''Settings''. And choose the tab named ''Tool Settings''.

[[Image:Eclipse_10.png]]

The first thing you want to do is add your include paths. As shown below, add the following directories under ''GCC C Compiler'' > ''Directories''. 
* asss/src
* asss/src/include
* asss/windeps

[[Image:Eclipse_11.png|300px]]

Without changing the page, navigate to ''MingGW C Linker'' > ''Miscellaneous''. You'll want to add the pthread.dll/pthreadGC2.dll file (actual name may vary), generally located in ASSS' ''/windeps'' folder.

[[Image:Eclipse_12.png|300px]]

Now click on the tab named ''Build Artifact''. The first thing you want to do is make sure you're creating a Shared Library file, and ''not'' an executable. Then, make sure that the artifact extension is '''dll'''. The latter two can be avoided if you already selected Shared Library at the beginning of [[#Step 1]]. You can also change the name of the name of your output file, and specify a prefix (though not necessary).

[[Image:Eclipse_13.png|300px]]

== Step 4 ==
Once you're all done, click on ''Apply'', then ''OK''. Your project should automatically build itself afterwards, but you can build and rebuild it at any time by clicking on the hammer button, or by going into ''Project'' > ''Build All''.

Eclipse may then give you several warnings and errors if you made a mistake somewhere. Revise the list of warnings and errors to see if there isn't something that you've forgotten (such as adding an #include), or a simple typo.

[[Image:Eclipse_14.png|300px]]

If you used the above example provided in [[#Step 2|Step 2]], you should obtain the following 3 errors and 1 warning:
<pre>
`NONE' undeclared (first use in this function)	hamburger.c	/hamburger	line 26
`ShoutHamburger' undeclared (first use in this function)	hamburger.c	/hamburger	line 26
`arena' undeclared (first use in this function)	hamburger.c	/hamburger	line 10
'Shout' defined but not used	hamburger.c	/hamburger	line 9
</pre>
These can be corrected by replacing ''NONE'' with ''NULL'', ''local void Shout(...'' with ''local void ShoutHamburger(...'', and ''arena'' with ''p''. As you familiarize yourself with both the C language and ASSS, it will be easier for you to understand your mistakes, and know how to fix them.

If everything is compiled properly, Eclipse should now say "Build complete for project X".

[[Image:Eclipse_15.png|300px]]

== Step 5 ==
Now that you've created your first module, you'll want to give it a test run in-game. Locate your dll file in your workspace under the folder ''projectname/Release''. Copy it, and paste in in your ASSS folder under ''/bin''. Now open the file named ''modules.conf'' located in your ''/conf'' folder. Scroll to the bottom of the page, and add a new line with the file name and entry point name (i.e. EXPORT int MM_'''hamburger''') as follows:
* FILENAME:MODULENAME  (e.g. hamburger:hamburger)

Make sure to save the file. If you've made a mistake in the name, then ASSS will close after you start it, as soon as it tries to load the non-existant or faulty module. Otherwise, you're now officially ready to give your module a spin!

In the hamburger example, you will also have to make one extra modification. Before starting ASSS, move over to the folder ''/conf/groupdef.dir''. Open up the file named ''Default'' (any text editor will do), and add the line ''cmd_hamburger''. This will now add the command ?hamburger. To test it, start up ASSS, and type ?hamburger in-game.

[[Category:Module]]
[[Category:Guides]]