1. Overview

In this tutorial, we’ll discuss sysroot and ways of tweaking it when calling the compiler.

2. Sysroot

Besides our own code files, compilers use many other files to generate their outputs. For instance, in order to generate programs, object files, and other sorts of outputs, C and C++ compilers search for headers and libraries.

By default, the compiler searches for those files in standard locations. However, we may want to use alternative directories. For instance, when cross-compiling binaries targeted at other platforms or when preparing experimental builds using non-standard headers and/or libraries.

The sysroot directory works as a root for headers and libraries. So, let’s consider that headers and libraries are searched by default under /usr/include/ and /usr/lib/, respectively. By defining the sysroot as /home/dir, the compiler will now look for headers and libraries under, respectively, /home/dir/usr/include/ and /home/dir/usr/lib/ instead.

3. Setting the sysroot

The options discussed below refer to the gcc compiler. However, the concept of sysroot is not exclusive of gcc. It isn’t even exclusive of C/C++ compilers in general: there are other languages whose compilers also employ the concept of sysroot and provide ways of changing it.

3.1. The –sysroot and -isysroot Options

The –sysroot=<dir> option tells the compiler to prepend both header and library default directories with <dir>. This option affects the linker too since it also changes the search location for libraries. Then, the linker also has to support this option. The GNU Linker (the ld program) supports sysroot since version 2.16. For other linkers, we must take a look at their respective docs.

In the example below, gcc will use /home/baeldung as the root for searching headers and library files:

$ gcc hello.c --sysroot=/home/baeldung

The -isysroot <dir> option works like –sysroot, but it affects only the root directory for header files.

The following example illustrates the -isysroot option. In this call, gcc will use /home/baeldung as the root for searching header files, but libraries will still be searched in the standard directories:

$ gcc hello.c -isysroot /home/baeldung

Notice that -isysroot is single-dashed. Then, it follows a convention other than –sysroot’s: there’s no equal symbol (=) between the option’s name and its value.

Defining both –sysroot and -isysroot is allowed. In that case, -isysroot will affect header search directories, while –sysroot will affect library ones.

3.2. Using the = and $SYSROOT Placeholders

The -I, -iquote, -isystem, and -idirafter options also provide ways of referencing sysroot. We just need to prepend their arguments with either ‘=’ or ‘$SYSROOT’ when setting search directories for those options. This way, they will work as placeholders for sysroot.

Let’s take the following C file:

#include <stdio.h>
#include "baeldung.h"

int main(int argc, char* argv[]) {
    printf("Hello world!\n");
    return 0;

And the following command:

$ gcc hello.c -isysroot /home/baeldung -iquote '$SYSROOT/quoted/'

Now, let’s dissect the command above:

  • The -isysroot /home/baeldung sets /home/baeldung as a sysroot for header file searches
  • The -iquote option sets an alternate path for header files included with the quoted form of the #include directive. The file baeldung.h in our sample C file has been referenced using the quoted form. Then, it will be affected by this option
  • ‘$SYSROOT/quoted/’ will expand to /home/baeldung/quoted/

Notice that we’ve used single quotes around ‘$SYSROOT/quoted/’. If we have used double quotes, $SYSROOT would have been processed as an environment variable by the shell.

The equals symbol (=), which also can be used as a placeholder for sysroot, wouldn’t suffer from that issue. The following command performs the same function as the example above:

$ gcc hello.c -isysroot /home/baeldung -iquote "=/quoted/"

4. Conclusion

In this short article, we’ve discussed the concept of sysroot, common motivations for changing it, and available options for setting alternative sysroots on the gcc compiler.

Comments are open for 30 days after publishing a post. For any issues past this date, use the Contact form on the site.