======================================
these instrunctions are for PC (as opposed to ie. Mac)
-------------------------
To get FactionsPlus from github into your Eclipse workspace:
------
Prerequisites:
- Eclipse for Java Developers or Eclipse SDK  ie. version 3.8.0
  ie. http://www.eclipse.org/downloads/packages/eclipse-ide-java-developers/junor
  unpack the zip somewhere then run 
  eclipse\eclipse.exe
  if you're being asked, select a workspace folder, inside it FactionsPlus project folder will be stored
  You may tick the use this as the default and do not ask again OR next time you start eclipse make sure you choose the same folder (it will be remembered automatically)
  Make sure you close the Welcome screen, or later after importing a project you won't see the Package Explorer view


- EGIT plugin for Eclipse (Help->Install New Software, Work with: All Available Sites, type filter text "egit" ...) this already exists in Eclipse Juno (4.2)
  to see if you have it, check if you have File->import, Git->Project From Git. If you don't then you have to install it (likely you're running Eclipse 3.x)

---
File->Import,  Git->Projects From Git, Next, URI, Next
fill in URI: with one of the following:
git://github.com/MarkehMe/FactionsPlus.git
https://github.com/MarkehMe/FactionsPlus.git
(for read-only access! if you're a dev with write access, log into github before you get the url from here:
 https://github.com/MarkehMe/FactionsPlus
)
Next, Next
Choose a location in your eclipse workspace under a folder named "FactionsPlus" (typically this means just Browse to
your eclipse workspace and click Save)
ie. Directory: C:\eclipse.workspace\FactionsPlus
or wherever else you want to store the git part
(If you name this anything other than FactionsPlus the automatic jar export script from later below won't work)
now copy this path to clipboard ie. Ctrl+D Ctrl+A then Ctrl+C
click Next, after the cloning is done (requires internet connection *doh* ) then
open explorer or Winkey+E
select the address/location  or Alt+D
paste the previously copied path ie. Ctrl+V
press Enter to go into that folder, 
you're now in the folder where you cloned the project

Copy some files from "dev_extras" into current folder:
   a) enter the "dev_extras" folder
   b) Ctrl+click aka select the following 3 folder/files: ".settings", ".classpath" and ".project"
      and Copy them (to clipboard) ie. Ctrl+C
   c) go into parent folder (the one you where before you entered "dev_extras") (ie. by pressing backspace key) and then press Ctrl+V aka Paste
   
you may close explorer, ie. Ctrl+W
then go back to the Cloning window in eclipse

ignore this in Eclipse Juno (aka 4.2), in Eclipse 3.8 you have to:
- Select Import existing projects
- Next,

Finish

You now have the project "[!] FactionsPlus [FactionsPlus master]" but it likely has a red "!" on it, because of missing required .jar files
======================================

In order to be able to compile this without errors in Eclipse, here's what you need:

------
A. jars needed (put them in the "lib" folder in the FactionsPlus project)
note: if "lib" doesn't exist(quite likely) just create it:
File->New->Folder
select FactionsPlus
type: lib
in the "Folder name:" field
Finish

1. bukkit.jar
    get one from here:
    http://dl.bukkit.org/downloads/bukkit/
    
    the jar name may vary so you might have to do one of the following(A is recommended):
    A) copy the downloaded .jar into 'lib' folder and then rename it to bukkit.jar
    OR
    B) copy the downloaded .jar into 'lib' folder as it is(or simply leave it where you downloaded it) 
    and then make sure the project points to it:
     -left click FactionsPlus project then right click, choose Properties, 
     -left click Java Build Path  then Libraries tab, click the "bukkit...jar" in list and Edit and 
     -choose the downloaded file, click Open, then Ok
     -then you may notice the other red [x] .jar files that you require in order to successfuly compile FactionsPlus, 
      but for now you may just press that Ok because you don't have to change those here, 
      just get those jars and place them in that `lib` folder ... see below.


2. DisguiseCraft.jar
   get the top one from here:
   http://dev.bukkit.org/server-mods/disguisecraft/files/
   v3.3 tested
   
3. MobDisguise.jar
    get top one from here:
    http://dev.bukkit.org/server-mods/mobdisguise/files/
    MobDisguise 1.81 tested
    
4. Vault.jar
    get top one from here:
    http://dev.bukkit.org/server-mods/vault/files/
    Vault 1.2.18 tested
    
5. WorldGuard.jar
    get second one (the .zip )from here (and extract the jar from it):
    http://dev.bukkit.org/server-mods/worldguard/files/
    WorldGuard 5.5.3 tested
    
6. WorldEdit.jar
    get the top .zip from here(and extract the jar from it):
    http://dev.bukkit.org/server-mods/worldedit/files/
    WorldEdit 5.4.2 tested

7. LWC.jar
   get the top one from here:
   http://dev.bukkit.org/server-mods/lwc/files/
   LWC 4.3.0 tested
   
8. Factions.jar
    get 1.6.9.1 (or any latest 1.6 version, actually now you may use 1.7 too, it won't err on compile):
    http://dev.bukkit.org/server-mods/factions/files/
    -make sure the file name is Factions.jar  (or modify the classpath yourself to point to it see step. 1)
    -use only one Factions.jar not both, or else you would never spot when you'll use a feature that
     exists in one version but doesn't in the other, ie. the field senderMustBeModerator exists in 1.6 but not in 1.7
     and using both jars would not err about this, and you cannot switch between the versions and spot this, unless ofc
     you'd remove the Factions 1.7 jar
    
9. Essentials.jar 
    http://dev.bukkit.org/server-mods/essentials/files/
    -tested with Essentials-Pre2.9.4.1
    -should be something like Essentials-2.9.3 OR Essentials-Pre2.9.4.1  definitely not Essentials 3 (if it exists)
    -get that zip (not the one with 'extra' in it's name), and unpack the Essentials.jar file into 'lib' folder;


After you put all the files in the lib folder don't forget to F5 aka refresh, in
eclipse on the project or the lib folder, else eclipse won't see them.

If you have all these, the FactionsPlus project should compile without errors.


======================================


To actually export the .jar file  which would be named FactionsPlus.jar
The following is the manual(unrecommended) cumbersome method(skip further below for the epic method):
------
Legend:
[ ] means deselected
[v] means selected
(*) radio button selected

left click the FactionsPlus project 
then right click on it or Alt+F  to open File menu
choose Export, Java->Jar file, Next, 
Expand FactionPlus, 
make sure only "src" folder is selected
click FactionsPlus
make sure only the following files are selected:
plugin.yml

now go below and ensure the options look like so:
[v] Export generated class files and resources
[ ] Export all output folders for checked projects
[v] (Optional)Export Java source files and resources(if you want to include sourcecode *.java files in the jar)
[ ] Export refactorings for checked projects.

Jar file: x:\XXX\FactionsPlus.jar
    where x:\XXX\ is your location like c:\dumps\

Options:
[v] Compress the contents of the JAR file
[v] Add directory entries
[v] Overwrite existing files without warning (Optional, up to you: it will not ask you if destination .jar exists already)

Next,
[ ] Export class files with compile errors
[v] Export class files with compile warnings

Next,
(*) Generate the manifest file
[ ] Save the manifest in the workspace

(*) Seal the JAR  (irrelevant)

leave empty at Main class:
Finish
--------------

This is how to export the .jar the "right" way (the simple epic method):
From within Eclipse, double click the file "fpexport_release_template.jardesc" which is under "dev_extras" folder. 
you shouldn't have to modify anything there, all the settings are right and if you just click Finish
it would create Factions.jar file inside the "built.jar" folder which resides in the project(you may have to F5 
aka Refresh to see it the first time)

Advanced epic method(by using the above simple epic method plus the following):
If you wanna go advanced, you can have build.jar folder symlink to the right folder you want the .jar to be exported into(useful if you compile the .jar frequently)
ie. go into shell and into the FactionsPlus folder then:
    make sure built.jar folder doesn't exist (ie. rmdir built.jar)
    mklink /d built.jar c:\craftbukkitserver\plugins\
    and every time you export now, the FactionsPlus.jar will be auto placed in the plugins of your running test server
    (this tested on Windows 7, on *nix would be similar, but on windows you likely need to have NTFS file system which you normally would anyway)

If you do want to modify the settings and keep them but only for you, then you can, go Next and tick the
"Save the description of this JAR in the workspace" but do not change the file name for it (because it's in .gitignore )
and this way, next time you will only have to double click your personalized file "fpexport_personalized.jardesc" when
you want to export, and everytime you change something inside it now it will be auto saved

Should you want to modify the fpexport_release_template.jardesc file to reflect changes for all the devs, then
run it once and set all the new settings and don't forget to enable the "Save the description of this JAR in the workspace"
but again do not change the output jardesc filename(then do Finish), this will export it to "fpexport_personalized.jardesc"
which you now have to edit it and make sure that:
saveDescription="false" 
inside the file(it's normally on true, and we don't want that - for obvious reasons)
 and then rename it and overwrite to fpexport_release_template.jardesc
and this is now detected and can be committed to the repository

===
To get the latest updates(get your source code up to date), then right click FactionsPlus 
then Team->Pull, when that's done then (re)export the .jar
If you made changes of your own, you might want to do Team->Fetch from upsteam and then Team->Merge, if there are any
conflicts you will have to resolve them before you can export the .jar
================

Caveats:
---1  (for users or devs)
Note: If you're getting these errors in bukkit:

[SEVERE] Could not load 'plugins\FactionsPlus.jar' in folder 'plugins'
org.bukkit.plugin.InvalidPluginException: java.lang.UnsupportedClassVersionError: 
markehme/factionsplus/FactionsPlus : Unsupported major.minor version 51.0

Caused by: java.lang.UnsupportedClassVersionError: markehme/factionsplus/FactionsPlus : 
Unsupported major.minor version 51.0

It just means, that your server is running in a JVM with a lower version that the compiled FactionsPlus.jar  
ie. your server running on jre6 and your jar was compiled with jre7 (well compiler compliance level (ccl) 1.7 to be 
more exact)

Fix:
1. either run the server in jre7
2. or recompile FactionsPlus.jar with jre6 (which automatically means it'll use 1.6 ccl)

(we do already have the project set to ccl 1.6 at the time of this writing, so you shouldn't have to worry about this)
---

---2  (for devs)
Do not use both Factions jars  which are v 1.6 and v1.7 or you won't spot fields/methods that actually don't exist in one
of the versions like the field senderMustBeModerator of FCommand class which means when running inside bukkit with the 
Factions version that didn't have the field, it will stack dump err on console
btw, senderMustBeModerator doesn't exist (well it's renamed) in Factions 1.7.x
java.lang.NoSuchFieldError: senderMustBeModerator

to fix: just use the Factions project in Eclipse, without having any Factions .jar files added to FactionsPlus classpath
you can switch between branches at will:  in Factions  1.6.x branch  and master (aka 1.7 branch)
OR you may simply use only one Factions.jar and switch between them by editing the Java Build Path->Libraries every time(harder 
than switching branches)
---

================

Note to devs:
---====----
1. never add .project or .settings folder(or files within) or the .classpath file to the repository
This would ensure that devs working on this won't accidentally overwrite eclipse project stuff on commit and affect each 
other 

------
To make sure we don't get errors due to Factions 1.6 vs 1.7
when you're ready to make the FactionsPlus.jar , first switch between 1.6 and 1.7 (jars or git branches of the 
Factions project) to check if FactionsPlus doesn't give errors on compile
 An example when this would happen, is when using senderMustBeModerator of FCommand and using Factions 1.6 jar or the 
1.6.x branch of Factions project, the FactionsPlus will compile just fine, but when you switch to 1.7 it will error, that
field doesn't exist in 1.7 (it's actually renamed).
 So this can go unnoticed and only actually fail on bukkit if they are using the 1.7 version of Factions

------
Always compile the project with java 6 not 7, because some bukkit users will run bukkit under jre6 and they'll fail to
load our plugin if it was compiled under java 7 with 'major/minor version' errors.

------
Avoid using the new File(parent, child); constructor but instead use one of:
1. new File(parentStr + File.separator + childString)
or
2. new File(parentFile + childFile);
or
3. just make sure parent is never empty if you still wanna use this: new File(parent, child);

Reason: (the following could happen behind your back)
 currentFolder=new File("");// S:\mcp62\eclipse\xcdds
 File fileInCurrent_not = new File(currentFolder, "file");// S:\file
 File fileInCurrent = new File("file");// S:\mcp62\eclipse\xcdds\file
 System.out.println(currentFolder.getAbsolutePath());
 System.out.println(fileInCurrent_not.getAbsolutePath());
 System.out.println(fileInCurrent.getAbsolutePath());
 
This will only happen when currentFolder.getPath() == "", if it's any non-empty string, it will work as expected,
simply said:
the new File(parent, child); [when parent.getPath().isEmpty() or parent.isEmpty() depending on parent type] 
will always resolve to root folder instead of current folder
when non-empty, should work as expected
parent is basically the path btw
Note: to accurately get currentFolder new File("."); is supposed to be used! which then does step 3.

-----
do not use/override onLoad() but instead do all in onEnable(), has the same effect but without the possibility of having
some bukkit calls NPE due to not yet being initialized ie. Bukkit.getConsoleSender()
-----

BEWARE of the evil char CONCAT
        char a='a';
        char b='b';
        String failConcat   =      a+b+"cdef"; // "195cdef"
        String correctConcat= "" + a+b+"cdef"; // "abcdef"
        
-----
always use -ea  java parameter when testing, both when compiling the classes in eclipse and when running the server
likely only the latter is necessary, to test if it works/is-enabled just do an "assert false;" line somewhere at onEnable()
-----
when checking if a faction is Wilderness/SafeZone/WarZone, to keep compability between 1.6 and 1.7 versions of Factions
please use the provided is*() methods in Utilities.class ie. Utilities.isSafeZone()
-----
-----


//end of: `Note to devs`
================

