eclipse plugin: Document the last build changes

This commit is contained in:
Timotei Dolean 2011-08-04 19:07:16 +00:00
parent bad5d3db18
commit d6822b1d06

View file

@ -1,174 +1,174 @@
\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.feature". \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" ( 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 scripts - those build 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 There are 2 files that are important: \textbf{build.sh} - For UNIX systems - and \textbf{build.cmd} - For Windows systems.
\item Both files need a one argument that specifies the path to a valid Eclipse + deltapack installation. The file you have previously downloaded contains this.
\item You can invoke the script with the 1st parameter as the path to the location where you have extracted the archive.
\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}
\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.feature". \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" ( 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}