README for Esmska
=================

Esmska is a program for sending SMS over the Internet.

Program links:
Esmska homepage . . . . . . http://esmska.googlecode.com/
Documentation . . . . . . . http://code.google.com/p/esmska/w/list
Issues. . . . . . . . . . . http://code.google.com/p/esmska/wiki/Issues
Forums. . . . . . . . . . . https://answers.launchpad.net/esmska
Translations. . . . . . . . https://translations.launchpad.net/esmska
Source code . . . . . . . . https://github.com/kparal/esmska

Program files:
README          - This file.
gateways/       - Script files for using operator gateways.
include/        - Files included in the binary distribution.
installjammer/  - Configuration files for InstallJammer.
launch4j/       - Configuration files for Launch4J.
lib/            - Program compilation and runtime libraries.
nbproject/      - Project files for the NetBeans IDE.
po/             - Localization files.
portable/       - Files for creating portable package.
resources/      - Different resource files.
scripts/        - Various scripts for managing building process.
src/            - Program sources.

Program license is GNU AGPL v3+, see include/license/ for more details.

Project root directory can be opened by NetBeans IDE as its project.


Getting program
===============

Check out Esmska repository:

 $ git clone git://github.com/kparal/esmska.git

By default you'll see the main development branch ('master'). You can switch
to any other branch or tagged version by using:

 $ git branch               # lists all branches
 $ git tag                  # lists all tags
 $ git checkout BRANCH|TAG


Compilation requirements
========================

 * Java 6 JDK (Sun tested)
 * Ant
   o in Ubuntu packaged as 'ant'

Provided by lib/ directory:
 * CopyLibs
   o included in NetBeans IDE 7.0
 * Mac UI
   o included in Apple Java
   o optional: see compiling section for information how to build without Mac OS
     support
 * all runtime requirements


Runtime requirements
====================

 * Java 6 JRE (Sun and OpenJDK tested)

Provided by lib/ directory:
 * Android vCard 1.2
   o http://code.google.com/p/android-vcard/
 * Apache Commons BeanUtils 1.8.3
   o http://commons.apache.org/beanutils/
 * Apache Commons CLI 1.2
   o http://commons.apache.org/cli/
 * Apache Commons Codec 1.3
   o http://commons.apache.org/codec/
 * Apache Commons Collections 3.2.1
   o http://commons.apache.org/collections/
 * Apache Commons HttpClient 3.1
   o http://hc.apache.org/httpclient-3.x/
 * Apache Commons IO 1.4
   o http://commons.apache.org/io/
 * Apache Commons Lang 2.6
   o http://commons.apache.org/lang/
 * Apache Commons Logging 1.1.1
   o http://commons.apache.org/logging/
 * Beans Binding 1.2.1
   o https://beansbinding.dev.java.net/
 * EZMorph 1.0.6
   o http://ezmorph.sourceforge.net/
 * JavaCSV 2.0
   o https://sourceforge.net/projects/javacsv/
 * Javascript Engine
   o js-engine.jar
   o https://scripting.dev.java.net/
 * JGoodies Looks 2.1.4
   o http://www.jgoodies.com/freeware/looks/
 * JSON-lib 2.4-jdk15
   o http://json-lib.sourceforge.net/
 * Mozilla Rhino 1.7R1
   o http://www.mozilla.org/rhino/
 * OpenIDE libraries:
   o org-openide-awt.jar
   o org-openide-util.jar
   o http://platform.netbeans.org/
   o included in NetBeans IDE 6.1
 * Substance 6.1
   o https://substance.dev.java.net/
 * Substance Extras 6.0
   o https://substance-extras.dev.java.net/
 * Substance SwingX 6.0
   o https://substance-swingx.dev.java.net/
 * Trident 1.3
   o http://kenai.com/projects/trident/

If you wish to use other libraries than the ones provided in lib/ directory
(e.g. package maintainers may want this) you can specify classpaths to
individual libraries in file lib/nblibraries.properties. Variables ending with
'.classpath' will be of interest to you.


Compiling program
=================

In sources root directory (where build.xml is located) run this command:

 $ ant clean jar

If you want to build the program without Mac OS support (for example Linux
package maintainers not willing to use Apple library), use command:

 $ ant -DnoMac=true clean jar

All the sources should be compiled in the build/ directory. In the dist/
directory the resulting esmska.jar should be created, together with all needed
libraries, available gateways and some additional files copied from include/
directory.


Running program
===============

After compiling you can run Esmska by command:

 $ ./dist/esmska.sh

or

 $ ant run

from the sources root directory.


Packaging program
=================

You can run command:

 $ ./scripts/create-package NAME

to obtain binary program packages inside the program root directory.

When creating custom packages it may be good to note that the only important
files for the program are esmska.jar, esmska.conf, lib/ and gateways/
directory. All other files are intended only for the end-user and the program
does not use them.

Package maintainer should be interested in resources/ directory. It contains
many files useful for making packages. Especially an always up-to-date
esmska.desktop file should be used, because it contains localized menu item
translations.

You should also see the esmska.conf file, which is a system-wide configuration
file. You can set some default configuration there (like turning off update
notification for example, when you are distributing program through linux
repositories).


Working with translations
=========================

Program uses src/esmska/resources/l10n*.properties files for localization.
There are gettext files in the po/ directory for simplifying user contributions.
By running command:

 $ ./scripts/update-translations

a new po/esmska.pot template is generated, all PO message catalogs are updated
and localized properties files are generated from them.


Creating Java WebStart package
==============================

First of all it is necessary to create a digital key to sign the jars. By using
'keytool' command create a keystore file with a key alias:

 $ keytool -genkeypair -keystore KEYSTORE -alias ALIAS -validity DAYS

Edit file nbproject/project.properties and set variables 'jnlp.signjar.keystore'
and 'jnlp.signjar.alias' to determine path to your keystore and your key alias.

The key password can be placed into file nbproject/private/private.properties as
a line 'jnlp.signjar.storepass=PASSWORD'. This way it will not be necessary to
type password everytime you build it. It supposes that keystore and key have the
same password.

Now open the project in NetBeans IDE and run the 'javaws' task. It is not
possible to build WebStart package on the command-line without using NetBeans.