\documentclass[10pt]{article}
\usepackage[top=1cm, bottom=1cm, left=1cm, right=1cm]{geometry}
\usepackage{graphicx}
\usepackage{multicol}
\usepackage[colorlinks=true]{hyperref}
\usepackage{verbatim}
\usepackage{enumerate}
\usepackage{wrapfig}

\title{Wesnoth UMC Development \\ Developer's Manual}
\author{Timotei Dolean - \href{mailto:timotei21@gmail.com}{timotei21@gmail.com}}

\begin{document}

\maketitle

\tableofcontents
\setcounter{tocdepth}{3}
\newpage

\newcounter{cnt}
\newcommand{\icnt}{ \stepcounter{cnt} \thecnt }

\section{Foreword}
\begin{multicols}{2}
  \begin{center}
    \includegraphics[scale=0.6]{definitions.png}
  \end{center}

The plugin has its homepage at: \href{http://eclipse.wesnoth.org/}{http://eclipse.wesnoth.org/} \\


Through this readme the following terms with the specified meaning will be used:
\begin{enumerate}
\item Navigator / Project Explorer / Package Explorer - an Eclipse view that shows the projects in the workspace
\item Project - a directory on the harddrive that is represented as a top directory in the navigator.
\item Container - this is a directory or a project. Basically it can contain any file or directory children.
\end{enumerate}

The following image will highlight the terms used: 1 - Navigator, 2 - Project, 3 - Containers, 4 - Map files, 5 - Config files that contain WML code
\end{multicols}

\section{Prerequisites}
A quick list before getting into details:
\begin{enumerate}
\item Java 6
\item Python 2.x
\item Eclipse 3.7 ( Indigo ) or newer
\item Wesnoth 1.9.x, trunk or newer
\end{enumerate}

Now for getting all those items:
\begin{enumerate}
\item The plugin runs on the following platforms: Windows 32/64 bit, Linux 32/64 bit and Mac OSX 64bit. Note that \textbf{Mac OSX 32 bit} is \textbf{not supported}. If you want to know why, please consult the Frequently Asked Questions section.
\item Download and install Oracle/Sun's Java Version 6 (Java SE6): \href{http://java.sun.com/javase/downloads/widget/jdk6.jsp}{Download JDK}

\textit{Note:} The plugin uses Java SE6, thus older versions (like 1.4 or 1.5) don't work with it.\\
\textit{Note:} Please double check the java installed on your system. On some machines there is the OpenJDK or other Java versions. Just use Oracle/Sun's so there will be no problems.

\item Download and install Python 2.x:
 \begin{enumerate}
   \item \textbf{Windows:} Download and install from here: \href{http://python.org/download/}{Download Python} , selecting a 2.x version
   \item \textbf{Linux:} Use the regular package manager for installing it from the repositories.
   \item \textbf{Mac:} Download and install from here: \href{http://python.org/download/}{Download Python} , selecting a 2.x version
   \item Check the guide over here: \href{http://wiki.python.org/moin/BeginnersGuide/Download}{Python Download and install}
  \end{enumerate}
 \textit{Note:} Please ensure you install the 2.x versions. Versions 3.x are \textbf{not} yet supported by the Wesnoth's WML Tools.

\item Download ``Eclipse" (The download links are in the right. Please ensure you are downloading at least the \textbf{3.7} version, otherwise the plugin will not work. Also, \textbf{don't} download a \textbf{64 bit version} unless you are sure you have Java JDK on 64 bit. If you are unsure, select the 32 bit version):  \href{http://eclipse.org/downloads/packages/eclipse-rcp-and-rap-developers/indigor}{Download Eclipse for RCP and RAP Developers}

\item Extract the downloaded archive in a known location and launch the executable (eclipse / eclipse.exe)

\item You will need to have a wesnoth version 1.9.x, trunk or newer, in order for the plugin's features to correctly work.
\end{enumerate}

\section{Setup the environment}
After you got all the prerequisites, you need to setup the eclipse installation.

\begin{enumerate}
\item Open up the ``Install new software" menu, and select from the list: ``Indigo - http://download.eclipse.org/releases/indigo"

\item In the list populated with items, select from the ``Modelling" category: ``Xtext SDK", and install it. Restart eclipse after that.

\item For the plugin's source, checkout the folder ``umc\_dev" from the following SVN url: http://svn.gna.org/svn/wesnoth/trunk/utils/.

\item In Eclipse, right click in \textbf{Package Explorer/Navigator} and then select \textbf{Import - General - Existing projects into Workspace}

\item Select the path where you downloaded the ``umc\_dev" folder, and check all the projects: ``org.wesnoth", ``org.wesnoth.ui", ``org.wesnoth.tests". \textbf{Don't} check the "Copy projects into workspace.

\item The projects will be compiled automatically. Just to be sure, as in each Java project, verify that the ``Build automatically" entry in the ``Project" menu is checked.
\end{enumerate}

\section{Running the plugin}
After you've setup the environment you can run the plugin.
\begin{enumerate}
	\item Go into the ``org.wesnoth" project.
	\item Select the ``plugin.xml" file, and double-click to open it.
	\item Click the ``Launch an Eclipse application" or ``Launch an Eclipse application in Debug mode" from the right part of the file, to launch the plugin.
\end{enumerate}
\begin{center}
	\includegraphics[scale=0.6]{launch_plugin.png}
\end{center}

If you want to know how you can use the plugin, please consult the User's Manual.

\section{Running the tests}
The plugin has a Test Suite based on JUnit 4, that tests some aspects of it. To run the tests follow the following steps:
\begin{enumerate}
	\item Go to the ``Run" menu, and select ``Run configurations..."
	\item In the left pane's list, right click on the ``JUnit" item
	\item Select ``New" from the opened context menu
	\item Select the first radio box: ``Run a single test"
	\item For the \textbf{Project}, enter: ``org.wesnoth.tests" ( or browse for it )
	\item For the \textbf{Test Class}, enter: ``org.wesnoth.tests.WMLTestsSuite" ( or ``Search..." for it. Just enter ``WMLTestsSuite" in the newly opened window, and select the item )
	\item For the \textbf{Test method}, let it as it is by default: ``(all methods)"
	\item In the ``Test runner" Combo Box select ``Junit 4"
	\item Go to the ``Arguments" tab, and in the ``VM Arguments" textbox, enter: $-DwesnothDataDir=<path>$
	\item Replace the $<path>$ portion with the current path to the wesnoth data directory
	\item Press ``Apply" and ``Run"
\end{enumerate}

\textit{Note:} You can always launch last runned configuration with F11 - Debug / CTRL+F11 - Run. Alternatively, you can launch them by clicking near the green bug/run icon, on the little down arrow, and selecting the run configuration.

\section{Building the plugin}
The plugin can be built as a zip archive (usually) for different operating systems. The built application can be launched without any Eclipse prerequisites. This plugin's version is called \textbf{Standalone}. To build the plugin, you need to follow the specified steps:

\begin{enumerate}
  \item Download the ``eclipse\_3.7.zip" archive, that contains an already existing eclipse installation and deltapack (used for building against other OSes than the native one). The link for the download is: \href{http://sourceforge.net/projects/wesnoth/files/wesnoth-umcplugin/build\_utils/eclipse\_3.7.zip/download}{Download}

  \item Extract the archive in the favorite location

  \item You now have 2 choices: Build the plugin from within Eclipse - this way you can build, say, just for your current OS/architecture - or you can use the already existing build script - that builds the plugin for all currently supported architectures.

  \item If you want to build the plugin from within Eclipse, you need to do the following steps:
  \begin{enumerate}
    \item Open Eclipse.
    \item Go to menu: Window -$>$ Preferences-$>$ Plug-in Development-$>$ Target Platform
    \item Select the \textbf{Running Platform (Active)} item and press ``Edit..." in the left buttons lane.
    \item A new window with tabs will be opened. Select the ``Locations" tab, and in the right buttons lane, select ``Add..."
    \item Select ``Directory" in the new windows, then press Next.
    \item Browse to the previous location where you have extracted the ``eclipse\_3.7.zip" archive.
    \item Press Finish and Ok until you exist all windows.
    \item Now, go into the ``org.wesnoth" project, and open the file ``org.wesnoth.product".
    \item In the bottom right part of the opened file, in section ``Exporting" there is a link: ``Eclipse Product export wizard". Click that.
    \item In the ``destination" group, select where you want the export/build to be done.
    \item Check the ``Generate metadata repository". You can also check ``Export for multiple platforms" if you want to build the plugin for other OSes/Architectures aswell.
    \item Press Next if you have selected ``Export for multiple platforms" and select the desired OSes/Architectures.
    \item Finally press ``Finish" to do the building.
  \end{enumerate}

  \item If you want to build the plugin using the scripts, do the following:
  \begin{enumerate}
    \item Go to the ``build" directory in the checked-out directory from the SVN.
    \item The build is done via Scons.
    \item When launching the build first time you need to specify the ``eclipsedir" argument that specifies the path to a valid Eclipse + deltapack installation. The file you have previously downloaded contains this.
    \item You can invoke the build like: \textit{scons  eclipsedir=/path/to/eclipsedir}. After the first run, the path is cached and you won't need to specify it anymore.
    \item The directory ``wesnoth\_umc\_dev" will contain now the built plugin as zip archives, while the ``update\_site" directory will contain the update site for the plugin.
  \end{enumerate}
\end{enumerate}

\section{Generating the WML Grammar}
The WML Editor uses the Xtext (\href{http://www.eclipse.org/Xtext/}{http://www.eclipse.org/Xtext/}) framework for getting the functionality an editor should have. The editor is based on the WML grammar defined in the ``org.wesnoth/src/org.wesnoth/WML.xtext" file.
The file is written in some EBNF variant (\href{http://www.eclipse.org/Xtext/documentation/2\_0\_0/020-grammar-language.php}{http://www.eclipse.org/Xtext/documentation/2\_0\_0/020-grammar-language.php} )

To (re-)generate the wml grammar, right click the ``org.wesnoth/src/org.wesnoth/GenerateWML.mwe2", and select ``Run as" and after that ``MWE2 Workflow". If this is your first time running the MWE2 Workflow, you'll be prompted to download the ANTLR generator jar file. Press (y) and that will continue.

\section{Frequently Asked Questions}
\subsection{Where can I submit any bugs found?}
Go over to Wesnoth's bug tracker: \href{https://gna.org/bugs/?func=additem&group=wesnoth&bug_group_id=116}{Add new bug}. Please be as specific as possible. Also, if you have any logs, please attach them.

\subsection{Why Mac OSX 32 bit is not supported?}
Apple decided to manage itself the versions that can run on each Mac version. Thus the modern Java SE6 version - which is used by the plugin - is not available on 32 bit Macs but on 64bit only. The 32bit Macs have just Java SE5 version available. Trying to port the plugin to the ``outdated" java version is not likely to be done, so please consider upgrading your OS.

\end{document}