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 "PDT/Contributing"

< PDT
(Quick guide)
(H2 is no longer used.)
(28 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 
[[Category:PDT]]
 
[[Category:PDT]]
== Quick guide ==
 
Following is a two-step guide to get and build PDT source code:
 
  
1. Get PDT source code:
+
== Working with PDT source code in Eclipse ==
 +
 
 +
=== Which Eclipse version? ===
 +
 
 +
To comfortably edit PDT source code and execute it, you can use '''Eclipse for RCP and RAP Developers''', which contains some required plugins (Java Development Tools, Plug-in Development Environment, Git Integration, …).
 +
 
 +
=== Required plugins ===
 +
 
 +
In addition to the plugins bundled with Eclipse RCP, PDT requires other plugins that can be installed via the ''Help'' → ''Install New Software…'' menu item.
 +
 
 +
You'll need to add the following software site (you can add them by clicking the Manage button in the Install dialog):
 +
 
 +
* DLTK Nightly: http://download.eclipse.org/technology/dltk/updates-dev/latest-nightly
 +
* Orbit:
 +
** for Eclipse Oxygen.1a: http://download.eclipse.org/tools/orbit/downloads/drops/R20170919201930/repository
 +
** for other versions see http://download.eclipse.org/tools/orbit/downloads
 +
 
 +
Once you defined the above update sites, you should install these plugins:
 +
 
 +
* Dynamic Languages Toolkit - Core Frameworks SDK
 +
* Dynamic Languages Toolkit - Core Lucene Index Frameworks SDK
 +
* Dynamic Languages Toolkit - Mylyn Integration
 +
* DLTK Core Tests
 +
* Eclipse Web Developer Tools
 +
* Apache Commons Exec Plug-in
 +
* TM Terminal
 +
* BIRT Framework
 +
* Zest SDK
 +
* Parallel Tools Platform
 +
* Eclipse/Gerrit integration (aka EGerrit)
 +
 
 +
=== Importing the PDT Projects ===
 +
 
 +
To import the PDT projects in Eclipse, choose the ''File'' → ''Import…'' menu item, then choose ''Team'' → ''Team Project Set'', and specify to import from the URL https://git.eclipse.org/c/pdt/org.eclipse.pdt.git/plain/dev/psf/pdt-dev.psf
 +
 
 +
PS: You can safely disable API Baselines errors (''Window'' → ''Preferences'' menu item, then ''Plug-in Development'' → ''API Baselines'', then choose ''Missing API baseline'' → ''Ignore'').
 +
 
 +
=== Running and debugging PDT ===
 +
 
 +
In order to run (and debug) PDT, you can choose the ''Run'' → ''Debug Configurations…'' menu item, and add a new ''Eclipse Application''.
 +
 
 +
You can keep the default settings, but it's very handy to go to the ''Common'' tab, and check ''Debug'' and ''Run'' in the ''Display in favorites menu'' checklist (so that you'll be able to launch the debug environment by clicking the Debug or Run icons in the toolbar).
 +
 
 +
When launching the debug application, a new Eclipse instance will be executed: you can create a new PHP project, and you can place breakpoints and analyze the execution in the Eclipse instance containing the PDT project.
 +
 
 +
PS: when executing PDT, you may see some validation warnings: you can safely ignore them.
 +
 
 +
 
 +
== Preparing and sending patches ==
 +
 
 +
When you decide to send us your new amazing patch, you'll need:
 +
 
 +
# an Eclipse account (you can create it [https://accounts.eclipse.org/user/register here])
 +
# to sign the [https://www.eclipse.org/contribute/cla Eclipse Contributor Agreement]
 +
# a public/private SSH RSA key pair (you can generate them with ssh-keygen on Linux and Mac, and PuTTYgen on Windows)
 +
# add the public key to https://git.eclipse.org/r/#/settings/ssh-keys
 +
# add your private key to Eclipse (''Window'' → ''Preferences'' menu item, then ''General'' → ''Network Connections'' → ''SSH2'')
 +
 
 +
Patches must be sent to Gerrit (a review system that can compile PDT and run tests).
 +
 
 +
In order to create a Gerrit patch from inside Eclipse, switch to the Git perspective (''Window'' → ''Perspective'' → ''Open Perspective'' → ''Git'').
 +
 
 +
In the ''Git Repositories'' view, you should have ''org.eclipse.pdt'': expand the ''Remotes'' node and right click ''origin'' → ''Gerrit Configuration''.
 +
 
 +
If your Eclipse username is ''myusername'', specify that
 +
* the push URI uses the SSH protocol
 +
* the push URI is ssh://myusername@git.eclipse.org:29418/pdt/org.eclipse.pdt.git
 +
 
 +
Before sending patches, you should file a bug report at https://bugs.eclipse.org: every bug report will be assigned an unique ID (let's say it's 1234)
 +
 
 +
To send the patch to Gerrit, in the Git perspective of Eclipse, right click the org.eclipse.pdt node in the Git Repositories view, then Commit…
 +
 
 +
The commit message must be like this:
 +
 
 +
  Bug 1234 - Description
 +
 
 +
  Notes
 +
 
 +
  Change-Id: I0000000000000000000000000000000000000000
 +
  Signed-off-by: Your Name <your-email@example.com>
 +
 
 +
Where:
 +
 
 +
* 1234<br />is the Eclipse bug ID. In case there's no Eclipse bug associates, use ''No bug'' instead of ''Bug 1234''.<br />If your patch is still in progress, to avoid confusion add a ''[WIP]'' prefix (eg: ''[WIP] No bug - This is an example'').
 +
* Description<br />is the main title of the patch.
 +
* Notes<br />are optional notes about the patch.
 +
* Change-Id: I0000000000000000000000000000000000000000<br />This blank Change-Id line must be added as-is in the commit message.<br />After pushing successfully your patch to Gerrit, Gerrit will create a unique and final ''Change-Id'' to identify your patch.<br />If later you need to update the patch, use the gerrit link added to your bug report to retrieve the ''Change-Id'' value and replace the blank identifier ''I0000000000000000000000000000000000000000'' by the ''Change-Id'' affected to your patch.
 +
* Your Name<br />is your real name.
 +
* your-email@example.com<br />is your email address.
 +
 
 +
PS: the commit author and submitter usually have the same value as the Signed-off-by.
 +
 
 +
By pushing the commit, you'll create - or update - a new Gerrit patch depending on the ''Change-Id'' value of your commit message.
 +
The link to view it should be automatically added to your bug report (the link will look like https://git.eclipse.org/r/#/c/112773)
 +
 
 +
 
 +
== Compiling PDT outside Eclipse ==
 +
 
 +
You can compile the PDT source code outside Eclipse.
 +
 
 +
First of all, you need to clone the PDT git repository:
  
 
   git clone http://git.eclipse.org/gitroot/pdt/org.eclipse.pdt.git
 
   git clone http://git.eclipse.org/gitroot/pdt/org.eclipse.pdt.git
  # or if you're PDT committer: git clone ssh://committerid@git.eclipse.org/gitroot/pdt/org.eclipse.pdt.git
 
  
2. Build PDT using Maven:
+
If you are an Eclipse user and/or a PDT committer:
  
   cd org.eclipse.pdt/org.eclipse.pdt.releng
+
   git clone ssh://committerid@git.eclipse.org:29418/pdt/org.eclipse.pdt.git
 +
 
 +
To build PDT, you need Maven, and launch these commands:
 +
 
 +
  # project root dir
 +
  cd org.eclipse.pdt
 +
  # build and run all tests
 
   mvn clean install
 
   mvn clean install
 +
  # build and ignore all tests
 +
  mvn clean install -DskipTests
 +
  # build and skip performance tests only (recommend)
 +
  mvn clean install -DskipPdtPerformanceTests
  
== Working with PDT source code in Eclipse ==
+
To build the PDT release:
 +
 
 +
  # project root dir
 +
  cd org.elipse.pdt
 +
  # this will produce normalized, signed and packed release, inside eclipse.org infrastructure
 +
  mvn clean install -Prelease
 +
  #this will produce normalized and packed release
 +
  mvn clean install -Prelease -DskipSign
 +
 
 +
 
 +
== Sonar ==
 +
 
 +
Sonar is used in order to track Code Quality:
 +
# Sonar dashboard: https://dev.eclipse.org/sonar/project/index/org.eclipse.php:org.eclipse.pdt.releng
 +
# Reports are ganerated based on dedicated build: https://hudson.eclipse.org/pdt/job/pdt-sonar/#https://hudson.eclipse.org/pdt/job/pdt-sonar
 +
 
 +
 
 +
== Developer Resources ==
 +
 
 +
After setting up PDT source code please have a look at a set of docs we have for our developers on the [[PDT#Developer_Resources]] page.
 +
 
 +
 
 +
== Update help pages ==
 +
 
 +
All help pages sitting under plugins/org.eclipse.php.help/docs/source/ in *.md format.
 +
 
 +
While make install, our build system converting it to *.html files in exactly same structure and also:
 +
 
 +
# Remove ###- part from each *.md file, and fix all internal links.
 +
# Regenerate IPHPHelpContextIds interface
 +
# Build helpContexts.xml file
 +
# Build toc.xml file
 +
 
 +
=== Which editor should I use? ===
 +
 
 +
You can work with any markdown editor, but because our build system use Mylyn Wikitext, you should install wikitext editor from https://eclipse.org/mylyn/downloads/ to be sure that everything is ok.
  
# To comfortably edit PDT source code you will need Eclipse JDT and PDE. Ideally Eclipse Classic package from Eclipse downloads page is what you need.
+
=== Howto register new help context id? ===
# Check out PDT plugins to Eclipse workspace. Select the XML text below and save it to file projectSet.psf
+
# In Eclipse, choose File->Import, select Team->Team Project Set and choose projectSet.psf file created in step 2. After finishing the import wizard, you should see all PDT source code in your workspace. Source code might not be compiling yet
+
# Find file org.eclipse.php.core/Resources/parserTools/build.xml and launch it as Ant Build. This will generate PHP language parser classes.
+
# Install missing dependencies:
+
## Dynamic Languages Toolkit - Core Frameworks
+
## Dynamic Languages Toolkit - Core H2 Index Frameworks (uncheck "Group items by category" to see this one)
+
## Eclipse Web Developer Tools
+
## Eclipse XML Editors and Tools
+
# In preferences (Window->Preferences->Plug-in Development->API Baselines), switch "Missing API baseline" to "Warning" or "Ignore".
+
# You can now run PDT in Eclipse self-hosting mode. Click on any of PDT projects and choose Run As->Eclipse Application
+
  
== PDT Team Project Set ==
+
Add this code to markdown file:
You can quickly set up your Eclipse workspace using the following [http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.platform.doc.user%2Ftasks%2Ftasks-cvs-project-set.htm Team Project Set]. Save the following text into a file named "pdt.psf"; use "File > Import > Team Project Set" to import that file.
+
  
   <?xml version="1.0" encoding="UTF-8"?>
+
   &lt;!--context:your_context_id--&gt;
  <psf version="2.0">
+
  <provider id="org.eclipse.team.cvs.core.cvsnature">
+
  <project reference="1.0,:pserver:dev.eclipse.org:/cvsroot/tools,org.eclipse.pdt/plugins/org.eclipse.php.core,org.eclipse.php.core"/>
+
  <project reference="1.0,:pserver:dev.eclipse.org:/cvsroot/tools,org.eclipse.pdt/plugins/org.eclipse.php.core.parser,org.eclipse.php.core.parser"/>
+
  <project reference="1.0,:pserver:dev.eclipse.org:/cvsroot/tools,org.eclipse.pdt/plugins/org.eclipse.php.debug.core,org.eclipse.php.debug.core"/>
+
  <project reference="1.0,:pserver:dev.eclipse.org:/cvsroot/tools,org.eclipse.pdt/plugins/org.eclipse.php.debug.daemon,org.eclipse.php.debug.daemon"/>
+
  <project reference="1.0,:pserver:dev.eclipse.org:/cvsroot/tools,org.eclipse.pdt/plugins/org.eclipse.php.debug.ui,org.eclipse.php.debug.ui"/>
+
  <project reference="1.0,:pserver:dev.eclipse.org:/cvsroot/tools,org.eclipse.pdt/plugins/org.eclipse.php.help,org.eclipse.php.help"/>
+
  <project reference="1.0,:pserver:dev.eclipse.org:/cvsroot/tools,org.eclipse.pdt/plugins/org.eclipse.php.server.core,org.eclipse.php.server.core"/>
+
  <project reference="1.0,:pserver:dev.eclipse.org:/cvsroot/tools,org.eclipse.pdt/plugins/org.eclipse.php.server.ui,org.eclipse.php.server.ui"/>
+
  <project reference="1.0,:pserver:dev.eclipse.org:/cvsroot/tools,org.eclipse.pdt/plugins/org.eclipse.php.ui,org.eclipse.php.ui"/>
+
  </provider>
+
  </psf>
+

Revision as of 06:37, 7 December 2017


Working with PDT source code in Eclipse

Which Eclipse version?

To comfortably edit PDT source code and execute it, you can use Eclipse for RCP and RAP Developers, which contains some required plugins (Java Development Tools, Plug-in Development Environment, Git Integration, …).

Required plugins

In addition to the plugins bundled with Eclipse RCP, PDT requires other plugins that can be installed via the HelpInstall New Software… menu item.

You'll need to add the following software site (you can add them by clicking the Manage button in the Install dialog):

Once you defined the above update sites, you should install these plugins:

  • Dynamic Languages Toolkit - Core Frameworks SDK
  • Dynamic Languages Toolkit - Core Lucene Index Frameworks SDK
  • Dynamic Languages Toolkit - Mylyn Integration
  • DLTK Core Tests
  • Eclipse Web Developer Tools
  • Apache Commons Exec Plug-in
  • TM Terminal
  • BIRT Framework
  • Zest SDK
  • Parallel Tools Platform
  • Eclipse/Gerrit integration (aka EGerrit)

Importing the PDT Projects

To import the PDT projects in Eclipse, choose the FileImport… menu item, then choose TeamTeam Project Set, and specify to import from the URL https://git.eclipse.org/c/pdt/org.eclipse.pdt.git/plain/dev/psf/pdt-dev.psf

PS: You can safely disable API Baselines errors (WindowPreferences menu item, then Plug-in DevelopmentAPI Baselines, then choose Missing API baselineIgnore).

Running and debugging PDT

In order to run (and debug) PDT, you can choose the RunDebug Configurations… menu item, and add a new Eclipse Application.

You can keep the default settings, but it's very handy to go to the Common tab, and check Debug and Run in the Display in favorites menu checklist (so that you'll be able to launch the debug environment by clicking the Debug or Run icons in the toolbar).

When launching the debug application, a new Eclipse instance will be executed: you can create a new PHP project, and you can place breakpoints and analyze the execution in the Eclipse instance containing the PDT project.

PS: when executing PDT, you may see some validation warnings: you can safely ignore them.


Preparing and sending patches

When you decide to send us your new amazing patch, you'll need:

  1. an Eclipse account (you can create it here)
  2. to sign the Eclipse Contributor Agreement
  3. a public/private SSH RSA key pair (you can generate them with ssh-keygen on Linux and Mac, and PuTTYgen on Windows)
  4. add the public key to https://git.eclipse.org/r/#/settings/ssh-keys
  5. add your private key to Eclipse (WindowPreferences menu item, then GeneralNetwork ConnectionsSSH2)

Patches must be sent to Gerrit (a review system that can compile PDT and run tests).

In order to create a Gerrit patch from inside Eclipse, switch to the Git perspective (WindowPerspectiveOpen PerspectiveGit).

In the Git Repositories view, you should have org.eclipse.pdt: expand the Remotes node and right click originGerrit Configuration.

If your Eclipse username is myusername, specify that

Before sending patches, you should file a bug report at https://bugs.eclipse.org: every bug report will be assigned an unique ID (let's say it's 1234)

To send the patch to Gerrit, in the Git perspective of Eclipse, right click the org.eclipse.pdt node in the Git Repositories view, then Commit…

The commit message must be like this:

 Bug 1234 - Description
 
 Notes
 
 Change-Id: I0000000000000000000000000000000000000000
 Signed-off-by: Your Name <your-email@example.com>

Where:

  • 1234
    is the Eclipse bug ID. In case there's no Eclipse bug associates, use No bug instead of Bug 1234.
    If your patch is still in progress, to avoid confusion add a [WIP] prefix (eg: [WIP] No bug - This is an example).
  • Description
    is the main title of the patch.
  • Notes
    are optional notes about the patch.
  • Change-Id: I0000000000000000000000000000000000000000
    This blank Change-Id line must be added as-is in the commit message.
    After pushing successfully your patch to Gerrit, Gerrit will create a unique and final Change-Id to identify your patch.
    If later you need to update the patch, use the gerrit link added to your bug report to retrieve the Change-Id value and replace the blank identifier I0000000000000000000000000000000000000000 by the Change-Id affected to your patch.
  • Your Name
    is your real name.
  • your-email@example.com
    is your email address.

PS: the commit author and submitter usually have the same value as the Signed-off-by.

By pushing the commit, you'll create - or update - a new Gerrit patch depending on the Change-Id value of your commit message. The link to view it should be automatically added to your bug report (the link will look like https://git.eclipse.org/r/#/c/112773)


Compiling PDT outside Eclipse

You can compile the PDT source code outside Eclipse.

First of all, you need to clone the PDT git repository:

 git clone http://git.eclipse.org/gitroot/pdt/org.eclipse.pdt.git

If you are an Eclipse user and/or a PDT committer:

 git clone ssh://committerid@git.eclipse.org:29418/pdt/org.eclipse.pdt.git

To build PDT, you need Maven, and launch these commands:

 # project root dir
 cd org.eclipse.pdt
 # build and run all tests
 mvn clean install
 # build and ignore all tests
 mvn clean install -DskipTests
 # build and skip performance tests only (recommend)
 mvn clean install -DskipPdtPerformanceTests

To build the PDT release:

 # project root dir
 cd org.elipse.pdt
 # this will produce normalized, signed and packed release, inside eclipse.org infrastructure
 mvn clean install -Prelease
 #this will produce normalized and packed release
 mvn clean install -Prelease -DskipSign


Sonar

Sonar is used in order to track Code Quality:

  1. Sonar dashboard: https://dev.eclipse.org/sonar/project/index/org.eclipse.php:org.eclipse.pdt.releng
  2. Reports are ganerated based on dedicated build: https://hudson.eclipse.org/pdt/job/pdt-sonar/#https://hudson.eclipse.org/pdt/job/pdt-sonar


Developer Resources

After setting up PDT source code please have a look at a set of docs we have for our developers on the PDT#Developer_Resources page.


Update help pages

All help pages sitting under plugins/org.eclipse.php.help/docs/source/ in *.md format.

While make install, our build system converting it to *.html files in exactly same structure and also:

  1. Remove ###- part from each *.md file, and fix all internal links.
  2. Regenerate IPHPHelpContextIds interface
  3. Build helpContexts.xml file
  4. Build toc.xml file

Which editor should I use?

You can work with any markdown editor, but because our build system use Mylyn Wikitext, you should install wikitext editor from https://eclipse.org/mylyn/downloads/ to be sure that everything is ok.

Howto register new help context id?

Add this code to markdown file:

 <!--context:your_context_id-->

Back to the top