Installation and Integration¶

SDK¶

For each platform supported by LIEF, SDK packages contain:

static and shared libraries
headers
compiled examples

Nightly build can be downloaded on: https://lief.s3-website.fr-par.scw.cloud/latest/sdk while releases are available on Github release page: https://github.com/lief-project/LIEF/releases.

Python¶

Nightly Python wheels are uploaded for each commit on the main branch in a S3 bucket. They can be installed through:

$ pip install [--user] --index-url https://lief.s3-website.fr-par.scw.cloud/latest lief

For tagged releases, the wheels are uploaded on PyPI and can by installed through:

$ pip install lief

One can also compile and install from source as follows

$ git clone https://github.com/lief-project/LIEF
$ pip install LIEF/api/python
# Or pip+git:
$ pip install git+https://github.com/lief-project/LIEF.git#subdirectory=api/python

For more details about the compilation options, see the Compilation section.

Rust¶

One can add LIEF as a dependency of a Rust project as follows:

# For nightly build
[dependencies]
lief = { git = "https://github.com/lief-project/LIEF", branch = "main" }

# For a tagged release
[dependencies]
lief = "0.16.0"

You can find more details in the Rust API section

CMake Integration¶

There are a few ways to integrate LIEF as a dependency in another project. The different methods are listed in order of preference and CMake best practice. These listings are only to show basic examples. Please refer to the CMake documentation for questions related to more complex project setup.

find_package()¶

Using CMake find_package():

# Use LIEF with 'find_package()'
# ==============================

# Find LIEF. If LIEF was not installed into a default system directory then
# specify the following option during CMake configuration:
# -DLIEF_DIR=<LIEF install prefix>/share/LIEF/cmake
find_package(LIEF REQUIRED COMPONENTS STATIC) # COMPONENTS: <SHARED | STATIC> - Default: STATIC

And now, to be integrated within a project:

# Add our executable
# ==================
add_executable(HelloLIEF main.cpp)

# Enable C++11
set_property(TARGET HelloLIEF
             PROPERTY CXX_STANDARD           11
             PROPERTY CXX_STANDARD_REQUIRED  ON)

# Link the executable with LIEF
target_link_libraries(HelloLIEF PRIVATE LIEF::LIEF)

For the compilation:

$ mkdir build
$ cd build
$ cmake -DLIEF_DIR=<PATH_TO_LIEF_INSTALL_DIR>/lib/cmake/LIEF/ ..
$ make
$ HelloLIEF /bin/ls # or explorer.exe or whatever

A full example is available in the examples/cmake/find_package directory.

add_subdirectory() or FetchContent¶

First, set up the options you want to set as default for the LIEF project:

# LIEF build config. Set the default options for LIEF's project setup
option(LIEF_DOC "Build LIEF docs" OFF)
option(LIEF_PYTHON_API "Build LIEF Python API" OFF)
option(LIEF_EXAMPLES "Build LIEF examples" OFF)
option(LIEF_TESTS "Build LIEF tests" OFF)

if(MSVC)
  set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded" CACHE STRING "CRT option")
endif()


# If you have LIEF as a submodule in a directory, then you can add it to this

Using CMake add_subdirectory() to add a submodule LIEF source directory:

# NOTE: This submodule does not exist for this example, but it does the same
# thing as FetchContent without the download part
set(vendorLIEF_submodule_dir "${CMAKE_CURRENT_LIST_DIR}/LIEF")
if(EXISTS "${vendorLIEF_submodule_dir}")
  add_subdirectory("${vendorLIEF_submodule_dir}")

# Else, we'll specify how to obtain LIEF another way (downloading)
else()

If we are using a CMake version greater than or equal to 3.11, we can use CMake FetchContent module to download or specify a LIEF source directory outside of the current directory:

  # URL of the LIEF repo (Can be your fork)
  set(LIEF_GIT_URL "https://github.com/lief-project/LIEF.git")

  # LIEF's version to be used (can be 'main')
  set(LIEF_VERSION 0.13.0)

  include(FetchContent)
  FetchContent_Declare(LIEF
    GIT_REPOSITORY  "${LIEF_GIT_URL}"
    GIT_TAG         ${LIEF_VERSION}
    # You may specify an existing LIEF source directory if you don't want to
    # download. Just comment out the above ``GIT_*`` commands and uncoment the
    # following ``SOURCE_DIR`` line
    #SOURCE_DIR      "${CMAKE_CURRENT_LIST_DIR}/../../.."
    )

  if(${CMAKE_VERSION} VERSION_LESS "3.14.0")
    # CMake 3.11 to 3.13 needs more verbose method to make LIEF available
    FetchContent_GetProperties(LIEF)
    if(NOT LIEF_POPULATED)
      FetchContent_Populate(LIEF)
      add_subdirectory(${LIEF_SOURCE_DIR} ${LIEF_BINARY_DIR})
    endif()
  else()
    # CMake 3.14+ has single function to make LIEF available (recommended)
    FetchContent_MakeAvailable(LIEF)
  endif()
endif()

And now, to be integrated within a project:

add_executable(HelloLIEF main.cpp)

# Enable C++11
set_property(TARGET HelloLIEF
             PROPERTY CXX_STANDARD           11
             PROPERTY CXX_STANDARD_REQUIRED  ON)

# Link the executable with LIEF
target_link_libraries(HelloLIEF PUBLIC LIEF::LIEF)

For the compilation:

$ mkdir build
$ cd build
$ cmake ..
$ make
$ HelloLIEF /bin/ls # or explorer.exe or whatever

A full example is available in the examples/cmake/add_subdirectory directory.

External Project¶

If you don’t want to use LIEF as a submodule or upgrade to CMake 3.11, we can use CMake External Project to set up a project as a *superbuild*:

cmake_minimum_required(VERSION 3.21)

project(CMakeLIEF LANGUAGES NONE)

include(ExternalProject)

# LIEF integration as an External Project
# ===========================
set(LIEF_PREFIX       "${CMAKE_CURRENT_BINARY_DIR}/LIEF")
set(LIEF_INSTALL_DIR  "${LIEF_PREFIX}/install")

# URL of the LIEF repo (Can be your fork)
set(LIEF_GIT_URL "https://github.com/lief-project/LIEF.git")

# LIEF's version to be used (can be 'main')
set(LIEF_VERSION 0.13.0)

# LIEF compilation config
set(LIEF_CMAKE_ARGS
  -DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>
  -DCMAKE_BUILD_TYPE=RelWithDebInfo
  -DLIEF_DOC=OFF
  -DLIEF_PYTHON_API=OFF
  -DLIEF_EXAMPLES=OFF
  -DLIEF_TESTS=OFF
)

if(MSVC)
  list(APPEND ${LIEF_CMAKE_ARGS} -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded)
endif()

ExternalProject_Add(LIEF
  PREFIX           "${LIEF_PREFIX}"
  GIT_REPOSITORY   "${LIEF_GIT_URL}"
  GIT_TAG          ${LIEF_VERSION}
  # You may specify an existing LIEF source directory if you don't want to
  # download. Just comment out the above ``GIT_*`` commands and uncoment the
  # following ``SOURCE_DIR`` line
  #SOURCE_DIR       "${CMAKE_CURRENT_LIST_DIR}/../../.."
  INSTALL_DIR      "${LIEF_INSTALL_DIR}"
  CMAKE_ARGS       ${LIEF_CMAKE_ARGS}

And now, to be integrated with our main HelloLIEF project that is located in a subdirectory and looks exactly like the find_package() example shown earlier:

# User project
# ============
ExternalProject_Add(HelloLIEF
  DEPENDS         LIEF
  SOURCE_DIR      "${CMAKE_CURRENT_LIST_DIR}/HelloLIEF"
  BINARY_DIR      "${CMAKE_CURRENT_BUILD_DIR}"
  INSTALL_COMMAND ""
  CMAKE_ARGS
    "-DLIEF_DIR=${LIEF_INSTALL_DIR}/lib/cmake/LIEF"
    -DCMAKE_BUILD_TYPE=RelWithDebInfo
)

For the compilation:

$ mkdir build
$ cd build
$ cmake ..
$ make
$ HelloLIEF /bin/ls # or explorer.exe or what ever

A full example is available in the examples/cmake/external_project directory.

Visual Studio Integration¶

Given a pre-compiled version of LIEF SDK (e.g. LIEF-0.14.1-win64.zip):

.
├── bin
│   ├── pe_reader.exe
│   └── vdex_reader.exe
├── include
│   └── LIEF
├── lib
│   ├── LIEF.dll
│   ├── LIEF.lib
│   └── pkgconfig
└── share
    └── LIEF

One should add the include/ directory in the compiler search path: Configuration Properties > C/C++ > General > Additional Include Directories and add either LIEF.lib or LIEF.dll in the link step:

Configuration Properties > Linker > Input > Additional Dependencies

Warning

LIEF.dll is compiled with the /MD flag (MultiThreadedDLL) while LIEF.lib is compiled with the /MT flag (MultiThreaded).

If this configuration is not suitable for your project, you can compile LIEF with your required runtime.

XCode Integration¶

Similarly to Visual Studio, one should configure the XCode project to include the include/ directory of LIEF and the lib/ directory:

include/: Build Settings > Search Paths > Header Search Paths
lib/: Build Settings > Search Paths > Library Search Paths

Then, we can add libLIEF.lib or libLIEF.dylib in the list of the libraries to link with:

Build Phases > Link Binary With Libraries