Open eCard

h1. Getting Started

This guide will give you a short briefing of how to get your development environment up and running within a few minutes.

h2. Basic Setup

For the basic setup of your development environment you need to obtain the following tools and programs:

* The "Java Development Kit":http://www.oracle.com/technetwork/java/javase/downloads/index.html (JDK) version 7 or higher

* A text editor or an IDE

* "Maven":http://maven.apache.org/ version 3.0.5 or higher

* "Git":http://git-scm.com/

* Optional the Android SDK if you want to help developing the Android client

Since the setup process of the development environment is dependent on the operating system used, you will find the instructions for different systems (Windows, OS X and Linux) below.

h3. Windows

# Download and install the "Java Development Kit":http://www.oracle.com/technetwork/java/javase/downloads/index.html

Version 7 of the JDK is sufficient, but we strongly recommend to use the most recent version.

# Get an editor or an IDE of your choice and install it

Good IDEs for Java development are "NetBeans":http://www.netbeans.org/ and "Eclipse":http://www.eclipse.org/. If you prefer a pure text editor, "Notepad++":http://notepad-plus-plus.org/ is worth trying.

# Download and install the most recent version of "Maven":http://maven.apache.org/

# Download "Git":http://git-scm.com/.

There are different options available in order to use Git on Windows:

* "Git Extensions":http://gitextensions.github.io/

Git Extensions is a graphical user interface for Git, that comes with Windows Explorer integration. It is based on "MSysGit":http://msysgit.github.io/. Our recommendation for Windows users.

* "TortoiseGit":https://tortoisegit.org

TortoiseGit is a port of TortoiseSVN. For those familiar with TortoiseSVN, TortoiseGit is worth trying. It requires "MSysGit":http://msysgit.github.io/.

* "MSysGit":http://msysgit.github.io/

Git on the command line.

You are done!

h3. OS X

# Download and install the "Java Development Kit":http://www.oracle.com/technetwork/java/javase/downloads/index.html

Version 7 of the JDK is sufficient, but we strongly recommend to use the most recent version.

# Get an editor or an IDE of your choice and install it.

Good IDEs for Java development are "NetBeans":http://www.netbeans.org/ and "Eclipse":http://www.eclipse.org/.

# Download and install Git and Maven. We recommend to use "homebrew":http://homebrew.sh to install the latest version of both. Note: you probably have to adjust your PATH variable if you have already installed a version from the AppStore.

You are done!

h3. Linux

On Linux you can use your system's package manager to install all required tools and programs. Below you will find the commands to do so, based on "aptitude":http://packages.debian.org/aptitude, a front-end for "Debian's":http://www.debian.org "Advanced Package Tool":http://wiki.debian.org/Apt (APT).

# Install "OpenJDK":http://openjdk.java.net/

OpenJDK 7: @sudo aptitude install openjdk-7-jdk@

OpenJDK 8: @sudo aptitude install openjdk-8-jdk@

If you prefer the Oracle JDK, you have to download and install it manually. You can get it from "here":http://www.oracle.com/technetwork/java/javase/downloads/index.html.

# Install an editor or an IDE of your choice

If you want to use a plain text editor, we recommend "Emacs":https://www.gnu.org/software/emacs/: @sudo aptitude install emacs@

"NetBeans":http://www.netbeans.org/: @sudo aptitude install netbeans@

"Eclipse":http://www.eclipse.org: @sudo aptitude install eclipse@

*Note:* If you want to use the most recent version of "NetBeans":http://www.netbeans.org/ or "Eclipse":http://www.eclipse.org, which is recommended, you should obtain the installer packages from the official websites and perform a manual installation.

# Install "Maven":http://maven.apache.org/

@sudo aptitude install maven@

# Install "Git":http://git-scm.com/

@sudo aptitude install git@

You are done!

h2. Configuration

In order to get started with the development we need the code to work with. The public repository with the source code is located at https://github.com/ecsec/open-ecard which needs to be cloned. How to clone a repository depends on the git integration in the used IDE or editor. The general process on the command line is as follows and should be the same on all platforms.

# Clone the repository

@git clone https://github.com/ecsec/open-ecard.git@

# Switch into the source directory

@cd open-ecard@

# Initialize and clone the BouncyCastle submodule 

@git submodule update --init@

You may now open the project in your preferred IDE or editor and start developing but be sure to have read the necessary documents regarding the development and contributions to the project.

h2. Further Reading

This section contains a collection of links to topics which are also relevant for the development process.

* [[code-style|Code Style Guideline]]: Information about code formatting, Javadoc creation.

* [[Repository Guidelines]]: Detailed information about the repository, their usage and commit rules.