Difference between revisions of "Linux Tools Project/Remote Tools"

Revision as of 19:47, 16 December 2011

Models

There are 2 remote models that Linux Tools intends to support.

1. Local build, remote execution/profiling/debugging
2. Remote build/execution/profiling/debug

The first model is one whereby the project builds locally but special remote launchers are added that allow the user to perform profiling on a compatible remote target. Compatibility includes the platform, required libraries, and installation requirements. As one can guess, this can be difficult when the host and target machines are maintained separately and some systems are completely incompatible (e.g. ppc vs x86). The remote profiling launcher allows the user to specify a remote location to upload the executable to for the purposes of performing profiling. All results of the profiling are shown in the local Eclipse session. At the moment, only Valgrind has support for this remote launching.

The second model does away with the compatibility requirement by keeping the project source code on the remote target and building/executing remotely. The host Eclipse session can view the project files and results. To the end-user, the project appears for all purposes the same as a local project. The location of the project is set when the project is initially created. For a C/C++ project, the project wizards have a check-box for specifying a location other than in the current workspace. Once checked, the user has a choice of file systems to use to specify the location. When RSE (Remote System Explorer) is installed, the user has a choice of local or rse. Using RSE, a remote location can be specified, assuming that an RSE connection has been registered for this remote target. Registering a remote location via RSE does not mean that a connection has been established yet. With the remote project model, tools are expected to be location-agnostic and handle the remote location internally. This means that there should be no UI changes required and a user that is familiar with how a local project works can easily use a remote project.

Remote Profiling Framework

The remote profiling framework is found in the linuxtools/profiling component. The main feature is org.eclipse.linuxtools.profiling.remote-feature. The feature is currently not built as part of the Linux tools Hudson builds so one must check-out the source from git and either build manually or use within a child Eclipse: see Linux Tools Project/Git for details on checking out code from the Linux tools git repository.

The framework provides a class: org.eclipse.linuxtools.profiling.launch.remote.RemoteConnection. This class is used to upload/download files as well as start execution on the remote platform. The following details the various methods provided:

• public void upload(IPath localPath, IPath remotePath, IProgressMonitor monitor) throws RemoteConnectionException
  • Upload files to remote target directory. This method is recursive. If a local directory is specified as the input, then all folders and files are uploaded to the remote target directory. The remote target directory must exist prior to calling this method or else failure will occur. A RemoteConnectionException is thrown on any failure condition.
• public void download(IPath remotePath, IPath localPath, IProgressMonitor monitor) throws RemoteConnectionException
  • Download a file or folder from a remote system. The method is recursive. If a remote folder is specified, all the contents of the folder are downloaded, including folders, and placed under the directory specified by the localPath variable. It is assumed that any remote non-binary file is UTF-8. A RemoteConnectionException is thrown if any failure occurs.
• public void createFolder(IPath remoteFolderPath, IProgressMonitor monitor) throws RemoteConnectionException
  • Create a folder on the remote system. A RemoteConnectionException is thrown if any failure occurs.
• public int runCommand(String command, IPath remoteWorkingDir, ArrayList<String> output, IProgressMonitor monitor) throws RemoteConnectionException
  • Run a command on the remote system. The return code of the command is returned.
• public void delete(IPath remotePath, IProgressMonitor monitor) throws RemoteConnectionException
  • Remote delete function. This method is recursive. If a remote directory is specified, the remote directory and all its contents are removed. A RemoteConnectionException is thrown if failure occurs for any reason.

For supplementing the UI for the profiler launchers, a tab page is provided: org.eclipse.linuxtools.profiling.launch.remote.RemoteTab. The RemoteTab class is abstract and is meant to be extended. The RemoteTab class presents the user with a list of potential connections to use for the remote execution/profiling and stores whatever choice the user makes inside the ILauncherDelegate instance. The ILauncherDelegate instance is used as input to construct the RemoteConnection class.

The RemoteTab has some callback methods that should be provided by the extending class:

• protected void localCreateControl(Composite top)
  • This callback is called at the end of the createControl method of the RemoteTab and is used to add widgets to the tab such as target location to run/profile the executable or working directory, for example. This is a callback so that the RemoteTab can be in control of the layout of the overall page.
• public void localInitializeFrom(ILaunchConfiguration configuration) throws CoreException
  • This callback is called at initialization and is used to initialize any fields of the tab based on the launch configuration. It is a callback so that the RemoteTab can initialize first and the isInitializing flag of the RemoteTab can be set to false once the callback has returned.

Other methods may be overridden as part of normal inheritance.

An example of extending the RemoteTab can be found in org.eclipse.linuxtools.internal.valgrind.launch.remote.ValgrindRemoteTab found in the Linux Tools profiling/org.eclipse.linuxtools.valgrind.launch.remote plug-in. The tab adds 3 widgets for the end-user to specify the location of the Valgrind binary on the remote target, the remote directory to upload and profile the executable, and the remote location to store the output data into. When the fields are set, the information is stored inside the ILaunchConfigurationWorkingCopy.

        @Override
	public void performApply(ILaunchConfigurationWorkingCopy configuration) {
		super.performApply(configuration);
		configuration.setAttribute(ValgrindRemoteLaunchConstants.ATTR_REMOTE_VALGRINDLOC, valgrindLocText.getText());
		configuration.setAttribute(ValgrindRemoteLaunchConstants.ATTR_REMOTE_DESTDIR, destDirText.getText());
		configuration.setAttribute(ValgrindRemoteLaunchConstants.ATTR_REMOTE_OUTPUTDIR, tmpDirText.getText());
	}

Thus, the launch delegate code only needs to extract these fields from the ILaunchConfiguration attributes.

The ValgrindRemoteTab is added to the UI simply by placing it in the ProfileRemoteLaunchConfigurationTabGroup as follows:

/******************************************************************************* 
 * Copyright (c) 2010 Elliott Baron
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *    Elliott Baron <ebaron@fedoraproject.org> - initial API and implementation
 *******************************************************************************/ 

package org.eclipse.linuxtools.internal.valgrind.launch.remote; 

import org.eclipse.debug.ui.AbstractLaunchConfigurationTab; 
import org.eclipse.linuxtools.internal.valgrind.launch.ValgrindOptionsTab; 
import org.eclipse.linuxtools.profiling.launch.remote.ProfileRemoteLaunchConfigurationTabGroup;

public class ValgrindRemoteLaunchTabGroup extends ProfileRemoteLaunchConfigurationTabGroup { 

  @Override public AbstractLaunchConfigurationTab[] getProfileTabs() { 
    return new AbstractLaunchConfigurationTab[] { new ValgrindRemoteTab(), new ValgrindOptionsTab(false) }; 
  } 

}