Skip to content

Commit ecefa7d

Browse files
Copilotlaeubi
Copilot
and
laeubi
committed
Add comprehensive README.md for Terminal feature
Co-authored-by: laeubi <[email protected]>
1 parent 24be9b0 commit ecefa7d

File tree

1 file changed

+365
-0
lines changed

1 file changed

+365
-0
lines changed

‎terminal/README.md‎

Lines changed: 365 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,365 @@
1+
# Eclipse Platform Terminal
2+
3+
The Eclipse Platform Terminal provides a comprehensive terminal emulation framework for the Eclipse IDE, enabling users to interact with command-line interfaces directly within the Eclipse workbench.
4+
5+
## Overview
6+
7+
The Terminal feature provides a flexible, extensible terminal emulation system that supports multiple connection types (local processes, SSH, Telnet) and integrates seamlessly with other Eclipse Platform components. It consists of a UI-less terminal model with an asynchronous SWT widget for high-performance terminal operations.
8+
9+
## Architecture
10+
11+
The Terminal feature is organized into several OSGi bundles:
12+
13+
### Core Bundles
14+
15+
#### org.eclipse.terminal.control
16+
The foundation bundle providing the terminal control widget and connector framework.
17+
18+
**Key Features:**
19+
- Terminal widget with ANSI escape sequence support
20+
- Character grid model for terminal display
21+
- Terminal connector extension point (`org.eclipse.terminal.control.connectors`)
22+
- VT100/VT102-compatible terminal emulation (subset)
23+
- Support for screen-oriented applications (vi, Emacs, readline-enabled apps)
24+
25+
**Key APIs:**
26+
- `ITerminalConnector` - Interface for connection type implementations
27+
- `ITerminalControl` - Control interface for terminal operations
28+
- `ITerminalTextData` - Model interface for terminal character data
29+
- `TerminalConnectorExtension` - Extension point for custom connectors
30+
31+
**Extension Point:**
32+
```xml
33+
<extension point="org.eclipse.terminal.control.connectors">
34+
<connector
35+
class="com.example.MyTerminalConnector"
36+
id="com.example.myconnector"
37+
name="My Custom Connector"/>
38+
</extension>
39+
```
40+
41+
#### org.eclipse.terminal.view.core
42+
Core services and APIs for terminal view management.
43+
44+
**Key Features:**
45+
- Terminal service API for programmatic terminal management
46+
- Terminal lifecycle events and listeners
47+
- Context properties framework
48+
- Line separator handling
49+
50+
**Key APIs:**
51+
- `ITerminalService` - Service for opening, closing, and managing terminals
52+
- `ITerminalTabListener` - Listener interface for terminal tab events
53+
- `ITerminalContextPropertiesProvider` - Provider for terminal context properties
54+
55+
**Usage Example:**
56+
```java
57+
// Get the terminal service
58+
ITerminalService terminalService = // obtain via OSGi service
59+
Map<String, Object> properties = new HashMap<>();
60+
properties.put(ITerminalsConnectorConstants.PROP_TERMINAL_CONNECTOR_ID,
61+
"org.eclipse.terminal.connector.local.LocalConnector");
62+
terminalService.openConsole(properties);
63+
```
64+
65+
#### org.eclipse.terminal.view.ui
66+
User interface components for terminal integration in Eclipse workbench.
67+
68+
**Key Features:**
69+
- Terminal view (`TerminalsView`)
70+
- Multiple terminal tabs support
71+
- Terminal launcher framework
72+
- Preferences and settings UI
73+
- "Show In" integration for explorers
74+
- Stream-based terminal support
75+
76+
**Key APIs:**
77+
- `ILauncherDelegate` - Interface for custom terminal launchers
78+
- Terminal launcher delegate extension point (`org.eclipse.terminal.view.ui.launcherDelegates`)
79+
80+
**Extension Point:**
81+
```xml
82+
<extension point="org.eclipse.terminal.view.ui.launcherDelegates">
83+
<delegate
84+
class="com.example.MyLauncherDelegate"
85+
id="com.example.mylauncher"
86+
label="My Custom Launcher">
87+
</delegate>
88+
</extension>
89+
```
90+
91+
**View Integration:**
92+
The terminal view is registered as `org.eclipse.terminal.view.ui.TerminalsView` and appears in:
93+
- Resource Perspective (stacked with Task List)
94+
- Debug Perspective (stacked with Console View)
95+
- Java Perspective (stacked with Problems View)
96+
- PDE Perspective (stacked with Problems View)
97+
98+
### Connector Bundles
99+
100+
#### org.eclipse.terminal.connector.local
101+
Local terminal connector for native shell access.
102+
103+
**Features:**
104+
- Opens system default shell (bash, cmd.exe, etc.)
105+
- PTY (pseudo-terminal) support via CDT utilities
106+
- Working directory context from workspace resources
107+
- "Show In > Terminal" integration for Project/Package Explorer
108+
109+
**Usage:**
110+
- Right-click on a project/folder in Project Explorer
111+
- Navigate > Show In > Terminal
112+
- Opens terminal in the selected resource's directory
113+
114+
#### org.eclipse.terminal.connector.process
115+
Generic process connector for custom command execution.
116+
117+
**Features:**
118+
- Execute arbitrary processes with terminal UI
119+
- Capture stdout/stderr in terminal
120+
- Process environment configuration
121+
- Working directory support
122+
123+
**Key APIs:**
124+
- `ProcessConnector` - Connector for process-based terminals
125+
- `IProcessSettings` - Configuration interface for process execution
126+
127+
#### org.eclipse.terminal.connector.ssh
128+
SSH terminal connector using JSch library.
129+
130+
**Features:**
131+
- SSH connection support
132+
- Password and key-based authentication
133+
- Session management
134+
- Eclipse secure storage integration
135+
136+
**Configuration:**
137+
Users can configure SSH connections via the Terminal view's connection dialog, providing:
138+
- Host and port
139+
- Username
140+
- Authentication method (password or key file)
141+
142+
#### org.eclipse.terminal.connector.telnet
143+
Telnet terminal connector for legacy systems.
144+
145+
**Features:**
146+
- Telnet protocol support
147+
- Connection dialog with host/port configuration
148+
- Session management
149+
150+
## Integration with Other Platform Components
151+
152+
### Debug Framework (org.eclipse.debug.terminal)
153+
154+
The Terminal feature is integrated with the Eclipse Debug framework to provide terminal-based process interaction.
155+
156+
**Key Integration Points:**
157+
158+
1. **Process Factories:**
159+
- `PtyProcessFactory` - Creates terminal-backed process instances
160+
- Extension point: `org.eclipse.debug.core.processFactories`
161+
162+
2. **Exec Factories:**
163+
- `PtyExecFactory` - Provides process execution with PTY support
164+
- Extension point: `org.eclipse.debug.core.execFactories`
165+
166+
3. **Console Integration:**
167+
- `TerminalConsoleFactory` - Creates terminal consoles in Console view
168+
- Extension point: `org.eclipse.ui.console.consoleFactories`
169+
- Accessible via Console view dropdown > "Terminal"
170+
171+
**Benefits:**
172+
- Native shell interaction for debug launches
173+
- Full terminal capabilities for launched processes
174+
- Better support for interactive applications
175+
- Pseudo-terminal (PTY) support for Unix-like behavior
176+
177+
**Usage in Debug Configurations:**
178+
Debug configurations can specify the terminal connector to use for process I/O, enabling full terminal capabilities for launched applications.
179+
180+
### CDT Integration
181+
182+
The Terminal feature uses CDT (C/C++ Development Tools) utilities for platform-specific PTY and process spawning:
183+
- `org.eclipse.cdt.utils.pty` - PTY (pseudo-terminal) support
184+
- `org.eclipse.cdt.utils.spawner` - Native process spawning
185+
186+
Platform-specific fragments are required:
187+
- `org.eclipse.cdt.core.linux.x86_64`
188+
- `org.eclipse.cdt.core.macosx`
189+
- `org.eclipse.cdt.core.win32.x86_64`
190+
- And others for different architectures
191+
192+
## Features and Capabilities
193+
194+
### Terminal Emulation
195+
- **ANSI Control Characters:** NUL, backspace, carriage return, linefeed
196+
- **ANSI Escape Sequences:** Cursor movement, text formatting, colors
197+
- **Screen Support:** Compatible with vi, Emacs, nano, less, top, htop
198+
- **Readline Support:** Full support for GNU readline (used in bash, bc, Python REPL, etc.)
199+
- **Color Support:** 16-color ANSI palette
200+
- **Text Styling:** Bold, underline, reverse video
201+
202+
### User Interface
203+
- **Multiple Tabs:** Support for multiple terminal sessions in one view
204+
- **Tab Naming:** Automatic and custom tab naming
205+
- **Context Menus:** Copy, paste, clear, terminate, close actions
206+
- **Scrollback Buffer:** Configurable history size
207+
- **Text Selection:** Mouse-based text selection and copying
208+
- **Font Configuration:** Customizable terminal font and size
209+
- **Encoding Support:** Configurable character encoding
210+
211+
### Programmatic Access
212+
- **Terminal Service:** Open/close terminals programmatically
213+
- **Connector API:** Create custom connection types
214+
- **Launcher API:** Integrate custom launchers
215+
- **Event Listeners:** Monitor terminal lifecycle events
216+
- **Stream API:** Redirect streams to/from terminals
217+
218+
## Extending the Terminal Feature
219+
220+
### Creating a Custom Terminal Connector
221+
222+
1. **Implement the Connector:**
223+
```java
224+
public class MyConnector extends AbstractTerminalConnector {
225+
@Override
226+
public void connect(ITerminalControl control) {
227+
// Establish connection
228+
// Get streams and connect to terminal
229+
OutputStream terminalToRemote = getTerminalToRemoteStream();
230+
InputStream remoteToTerminal = // your input source
231+
232+
// Start pumping data
233+
// ...
234+
}
235+
236+
@Override
237+
public void disconnect() {
238+
// Clean up connection
239+
}
240+
241+
@Override
242+
public OutputStream getTerminalToRemoteStream() {
243+
return outputStream;
244+
}
245+
}
246+
```
247+
248+
2. **Register via Extension Point:**
249+
```xml
250+
<extension point="org.eclipse.terminal.control.connectors">
251+
<connector
252+
class="com.example.MyConnector"
253+
id="com.example.myconnector"
254+
name="My Connector"/>
255+
</extension>
256+
```
257+
258+
### Creating a Custom Launcher Delegate
259+
260+
1. **Implement the Delegate:**
261+
```java
262+
public class MyLauncherDelegate implements ILauncherDelegate {
263+
@Override
264+
public boolean needsUserConfiguration() {
265+
return true; // Show configuration dialog
266+
}
267+
268+
@Override
269+
public void execute(Map<String, Object> properties,
270+
ILauncherDoneCallback callback) {
271+
// Configure and launch terminal
272+
properties.put(ITerminalsConnectorConstants.PROP_TERMINAL_CONNECTOR_ID,
273+
"com.example.myconnector");
274+
// ...
275+
callback.done(Status.OK_STATUS);
276+
}
277+
}
278+
```
279+
280+
2. **Register via Extension Point:**
281+
```xml
282+
<extension point="org.eclipse.terminal.view.ui.launcherDelegates">
283+
<delegate
284+
class="com.example.MyLauncherDelegate"
285+
id="com.example.mylauncher"
286+
label="My Launcher"/>
287+
</extension>
288+
```
289+
290+
## Configuration and Preferences
291+
292+
Terminal preferences are available at: **Window > Preferences > Terminal**
293+
294+
Key settings:
295+
- **Font:** Terminal display font and size
296+
- **Buffer Size:** Scrollback buffer line limit
297+
- **Encoding:** Character encoding for terminal I/O
298+
- **Invert Colors:** Black-on-white or white-on-black display
299+
- **Local Echo:** Echo characters locally (for certain connector types)
300+
301+
## Building and Testing
302+
303+
### Build Individual Bundles
304+
```bash
305+
cd terminal/bundles/<bundle-name>
306+
mvn clean verify -Pbuild-individual-bundles
307+
```
308+
309+
### Build All Terminal Bundles
310+
```bash
311+
cd terminal
312+
mvn clean verify
313+
```
314+
315+
### Run Tests
316+
```bash
317+
cd terminal/tests/org.eclipse.terminal.test
318+
mvn clean verify -Pbuild-individual-bundles
319+
```
320+
321+
**Note:** Some tests require a graphical display. Use `Xvfb` or `Xvnc` in headless environments.
322+
323+
## Dependencies
324+
325+
### Required Bundles
326+
- Eclipse Platform UI (`org.eclipse.ui`)
327+
- Eclipse Core Runtime (`org.eclipse.core.runtime`)
328+
- Eclipse SWT (`org.eclipse.swt`)
329+
- CDT Core Native utilities (platform-specific)
330+
331+
### Optional Bundles
332+
- `org.eclipse.core.resources` - For workspace integration
333+
- `org.eclipse.debug.ui` - For debug integration
334+
- `org.eclipse.jsch.core` - For SSH support
335+
336+
## Known Limitations
337+
338+
- **VT100/VT102 Compatibility:** Not fully compliant; supports a commonly-used subset
339+
- **Unicode Support:** Limited support for wide characters and combining characters
340+
- **Terminal Size:** May not update properly for some edge cases
341+
- **Platform Dependencies:** Requires platform-specific CDT fragments for PTY support
342+
343+
## Contributing
344+
345+
Contributions to the Terminal feature are welcome! Please follow the [Eclipse Platform contribution guidelines](../../CONTRIBUTING.md).
346+
347+
Key areas for contribution:
348+
- Enhanced VT100/VT102 compatibility
349+
- Additional connector implementations
350+
- Performance improvements
351+
- Unicode and internationalization support
352+
- Additional platform support
353+
354+
## Resources
355+
356+
- **Terminal Control Bundle README:** `bundles/org.eclipse.terminal.control/README.txt`
357+
- **Extension Point Schemas:** `bundles/*/schema/*.exsd`
358+
- **Eclipse Terminal Wiki:** https://wiki.eclipse.org/Terminal
359+
- **Bug Reports:** https://github.com/eclipse-platform/eclipse.platform/issues
360+
361+
## License
362+
363+
This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-2.0/
364+
365+
SPDX-License-Identifier: EPL-2.0

0 commit comments

Comments
 (0)