Target Communication Framework: Getting Started

Copyright (c) 2007-2019 Wind River Systems, Inc. and others. Made available under the EPL 2.0
Agent portion made available under your choice of EPL 2.0 or EDL v1.0 dual-license.

Direct comments, questions to the tcf-dev@eclipse.org mailing list

Table of Contents

• Creating an Eclipse Workspace for Development
• TCF Plugins
• Target Explorer Plugins
• Building TCF Agent
• TCF Integration with Python
• TCF Integration with Lua
• Browsing Agent Source Code in CDT
• Using TCF With Target Explorer
• Using TCF With Eclipse Debugger
• Using TCF With Remote System Explorer

Creating an Eclipse Workspace for Development

Eclipse can be used for developing clients for TCF in Java. The TCF host side code is organized into several Eclipse plug-in projects, below are steps to create and populate an Eclipse workspace with TCF projects:

• Install JDK 1.8.0 or later
• Install Eclipse SDK 3.8.2 or later
  https://download.eclipse.org/eclipse/downloads/
• Run Eclipse:

  eclipse.exe -vm <JDK path>/bin/javaw.exe -data <Workspace path> -vmargs -Xmx1024M

• Open the "Java" perspective.
• In "Package Explorer" view: do right click and then select "Import...".
  • If EGit is installed, choose "Git", otherwise choose "General/Existing Projects into Workspace" and click "Next".
  • Clone TCF Java code from Eclipse GIT repository. If you intend contributing, best get an account from Eclipse Gerrit, sign the CLA, and use the https: URL with your username below. Alternatively, anonymous access is possible as well from any of the below:

    git clone https://git.eclipse.org/r/tcf/org.eclipse.tcf.git
    git clone ssh://<user>@git.eclipse.org:29418/tcf/org.eclipse.tcf.git
    

• Setting the Target Platform:
  • For import, select root directory: <TCF Root>/admin, and click "Next".
  • From the (admin project)/target-defs/*.target , choose the intended Target Platform and "Open With" > "Target Editor"
  • In the Target Editor, choose "Reload" and "Set as Target Platform". This pulls in all required as well as optional dependencies, along with SWTBot for testing:
    • Optional dependencies for TCF/CDT and TCF/RSE integration: these are not required by TCF itself or TCF based debugger.
      • CDT (C/C++ Development Tools) SDK 8.3.0 or later
        https://www.eclipse.org/cdt/downloads.php
      • RSE (Remote System Explorer) SDK 3.4 or later
        https://download.eclipse.org/tm/downloads/
• In "Package Explorer" view: do right click and then select "Import...".
• Select "General/Existing Projects into Workspace" and click "Next".
• Select root directory: <TCF Root>/plugins, and click "Next".
  • If CDT is not installed, don't import the following plugins into your workspace:
    • org.eclipse.tcf.cdt.ui
  • If RSE is not installed, don't import the following plugins into your workspace:
    • org.eclipse.tcf.rse
• Optional: From Window > Preferences > PDE > API Baselines, pick the admin/target-defs/tcf-baseline.target, to get proper warnings and errors about proper API versioning and @since tags.

TCF Plugins

TCF plugins source code is stored in <TCF Root>/plugins directory.
Examples source code is stored in <TCF Root>/examples directory.

org.eclipse.tcf

This is the main TCF plugin. It contains Eclipse integration code for the framework. It is the only TCF plugin, which (together with its fragments) should be required by a TCF client. The rest of TCF plugins are clients developed as a reference implementation or for demonstration purposes.

org.eclipse.tcf.core

This is a fragment of org.eclipse.tcf plugin. It contains the framework itself and interfaces for standard services. The Java code in the fragment does not have any Eclipse dependencies and can be used outside Eclipse.

org.eclipse.tcf.debug, org.eclipse.tcf.debug.ui

This code connects Eclipse Debug Framework and Target Communication Framework. It allows to launch Eclipse debug session by connecting to a target running TCF agent, and then perform basic debugging tasks, like resuming, suspending, single-stepping, setting/removing breakpoints, etc. The code can be used as a reference for developing new TCF clients.

org.eclipse.tcf.rse

This optional plugin allows Remote System Explorer (RSE) to connect to remote machines using TCF as communication protocol. It includes implementation of RSE services as TCF clients.

org.eclipse.tcf.cdt.ui

This optional plugin improves integration between CDT and TCF debugger. It helps to search for CDT projects and executable files when creating TCF launch configuration.

org.eclipse.tcf.examples.daytime

This is an example plugin. The Example shows how TCF/Java binding can be extended for a new, user defined service. The plugin provides Java binding for DayTime service. Also, see directory <TCF Root>/examples/org.eclipse.tcf.examples.daytime.agent for example code of a customized TCF agent, which implements DayTime service.

Pre-built TCF plugins are available at Eclipse Update site/p2 repositories. The repositories can be accessed from Eclipse using Help/Install New Software command.

• TCF 1.7 maintenance build, requires Eclipse 3.8 or later: https://download.eclipse.org/tools/tcf/builds/1.7/nightly
• TCF latest development build: https://download.eclipse.org/tools/tcf/builds/development/nightly

Target Explorer Plugins

Target Explorer plugins source code is stored in the <TCF Root>/target_explorer/plugins directory.

• Target Explorer 1.7 maintenance build, requires Eclipse 3.8 or later: https://download.eclipse.org/tools/tcf/builds/1.7/nightly
• Target Explorer latest development build: https://download.eclipse.org/tools/tcf/builds/development/nightly

Building TCF Agent

git clone https://git.eclipse.org/r/tcf/org.eclipse.tcf.agent.git
git clone ssh://<user>@git.eclipse.org:29418/tcf/org.eclipse.tcf.agent.git

CDT can be used to build TCF agent. CDT .project file is located in <TCF Root>/agent directory.

Linux: To build the agent:

• Check that SSL and UUID libraries are installed. Fedora package names are: openssl, openssl-devel, libuuid, libuuid-devel.
• Run make command in <TCF Root>/agent directory.
• Start agent:

  obj/GNU/Linux/i686/Debug/agent -L- -l0

  Use other -l option values to increase agent log details level.

Windows: For building the agent, there are two possibilities:

• Building with gcc (freely available from Wascana, Cygwin or the MinGW32 project): run

  make

  or

  make OPSYS=Msys

  in the agent directory.
• Building with Microsoft Visual C++: open workspace file <TCF Root>/agent/msvc/agent-vc2015.sln and then build and run the agent using Development Studio commands. If getting an error about

TCF Integration with Python

The TCF integration with Python allows writing TCF client and server programs in the Python programming lanugage. TCF Python code is stored in <TCF Root>/python directory.

TCF Integration with Lua

The TCF integration with Lua allows writing TCF client and server programs in the Lua programming lanugage. See TCF Lua Integration for details.

Browsing Agent Source Code in CDT

On Windows, open Project Properties of the agent project, and under C/C++ General > Indexer switch the configuration to "Win32 - Cygwin" or "Win32 - DevStudio" as needed.

For VxWorks, browsing should be configured automatically through the WR Workbench Kernel Module Project.

Using TCF With Target Explorer

The Target Explorer aims to create a lightweight but highly flexible and extensible remote system management framework. The focus is on TCF remote system management, but is by no means limited to it. The Target Explorer comes with full remote file system and remote process support, and allows to connect a terminal to the remote system using TCF, SSH, Telnet and serial line.

If building from source, import all org.eclipse.tcf.te.* plug-in's to enable the Target Explorer.

Since Eclipse version 3.8, Target Explorer is available for download from main Eclipse p2 repository. The feature name is "Mobile and Device Development / Target Explorer, TCF".

To connect a remote machine over TCF:

• Make sure TCF agent is running on remote machine.
• Run Eclipse with Target Explorer and TCF plugins installed.
• In Eclipse, do "Window/Open Perspective/Target Explorer" command.
• If the remote machine is on the same subnet as the host, than expand the "Neighborhood" and/or "My Targets" nodes in the "Target Explorer" view to select the remote machine.
• If the remote machine is not on the same subnet as the host, In "Target Explorer" view: press "CTRL+N" or click on the "New wizard" button in the views toolbar.
• In "New" dialog box: select "Peer" and press "Next" button.
• In the upcoming editor window, enter the "Peer Name" and "Host" - IP host name of the target machine. Press "CTRL+S" to save the connection properties.
• New tabs "File System" and "Processes" should appear in editor.
  • To add the remote file system tree and/or running processes directly into the "Target Explorer" view, select "Content..." from the views menu and enable "File System" and/or "Processes".

Using TCF With Eclipse Debugger

Plugins org.eclipse.tcf.debug and org.eclipse.tcf.debug.ui allow to start a debug session by connecting to a machine runnning TCF agent. Plugin org.eclipse.tcf.cdt.ui handles integration of the debugger with CDT UI.

Since Eclipse version 3.8, TCF Debugger is available for download from main Eclipse p2 repository. The feature name is "Mobile and Device Development / Target Communication Framework, CDT Extender".

To start a debug session over TCF:

• Make sure TCF agent is running on remote machine.
• Run Eclipse with TCF plugins installed.
• In Eclipse, do "Window/Open Perspective/Debug" command.
• Do "Run/Debug Configurations..." command.
• In "Debug Configurations" dialog box: select "Target Comminucation Framework" configuration type and press "New" button.
• Enter a name for the configuration.
• On "Target" page, uncheck "Run instance of..." and "Use local host...".
• Select a target machine in "Available targtes" list. The list shows targets autodetected on local network.
• Press "Run Diagnostics" button to test connectivity for selected target.
• On "Main" page, enter a program name to run in debug session, for example "/bin/ls".
• Press "Debug" to start the debugger.

The TCF Debugger implements advanced, asynchronous, transaction based retrieval and caching of remote data. The technology allows excellent data coherency and communication performance.

The debugger fully supports multi-threaded, multi-process, multi-core, whole system and multi-system debugging in a single debug session.

In TCF debug session, "Debug", "Breakpoints", "Registers", "Variables", "Expressions", "Memory" and "Modules" views are populated by the TCF debugger. "Disassembly" view and instruction level stepping are available if the agent supports it. Reverse execution is available if the agent supports it. TCF Trace view can be used to display TCF communication traffic. Remote process standard I/O is redirected to the Console view. Source level debugging is fully supported.

Using TCF With Remote System Explorer

Remote System Explorer is an Eclipse based component that allows users to create connections to remote machines and explore their file systems, see list of processes and access some other resources, like remote shells. Remote System Explorer has been designed as a flexible, extensible framework to which Eclipse plug-in developers can contribute their own system definitions, actions, etc.

Plugin org.eclipse.tcf.rse enables use of Processes, Shells, Terminals and Files subsystems of Remote System Explorer over TCF. It also extends Processes subsystem to include CPU utilization data and some other process attributes in RSE views.

Since Eclipse version 3.8, TCF-RSE is available for download from main Eclipse p2 repository. The feature name is "Mobile and Device Development / Target Communication Framework, RSE Extender".

To connect a remote machine over TCF:

• Make sure TCF agent is running on remote machine.
• Run Eclipse with RSE and TCF plugins installed.
• In Eclipse, do "Window/Open Perspective/Remote System Explorer" command.
• In "Remote Systems" view: do right click and select "New/Connection..."
• In "New Connection" dialog box: select TCF and press "Next" button.
• Enter "Host name" - IP host name of the target machine, and "Connection name" - arbitrary string to name new connection. Press "Finish" button.
• New connection should appear in "Remote Systems" view and it is ready to be explored.

RSE features supported by TCF connection:

• File Subsystem: full support, i.e. browse, upload, download, copy, move, delete
• Processes: browse, including parent/child relationship
• Terminals and Shells: supported, but without authentication, TCF terminal and shell inherit credentials of the TCF agent.