SummerofCode2011 Timotei21

From The Battle for Wesnoth Wiki
Revision as of 15:03, 7 April 2011 by Timotei21 (talk | contribs) (add new details)


This page is related to Summer of Code 2011
See the list of Summer of Code 2011 Ideas



This is a Summer of Code 2011 student page
Project: SoC_Ideas_Eclipse_Plugin2011



Description

timotei - Improving the Eclipse Plugin

I aim at improving the plugin, so it will become the tool used by all UMC Authors.

Contacts

IRC

timotei, timotei21

Other

Forum: timotei
gna.org: timotei

SoC Application

Battle for Wesnoth - Google Summer of Code Application

Proposal Summary

Page Last Updated: 05 April 2011

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

Multiple Wesnoth installations

Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin. For that, there will be a new preferences page. The page will look something like this: installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking wesnoth --version). The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project.

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

  1. Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
  2. Default automatically to the current plugin's default installation.
  3. "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.


Enhance the Content Assist(CA) feature

The CA framework is very extensible but it lacks proper contexts for providing the content. I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the schema.cfg the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

Project files dependecy tree

In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project file tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers

This tree will be (re)built in 2 situations:

  1. A file is added/removed/changed it's name
  2. A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:

  1. files are processed in the alphabetically order
  2. _initial.cfg is the first processed before anything else.
  3. _final.cfg is the last processed after anything else.
  4. if there is a _main.cfg in the directory, it is the only one processed.

Since the current WesnothProjectBuilder doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely get_files_from_in_dir() found in src/filesystem.cpp:93.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Content Assist Config(CAC) Files

The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

  • The cac/variables.txt will contain variables available. The list is currently available at [1]. For example the file could look like:
$side_number
$turn_number
...
  • The cac/events.txt will contain the game events. The list is availabe at: [2]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.

Variables

The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:

{VARIABLE var_name "value"}

or the [set_variable] tag:

[set_variable]
	name=my_var
	value="value"
[/set_variable]

The ConfigFile class in the org.wesnoth.wml.core already has a list of variables. The Variable class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers. When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the Variable class needs to be extended, so it can represent the scope aswell.

//TODO: detail about: scoping for same vars name, expanded macros that use variables, getting the original line in the file -> maybe use a custom parser?

Events

Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the name attribute of the [event] tag.

Attributes

All attributes are currently got from the schema.cfg

Attributes Values

Macros

The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared.

Support for custom luaWML tags

The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the schema.cfg. The lua will be easily parsed, since there is a simple pattern for creating new tags:

wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the wml-tags.lua from the data/lua uses:

local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an optional enhancement, I could also search that function to see if it needs/has some extra attributes. //TODO: find a pattern for this.

Automatic/headless building

The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

More info at:

Standalone app auto-update

The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

Documentation

The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:

  • Prerequisites and Installing the prerequisites
  • Installing the plugin / standalone version
  • Using the plugin
  • Plugin features
  • Step-by-step use cases
    • Setupping the workspace
    • Creating a new project and running it in the game
    • Importing existing projects
    • Using the WML Editor
    • Updating the plugin
  • Frequently Asked Questions

The developer manual will contain:

  • Prerequisites and Installing the prerequisites
  • Adding the plugin's projects in the
  • Compiling and Running the plugin
  • Deploying the plugin and standalone app

Other ideas

Addons management

There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from data/tools/wesnoth_addon_manager, like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.

File Templates

- new file/projects templates management -> download from webserver? <_use apache velocity

Unit testing

Grammar

For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

//TODO: Grammar: don't allow empty keys

Parsing and getting information from files

I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:

scenario name
campaign name
next_scenario
first_scenario
variables
macros

Timeline

The GSOC period is between 24th May and 20th August. But since I have exams for about 3 weeks (during 31.05-20.06.2010), I will start working on the plugin before the 24th of May. The timeline will be written as the coding starts on 23 May.

Here is a table with key periods of the time spend on this project.

Period Actions
23 May Work starts
23 May - 3 June Add Support for multiple installations
4 June - 11 June Allow headless build of the plugin
12 June - 19 June Add the auto-update feature for the standalone app
20 June - 25 June Create the documentation
26 June - 17 July Enhance Content Assist
15 July Mid-term evaluations deadline
18 July - 25 July Addons management view
26 July - 2 August Unit testing
15 August Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
22 August Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.

Tasks

This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

Project part Details Status (Legend: None, Done, Not done, In Progress)
Multiple installations Implement the preferences pages None
Multiple installations Implement the logic for saving and loading the installations's paths on the disk None
Multiple installations Implement the project preferences page None
Multiple installations Rewrite the current mechanisms that use the paths to use the ones based on the project. None
Headless build Research about what system to use for automatic building of the plugin None
Headless build Implement the chosen system for the wesnoth plugin None
Auto-update Implement the auto-update feature. None
Documentation Write the User Manual None
Documentation Write the Developer Manual None
Enhance Content Assist Project dependency tree None
Enhance Content Assist Content assist files None
Enhance Content Assist Variables None
Enhance Content Assist Events None
Enhance Content Assist Lua tags None
Enhance Content Assist Lua tags attributes None
Addon management Create the GUI of the view None
Addon management Create the view's logic None
Unit testing Tests for the grammar None
Unit testing Tests for parsing the config files None
None

Questionnaire

The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire