Installing New Modules

When you want to add more functionality to your server you can install new custom modules. Differences in server versions often mean something will break in a module, compiling from source can help fix this.

C modules

Using Makefile fragments

This is probably the easiest way to get a new module compiling under linux. Let's call *.mk files "Makefile fragments". All the correct compiler flags and such are supplied for you since the Makefile fragments are in included into the main Makefile.

This example will demonstrate how to create a shared library example.so containing two modules moo and lala. Create a directory for your module as a subdirectory of src, the directory containing all the ASSS code.

$ cd asss-1.4.3/src
$ mkdir example

Place your source code moo.c and lala.c into this newly created directory. Then create a file called example.mk within that directory that looks like this:

example_mods = moo lala

$(eval $(call dl_template,example))

All *.mk files in any subdirectories will be included during compilation. Two fragments come in the contrib and turf directories of the ASSS package, which you might want to look at as examples.

Now before we can compile the module we need to update the "deps". Make sure you are in the src directory.

$ cd ..
$ pwd
asss-1.4.3/src
$ make deps
(some output here, some warnings can be safely ignored)

Finally we can compile it, this step will automatically install it to the bin directory:

$ make
(some output here)

The module specifier for the new modules will be example:moo and example:lala, for use in modules.conf or with ?insmod.

Using a custom Makefile

Sometimes you might want to create your own Makefile, if you need to use custom compilation options, or a different source file layout. Here is a very basic one (they can get very long).

# simple makefile

OUTFILE = somefile.so
MODULES = autoturret.o

CC = gcc -std=gnu99 -pipe
CFLAGS = -s -O2 -Wall

all: ${OUTFILE}

${OUTFILE}: ${MODULES}
	${CC} -fPIC -shared -o ${OUTFILE} ${MODULES}

install: ${OUTFILE}
	install ${OUTFILE} ../bin/${OUTFILE}

clean:
	rm -f ${OUTFILE} ${MODULES}

You can change the name of the resulting file with OUTFILE and add more modules on the MODULES line. Note: the indentation must be a tab and not a bunch of spaces.

To use a makefile one would type something like this:

$ make -f some.mk
$ make -f some.mk install

The -f switch tells make to use some.mk instead of the default which is 'Makefile'. Also two commands are used so you can spot any errors during compilation.

With Dev C++

This tutorial uses Dev C++ 4.9.9.2 ASSS 1.4.0 and Smong's nomysql module. Although it should work with all modules and a recent version of Dev C++.

Step 1

Load up Dev C++ and go to File, New, Project.

Step 2

Choose the DLL project and give the project a descriptive name. Note: the name of the project will also be the name of the final .dll file, more about that later. Make sure to select C Project.

Step 3

A) The DLL project comes with some template files. Remove them by right clicking on their tab and selecting close.

B) Click the icon of a document with a plus sign on it. This will open a dialog that lets you add files to the project. Here you can add the module's source files. For nomysql this is just nomysql.c. Also add util.c from from asss/src/main. You can download the ASSS source code from http://asss.yi.org/asss.

Step 4

Before compiling some include and library paths must be setup. Go to Project, Project Options from the menu bar.

Step 5

First add pthread.dll by going to the Parameters tab and clicking on Add Library or Object.

Step 6

You need to change the file type filter in the open file dialog to All Files (*.*). Then select pthread.dll (actual name may vary).

Step 7

Now add the following include directories:

• asss/src
• asss/src/include
• asss/windeps

These are needed so the compiler can find all the .h files that the module source requires.

Step 8

This part is optional. You may want to change the name of the output .dll file and you can do so from the Build Options tab. The default name for the output .dll file is the name you gave the project when you created it.

Step 9

Now click the compile button. It looks like four colored squares.

Step 10

If all goes well you should see this dialog. Congratulations on compiling your first module!

With Eclipse

See Installing New Modules with Eclipse for more details.

With MSVC

-write me-

By hand

You may need to execute the commands to compile from source, and then move the resulting .so file to the bin directory using install if running ASSS on Linux. If you are running ASSS on Windows and are updating a module you should shutdown the server before copying the .dll file to the bin directory.

Python modules

No compiling is necessary. Move the .py file to the bin directory. There may be 'softcoded' settings within the .py file, so examine any comments near the top of the file for instructions.

Configuring

It is a good idea to examine any documents that came with the module. There may be comments at the top of the source code and if you are unsure you can do a search on the file for 'cfg->Get', which will return all customisable settings this module reads.

$ grep 'cfg->Get' src/module.c
$ grep 'cfg.Get' bin/module.py

I suggest putting module settings in their own .conf file and include this from your arena.conf.

There may also be commands that you must set the permissions for. You can add new commands to the group files found in conf/groupdef.dir. Prefix cmd_ to the command to allow users to send the command publicly and privcmd_ for team and private targets.

Finally you must load the module. Either add an entry to conf/modules.conf or use ?insmod. Some modules are arena specific, in which case you must also add it to your arena.conf Modules:AttachModules setting or use ?attmod.

If you have any questions left chances are they have already been answered at the Module FAQ.