AboutLibraryPaths.md

About LD_LIBRARY_PATH and library paths

Background

Libraries are hard. Libraries can be needed for user code, but also to run compilers.

For CE we use a lot of different compilers and environments that need to be separated from the OS's installation, and that makes things more complicated than just building with your standard OS's compiler.

Including header files or equivalent is usually the easy part. If there are binaries involved, things get complicated.

We have a couple of separate stages where we use and mix different techniques to be able to produce the right assembly or executables.

• Compilation without linking
  • The LD_LIBRARY_PATH environment variable is used here to enable the compiler to find the .so files that they need to run.
  • If you're running a local installation, this is usually your own systems' LD_LIBRARY_PATH plus extra things that CE adds through properties.
  • On godbolt.org we always start with an empty LD_LIBRARY_PATH and add what is set in the properties.
• Building an executable or binary
  • We use -Wl,-rpath= (or equivalent rpathFlag) to force library paths into the executable so that they will always find the same .so files no matter where they are run. Usually this also includes lib64 and lib folders that the compiler offers for standard libraries that the toolchain offers.
  • Library paths supplied through -Wl,-rpath= for shared libraries will be able to dynamically link to the right architecture's .so even if multiple paths are given that contain the same .so file.
  • We use -L (or equivalent libpathFlag) to enable the compiler to find both static (.a) and shared (.so) libraries.
  • We always add '.' as a path as well because that's where we put libraries that are downloaded from our Conan server.
  • We use -l (or equivalent linkFlag) to say we want to statically or dynamically link to a named library binary (the compiler and linker decide if it's gonna be static or dynamic).
• Running the executable
  • We use LD_LIBRARY_PATH just in case these are dependencies inherited from the compiler - and for the libraries that are used (also just in case).

Specific properties that are used in certain situations

• Compiler .ldPath
  • is used for LD_LIBRARY_PATH to support running the compiler
  • is used for linking (-Wl,-rpath= and/or -L) during building binaries
  • is used for LD_LIBRARY_PATH to enable the users's executable to find .so files
• Compiler .libPath
  • is used for linking (-Wl,-rpath= and/or -L) during building binaries
  • is used for LD_LIBRARY_PATH to enable the users's executable to find .so files
• Library .libPath
  • is used for linking (-Wl,-rpath= and/or -L) during building binaries
  • is used for LD_LIBRARY_PATH to enable the users's executable to find .so files (just in case)

Example

Say we have the following things in a c++.local.properties file:

compilers=mycl
compiler.mycl.exe=/home/ubuntu/mycl/bin
compiler.mycl.ldPath=/home/ubuntu/mycl/lib/lib64
compiler.mycl.libPath=/home/ubuntu/mycl/lib/lib64:/home/ubuntu/mycl/lib/lib32
compiler.mycl.options=--gcc-toolchain=/home/ubuntu/gcc10
compiler.mycl.includeFlag=-I

libs=mylib
libs.mylib.name=My library
libs.mylib.path=/home/ubuntu/mylib/include
libs.mylib.libpath=/home/ubuntu/mylib/lib
libs.mylib.staticliblink=mylib

This will result in the following situations if we want to compile some code with both the mycl compiler and the mylib library:

• Compilation without linking
  • LD_LIBRARY_PATH is set to /home/ubuntu/mycl/lib/lib64
  • -I/home/ubuntu/mylib/include is added to the compilation arguments
• Building an executable or binary
  • LD_LIBRARY_PATH is set to /home/ubuntu/mycl/lib/lib64
  • The following are added to the compilation arguments
    • -I/home/ubuntu/mylib/include (library include path)
    • -Wl,-rpath=/home/ubuntu/mycl/lib/lib64 (compiler library paths)
    • -Wl,-rpath=/home/ubuntu/mycl/lib/lib32
    • -Wl,-rpath=. (conan library path)
    • -L.
    • -Wl,-rpath=/home/ubuntu/gcc10/lib/lib (gcc toolchain library paths)
    • -Wl,-rpath=/home/ubuntu/gcc10/lib/lib32
    • -Wl,-rpath=/home/ubuntu/gcc10/lib/lib64
    • -Wl,-rpath=/home/ubuntu/mylib/lib (mylib library path - just in case there are .so files used)
    • -L/home/ubuntu/mylib/lib (mylib library path used to find libmylib.a)
    • -lmylib (mylib library name)
• Running the executable
  • LD_LIBRARY_PATH is set to /home/ubuntu/mycl/lib/lib64:/home/ubuntu/mycl/lib/lib32:/home/ubuntu/mylib/lib