3.6. Using Sourcery G++ Lite on GNU/Linux Targets
Prev | Chapter 3. Sourcery G++ Lite for ARM GNU/Linux | Next

## 3.6. Using Sourcery G++ Lite on GNU/Linux Targets

In order to run and debug programs produced by Sourcery G++ on a GNU/Linux target, you must install runtime support files on the target. You may also need to set appropriate build options so that your executables can find the correct dynamic linker and libraries at runtime.

The runtime support files, referred to as the sysroot, are found in the `arm-none-linux-gnueabi/libc` directory of your Sourcery G++ Lite installation. The sysroot consists of the contents of the `etc`, `lib`, `sbin`, and `usr` directories. There may be other directories in `arm-none-linux-gnueabi/libc` that contain additional sysroots customized for particular combinations of command-line compiler flags, or multilibs. Refer to Section 3.2, “Library Configurations” for a list of the included multilibs in this version of Sourcery G++ Lite, and the corresponding sysroot directory pathnames.

### Note for Windows Host Users

The sysroots provided in Windows host packages for Sourcery G++ are not directly usable on the GNU/Linux target because of differences between the Windows and GNU/Linux file systems. Some files that are hard links, or copies, in the sysroot as installed on the Windows file system should be symbolic links on the GNU/Linux target. Additionally, some files in the sysroot that should be marked executable on the GNU/Linux target are not marked executable on Windows. If you intend to use the sysroot provided with Sourcery G++ on a Windows host system as the basis for your GNU/Linux target filesystem, you must correct these issues after copying the sysroot to the target.

You have these choices for installing the sysroot on the target:

- You can install the files in the filesystem root on the target (that is, installing the files directly in `/etc/`, `/lib/`, and so on). All applications on the target then automatically use the Sourcery G++ libraries. This method is primarily useful when you are building a GNU/Linux root filesystem from scratch. If your target board already has a GNU/Linux filesystem installed, overwriting the existing C library files is not recommended, as this may break other applications on your system, or cause it to fail to boot.

- You can install the sysroot in an alternate location and build your application with the `-rpath` and `--dynamic-linker` linker options to specify the sysroot location.

- You can install the sysroot in an alternate location and explicitly invoke your application through the dynamic linker to specify the sysroot location. If you are just getting started with Sourcery G++ Lite, this may be the easiest way to get your application running, but this method does not support use of the debugger.

Setting the environment variable `LD_LIBRARY_PATH` on the target is not sufficient, since executables produced by Sourcery G++ depend on the Sourcery G++ dynamic linker included in the sysroot as well as the Sourcery G++ runtime libraries.

### 3.6.1. Installing the Sysroot

If you are modifying an existing system, rather than creating a new system from scratch, you should place the sysroot files in a new directory, rather than in the root directory of your target system.

If you choose to overwrite your existing C library, you may not be able to boot your system. You should back up your existing system before overwriting the C library and ensure that you can restore the backup even with your system offline.

The next step is to identify the correct sysroot subdirectory in the Sourcery G++ Lite install directory on your host system. The sysroot you copy to the target must be the one that corresponds to the linker options you are using to build your applications. The tables in Section 3.2, “Library Configurations” tell you which sysroot subdirectories correspond to which sets of command-line options. From the command line, you can identify the appropriate sysroot for your program by invoking the compiler with `-print-sysroot` added to your other build options. This causes GCC to print the host sysroot pathname and exit.

The mechanism you use for copying the sysroot to your target board depends on its hardware and software configuration. You may be able to use FTP or SSH with a server already running on your target. If your target board does not have networking configured, you may be able to copy files using an SD card or USB memory stick, or via a file transfer utility over a serial line. The instructions that come with your board may include specific suggestions.

When running Sourcery G++ on a GNU/Linux host, as an alternative to copying files to the target system, you may be able to NFS-mount the Sourcery G++ Lite installation directory from your host system on the target system. It is especially convenient for debugging if you can make the sysroot pathname on the target system be identical to that on the GNU/Linux host system; refer to Section 3.7.3, “Setting the Sysroot in the Debugger” for further discussion of this issue.

Otherwise, you must copy files from the appropriate sysroot subdirectory in the `arm-none-linux-gnueabi/libc` directory of your Sourcery G++ Lite install to the target system. In many cases, you do not need to copy all of the files in the sysroot. For example, the `usr/include` subdirectory contains files that are only needed if you will actually be running the compiler on your target system. You do not need these files for non-native compilers. You also do not need any `.o` or `.a` files; these are used by the compiler when linking programs, but are not needed to run programs. You should definitely copy all `.so` files and the executable files in `usr/bin` and `sbin`.

### 3.6.2. Using Linker Options to Specify the Sysroot Location

If you have installed the sysroot on the target in a location other than the file system root, you can use the `-rpath` and `--dynamic-linker` linker options to specify the sysroot location.

If you are using Sourcery G++ from the command line, follow these steps:

1. First find the correct sysroot directory, dynamic linker, and library subdirectory for your selected multilib. Refer to Section 3.2, “Library Configurations”. In the following steps, `sysroot` is the absolute path to the sysroot directory on the target corresponding to your selected multilib. For the default multilib, the dynamic linker path relative to the sysroot is `lib/ld-linux.so.3`, and the library subdirectory is `lib`. This is used in the example below.

2. When invoking `arm-none-linux-gnueabi-gcc` to link your executable, include the command-line options:

       -Wl,-rpath=sysroot/lib:sysroot/usr/lib \
       -Wl,--dynamic-linker=sysroot/lib/ld-linux.so.3

   where `sysroot` is the absolute path to the sysroot directory on the target corresponding to your selected multilib.

3. Copy the executable to the target and execute it normally.

Note that if you specify an incorrect path for `--dynamic-linker`, the common failure mode seen when running your application on the target is similar to

    > ./factorial
    ./factorial: No such file or directory

or

    > ./factorial
    ./factorial: bad ELF interpreter: No such file or directory

This can be quite confusing since it appears from the error message as if it is the `./factorial` executable that is missing rather than the dynamic linker it references.

### 3.6.3. Specifying the Sysroot Location at Runtime

You can invoke the Sourcery G++ dynamic linker on the target to run your application without having to compile it with specific linker options.

To do this, follow these steps:

1. Build your application on the host, without any additional linker options, and copy the executable to your target system.

2. Find the correct sysroot directory, dynamic linker, and library subdirectory for your selected multilib. Refer to Section 3.2, “Library Configurations”. In the following steps, `sysroot` is the absolute path to the sysroot directory on the target corresponding to your selected multilib. For the default multilib, the dynamic linker is `lib/ld-linux.so.3`, and the library subdirectory is `lib`. This is used in the example below.

3. On the target system, invoke the dynamic linker with your executable as:

       > sysroot/lib/ld-linux.so.3 \
         --library-path sysroot/lib:sysroot/usr/lib \
         /path/to/your-executable

   where `sysroot` is the absolute path to the sysroot directory on the target corresponding to your selected multilib.

   Invoking the linker in this manner requires that you provide either an absolute pathname to your executable, or a relative pathname prefixed with `./`. Specifying only the name of a file in the current directory does not work.

Prev | Up | Next
3.5. Target Dynamic Loader Requirements | Home | 3.7. Using GDB Server for Debugging