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 "The Official Eclipse FAQs"

(Implementing Support for Your Own Language: Added a reference to Xtext)
 
(3 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
{{Warning|This page has been migrated to to https://github.com/eclipse-platform/eclipse.platform/blob/master/docs/FAQ/The_Official_Eclipse_FAQs.md}}
 +
 
Note that this FAQ is updated less frequently than [[IRC FAQ|this FAQ]]. You may find your answer there before it makes its way here.
 
Note that this FAQ is updated less frequently than [[IRC FAQ|this FAQ]]. You may find your answer there before it makes its way here.
  
Line 168: Line 170:
 
:*[[FAQ How do I use a SubProgressMonitor?]]
 
:*[[FAQ How do I use a SubProgressMonitor?]]
 
:*[[FAQ How do I use the platform logging facility?]]
 
:*[[FAQ How do I use the platform logging facility?]]
:*[[FAQ How do I use the platform debug tracing facility?]]
+
:*[[FAQ How do I use the platform debug tracing facility]]?
 
:*[[FAQ How do I load and save plug-in preferences?]]
 
:*[[FAQ How do I load and save plug-in preferences?]]
 
:*[[FAQ How do I use the preference service?]]
 
:*[[FAQ How do I use the preference service?]]
Line 179: Line 181:
 
:*[[FAQ How can I track the lifecycle of jobs?]]
 
:*[[FAQ How can I track the lifecycle of jobs?]]
 
:*[[FAQ How do I create a repeating background task? ]]
 
:*[[FAQ How do I create a repeating background task? ]]
 
  
 
=== Standard Widget Toolkit (SWT) ===
 
=== Standard Widget Toolkit (SWT) ===
Line 449: Line 450:
  
 
=== Implementing Support for Your Own Language ===
 
=== Implementing Support for Your Own Language ===
Through its JDT project, Eclipse has strong support for Java development, such as editing, refactoring, building, launching, and debugging. Likewise, the C development tools (CDT) project aims for similar support for writing C/C++ code.
 
  
This chapter discusses the nuts and bolds with which JDT and CDT are implemented. It is helpful to understand the low level details of how Eclipse works internally. However, as Eclipse now has the Xtext framework (http://www.eclipse.org/Xtext) implementing support for your own language has become much easier.
+
==== The language already has parsers, compilers, and other services ====
 +
 
 +
In this case, you can simply reuse them and skip the parts about writing a compiler, a DOM and so on; and focus in integration of the language into the workbench:
 +
 
 +
The following FAQ may be relevant:
 +
:*[[FAQ How do I run an external builder on my source files?]]
 +
:*[[FAQ How do I react to changes in source files?]]
 +
:*[[FAQ How do I implement an Eclipse builder?]]
 +
:*[[FAQ Where are project build specifications stored?]]
 +
:*[[FAQ How do I add a builder to a given project?]]
 +
:*[[FAQ How do I implement an incremental project builder?]]
 +
:*[[FAQ How do I handle setup problems for a given builder?]]
 +
:*[[FAQ How do I make my compiler incremental?]]
 +
:*[[FAQ Language integration phase 3: How do I edit programs?]]
 +
:*[[FAQ How do I write an editor for my own language?]]
 +
:*[[FAQ How do I add Content Assist to my language editor?]]
 +
:*[[FAQ How do I add hover support to my text editor?]]
 +
:*[[FAQ How do I create problem markers for my compiler?]]
 +
:*[[FAQ How do I implement Quick Fixes for my own language?]]
 +
:*[[FAQ How do I support refactoring for my own language?]]
 +
:*[[FAQ How do I create an Outline view for my own language editor?]]
 +
:*[[FAQ Language integration phase 4: What are the finishing touches?]]
 +
:*[[FAQ What wizards do I define for my own language?]]
 +
:*[[FAQ When does my language need its own nature?]]
 +
:*[[FAQ When does my language need its own perspective?]]
 +
:*[[FAQ How do I add documentation and help for my own language?]]
 +
:*[[FAQ How do I support source-level debugging for my own language?]]
 +
 
 +
==== This is a DSL of your own ====
 +
 
 +
In this case, you should consider using [http://www.eclipse.org/Xtext Xtext] to define the language. From the language definition, XText will generate the parser, DOM API, Editors, and most integration in the Eclipse IDE (and also in JetBrains tools). Extensive documentation is available on the XText site linked earlier.
 +
 
 +
==== Legacy ====
 +
 
 +
Through its JDT project, Eclipse has strong support for Java development, such as editing, refactoring, building, launching, and debugging. Likewise, the C development tools (CDT) project aims for similar support for writing C/C++ code, PDT for PHP, Phortran for Fortran, JSDT for JavaScript...
 +
 
 +
This chapter discusses the nuts and bolds with which JDT and CDT are implemented. It is helpful to understand the low level details of how Eclipse works internally. However, as Eclipse Platform has some Common Navigator and Generic Editor, and Eclipse now has the [http://www.eclipse.org/Xtext Xtext] framework implementing support for your own language has become much easier. So this FAQ can somehow be considered as an '''out of date''' recommendation, although the technical parts are still valid.
  
In the following we look at the various ways of integrating with Eclipse: from no integration to a fully integrated language development environment. To structure our discussion, we take a closer look at eScript, an experimental script language developed especially for this book. As is the case for all examples described in this book, you can find eScript on this book’s CD-ROM or Web site (http://eclipsefaq.org).
+
In the following we look at the various ways of integrating with Eclipse: from no integration to a fully integrated language development environment. To structure our discussion, we take a closer look at eScript, an experimental script language developed especially for this book.
  
 
Many questions have been addressed in other FAQs in this book and may be somewhat repetitive. However, if you are planning to implement support for your own programming language, this chapter might serve well as a comprehensive overview of how to approach this big task.
 
Many questions have been addressed in other FAQs in this book and may be somewhat repetitive. However, if you are planning to implement support for your own programming language, this chapter might serve well as a comprehensive overview of how to approach this big task.
Line 461: Line 497:
 
* Phase 1—Compiling code and building projects. To obtain full integration with Eclipse in the area of compilation of programs and build processes for your own language, follow the various steps outlined in the FAQs below.
 
* Phase 1—Compiling code and building projects. To obtain full integration with Eclipse in the area of compilation of programs and build processes for your own language, follow the various steps outlined in the FAQs below.
 
        
 
        
* Phase 2—Implementing a DOM. The DOM is an in-memory structural representation of the source code of a program written in your language. Using the structural information contained in the DOM, all kinds of analysis and refactoring tools can be built.  
+
* Phase 2—Implementing a DOM. The DOM is an in-memory structural representation of the source code of a program written in your language. Using the structural information contained in the DOM, all kinds of analysis and refactoring tools can be built. '''IMPORTANT''': As your language is likely to be used also outside of Eclipse environment, you also need to consider alternative ways to implement the DOM, which aren't tied to Eclipse.
 
        
 
        
* Phase 3—editing programs. After writing a compiler, a builder, and a DOM, you are ready to consider all the individual steps to build the ultimate Eclipse editor for your language.  
+
* Phase 3—editing programs. After writing a compiler, a builder and a DOM; or by reusing existing libraries or services providing necessary features to integrate in the IDE, you are ready to consider all the individual steps to build the ultimate Eclipse editor for your language.  
 
        
 
        
 
* Phase 4—Adding the finishing touches. To give your language IDE a professional look, follow the steps outlined in the FAQs below.  
 
* Phase 4—Adding the finishing touches. To give your language IDE a professional look, follow the steps outlined in the FAQs below.  

Latest revision as of 07:52, 27 February 2024


Note that this FAQ is updated less frequently than this FAQ. You may find your answer there before it makes its way here.

Part I -- The Eclipse Ecosystem

The Eclipse Community

Eclipse has taken the computing industry by storm. The download data for the Eclipse Software Development Kit (SDK) is astounding and a true ecosystem is forming around this new phenomenon. In this chapter we discuss what Eclipse is and who is involved in it and give you a glimpse of how large a community has put its weight behind this innovative technology.

An open source project would be nothing without a supporting community. The Eclipse ecosystem is a thriving one, with many research projects based on Eclipse, commercial products that ship on top of Eclipse, lively discussions in newsgroups and mailing lists, and a long list of articles and books that address the platform. The following pages will give you a roadmap of the community, so that you will feel more at home as you come to wander its winding streets.

Getting Started

Eclipse can be seen as a very advanced Java program. Running Eclipse may sound simple—simply run the included eclipse.exe or eclipse executable—yet in practice, you may want to tweak the inner workings of the platform. First, Eclipse does not come with a Java virtual machine (JVM), so you have to get one yourself. Note that any version later than Eclipse 3.0 needs a 1.4-compatible Java runtime environment (JRE), and the Java 5 JRE is recommended for Eclipse version 3.3.

To use Eclipse effectively, you will need to learn how to make Eclipse use a specific JRE. In addition, you may want to influence how much heap Eclipse may allocate, where it loads and saves its workspace from, and how you can add more plug-ins to your Eclipse installation.

This chapter should get you going. We also included some FAQs for plug-in developers who have already written plug-ins and want to get started with plug-in development for Eclipse 3.0.

Java Development in Eclipse

The topic of how to use Eclipse for typical Java development is beyond the scope of this FAQ list. We focus more on the issues Eclipse users may run into when developing new plug-ins for the platform. Also, as a plug-in developer, you need to be familiar with the ways in which Eclipse is used. To achieve seamless integration with the platform, your plug-in must respect common usage patterns and offer the same level of functionality that users of your plug-in have come to expect from the platform. This chapter focuses on user-level issues of interest to plug-in developers as users or as enablers for other users of the platform.

For a comprehensive guide to using Eclipse, refer to other books such as The Java Developer’s Guide to Eclipse (Addison-Wesley, 2003).

Plug-In Development Environment

This book is all about extending the Eclipse Platform. The main instrument for extending the platform is a plug-in. Plug-ins solidify certain crucial design criteria underlying Eclipse. Special tooling has been developed as part of Eclipse to support the development of plug-ins. This set of plug-ins is called the Plug-in Development Environment; or PDE. The PDE tools cover the entire lifecycle of plug-in development, from creating them using special wizards to editing them to building them to launching them to exporting and sharing them.

This chapter describes the mechanics of plug-in development, such as creating plug-ins, features, and update sites, and introduces the PDE tooling. We go into much more depth about what plug-ins are in later FAQs. If you want to jump ahead, we suggest that you first visit FAQ What is a plug-in?.

Part II -- The Rich Client Platform

All about Plug-ins

Part I discussed the Eclipse ecosystem: how to run it, how to use it, and how to extend it. In this chapter, we revisit the topic of plug-ins and lay the groundwork for all plug-in development topics to be discussed in later chapters. This chapter answers questions about the core concepts of the Eclipse kernel, including plug-ins, extension points, fragments, and more. All APIs mentioned in this chapter are found in the org.eclipse.core.runtime plug-in.


Runtime Facilities

Above, we already discussed most of the basic functionality of the org.eclipse.core.runtime plug-in. This chapter covers the remaining facilities of Eclipse Platform runtime: APIs for logging, tracing, storing preferences, and other such core functionality. These various services, although not strictly needed by all plug-ins, are common enough that they merit being located directly alongside the Eclipse kernel. In Eclipse 3.0, this plug-in was expanded to add infrastructure for running and managing background operations. This chapter answers some of the questions that may arise when you start to use this new concurrency infrastructure.

Standard Widget Toolkit (SWT)

One of the great success stories of the Eclipse Platform has been the overwhelming groundswell of support for its windowing toolkit, SWT. This toolkit offers a fast, thin, mostly native alternative to the most common Java UI toolkits, Swing and Abstract Windowing Toolkit (AWT). Religious debates abound over the relative merits of Swing versus SWT, and we take great pains to avoid these debates here. Suffice it to say that SWT generates massive interest and manages to garner as much, if not more, interest as the Eclipse Platform built on top of it.

The popularity of SWT has forced us to take a slightly different approach with this chapter. The SWT newsgroup was created in July 2003 and since then has generated an average of 136 messages every day. In this book, we could not even scratch the surface of the information available there. Although we could present the illusion of completeness by answering a couple dozen popular technical questions, we would not be doing the topic justice. Instead, we focus on answering a few of the higher-level questions and providing as many forward pointers as we can to further information on SWT available elsewhere. A benefit of SWT’s popularity is the wealth of Web sites, discussion forums, books, and other forms of documentation out there. Thus, although we won’t be able to answer all SWT questions, we hope at least to steer you to the resources that can. However, a handful of questions are asked so often that we can’t resist answering them here.

JFace

JFace is a Java application framework based on SWT. The goal of JFace is to provide a set of reusable components that make it easier to write a Java-based GUI application. Among the components JFace provides are such familiar GUI concepts as wizards, preference pages, actions, and dialogs. These components tend to be the bits and pieces that are integral to the basic widget set but are common enough that there is significant benefit to drawing them together into a reusable framework. Although its heritage is based on a long line of frameworks for writing IDEs, most of JFace is generally useful in a broad range of graphical desktop applications. JFace has a few connections to classes in the Eclipse runtime kernel, but it is fairly straightforward to extract JFace and SWT for use in stand-alone Java applications that are not based on the Eclipse runtime. JFace does not make use of such Eclipse-specific concepts as extensions and extension points.

Generic Workbench

This chapter covers FAQs relating to the generic workbench and its APIs. Workbench is the term used for the generic Eclipse UI. Originally the UI was called the desktop, but because Eclipse was a platform primarily for tools rather than for stationery, workbench was deemed more suitable. In Eclipse 3.0, tools are no longer the sole focus, so the term Rich Client Platform, is starting to creep in as the term for the generic, non-tool-specific UI. After all, people don’t want to play mine sweeper or send e-mails to Mom from such a prosaically named application as a workbench. A rich client, on the other hand, is always welcome at the dinner table.

Many of the important workbench concepts, such as editors, views, and actions, generate enough questions that they deserve their own chapters. This chapter focuses on general questions about integrating your plug-in with the various extension hooks the workbench provides.

Perspectives and Views

This chapter answers questions about two central concepts in the Eclipse Platform UI. Perspectives define the set of actions and parts that appear in a workbench window and specify the initial size and position of views within that window. Views are the draggable parts that make up the bulk of a workbench window’s contents. This chapter does not deal with any specific perspectives or views, but with questions that arise when you implement your own perspectives and views.


Generic Editors

In Eclipse, editors are parts that have an associated input inside a workbench window and additional lifecycle methods, such as save and revert. This chapter answers questions about interacting with editors and about writing your own editors, whether they are text based or graphical. See Chapter 15 for a complete treatment of questions about writing your own text-based editors.


Actions, Commands, and Activities

This chapter answers questions about creating menu bars, context menus, and tool bars and the actions that fill them. A variety of both declarative and programmatic methods are available for contributing actions to the Eclipse UI and for managing and filtering those actions once they have been defined. This chapter also discusses the various ways to execute the long-running tasks that can be triggered by menu and toolbar actions.

Actions are currently considered to be inferior to commands. The following information about actions is still left here to help people which are still using actions. If you can you should use commands.


Building Your Own Application

Prior to the introduction of RCP, most of the Eclipse community was focused on developing plug-ins for a particular Eclipse application called the workbench. Eclipse, however, has always supported the ability to create your own stand alone applications based on the Eclipse plug-in architecture. Eclipse applications can range from simple headless programs with no user interface to full-blown IDEs. In Eclipse 3.0, the platform began a shift toward giving greater power and flexibility to applications built on the Eclipse infrastructure. This chapter guides you through the process of building your own Eclipse application and explores some of the new Eclipse 3.0 APIs available only to applications.

Productizing an Eclipse Offering

In this chapter, we look at turning an Eclipse configuration into a product. When an Eclipse product is created, the anonymous collection of plug-ins takes on application-specific branding, complete with custom images, splash screen, and launcher. In creating your own product, you typically also need to write an installer and uninstaller and consider how your users will obtain and upgrade your product.


Part III -- The Eclipse IDE Platform

Text Editors

The most important purpose of an IDE is to browse and edit code. Therefore, perhaps even more than any other IDE platform, the Eclipse editor framework has grown into a highly evolved, flexible, easy-to-use, and easy-to-extend environment for editing program source files. In this chapter, we look at what support exists for writing editors and how easy it is to plug them into the Eclipse IDE platform.

Help, Search, and Compare

Admittedly, this chapter covers a number of unrelated components in the Eclipse Platform. They have in common the fact that each is designed as an independent plug-in that can be added to any Eclipse-based application. Although they are at home mostly in IDE applications, these plug-ins can also be inserted into RCP applications when help, search, or compare facilities are needed.

Workspace and Resources API

A program is never written in isolation but instead depends on other code, icons, data, and configuration files. An extendable IDE should provide access to wherever these artifacts are stored. In Eclipse, the artifacts are referred to as resources and are stored in a workspace. The FAQs in this chapter show how resources are managed in a workspace and what API is available to control and track their lifecycle.


Workbench IDE

The remaining plug-ins in the Eclipse Platform are truly oriented toward writing development tools. This chapter covers elements of the Eclipse IDE workbench, found in the org.eclipse.ui.ide plug-in. This plug-in includes most of the standard platform views, such as Navigator, Tasks, Problems, Properties, and Bookmark. We also take a quick look at advanced topics, such as writing repository clients and debuggers.


Implementing Support for Your Own Language

The language already has parsers, compilers, and other services

In this case, you can simply reuse them and skip the parts about writing a compiler, a DOM and so on; and focus in integration of the language into the workbench:

The following FAQ may be relevant:

This is a DSL of your own

In this case, you should consider using Xtext to define the language. From the language definition, XText will generate the parser, DOM API, Editors, and most integration in the Eclipse IDE (and also in JetBrains tools). Extensive documentation is available on the XText site linked earlier.

Legacy

Through its JDT project, Eclipse has strong support for Java development, such as editing, refactoring, building, launching, and debugging. Likewise, the C development tools (CDT) project aims for similar support for writing C/C++ code, PDT for PHP, Phortran for Fortran, JSDT for JavaScript...

This chapter discusses the nuts and bolds with which JDT and CDT are implemented. It is helpful to understand the low level details of how Eclipse works internally. However, as Eclipse Platform has some Common Navigator and Generic Editor, and Eclipse now has the Xtext framework implementing support for your own language has become much easier. So this FAQ can somehow be considered as an out of date recommendation, although the technical parts are still valid.

In the following we look at the various ways of integrating with Eclipse: from no integration to a fully integrated language development environment. To structure our discussion, we take a closer look at eScript, an experimental script language developed especially for this book.

Many questions have been addressed in other FAQs in this book and may be somewhat repetitive. However, if you are planning to implement support for your own programming language, this chapter might serve well as a comprehensive overview of how to approach this big task.

Any classification of integration of a new programming language with Eclipse is somewhat arbitrary. We have identified the following degrees of integration of a new programming language, such as eScript, with Eclipse:

  • Phase 1—Compiling code and building projects. To obtain full integration with Eclipse in the area of compilation of programs and build processes for your own language, follow the various steps outlined in the FAQs below.
  • Phase 2—Implementing a DOM. The DOM is an in-memory structural representation of the source code of a program written in your language. Using the structural information contained in the DOM, all kinds of analysis and refactoring tools can be built. IMPORTANT: As your language is likely to be used also outside of Eclipse environment, you also need to consider alternative ways to implement the DOM, which aren't tied to Eclipse.
  • Phase 3—editing programs. After writing a compiler, a builder and a DOM; or by reusing existing libraries or services providing necessary features to integrate in the IDE, you are ready to consider all the individual steps to build the ultimate Eclipse editor for your language.
  • Phase 4—Adding the finishing touches. To give your language IDE a professional look, follow the steps outlined in the FAQs below.

If you carefully observe these four phases, you will find that the visual aspects of your language IDE happen late in the process. You will have to do some legwork before you are able to get to the pretty parts. We recommend patience and restraint. Time spent in phases 1 and 2 will be well spent, and once you get to phase 3 and 4, you will be grateful that you followed all the steps we outlined.

Java Development Tool API

From the outset, Eclipse has been used to develop Eclipse itself. The plug-ins that make up Eclipse are written in Java, and the concept of self-hosting has propelled the JDT to their current maturity level. When you are writing your plug-ins, you will also spend considerable time inside the JDT. A full coverage of JDT’s functionality is way beyond the scope of the list of FAQs in this chapter; however, we do focus on topics that are directly related to writing plug-ins and discuss aspects of JDT that warrant a discussion about how they are implemented rather than used.

It is important to realize that JDT itself has been written as a set of plug-ins and receives no special support from the platform. JDT represents a wealth of knowledge and is by far the most elaborate and advanced set of plug-ins in Eclipse. It is definitely worth spending some time to observe how JDT extends the platform and how its own extension points and API have been designed. It is likely that your plug-ins will deploy very similar patterns of extensions, extendibility, and reuse.

Finally, the JDT is a useful set of plug-ins in its own right, but it has also been carefully designed for extension by other plug-ins. By having a published API, it is easy to create new Java projects, generate Java source code, manage Java builds, inspect and analyze Java projects, and implement special refactorings. Refer to Help > Help Contents > JDT Plug-in Developer Guide for extensive documentation and tutorials describing the extension points and API published by JDT. For a comprehensive guide to Java development using Eclipse, see the Java Developers Guide to Eclipse (Addison-Wesley, 2003).

Where to buy the original book

The initial contents for these FAQ pages has come from The Offical Eclipse 3.0 FAQs written by John Arthorne and Chris Laffra.

Permission to publish the FAQ book contents here has been graciously offered by Addison-Wesley, publishers of the official Eclipse Series which wouldn't be possible without the great help from Greg Doench.

The book can be purchased from Amazon.com

Back to the top