Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "JSDT/Development"

(Development Environment Setup)
(Target Platform, API Baseline and Other Preferences)
 
(53 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
{{JSDT}}
 
{{JSDT}}
  
As of WTP 3.0, JSDT is part of the Web Tools Platform.
+
''JSDT'' is a subproject of ''WTP'' providing JavaScript editing features based on ''JDT''; other editors based on ''SSE''; Nodejs and JS debugging support based on ''ChromeDevTools'' and much more. Check the project pages below and see ''Developer Resources'' to get the list of Source repositories:
 +
 
 +
* [https://projects.eclipse.org/projects/webtools.jsdt JSDT]: ''JavaScript Development Tools''
 +
* [https://projects.eclipse.org/projects/webtools WTP]: ''WebTools Platform'', parent project since WTP3.0
 +
* [https://projects.eclipse.org/projects/webtools.sourceediting SSE]: ''Structured Source Editing'', for editors like XML, CSS, JSON
 +
* [https://projects.eclipse.org/projects/eclipse.jdt JDT]: ''Java Development Tools'', extended by the JavaScript Editor
  
 
== Contributing to JSDT ==
 
== Contributing to JSDT ==
The JSDT is driven by a very small development group with limited resources. ANY serious developers or contributors will be enthusiastically welcomed. For more information on how to become a Committer, check the standard Eclipse process (see [http://www.eclipse.org/projects/dev_process/new-committer.php New Committer Election]).  For more information about contributing to JSDT in general, or for questions about its internals, contact [mailto:wtp-dev@eclipse.org?subject=JSDT wtp-dev].
+
The JSDT is driven by a small and dedicated development team with limited resources. ANY serious developers or contributors will be enthusiastically welcomed. For more information on how to become a Committer, read how we [http://www.eclipse.org/projects/dev_process/new-committer.php nominate and elect new committers] according the standard Eclipse process.  
  
=== JSDT Functional Testing ===
+
To contribute to JSDT you can report bugs, resolve bugs and write documents or create media contents to spread your knowledge.
[[JSDTestScenarios | Testing Scenarios ]]
+
 
 +
=== Getting in touch with the Community ===
 +
For more ''information about contributing'' to JSDT or for ''questions about its internals'' you have few options:
 +
* contact [mailto:wtp-dev@eclipse.org wtp-dev@eclipse.org] after you subscribed to the [https://dev.eclipse.org/mailman/listinfo/wtp-dev wtp-dev mailing list].
 +
* chat via [https://wiki.eclipse.org/IRC_FAQ#What_are_.23eclipse_and_.23eclipse-dev_about.3F IRC] on the #eclipse or #eclipse-dev channel
 +
* get in touch on the [https://mattermost-test.eclipse.org/eclipse/channels/webtools Eclipse mattermost webtools channel]
 +
* ask the [https://www.eclipse.org/forums/index.php/f/88/ WebTools Project forum]
 +
* check the [https://wiki.eclipse.org/JSDT/Confcalls JSDT Confcalls]
  
=== Reporting Bugs ===
+
=== Bugzilla for JSDT Bugs ===
[https://bugs.eclipse.org/bugs/enter_bug.cgi?product=JSDT Report a bug] through [http://bugs.eclipse.org/bugs/ Eclipse Bugzilla] under WebTools catagory, JSDT component.
+
You can [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=JSDT Report a JSDT bug] through [http://bugs.eclipse.org/bugs/ Eclipse Bugzilla] choosing WebTools category, JSDT component.
  
 
Here is a [https://bugs.eclipse.org/bugs/buglist.cgi?list_id=3212991&resolution=---&classification=WebTools&query_format=advanced&product=JSDT list of open JSDT bugs]. We're working through them as fast as we can!
 
Here is a [https://bugs.eclipse.org/bugs/buglist.cgi?list_id=3212991&resolution=---&classification=WebTools&query_format=advanced&product=JSDT list of open JSDT bugs]. We're working through them as fast as we can!
  
You can receive notifications of incoming bugs by monitoring account ''jsdt.javascript-inbox@eclipse.org'' in https://bugs.eclipse.org/bugs/userprefs.cgi?tab=email
+
Don't forget to subscribe to Bugzilla notifications for JSDT. Here is an "how-to" reminder:
 +
* Go to https://bugs.eclipse.org/bugs/userprefs.cgi?tab=email
 +
* Add  jsdt.web-inbox@eclipse.org to the watch list, at the end of the page.
  
=== Development Environment Setup ===
+
=== Contribute Code ===
  
There are several ways to setup the development environment. Here are 2 good ones:
+
As Contributor, you can fix JSDT bugs and send code contributions via Gerrit:
 +
* To start you need to sign the [https://eclipse.org/legal/CLA.php CLA] and to [setup the development environment]
 +
* Then pick an [https://bugs.eclipse.org/bugs/buglist.cgi?bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&list_id=13964165&product=JSDT open JSDT Bug], if not assigned to any team member, assign it to yourself.
 +
* Solve the bug and test the solution, so you can commit and push your change with Gerrit.
 +
* Now wait for a committer who has to review and approve (+1) before your changes are committed.
  
==== Eclipse IDE + Target Platform aside ====
+
Below you can read how to setup the development environment, get the source code, edit the source, run the application, perform tests, and commit the changes via Gerrit.
  
For this setup we will need two Eclipse installations. The first one is an '''Eclipse IDE''' ''for development''. The second one is a '''Eclipse SDK + WTP SDK''', to ''be used as a Target Platform in the development instance''.
+
== Setup the Development Environment ==
  
With this setup, is possible to use the latest stable SDK for development and switch between different Target Platforms when needed.  
+
To setup the development environment you can either use a Full Stack ''Eclipse IDE loaded with the Target Platform Plug-ins'', or use an ''Eclipse IDE'' for coding and keep a separate installation as a ''Target Platform''.  
  
''Target Platform'', and ''API Baselines'', are set via '''Windows > Preferences > Plug-in Development'''
+
Separating your development IDE from Target Platform makes your IDE lighter, more stable when adding development plug-ins and more flexible for development against different versions.
  
==== Full WTP SDK Stack ====
+
If you're new to this setup, watch once this video to see a full setup for JSDT development environment: https://www.youtube.com/watch?v=SFxfuudlau8 (for Mars.1).
  
The Full Stack is an installation made of Eclipse SDK + WTP SDK, to be used as dev environment and Target Platform at the same time. This solution shouldn't be faster than the previous setup, and it has limitations when testing again different targets, as it'll be needed to have multiple IDEs.
+
=== Eclipse IDE + Target Platform aside ===
  
=== JSDT Sources ===
+
Download recent builds of Eclipse IDE and Target Platform from the eclipse download page: https://www.eclipse.org/downloads/
  
You find the Git Repository: [http://git.eclipse.org/c/jsdt/webtools.jsdt.git/ webtools.jsdt.git].
+
As an example, for Mars.2, you need to download:
See also [https://projects.eclipse.org/projects/webtools.jsdt/developer JSDT/Developer Resources]  
+
* Eclipse IDE (dev tools) : [https://www.eclipse.org/downloads/packages/eclipse-rcp-and-rap-developers/mars2 for RCP and RAP developers]
 +
* Eclipse TP (target) : [https://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/mars2 for Java EE developers]
  
Detailed repository contents you can find at this page: http://wiki.eclipse.org/WTP_Git_Migration_Checklist
+
After the downloads, unzip both installations. Launch the IDE, and remember you should never launch or update the Target Platform.
  
These plug-ins have no dependencies other than the Eclipse base (nor do they depend on anything else in WTP).  Using these plug-ins, a standalone JavaScript Project can be created and used:
+
=== Target Platform, API Baseline and Other Preferences ===
* bundles/org.eclipse.wst.jsdt.core
+
* org.eclipse.wst.jsdt.manipulation
+
* org.eclipse.wst.jsdt.ui
+
  
The Feature project for these is:
+
For the development you'll need to edit '''Preferences''', and set the Target Platform, API Baselines and other recommended values.
* features/org.eclipse.wst.jsdt.feature
+
 
 +
[[File:Set-downloaded-instalaltion-as-target-platform.png|650px]]
 +
 
 +
To set the ''Target Platform'' and the ''API Baseline'' open '''Windows > Preferences''' from menu and then select:
 +
* '''Plug-in Development''' > ''' API Baseline''' Click "Add Baseline" and point to the Target Platform installation
 +
* '''Plug-in Development''' > '''Target Platform''' Click "Add.." and point to the Target Platform installation.
 +
 
 +
To set the other recommended preferences in line with the [[Platform_UI/How_to_Contribute]] guidelines open '''Windows > Preferences''' from menu and then select:
 +
* '''Preferences > General > Workspace''', set text file delimiters to Unix line delimiters
 +
* '''Preferences > Java  > Editor > Save Actions''', enable the “Perform the selected actions ..” and set:
 +
** '''Format Source Code > Format Edited Lines''': to avoid formatting the whole file, but limit the changes to edited lines.
 +
** '''Additional Actions > Remove Trailing Whitespaces''': to avoid adding trailing whitespaces
 +
* '''Preferences > Java  > Installed JREs''' add the needed JREs. Usually I add Java8, 7 and 6.
 +
 
 +
=== Get the Source Code ===
 +
 
 +
''Note'': If you already have local Git repositories with JSDT projects, you can switch to Git perspective, and import them in the Git Repository View, via the "Add an existing local repository" Link. So doing, the download of projects from the project set will re-use those imported repositories, instead of doing a full download.
 +
 
 +
==== JSDT Source Repositories ====
 +
 
 +
To edit JSDT code, you will need to fetch code from four project repositories. Below you can see the Gerrit URLs.
 +
<pre>
 +
https://git.eclipse.org/r/p/jsdt/webtools.jsdt
 +
https://git.eclipse.org/r/p/sourceediting/webtools.sourceediting
 +
http://git.eclipse.org/gitroot/www.eclipse.org/webtools.git
 +
https://git.eclipse.org/r/platform/eclipse.platform.runtime
 +
</pre>
 +
 
 +
If you already provided Eclipse your [https://git.eclipse.org/r/#/settings/http-password Gerrit https password], you can clone and setup quickly by prepending your username to the URL as  <code>https://<YOUR-USERNAME>@git.eclipse.org/...</code>.
 +
 
 +
==== JSDT ProjectSet  ====
 +
 
 +
The JSDT ProjectSet defines all the project needed to develop on JSDT, along with the needed repositories.
 +
 
 +
[http://www.asegno.com/wp-content/uploads/2016/02/wst.jsdt_.allProjects_20160209.psf wst.jsdt_.allProjects_20160209.psf]
 +
 
 +
Then import all projects via:
 +
 
 +
* '''Import > Team > Team Project Set''' and choose the project set file
 +
 
 +
[[File:Import-jsdt-project-set.png|500px]]
 +
 
 +
'''Please Note''': Sometimes the ProjectSet could be not in sync with latest developments. If so, you can fix by adding missing projects, and looking in the \bundles\ folder of JSDT repositories.
 +
 
 +
==== JSDT Git Sources ====
 +
 
 +
* Git Repositories: http://git.eclipse.org/c/jsdt/webtools.jsdt.git/ webtools.jsdt.git
 +
* Developer resources https://projects.eclipse.org/projects/webtools.jsdt/developer
 +
* Detailed repository contents: http://wiki.eclipse.org/WTP_Git_Migration_Checklist
 +
 
 +
== Testing ==
 +
 
 +
Here you can find information on JSDT testing by launching an inner eclipse, by building and testing locally and about functional testing scenarios.
 +
 
 +
=== Launch the Target Platform from IDE ===
 +
 
 +
Launching an inner eclipse with target platform plugins onboard, added by the plugins of which you are editing the source code:
 +
* Create a new launch configuration, based on plugins contained in the target platform
 +
* Then Run the launch configuration. You will see a new Inner Eclipse popping up.
 +
* If needed you can debug this Eclipse instance you’re going to develop against.
 +
 
 +
You can check the [https://youtu.be/SFxfuudlau8?t=9m44s video starting 9'44"] to see how to choose plug-ins and run the application.
  
 
=== Building and testing JSDT locally ===
 
=== Building and testing JSDT locally ===
Line 51: Line 128:
 
Simply run <tt>mvn clean verify -Pbuild-individual-bundles -DskipTests=false</tt>. This command will run the Unit-tests. After the build, you can install your JSDT snapshot in an Eclipse IDE or other RCP application using the p2 repository in location <tt>site/target/repository</tt>
 
Simply run <tt>mvn clean verify -Pbuild-individual-bundles -DskipTests=false</tt>. This command will run the Unit-tests. After the build, you can install your JSDT snapshot in an Eclipse IDE or other RCP application using the p2 repository in location <tt>site/target/repository</tt>
  
=== Gerrit Reviews ===
+
=== JSDT Functional Testing ===
 +
[[JSDTestScenarios | Testing Scenarios ]]
 +
 
 +
== Gerrit Reviews ==
  
 
==== Pushing a new patch for review ====
 
==== Pushing a new patch for review ====
Line 88: Line 168:
  
 
JSDT uses SonarQube to get reports about static analysis. Those can show potential bugs, performance traps, or just bad practices. Here is the status of JSDT on these topics: https://dev.eclipse.org/sonar/dashboard/index/org.eclipse.webtools.jsdt:jsdt-parent . Any help to clean up warnings is welcome!
 
JSDT uses SonarQube to get reports about static analysis. Those can show potential bugs, performance traps, or just bad practices. Here is the status of JSDT on these topics: https://dev.eclipse.org/sonar/dashboard/index/org.eclipse.webtools.jsdt:jsdt-parent . Any help to clean up warnings is welcome!
 
== Architecture ==
 
 
=== HTML an JSP editors ===
 
 
JSDT provides JavaScript support for the WTP HTML and JSP editors in the WTP Source Editing project [http://git.eclipse.org/c/sourceediting/ Git repositories]. [https://github.com/eclipse/webtools.sourceediting GitHub]
 
 
The following plug-in projects provide JSDT integration with WTP's HTML and JSP editors:
 
* webtools.sourceediting.git/bundles/org.eclipse.wst.jsdt.web.core
 
* webtools.sourceediting.git/bundles/plugins/org.eclipse.wst.jsdt.web.ui
 
* webtools.sourceediting.git/bundles/plugins/org.eclipse.wst.jsdt.web.support.jsp - contains JSP-specific functionality
 
* webtools.sourceediting.git/bundles/plugins/org.eclipse.wst.jsdt.support.firefox - contains bindings for Mozilla FireFox, current as of FF 2.0.x (deprecated)
 
* webtools.sourceediting.git/bundles/plugins/org.eclipse.wst.jsdt.support.ie - contains bindings for Microsoft Internet explorer (deprecated)
 
 
=== JSDT tests ===
 
 
The following are the JUnits test plug-ins for JSDT:
 
* tests/org.eclipse.wst.jsdt.core.tests.compiler  - (test suite is org.eclipse.wst.jsdt.core.tests.compiler.JSDTTestAll)
 
* tests/org.eclipse.wst.jsdt.core.tests.model - (test suite is org.eclipse.wst.jsdt.core.tests.model.AllJavaModelTests)
 
 
These test plug-ins are new to WTP 3.1 and above:
 
* webtools.sourceediting.tests.git/tests/org.eclipse.wst.jsdt.web.core.tests  - (test suite is org.eclipse.wst.jsdt.web.core.tests.translation.AllWebCoreTests)
 
* webtools.sourceediting.tests.git/tests/org.eclipse.wst.jsdt.web.ui.tests - (test suite is org.eclipse.wst.jsdt.web.ui.tests.AllWebUITests)
 
 
These test plug-ins are new to WTP 3.2 and above:
 
* webtools.jsdt.tests.git/tests/org.eclipse.wst.jsdt.ui.tests  - (test suite is org.eclipse.wst.jsdt.ui.tests.JSDTUITests)
 
 
=== JSDT packages ===
 
 
==== JSDT Core ====
 
The JSDT core plugin (org.eclipse.wst.jsdt.core) provides the core JavaScript modeling.
 
 
 
{| border="1"
 
|+ Core plugin packages
 
! package !! function
 
|-
 
! org.eclipse.wst.jsdt.core
 
| public apis for the module
 
|-
 
! org.eclipse.wst.jsdt.core.ast
 
| The public apis for the read-only AST used by inference engines
 
|-
 
! org.eclipse.wst.jsdt.core.compiler
 
| the public apis for the validator
 
|-
 
! org.eclipse.wst.jsdt.core.compiler.libraries
 
| libraries which define the javascript language apis and the browser DOM apis
 
|-
 
! org.eclipse.wst.jsdt.core.dom
 
| Modifiable JavaScript model DOM
 
|-
 
! org.eclipse.wst.jsdt.core.dom.rewrite
 
| support for updating the dom
 
|-
 
! org.eclipse.wst.jsdt.core.eval
 
| support for evaluating code fragments
 
|-
 
! org.eclipse.wst.jsdt.core.formatter
 
| public apis for javascript formatting
 
|-
 
! org.eclipse.wst.jsdt.core.infer
 
| support for inferencing and inferencing extensions
 
|-
 
! org.eclipse.wst.jsdt.core.search
 
| public apis for search
 
|-
 
! org.eclipse.wst.jsdt.core.util
 
| public utility apis
 
|-
 
! org.eclipse.wst.jsdt.internal.codeassist
 
| support for code assist and selection
 
|-
 
! org.eclipse.wst.jsdt.internal.codeassist.complete
 
| support for code assist
 
|-
 
! org.eclipse.wst.jsdt.internal.codeassist.impl
 
| support for code assist
 
|-
 
! org.eclipse.wst.jsdt.internal.codeassist.select
 
| support for code selection
 
|-
 
! org.eclipse.wst.jsdt.internal.compiler
 
| validation code
 
|-
 
! org.eclipse.wst.jsdt.internal.compiler.ast
 
| internal javascript AST (Abstract Syntax Tree)
 
|-
 
! org.eclipse.wst.jsdt.internal.compiler.batch
 
| support for batch validation
 
|-
 
! org.eclipse.wst.jsdt.internal.compiler.classfmt
 
| ??
 
|-
 
! org.eclipse.wst.jsdt.internal.compiler.env
 
| ??
 
|-
 
! org.eclipse.wst.jsdt.internal.compiler.flow
 
| support for analyzing code flow for unused vars, etc
 
|-
 
! org.eclipse.wst.jsdt.internal.compiler.impl
 
| implementation of public apis
 
|-
 
! org.eclipse.wst.jsdt.internal.compiler.lookup
 
| support for resolving var/function references
 
|-
 
! org.eclipse.wst.jsdt.internal.compiler.parser
 
| the parser
 
|-
 
! org.eclipse.wst.jsdt.internal.compiler.parser.diagnose
 
| the diagnose parser used when there are syntax errors
 
|-
 
! org.eclipse.wst.jsdt.internal.compiler.problem
 
| support for problem messages
 
|-
 
! org.eclipse.wst.jsdt.internal.compiler.util
 
| parser/validator utilities
 
|-
 
! org.eclipse.wst.jsdt.internal.core
 
| implementation of public apis
 
|-
 
! org.eclipse.wst.jsdt.internal.core.builder
 
| implementation of eclipse builder extension
 
|-
 
! org.eclipse.wst.jsdt.internal.core.dom.rewrite
 
| support for updating code on DOM changes
 
|-
 
! org.eclipse.wst.jsdt.internal.core.hierarchy
 
| support for generating class hierarchy
 
|-
 
! org.eclipse.wst.jsdt.internal.core.index
 
| support for indexing the model, used by search
 
|-
 
! org.eclipse.wst.jsdt.internal.core.interpret
 
| javascript interpreter - under development , currently not used
 
|-
 
! org.eclipse.wst.jsdt.internal.core.interpret.builtin
 
| implementation of javascript language functions used by interpreter
 
|-
 
! org.eclipse.wst.jsdt.internal.core.search
 
| searching functions
 
|-
 
! org.eclipse.wst.jsdt.internal.core.search.indexing
 
| indexing of javascript
 
|-
 
! org.eclipse.wst.jsdt.internal.core.search.matching
 
| functions to determine if possible search match is exact match
 
|-
 
! org.eclipse.wst.jsdt.internal.core.search.processing
 
| search
 
|-
 
! org.eclipse.wst.jsdt.internal.core.util
 
| internal utilities
 
|-
 
! org.eclipse.wst.jsdt.internal.formatter
 
| formatter implementation
 
|-
 
! org.eclipse.wst.jsdt.internal.formatter.align
 
| formatter implementation
 
|-
 
! org.eclipse.wst.jsdt.internal.formatter.comment
 
| comment formatter implementation
 
|-
 
! org.eclipse.wst.jsdt.internal.oaametadata
 
| support for OpenAjax metadata
 
|-
 
! org.eclipse.wst.jsdt.launching
 
| misc utilities
 
|-
 
! org.eclipse.wst.jsdt.libraries
 
| Library support
 
|}
 
 
====JSDT UI====
 
User interface code
 
 
{| border="1"
 
|+ Core plugin packages
 
! package !! function
 
|-
 
! org.eclipse.wst.jsdt.internal.corext
 
|  refactoring support
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.buildpath
 
| support for include path editing
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.callhierarchy
 
| support for call hierarchy
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.codemanipulation
 
|  support for code refactoring
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.dom
 
 
|- support for dom maniputation used for refactoring
 
! org.eclipse.wst.jsdt.internal.corext.dom.fragments
 
|  support for manipulating dom fragments
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.fix
 
|  support for quick fix
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.javadoc
 
| support for jsdoc editing
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring
 
|  support for refactoring
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.base
 
|  support for refactoring
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.binary
 
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.changes
 
| refactoring change classes
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.code
 
|  refactoring of code segments
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.code.flow
 
| support for refactoring of code segments
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.delegates
 
|  support for "create delegates" action
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.generics
 
|  currently unused
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.nls
 
| currently unused
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.nls.changes
 
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.participants
 
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.rename
 
|  rename refactoring
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.reorg
 
| copy/move refactoring
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.scripting
 
|  support for scripiting of refactoring
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.sef
 
| encapsulate field refactoring
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.structure
 
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.structure.constraints
 
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.surround
 
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.tagging
 
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.typeconstraints
 
|  currently unused
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.typeconstraints.types
 
|  currently unused
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.typeconstraints.typesets
 
|  currently unused
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.typeconstraints2
 
|  currently unused
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.refactoring.util
 
|  refactoring utilities
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.template.java
 
|  support for templates
 
|-
 
! org.eclipse.wst.jsdt.internal.corext.util
 
 
|-
 
! org.eclipse.wst.jsdt.internal.ui
 
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.actions
 
|  implementation of actions
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.browsing
 
|  currently unused - support for browse perspective
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.callhierarchy
 
|  ui for call hierarchy
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.commands
 
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.compare
 
|  compare ui
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.dialogs
 
|  various diaglogs
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.dnd
 
|  drag/drop support
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.filters
 
|  implementation of view filters
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.fix
 
|  automatic cleanup functions
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.infoviews
 
|  various views
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.javadocexport
 
|  export of js doc
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.javaeditor
 
|  javascirpt editor implementation
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.javaeditor.saveparticipant
 
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.javaeditor.selectionactions
 
|  change selection actions
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.model
 
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.navigator
 
|  implementation of navigator
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.packageview
 
| implementation of script explorer
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.preferences
 
| preferences ui
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.preferences.cleanup
 
| ui for cleanup preferences
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.preferences.formatter
 
| ui for formatter preferences
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.refactoring
 
| ui for refactoring preferences
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.refactoring.actions
 
| actions for refactoring
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.refactoring.binary
 
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.refactoring.code
 
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.refactoring.contentassist
 
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.refactoring.nls
 
| current unused
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.refactoring.nls.search
 
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.refactoring.reorg
 
| move/copy/delete
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.refactoring.sef
 
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.search
 
| search ui
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.text
 
| javascript source editing utilites
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.text.comment
 
| comment editing
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.text.correction
 
| quick fix implementation
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.text.folding
 
|  folding implementation
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.text.html
 
| editing of html inside jsdoc
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.text.java
 
|  content assist implementation
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.text.java.hover
 
| hover help 
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.text.javadoc
 
|  jsdoc editing
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.text.spelling
 
| spell checking
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.text.spelling.engine
 
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.text.template.contentassist
 
| content assist templates
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.text.template.preferences
 
| template editing
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.typehierarchy
 
| type hierarchy ui
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.util
 
| utilities
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.viewsupport
 
| view utilities
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.wizards
 
| wizards
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.wizards.buildpaths
 
| include path editing
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.wizards.buildpaths.newsourcepage
 
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.wizards.dialogfields
 
 
|-
 
! org.eclipse.wst.jsdt.internal.ui.workingsets
 
 
|-
 
! org.eclipse.wst.jsdt.libraries
 
 
|-
 
! org.eclipse.wst.jsdt.ui
 
 
|-
 
! org.eclipse.wst.jsdt.ui.actions
 
 
|-
 
! org.eclipse.wst.jsdt.ui.dialogs
 
 
|-
 
! org.eclipse.wst.jsdt.ui.project
 
 
|-
 
! org.eclipse.wst.jsdt.ui.refactoring
 
 
|-
 
! org.eclipse.wst.jsdt.ui.search
 
 
|-
 
! org.eclipse.wst.jsdt.ui.text
 
 
|-
 
! org.eclipse.wst.jsdt.ui.text.folding
 
 
|-
 
! org.eclipse.wst.jsdt.ui.text.java
 
 
|-
 
! org.eclipse.wst.jsdt.ui.text.java.hover
 
 
|-
 
! org.eclipse.wst.jsdt.ui.wizards
 
 
|}
 
 
=== Generating the parser ===
 
Follow the instructions at http://www.eclipse.org/jdt/core/howto/generate%20parser/generateParser.html for generating the parser.  The parser grammer file is located in cvs at sourceediting/plugins/org.eclipse.wst.jsdt.core/grammer/js.g
 
 
 
== Design ==
 
The JavaScript Development Tools design would use the JDT design with the necessary adjustments made for JavaScript.
 
 
As far as the JavaScript Development Tools design is concerned, the major differences between Java and JavaScript are:
 
 
* Javascript has no explicit typing support, whereas in Java everything is typed, and incorporates argument types in function signatures.
 
* At the top level, a JavaScript file can contain any program statement, whereas a Java file only contains a Class.
 
* JavaScript has no classpath/jar file concept
 
 
Other areas where the java/JavaScript differences will necessitate changes:
 
 
* syntax differences - parse definitions
 
* additional program elements with no correspondence in Java
 
** object literals
 
** for (var in collection)
 
 
=== Inferred Types ===
 
 
In order for some JDT-based functionality (such as code completion) to work correctly, class type information needs to be available. This information is not available in JavaScript, but it can be inferred in many cases. A type inferring framework has been put in place to support this functionality, examining the JavaScript Abstract Syntax Tree (AST) and generating "virtual" class information.  Type inferring is extensible, so the unique conventions among various JavaScript Toolkits (e.g. Dojo, jQuery, Prototype, etc.) can be handled, although through WTP 3.1 it has remained provisional.  Inferred types may participate in refactoring, but their visibility within the UI is still being discussed.
 
 
=== JavaScript file handling ===
 
 
Java files have a very top down structure, where files only contain classes, which only contain fields, methods, and inner classes, and program statements only contained within methods. Because of this, some JDT functionality will not work for JavaScript, because a program statement can be directly at the top of a JavaScript file. The relevant JDT code is still undergoing refactorings to support these scenarios.
 
 
=== Variable/function resolution ===
 
 
In Java, everything is resolvable because of the classpath, package structure, and import statements. This has no correspondence in JavaScript, where functions themselves may also be resolvable as types.
 
 
==== Libraries ====
 
 
The JSDT mimics the JDT Java Build Path and classpath container mechanisms to offer JavaScript library support.  JSDT libraries are collections of JavaScript source files that have prototyped object/class definitions and JSDoc.  The inference engine then models these libraries and places each object/field/function in the projects Global Scope, making them available to every JavaScript file in the project.  Because the library contents are not directly executed by JSDT, it isn't necessary for them to contain the complete implementation of those objects.  In fact, the standard JavaScript runtime is itself presented as a source file containing stubs for the specification's contents.  Bindings for nonstandard and future runtimes are similarly easy to create and use.
 
 
To illustrate-- the JSDT contains a FireFox library plugin with about 150k of JavaScript and JsDoc.  This library represents the class structure within the FireFox browser that is accessible to a web page's JavaScript, but does not contain any implementation to the functions it declares.  If a user wishes to target their JavaScript source to FireFox specifically, they would add the FireFox library to their project and gain content completion and hover help for the FireFox objects. Users may also limit the objects/functions/fields visible in the project by adding or removing libraries.
 
 
Libraries aren't limited to browser objects.  AJAX runtimes can fit nicely into libraries, as would a website's standard set of utility functions.  Really the possibilities are limitless.  And the library mechanism is extremely easy to expand both by the end-user or through extension points.
 
 
=== Functionality mapping ===
 
 
This table shows how the JDT functionality corresponds to the JavaScript functionality. It does not include anything where there is a direct one to one correspondence.
 
 
{| border="1"
 
|-
 
| '''JDT function''' || '''JSDT function'''
 
|-
 
| Build path || Libraries + Global Scope (frequently referred to as an "Include Path")
 
|-
 
| JDK level (1.4 vs 1.5) || ECMAscript level 3 vs 4 (v.3 supported now, v.4 will not be implemented as the specification was abandoned)
 
|-
 
| Compile || Validation & flow analysis
 
|}
 
 
=== Extension Points ===
 
 
The JSDT functionality is embeddable. This means, for instance, that the JavaScript editing capabilities is embeddable within HTML and JSP Editors, both within script tags, and script attribute values.  The JSDT is flexible so script support in other languages is possible using translator interfaces being planned for WTP 3.1.
 
 
The following JSDT extension points are supported :
 
 
* Global Scope variable initializer
 
* Global Scope container initializer core
 
* Code formatter
 
* Validation participant
 
 
<!--In addition, the JavaScript syntax tree will be presented as an XML dom (future), so that various XML processors can be run against it for a variety of reasons, for instance, a Schematron processor could be used to do validation.-->  Currently the JSDT is represented in an AST.
 
 
The following jsdt.ui extension points will be supported :
 
 
* Global Scope container initializer ui  (Wizzard, content assist images and type/text naming)
 
* javascript element filter
 
* javaScriptEditorTextHovers
 
* jsdocCompletionProcessor
 
* quickFixProcessors
 
* quickAssistProcessors
 
* foldingStructureProviders
 
* queryParticipants
 
* javaScriptCompletionProposalComputer
 
* javaScriptCompletionProposalSorters
 
  
  
 
[[Category:JSDT]]
 
[[Category:JSDT]]

Latest revision as of 19:29, 19 April 2016


JSDT
Website
Download
Community
Mailing ListForumsIRCmattermost
Issues
OpenHelp WantedBug Day
Contribute
Browse Source


JSDT is a subproject of WTP providing JavaScript editing features based on JDT; other editors based on SSE; Nodejs and JS debugging support based on ChromeDevTools and much more. Check the project pages below and see Developer Resources to get the list of Source repositories:

  • JSDT: JavaScript Development Tools
  • WTP: WebTools Platform, parent project since WTP3.0
  • SSE: Structured Source Editing, for editors like XML, CSS, JSON
  • JDT: Java Development Tools, extended by the JavaScript Editor

Contributing to JSDT

The JSDT is driven by a small and dedicated development team with limited resources. ANY serious developers or contributors will be enthusiastically welcomed. For more information on how to become a Committer, read how we nominate and elect new committers according the standard Eclipse process.

To contribute to JSDT you can report bugs, resolve bugs and write documents or create media contents to spread your knowledge.

Getting in touch with the Community

For more information about contributing to JSDT or for questions about its internals you have few options:

Bugzilla for JSDT Bugs

You can Report a JSDT bug through Eclipse Bugzilla choosing WebTools category, JSDT component.

Here is a list of open JSDT bugs. We're working through them as fast as we can!

Don't forget to subscribe to Bugzilla notifications for JSDT. Here is an "how-to" reminder:

Contribute Code

As Contributor, you can fix JSDT bugs and send code contributions via Gerrit:

  • To start you need to sign the CLA and to [setup the development environment]
  • Then pick an open JSDT Bug, if not assigned to any team member, assign it to yourself.
  • Solve the bug and test the solution, so you can commit and push your change with Gerrit.
  • Now wait for a committer who has to review and approve (+1) before your changes are committed.

Below you can read how to setup the development environment, get the source code, edit the source, run the application, perform tests, and commit the changes via Gerrit.

Setup the Development Environment

To setup the development environment you can either use a Full Stack Eclipse IDE loaded with the Target Platform Plug-ins, or use an Eclipse IDE for coding and keep a separate installation as a Target Platform.

Separating your development IDE from Target Platform makes your IDE lighter, more stable when adding development plug-ins and more flexible for development against different versions.

If you're new to this setup, watch once this video to see a full setup for JSDT development environment: https://www.youtube.com/watch?v=SFxfuudlau8 (for Mars.1).

Eclipse IDE + Target Platform aside

Download recent builds of Eclipse IDE and Target Platform from the eclipse download page: https://www.eclipse.org/downloads/

As an example, for Mars.2, you need to download:

After the downloads, unzip both installations. Launch the IDE, and remember you should never launch or update the Target Platform.

Target Platform, API Baseline and Other Preferences

For the development you'll need to edit Preferences, and set the Target Platform, API Baselines and other recommended values.

Set-downloaded-instalaltion-as-target-platform.png

To set the Target Platform and the API Baseline open Windows > Preferences from menu and then select:

  • Plug-in Development > API Baseline Click "Add Baseline" and point to the Target Platform installation
  • Plug-in Development > Target Platform Click "Add.." and point to the Target Platform installation.

To set the other recommended preferences in line with the Platform_UI/How_to_Contribute guidelines open Windows > Preferences from menu and then select:

  • Preferences > General > Workspace, set text file delimiters to Unix line delimiters
  • Preferences > Java > Editor > Save Actions, enable the “Perform the selected actions ..” and set:
    • Format Source Code > Format Edited Lines: to avoid formatting the whole file, but limit the changes to edited lines.
    • Additional Actions > Remove Trailing Whitespaces: to avoid adding trailing whitespaces
  • Preferences > Java > Installed JREs add the needed JREs. Usually I add Java8, 7 and 6.

Get the Source Code

Note: If you already have local Git repositories with JSDT projects, you can switch to Git perspective, and import them in the Git Repository View, via the "Add an existing local repository" Link. So doing, the download of projects from the project set will re-use those imported repositories, instead of doing a full download.

JSDT Source Repositories

To edit JSDT code, you will need to fetch code from four project repositories. Below you can see the Gerrit URLs.

https://git.eclipse.org/r/p/jsdt/webtools.jsdt
https://git.eclipse.org/r/p/sourceediting/webtools.sourceediting
http://git.eclipse.org/gitroot/www.eclipse.org/webtools.git
https://git.eclipse.org/r/platform/eclipse.platform.runtime

If you already provided Eclipse your Gerrit https password, you can clone and setup quickly by prepending your username to the URL as https://<YOUR-USERNAME>@git.eclipse.org/....

JSDT ProjectSet

The JSDT ProjectSet defines all the project needed to develop on JSDT, along with the needed repositories.

wst.jsdt_.allProjects_20160209.psf

Then import all projects via:

  • Import > Team > Team Project Set and choose the project set file

Import-jsdt-project-set.png

Please Note: Sometimes the ProjectSet could be not in sync with latest developments. If so, you can fix by adding missing projects, and looking in the \bundles\ folder of JSDT repositories.

JSDT Git Sources

Testing

Here you can find information on JSDT testing by launching an inner eclipse, by building and testing locally and about functional testing scenarios.

Launch the Target Platform from IDE

Launching an inner eclipse with target platform plugins onboard, added by the plugins of which you are editing the source code:

  • Create a new launch configuration, based on plugins contained in the target platform
  • Then Run the launch configuration. You will see a new Inner Eclipse popping up.
  • If needed you can debug this Eclipse instance you’re going to develop against.

You can check the video starting 9'44" to see how to choose plug-ins and run the application.

Building and testing JSDT locally

Simply run mvn clean verify -Pbuild-individual-bundles -DskipTests=false. This command will run the Unit-tests. After the build, you can install your JSDT snapshot in an Eclipse IDE or other RCP application using the p2 repository in location site/target/repository

JSDT Functional Testing

Testing Scenarios

Gerrit Reviews

Pushing a new patch for review

You can use Gerrit (mandatory reading, important to set up hooks, SSH keys, CLA & other) to push Git commits on JSDT repositories. The repo URL for JSDT@Gerrit is ssh://user@git.eclipse.org:29418/jsdt/webtools.jsdt. Once logged into Gerrit, you can see more details about the URL at https://git.eclipse.org/r/#/admin/projects/jsdt/webtools.jsdt .

Assuming you named this repo gerrit, you can push a commit to one of this repository with

$ git push gerrit HEAD:refs/for/master

This will give you the URL of the Gerrit review where you can interact with project committers to get your commit merged.

In case you need to push another version of the patch, don't forget to copy the Change-Id from the Gerrit review if you didn't set up the git hook. Providing another version of the patch doesn't require a new commit, simply amend the one you already pushed, and push it again:

$ git log -1 #Shows the commit. Message should contain Sign-Off-By and Change-Id
$ git add file/to/change
$ git commit --amend # add --signoff if Sign-Off-By is missing, and copy Change-Id from Gerrit review if missing
$ git push gerrit HEAD:refs/for/master # will create another version of the patch, on the same review.

Reviewing a patch

Incoming patch automatically triggers a build and will receive an automated vote according to whether patch breaks the build/tests or not. The CI job providing this vote is https://hudson.eclipse.org/webtools/job/jsdt-gerrit.

  • Anytime Hudson votes with -1, it generally means that something is wrong with the patch: it breaks build or make a test failing, so the patch shouldn't be merged. The build log should be inspected by submitter and reviewers to understand the cause of the bug and submit (or assist in submitting) a better patch.
  • Hudson voting +1 means that the test didn't introduce any regression visible by build or automated tests.

Anyone is free to add comments and vote on a review. Committers have the final power to decide whether or not a patch can be merged.

List reviews and be notified

You can see the list of open Gerrit reviews at https://git.eclipse.org/r/#/q/status:open+project:jsdt/webtools.jsdt,n,z .

Regular contributors and committers should really subscribe to notifications of proposed patches. You can set up notifications for proposed incoming changes at https://git.eclipse.org/r/#/settings/projects

Static analysis with SonarQube

JSDT uses SonarQube to get reports about static analysis. Those can show potential bugs, performance traps, or just bad practices. Here is the status of JSDT on these topics: https://dev.eclipse.org/sonar/dashboard/index/org.eclipse.webtools.jsdt:jsdt-parent . Any help to clean up warnings is welcome!

Back to the top