Difference between revisions of "DSDP/TML/TmL FAQ"

Latest revision as of 19:33, 29 December 2008

Introduction

How do I contribute to this FAQ?

Simply edit this page and add content. You can now use your bugzilla username and password to gain access.

How can I get notified of additions to that FAQ?

Log in to the Wiki. On your personal Preferences page, enable E-Mail notification. Then, click the watch tab of this page.

Is it really that easy?

Yes!

General

What is the Tools of mobile Linux?

• For a more official answer, see the

Tools for mobile Linux Project Homepage.

• For an excellent document we prepared when the project was started on the terminology we choose and the whole list of use cases we want to address in the long term, see the TmL Use Cases Document.

• The EclipseCon 2007 Short Talk slides give a good quick overview of the project. PPT slides include comments with additional explanations.

Which components are part of TmL?

• Emulator Framework (Deprecated)

• Device Framework

• VNC Viewer

How is TmL licensed?

The software produced by the TmL team is licensed under the Eclipse Public License (EPL). The software designed by third parties is made available under their respective licenses. Refer to the about.html file in the root directory of every TmL plugin for specific licensing information.

How do I find out about future releases of TmL?

See the TmL Project Plan (official plan) and the TmL Future Planning page (unofficial).

If you wish to contribute to the development of TmL, we welcome the opportunity to work with you. The plans will be updated to reflect the commitments made by contributors to this projects. See #Working on TmL for information on how to get started.

Download, Installation and Bug Reports

Which TmL build should I download?

The latest stable release version is available from the TmL downloads page.

Where can I find TmL using the Install/Update Manager from the Europa Discovery Site?

All components of TmL are available for download under Remote Access and Device Development in the Install/Update manager. The specific downloads from TmL under this category are:

• Emulator Framework 0.1(Deprecated)
• Emulator Framework 0.2(Deprecated)
• Device Framework 0.1
• VNC Viewer 0.1
• VNC Viewer 0.2
• VNC Viewer 0.3

Which operating systems does TmL support?

The TmL Framework is platform independent. It will run where Eclipse will run. According to the TmL Project Plan, we are testing on a set of Reference Platforms including Windows and Linux.

How do I ask questions?

Tools for mobile Linux related questions that are not answered in this FAQ or the documentation should be posted to the TmL newsgroup. You will need a newsreader and a password. You can also use this simple web interface or this more advanced web interface to browse the newsgroup. General Questions about the Eclipse SDK which includes the Eclipse Platform, JDT (Java Development Tools), or PDE (Plugin Development Environment) should be posted to the Eclipse newsgroup.

Keep in mind that these newsgroups are public, so do not include any confidential information in your questions. You should also read "How to ask questions the smart way" by Eric Raymond before participating in the newsgroups. NOTE: Please submit bugs to bugzilla, not to the newsgroups. #How do I report a bug or request a feature? section of this document.

People will still come into a newsgroup asking questions that have been answered before and often will not provide any information about what versions they have installed, and what the problem is. You will be much more likely to get help if you provide enough information to reproduce the problem. The section on #How do I report a bug or request a feature? gives a list of some information which could be useful.

How do I report a bug or request a feature?

The Tools for mobile Linux Project (like the Eclipse Project) uses bugzilla as its bug and feature tracking system. Around, this, we have developed some queries and best practices on the TmL Bug Process Page.

Entering a bug/feature report is as simple as filling in a web form on the eclipse bugzilla page. The first time you enter a bug you will need to create a new bugzilla account for yourself by providing an email address and choosing a password.

Entering a bug report or enhancement request is really simple, and we encourage users to just go ahead and do it so the request gets tracked. If, on the other hand, you prefer to first search if a similar bug has been reported before, just use the bugzilla search form. The TmL Bug Process Page also has some pre-defined queries that you can modify (just press the "Edit this search" link after running the query). If you find a bug report that outlines the problem you are seeing, you can simply annotate it with your comments to let the developers know that you have also hit the bug. Also you can add yourself to the CC list of the bug so that you will notified when the status of the bug changes or someone adds comments.

Once you have searched bugzilla and not found anything, you can go ahead and enter a new bug report. Don't let yourself be constrained too much by the bug writing guidelines. Following these is helpful for us but not an absolute must. Fill in what's easily accessible for you from the following:

Environmental settings:

1. The build level of Eclipse that you are using. For example, "Eclipse 3.2.1"

2. The component name and build level of TmL that you are using. For example, "TmL Device 1.0 build I20071104"

3. Your computer's specifications (OS version + patch level, memory, other pertinent info)

4. The contents of your .log file (or lack thereof). This is especially important if you get a dialog that reports an internal error. See #Where is this .log file I hear so much about? for information on finding your .log file.

5. The Java runtime or development kit you are using to run eclipse (use java -version or java -fullversion)

Problem Description:

1. A description of what you were doing,

2. A description of what behavior that you observed, and

3. An explanation of how the observed behavior differs from the expected behavior

Note that once you have filled in your environmental settings in one bug report, you can "Remember values as bookmarkable template" in bugzilla to easily file your next bug report on the same computer the next time.

Where is this .log file that I hear so much about?

The .log file is located in the workspace/.metadata directory.

The .log file is used by the Eclipse Platform to log runtime errors. It is useful to include it in bug reports because it contains stack traces that occur in plug-ins.

You can also see the .log file in Eclipse from Help > About > Configuration Details > View Error Log or, if you have installed eclipse-SDK (with JDT and PDE) from Window > Show View > Other > PDE Runtime > Error Log.

When you report a bug, including backtraces or error info from your .log is tremendously helpful! If you see multiple backtraces that seem to be related to your problem, it's best to just go and attach your entire .log file to the bug.

Working with TmL as a User

Working on TmL

How do I build TmL from CVS if I want a more recent build than is on the downloads page?

Start Eclipse SDK, and import a CVS Team Project Set as explained on the TmL CVS Setup page.

How do I export it so that it can be used with an external Eclipse installation?

You can either:

a) Export an TmL feature via File->Export->Plugin Development->Deployable Features. This will automatically export all the required plugins.

b) Export all the plugins etc. individually or all at once via File->Export->Plugin Development->Deployable Plugins and Fragments. However, this is more error prone and you're better off doing a).

How do I use eclipse to develop eclipse?

The self-hosting instructions explain how to use eclipse to develop eclipse.

• If you want to work with the current version of the eclipse code, you will need to connect to the Eclipse Project CVS repository. To connect to the Eclipse Project CVS repository, open the CVS repositories view (Perspective->Show View->Other...->CVS->CVS Repositories) and create a new CVS repository location (right click->New->CVS Repository Location. Paste the following information into the "Add CVS Repository" dialog, "Host" field:

•  :pserver:anonymous@dev.eclipse.org:/cvsroot/dsdp

• For connecting to the TmL CVS repository, see instructions on th TmL CVS Setup page.

NOTE: When you are connected as anonymous you will have read rights to the repository, but you will not be able to commit any code. See #How do I submit a fix for a bug? below for how to contribute back your changes.

How do I modify the code

Change any file you want. When you save it, it will be built.

How do I run or debug with my changes?

After successfully building TmL inside Eclipse, one typically wants to run an instance of Eclipse with the freshly built plugins (perhaps after making some changes to the source code). This is very easy to do in the PDE. Here are the steps:

1. Open the "Plug-in Development" perspective (you may have to go to "Others" to find it).

2. Set breakpoints in the code where you need them

3. Ensure that the Project you changed is selected in the Project Explorer

4. Select the menu action Run -> Debug As... -> Eclipse Application. (

4a. You may also -> Run As..., or use the toplevel run/debug icon, which also allows you to edit or re-launch the previous launch.

How do I submit a fix for a bug?

While using the Eclipse SDK to develop your plug-in, you found a bug in TmL. You submitted a bug report, but need the fix now. You've debugged the problem, and there is a simple fix. So you figured out how to use eclipse to develop eclipse and have written a fix for the bug you found. Now you want to release the fix to the eclipse community. How do you do this?

First, create a patch. You can create a patch by using the Team patch creation facility.

1. Select the project you have patched. It must be connected to the TmL CVS repository, so it's best if you got the project from our team project set.

2. Right click->Team->Create Patch...

3. The Create Patch wizard will prompt you for a file name. You should name your patch with the bugzilla bug report id.

Now you can submit the patch to the appropriate component developer mailing list. Be sure to include information about what your patch fixes. The committers for the component will evaluate your patch to see if it fixes the bug and is acceptable. If your patch is accepted, it will be released by the component team into the repository.

When you submit your patch to bugzilla, it helps streamlining the process when you add a few simple statements verifying that you authored the patch yourself and you are authorized (by your employer) to contribute it under the EPL. See the TmL committer HOWTO for a template statement you can copy and paste.

How do I submit a contribution beyond a simple bug fix?

We are always keen to get contributions beyond simple bug fixes as well. But since we need to remain within our charter, and make sure that all code coming from Eclipse.org is really clean in terms of IP and legal / copyright issues, we need to be a little bit more careful with substantial contributions (exceeding 250 lines of code and documentation).

1. Make yourself known to the TmL team, either by entering an enhancement request for the stuff you can contribute, or through the developer mailing list. Describe what you want to contribute, and verify that the TmL team can receive it. Our charter and process requires that we verify with the DSDP PMC (Project Management Council) that the actual contribution is welcome. This is mostly in order to avoid babylonic disgression and unnecessary duplication of features which are also available in other Eclipse projects you might not know about.

2. Make sure that your employer is OK with you contributing the code. We're most happy if you can contribute it under the Eclipse Public License (EPL). If you employer asks questions, there is a good EPL FAQ available online, as well as other guide to legal documents. If you can not contribute under the EPL but want some other license, please contact us directly.

3. Attach your code on bugzilla as soon as you can. This makes your code available under the Eclipse Website terms of use. It allows committers to review the code and make further suggestions - after all, we're all developers and see most right from the code. You don't need to refactor the code into an org.eclipse namespace just yet. A committer may pick up your code and make further suggestions for modification: you may need to review your code and make it fit for actual contribution. Get rid of any profanity you might have put into comments when the computer didn't like you. Did you write it yourself, or know all the people who wrote it? That's best. Make sure there's a copyright notice in all the source files, telling the author of the code (we call that pedigree, or also provenience). If the code is legacy, and you don't know exactly where it came from, it's harder and you'll need to let us know.

4. Add your legal statement verifying that you are actually authorized to contribute. By doing that, it's official already and you publish the code under your license (hopefully EPL). Anybody can look at your code now, download it and try it out! But, before we can accept it into the CVS Repository we'll need to have it reviewed by the Eclipse.org legal team (we call that "due diligence"). So be prepared to wait (hopefully not more than 1 month for EPL contributions) before your code shows up in an official Eclipse / Tools for mobile Linux release - the benefit of this review is that even large, cautious companies will adopt your code into their products because they are pretty sure that everything is OK from a legal standpoint.

That's it! - The process may sound scary at first, but all the steps are important and it's really not that bad once you've done it. Thanks and Kudos - we'll happily give you credit on our website for your generous contribution!

How do I distribute my changes to my customers?

Anyway that you see fit! Actually, if anybody has suggestions for this answer, please fill them in here.