Developers introduction

Application Command Definitions
Testing your ACD file
Application template
Makefile changes
What next?

This document is intended as a simple guide to getting started as a developer using EMBOSS.

EMBOSS is a new package, and can seem difficult at first. If you follow these steps you will find it can be easy.

We start by assuming you want to write a new application. You will need to write the application source code, which will use the EMBOSS libraries, and you also need to add the application to EMBOSS.

Application Command Definitions

Strangely, you add the application to EMBOSS before you write any source code.

This is because EMBOSS can use the application command definition (ACD) file to test all the input for you, without any new source code.

ACD files live in the emboss/acd/ directory with a filename or appname.acd ("appname" is the name of your application).

You will find some files there already which you are welcome to use as templates for your own ACD file.

ACD files usually need:

appl: appname: Defines the application name. All ACD files start this way.
sequence: sequence [ param: 1 ]: This asks for a sequence as the first parameter on the command line.
outfile: outfile [param: 2 ]: This asks for an output file name as the second parameter on the command line.
int: weight [ ]: Allows an integer value to be specified by "-weight" on the command line. It will not be prompted for unless you add "required:Y", in which case you should add "prompt: 'prompt for the user'" as well.

There are other things you can specify too. All values can have defaults provided in the ACD file, and tests to make sure the values are reasonable. See the ACD documentation for more information.

Testing your ACD file

Now for the cunning part. EMBOSS has an application called acdc which can pretend to be any other application. You put acdc appname on the command line. It will read appname.acd and will read in any required data just as if the application itself was running. It will also test anything else you add on the command line.

Application template

When the ACD file is ready, which should not take long, you can start on the application code.

This lives in emboss/appname.c and to start with you will simply call the startup routines and pick up the values you defined in the ACD file.


#include "emboss.h"

AjPSeq seq;
AjPFile outfile;
int iweight;

int main (int argc, char * argv[]) {

  embInit ("appname", argc, argv);

  seq = ajAcdGetSeq ("sequence");
  outfile = ajAcdGetOutfile ("outfile");
  iweight = ajAcdGetInt ("weight");

  ajExit();

}

The "embInit" call is exactly what acdc was doing. It will read appname.acd and read everything you need from the command line or by prompting the user.

The next 3 lines pick up the sequence, output file and integer value in the suggested ACD file (you will have your own set of calls here).

Now you are ready to write your code. The sequence is in seq in an internal representation. You can use EMBOSS functions to work with this sequence, or convert it to a string and use the string functions, or convert it to a null-terminated C character string and use the C library functions and C pointers. It does not really matter which you choose.

All output will be written to outfile. You should use the EMBOSS output functions to do this, typically ajFmtPrintF which works just like C's "printf" except that it uses an AJAX file object (AjPFile) and has some extra format options like %S for AJAX strings (AjPStr).

Makefile changes

You can add a new application without to omuch difficulty.

Go to the emboss directory. Edit file Makefile.am and make two changes. Add appname to the list of applications in bin_PROGRAMS and add a new line:

appname_SOURCES = appname.c

Then cd back up to the top directory, and run ./configure which will magically update the makefiles for you. You can then use make to make EMBOSS with your new application.

What next?