Home

alxndrsn edited this page Oct 7, 2011 · 17 revisions
Clone this wiki locally

Welcome to the Frontline SMS wiki. This wiki should contain helpful information for developers working with this code. If you are a user of the software and would like help, please go to the FrontlineSMS Community.

Introduction

FrontlineSMS is a desktop application for managing bulk SMS messaging. It is written in Java and the build and config is managed using Maven.

Getting Started

Core

To get set up with FrontlineSMS, please check the README attached to the FrontlineSMS Super Project.

Once you've checked out the super-project and its submodules, you may want to set up FrontlineSMS in an IDE.

Eclipse setup

Currently we develop on Windows 7, Ubuntu and OSX using Eclipse with the following plugins:

Once you have installed Eclipse with these plugins, create a new workspace pointing at the super-project's directory. For each submocule (e.g. core, dist), create a new Java Project in Eclipse and then enable Maven's dependency management for that project.

Plugins

Using other peoples

To make sure that a plugin is included with FrontlineSMS at runtime you must

  1. Make sure that the plugin is available on the classpath.
  2. Make sure that the PluginController implementation is listed in META-INF/frontlinesms/PluginControllers in your plugin's JAR.

Making your own

There is a plugin template available from https://github.com/frontlinesms/frontlinesms-plugin-template which should help you get started.

Internet SMS Services

The simplest way to implement your own SmsInternetService is to extend net.frontlinesms.messaging.sms.internet.AbstractSmsInternetService. The Clickatell and IntelliSMS services bundled with the core application may be useful examples. You must also remember to add the details of your SmsInternetService implementation to the META-INF/frontlinesms/SmsInternetServices file.

You can see examples for doing this in the FrontlineSMS source code, e.g.

Execution

To run FrontlineSMS, execute mvn exec:java in the dist project. To run FrontlineSMS with a plugin you are developing, execute mvn exec:java from within your plugin's directory.

Building

To build the project, you should run mvn package on the frontline-dist project. This will build create a zip containing all files needed to run FrontlineSMS from the command line with Java.

Platform Specific Builds

It is also possible to build FrontlineSMS bundles for specific platforms.

Windows

Make sure you

  • have Excelsior JET installed
  • are on the branch/tag you would like to build

And then call

mvn clean package jetpackager:jetbuild

We use JET 6.5. Unfortunately it requires a commercial licence - otherwise the build will expire after 30 days. Many thanks to the people at Excelsior for providing our licence.

OS X

mvn clean package osxappbundle:bundle

This should build a .dmg containing FrontlineSMS as a .app. You must be using a Mac running OS X for this command to work.

Maven

FrontlineSMS and its libraries use Maven to manage dependencies and builds.

What is a SNAPSHOT?

A SNAPSHOT is a work in progress - a non-specific set of code. When you want to deploy, you need to release your code as a specific (non-SNAPSHOT) version.

Deploying SNAPSHOTs is often undesirable because:

  • it's hard to fix bugs consistently
  • it's hard to migrate data to a new version

Releasing

Requirements

Before you can release you need to make sure

  • there are no SNAPSHOT dependencies in your pom.xml
  • you have commit rights to your source repository (SCM) (as specified in pom.xml)
  • you have upload rights to your maven repository (as specified in pom.xml)

Do it!

To release a version of a library, use the Maven release plugin. You will need the following commands:

mvn release:prepare

mvn release:perform

Repositories

FrontlineSMS Repository

You can find the FrontlineSMS Maven repository at http://dev.frontlinesms.com/m2repo/.

Old repository

FrontlineSMS previous hosted its Maven repository at cleone.net, and there may be some old references to this domain in dependency POMs. You can check your local maven repository for references using grep -i cleone ~/.m2/repository. If references exist, remove directories containing those references and add the following to ~/.m2/settings.xml:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
		xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
	...
	<mirrors>
		<mirror>
			<id>cleone.net.repo.replacement</id>
			<url>http://dev.frontlinesms.com/m2repo</url>
			<mirrorOf>cleone.net.repo</mirrorOf>
		</mirror>
	</mirrors>
	...
</settings>

Getting in Touch

For details of the mailing list, IRC etc. please go to the FrontlineSMS developers portal.