Doc: contributors guide, how to set up plugin development environment

[atsu85]

To encourage other developers
(who might not know anything about Eclipse plugin development)
to contribute to this project
(either pull requests or by helping to debug issues),
it would help a lot if there was a guide to set up typescript.java plugin development environment.

Things to consider

I'm adding bellow few things You might want to consider. I'm neither asking to cover everything I mention bellow or to write everything from scratch. Add links to other resources when applicable and leave out things You don't consider important:

Running the plugin in development environment

• Eclipse version
• distribution
• importing project
• launching the plugin from development environment

Contribution guides

• How to format code before committing (what formatter to use)
• Line endings, file encoding, ...
• How to send pull requests
  • Anything specific for commit messages and the format? Maybe issue number?
  • Adding only code specific to single issue to one pull request?
    • Should the issue be created before committing?
    • Separate branch for each pull request?
  • Do You prefer squashing all commits to single commit before sending the pull request?

Other instructions

• Plugin structure (how features are distributed)
• Links to resources related to Eclipse plugin development.

[angelozerr]

who might not know anything about Eclipse plugin development

@atsu85 to be honnest with you my time is very limitated and I have not time to explain how to configure Eclipse env for developping plug, etc

Contribution are really welcome, but I prefer having PR from guys who have skills about Eclipse plugins, because review code is easy for me (I trust the guy who has done the PR).

I'm working like this for https://github.com/angelozerr/tern.java where I have the luck to have PR from impressive guys coming from MyEclipse, IBM, RedHat, Liferay IDE, Zend Studio.

Hope you will understand.

[lorenzodallavecchia]

Hi @angelozerr, after commit f2982c9 there are some new dependencies (Eclipse features/plugins) that I can't trace.
Can you tell me what should I install (and from which update sites) to work on typescript.java sources?

FYI, this is what I am currently installing to work on 1.2.0 (I mostly reverse-engineered it myself).

• From the Eclipse Neon repository:
  • Eclipse JSON Editors and Tools SDK - 1.0.0
  • Eclipse XML Editors and Tools SDK - 3.8.0
  • JavaScript Development Tools SDK - 2.0.0
• From http://oss.opensagres.fr/typescript.ide/1.2.0/
  • TextMate Core - 0.1.0
• From http://download.eclipse.org/tm/terminal/updates/4.0
  • TM Terminal - 4.0.0

I'm asking here because this is somewhat related to the future contributor's guide.
Thanks.

[angelozerr]

there are some new dependencies (Eclipse features/plugins)

typescript.java now support CodeLens #181 (comment). For the moment I have copied/pasted Eclipse CodeLens support from https://github.com/angelozerr/codelens-eclipse to typescript.java so you should not have some troubles.

Have you some troubles?

Please give me feedback with CodeLens. Thanks!

[lorenzodallavecchia]

Thanks for the quick response: you were so quick that you probably missed the list that I updated into the previous comment. Sorry about that.

I tried again and now it is much better. The last time I probably forgot to import some new project from Git into the workspace. I had to create some missing empty src folders to silent some errors.
Now, I'm left with one problem on org.eclipse.codelens.swt.fragment:

Unsatisfied version constraint: '3.105.3.v20170228-0512'

My version of org.eclipse.swt is 3.105.2.v20161122-0613.
Do I have to also update the base Eclipse platform? I'm on Neon 2 right now.

[angelozerr]

Do I have to also update the base Eclipse platform? I'm on Neon 2 right now.

I'm using Neon 3 for dev, but CodeLens should work with older JFace text. Try to remove Host Minimum Version for the 2 fragments. Thoses 2 fragments are used to set Javaassist classes in the classloader of SWT and JFace Text because by waiting for Eclipse Contribution for CodeLens, I'm using Javassisit to update behaviour of StyledTextRenderer and LineNumberChangeRulerColumn.

[angelozerr]

If you install Eclipse JEE distribution you will the whole plugins where typescript.java depends on (except for tm4e).

[lorenzodallavecchia]

Removing the Host Minimum Version did fix the problem on the fragment.

However, I also now noticed these problems.

• ISourceMapLanguageSupport cannot be resolved to a type
  TypeScriptSourceMapLanguageSupport.java /ts.eclipse.ide.jsdt.debug/src/ts/eclipse/ide/jsdt/debug/internal/support line 27 Java Problem
• The import org.eclipse.wst.jsdt.chromium cannot be resolved
  TypeScriptSourceMapLanguageSupport.java /ts.eclipse.ide.jsdt.debug/src/ts/eclipse/ide/jsdt/debug/internal/support line 17 Java Problem
• The method getJsFile(IPath) of type TypeScriptSourceMapLanguageSupport must override or implement a supertype method
  TypeScriptSourceMapLanguageSupport.java /ts.eclipse.ide.jsdt.debug/src/ts/eclipse/ide/jsdt/debug/internal/support line 30 Java Problem
• The method getSourceMapFile(IPath) of type TypeScriptSourceMapLanguageSupport must override or implement a supertype method
  TypeScriptSourceMapLanguageSupport.java /ts.eclipse.ide.jsdt.debug/src/ts/eclipse/ide/jsdt/debug/internal/support line 56 Java Problem
• Unknown extension point: 'org.eclipse.wst.jsdt.chromium.debug.core.sourceMapLanguageSupports'
  plugin.xml /ts.eclipse.ide.jsdt.debug line 6 Plug-in Problem
• Unsatisfied version constraint: 'org.eclipse.wst.jsdt.chromium.debug.core: 0.5.300'
  MANIFEST.MF /ts.eclipse.ide.jsdt.debug/META-INF line 9 Plug-in Problem
• Unknown extension point: 'org.eclipse.tm4e.ui.snippets'
  plugin.xml /ts.eclipse.ide.jsdt.ui line 760 Plug-in Problem

I did not see them before because I'm used to ignore another problem on ts.eclipse.ide.jsdt.ui

If you install Eclipse JEE distribution you will the whole plugins where typescript.java depends on (except for tm4e).

Nice to know: maybe I will try this.
Still, I usually prefer to work on the absolute minimum Eclipse, so that I can have precise control on my dependencies.

[angelozerr]

The ts.eclipse.ide.jsdt.debug provide an extension point to debug TypeScript with breakpoint, but it will be available with Eclipse Oxygen since my patch for SourceMap debugging was merged in the Eclipse master. For the moment ts.eclipse.ide.jsdt.debug doesn't belong to the update site. I suggest you that you close this project.

Unknown extension point: 'org.eclipse.tm4e.ui.snippets'

Problem comes from tm4e update site which cannot be updated eclipse-tm4e/tm4e#111 Please be patient.

[angelozerr]

@lorenzodallavecchia and soon you will perhaps having a depdnency to egit (orjgit only) to support Git CodeLens.

[lorenzodallavecchia]

Ok, I'll try your suggestions soon and let you know.

EGit should not be a problem: I use that every day in all workspaces.

[probert94]

I have reinstalled Eclipse (I am using Oxygen now) and so I had to re-import the project(s).
What I did is the following:

1. Clone the repository (I used TortoiseGIT)
2. In Eclipse use File > Open Projects from File System
3. Select typescript.java root directory
4. Make sure that "Search for nested projects" is checked
5. Finish
   The result:
   

Note, that I had to close 2 projects (nodejs.embed), which had build path errors. Other then that there are no errors, only warnings (1701 in my case).

I tryed using Import from git before, which resulted in > 700 errors for me. It seemed like not all sources have been imported...

EDIT:
3 Projects ("json", "terminal" and "update-site") don't seem to be neccessary. The .project-files have been created automatically and are not versioned, so I deleted them and the projects in eclipse too,

[angelozerr]

@Springrbua you can remove from your workspace "parent" projects like codelens, core, eclipse, embed, jsdt, json, etc

It's better to use Import as Maven project because it will download the dependency like tm4e.

@lorenzodallavecchia please note that if you use Oxygen you will not have the problem error with ts.eclipse.ide.jsdt.debug and you can do a Run as or Debug as from your ts file if you have sourcemap. Debugging is litlle bugged (the debug starts every time on the first line of ts file even if there is no breakpoint, sometimes debugger is lost, you need to reselect the process debugger tree item, etc) but it's issues from JSDT, please create issues at JSDT bugzilla.

Is it ok for you now @Springrbua ?

[probert94]

@angelozerr I'll try to import using maven as soon as I find time. If that works I'll probably create an entry in the Wiki if thats okay for you?
Also, is there any guideline for formatting etc? If not I guess we should consider creating one. Consistent formatting can really help to make code more readable.
What do you think about that?

[lorenzodallavecchia]

Thanks for the updates @angelozerr: I will try with Oxygen.

About importing projects, I used to do that by importing as @Springrbua did and removing "parent" folders that are not real projects. I have a Team Project Set file with only the correct projects and also some working sets to separate them.
However, I should also probably use Maven.

@Springrbua I have been using the Eclipse [built-in] style and the resulting formatting is usually identical to the one checked out. Note however that I have auto-format active only on modified lines to avoid unexpected changes in parts of the files that I am not looking at.

Also, while we are on it, I have found that files use inconsistent line endings, probably because of misconfigured Git on Windows. The guide should probably include the recommended Git line ending configuration.

[PhaserEditor2D]

Oh lord! I am not able to setup this. I imported the projects as maven projects but it keeps showing lot of errors like:

Error resolving version for plugin 'org.apache.maven.plugins:maven-site-plugin' from the repositories [local (C:\Users\arian\.m2\repository), central (https://repo.maven.apache.org/maven2)]: Plugin not found in any plugin repository

[PhaserEditor2D]

It is pretty frustrating. I am new to maven/tycho, but I really want to contribute with this project. I think @angelozerr that more love for the build guide will be good for your project, since not advanced users could contribute too, in simple tasks like better icons or adding some GUI.

[angelozerr]

@boniatillo-com if you import codelens, tm4e and typescript.java projects as maven projects, it should work. You can ignore maven errors.

[PhaserEditor2D]

Hi @angelozerr yes it is a good idea, at least to make it to run inside Eclipse.

• tm4e imported.
• typescript.java imported.
• codelens imported

Compile errors:

• Missing org.eclipse.wst.jsdt
• Missing org.eclipse.json
• Missing org.eclipse.tm
• No available bundle exports package 'javassist' on org.eclipse.codelens.jface.fragment MANIFEST.MF

[PhaserEditor2D]

By the way, I see in the Target Platforms there are two options:

• org.eclipse.tm4e/target-platform/tm4e
• tm4e-target

I selected the first one, let's see if it downloads all dependencies.

[angelozerr]

Missing org.eclipse.wst.jsdt
Missing org.eclipse.json
Missing org.eclipse.tm

Use Eclipse JEE Distribution.

No available bundle exports package 'javassist' on org.eclipse.codelens.jface.fragment MANIFEST.MF

Import https://github.com/angelozerr/codelens-eclipse/tree/master/javassist in your workspace.

[PhaserEditor2D]

I added TM and JSDT to the target platform.

• Missing org.eclipse.jdt.core

[angelozerr]

Missing org.eclipse.jdt.core

Where have you that?

[PhaserEditor2D]

/org.eclipse.codelens.jdt/META-INF/MANIFEST.MF

[angelozerr]

/org.eclipse.codelens.jdt/META-INF/MANIFEST.MF

Close this project. This project is to manage CodeLens inside JDT Java Editor:

[PhaserEditor2D]

Done

• Missing com.eclipsesource.json

I do not find the way to add it to the target platform.

[angelozerr]

Missing com.eclipsesource.json

Import https://github.com/angelozerr/typescript.java/tree/master/thirdparties/minimal-json

[PhaserEditor2D]

Ok, I did, but it is not a maven project so I had to import it as a common project.

I had to add a src folder (and others, like main/java) to:

• javaassist
• org.eclipse.codelens.jface.fragment
• org.eclipse.codelens.repository
• org.eclipse.codelens.swt.fragment

I guess a .gitkeep file in the empty folders is needed.

Now the problem I have is:

Unknown extension point: 'org.eclipse.ui.genericeditor.autoEditStrategies' in /org.eclipse.tm4e.languageconfiguration/plugin.xml

[angelozerr]

Unknown extension point: 'org.eclipse.ui.genericeditor.autoEditStrategies' in /org.eclipse.tm4e.languageconfiguration/plugin.xml

Ignore this error. It's for Generic Editor but you don't use it.

[PhaserEditor2D]

Ok, I will ignore it for the moment but I guess if I want to contribute to the lsp4e integration I will need right?

[angelozerr]

Ok, I will ignore it for the moment but I guess if I want to contribute to the lsp4e integration I will need right?

Not directly. Language configuration is used to manage auto close, indentation etc by using a simple JSON file configuration. It is not linked to lsp4e.

[PhaserEditor2D]

Yes true, is generic editor. Anyway, I see it is an extension point arrived now on 4.8-m1.

[PhaserEditor2D]

Great, it is working now.

[probert94]

@boniatillo-com Is it possible for you to sum up what you had to do to make it work?
It might help other possible contirbutors in future, if we have some kind of guide.

[PhaserEditor2D]

Sure I can do it!!!

I guess it should be a temporal guide because it is full of workarounds, yet I need to understand how Maven works because that's the tooling promoted by Eclipse and this project.

[PhaserEditor2D]

I added a new wiki page with a resume of the steps:

https://github.com/angelozerr/typescript.java/wiki/Development-environment-setup-(without-Maven)

[probert94]

@boniatillo-com thank you very much.
I'll try to reimport the projects using this steps, to verify, if it works for my environment to.

[angelozerr]

Thanks @boniatillo-com !

[lorenzodallavecchia]

@boniatillo-com that's great news.
Since I have a new PC I will need to setup my environment again and I will surely take a look at your guide.

[arjunpanicker]

Hi,

I want to use the Typescript.java as a dependency to my project so that I can enable TS editing in the workspace.

I am not able to do so even after including the packages as a jar file to the classpath of the plugin I am creating.

Oh, and by the way, I am creating a plugin for a perspective for study purposes.

Any info on the same will be helpful.

Thanks.