Run your application on a remote Linux system using the CLI

You may have noticed a process running on your ISS Linux IoT target system named agent. This is a special Eclipse Linux application used by ISS Eclipse to provide remote file copy services. It is used by ISS to copy files from your local Linux build container onto your remote Linux target device.

The oneAPI IoT approach to working with your remote Linux target device is to make use of existing industry standard tools. Rather than using agent to transfer files between your development system and your remote Linux target, we recommend using scp or the tool that works best for your situation to facilitate copying files between your development system and your remote Linux IoT target (for example, a network file share).

NOTE: The scp command is generally distributed as part of the ssh collection of tools on Linux systems, and is usually pre-installed. Likewise, the ssh and scp commands are pre-installed on macOS systems. The OpenSSH version of these tools is pre-installed on Windows 10 version 1809 and later, as well as being present in most WSL (Windows Subsystem for Linux) Linux command-line environments on the latest versions of Windows 10.

Assuming you are using scp to copy the Linux IoT application you have built onto your remote Linux target system, be sure to:

• Enable sshd on the remote Linux IoT target system.

• Install any shared libraries needed by your application onto the remote target.

• Copy the application binaries to the remote using the scp command.

• Use an ssh session to the remote to start your application on the target.

• Remember to chmod 755 your application after the scp to your target.

There are other ways to do this; however, the steps above still generally apply, even if you use another technique to transfer files to your remote system and/or interact with the remote system (for example, VNC or RDP). The steps described above are common if you are working at the command-line. A later section of this documentation will describe how to do this using the Eclipse IDE for C/C++ Developers and the Microsoft* Visual Studio Code* editor.

Debug your application on a remote Linux system at the CLI

Once you have copied your Linux IoT application to your remote Linux target and you are able to run that application on the remote target, you are ready to debug your remote application. There are two ways to debug your remote application using the command line.

Using the ``gdb` debugger <https://www.gnu.org/software/gdb/documentation>`_ remotely:

• ssh into your remote Linux target (establish a remote shell)

• gdb <app-name> in your remote shell to start debugging your remote application

• interact with gdb in your remote shell

Using gdb locally and ``gdbserver` <https://sourceware.org/gdb/current/onlinedocs/gdb/Server.html#Server>`_ remotely:

• $ ssh into your remote Linux target (establish a remote shell)

• $ gdbserver --once :2345 <app-name> in your remote shell to start a remote debug session

• $ gdb <app-name> in your local shell to start a local gdb session

• (gdb) target remote <target-ip-addr>:2345 in your local shell to connect to your remote session

• interact with the gdb debugger in your local shell

IMPORTANT: Ensure that your remote gdbserver and local gdb are the same version.

More details regarding how to connect gdb to the remote gdbserver application can be found in the Connecting to a Remote Target chapter of the The GNU Project Debugger documentation. See also the ``gdb` <https://man7.org/linux/man-pages/man1/gdb.1.html>`_ and ``gdbserver` <https://man7.org/linux/man-pages/man1/gdbserver.1.html>`_ manpages, they are a bit easier to understand when getting started with gdb and gdbserver.

This second approach (gdb locally and gdbserver remotely) is essentially how remote ISS IoT application debugging is performed. ISS uses this approach because it allows Eclipse to connect to a remote debug session by interacting with a local instance of gdb regardless of the host OS on which the ISS instance of Eclipse was running and the availability of ssh on the local host. In the case of ISS that “local instance” of gdb was inside the ISS build container.

Using gdbserver is not absolutely necessary for remote debugging, but is handy when the remote target system has limited resources or the remote system does not have a copy of the debug symbols. They may have been stripped from the binary or access to third-party library symbol files are needed and they are not available on the target system.

NOTE: The instructions above assume you are using the standard gdb that is part of your Linux distribution. The oneAPI Base Toolkit includes an enhanced gdb debugger called gdb-oneapi. This enhanced version of the debugger adds support for registers and instructions that are unique to Intel processors, as well as support for debugging DPC++ GPU applications. For details see Getting Started with the Intel Distribution for GDB.

A later section of this documentation will describe how to remote debug your Linux IoT application using the Eclipse IDE for C/C++ Developers and the Microsoft* Visual Studio Code* editor.

See Also

• Get Started with the Intel oneAPI IoT Toolkit for Linux

• SSH Connection: Password-less Access to a Remote Linux Target Device

• Running an Application Built with Eclipse* on an SSH Target

• Build and Run a Sample Project Using Visual Studio Code

*Other names and brands may be claimed as the property of others.