Developer Guide

  • 2021.3
  • 06/10/2021
  • Public Content

Deploying and Debugging Your Application on a Remote Linux Machine

An Intel® System Studio (ISS) Eclipse* Linux* IoT project utilizes a Docker* container to build
and
remotely debug your Linux IoT project. The previous section described how to convert your ISS Eclipse IoT project into a Linux command-line (CLI) project that you can build using the
make
command. The following instructions describe how to setup your Linux IoT project for remote deployment and debugging.
NOTE:
The following can be skipped if you plan to use your Linux build system to also run and debug your Linux IoT application.

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.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.