Installation and Integration¶

SDK¶

For each platform supported by LIEF there is an SDK that contains:

Static library
Headers
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¶

Since 0.12.0¶

Since LIEF v0.12.0 the Python nightly wheels have moved to Scalway S3. They can be installed through:

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

Since 0.10.0¶

To install nightly build (master):

$ pip install [--user] --index-url  https://lief-project.github.io/packages lief

You can also directly download the Python wheel package on: https://lief-project.github.io/packages/lief

Note

If you already installed a nightly version of LIEF you may need the flag: --no-cache-dir

To install release package

$ pip install lief

Release packages can be found on PyPI and the Github release page: https://github.com/lief-project/LIEF/releases

Using setup.py, one can build and install lief as follows:

$ python ./setup.py [--user] install

LIEF modules can also be parameterized using the following options:

$ python ./setup.py --help
...

--lief-test         Build and make tests
--ninja             Use Ninja as build system
--sdk               Build SDK package
--lief-no-json      Disable JSON module
--lief-no-logging   Disable logging module
--lief-no-elf       Disable ELF module
--lief-no-pe        Disable PE module
--lief-no-macho     Disable Mach-O module
--lief-no-android   Disable Android formats
--lief-no-art       Disable ART module
--lief-no-vdex      Disable VDEX module
--lief-no-oat       Disable OAT module
--lief-no-dex       Disable DEX module

From 0.8.0 to 0.9.0¶

To install release package

$ pip install pylief-VERSION.zip

Release packages can be found here: Releases

Before 0.8.0¶

To install the Python API (example with Python 3.5):

$ pip install lief-XX.YY.ZZ_py35.tar.gz

Visual Studio Integration¶

The pre-built SDK is compiled in release configuration with the Multi-threaded runtime library.

As example we compile the following snippet with Visual Studio 2015

#include "stdafx.h"

#include <LIEF/LIEF.hpp>

int main()
{
  std::unique_ptr<LIEF::PE::Binary> pe_binary = LIEF::PE::Parser::parse("C:\\Windows\\explorer.exe");
  std::cout << *pe_binary << std::endl;
  return 0;
}

First the build type must be set to Release:

_images/s1.png — Build type set to `Release`¶

Then we need to specify the location of the LIEF include directory:

_images/s2.png — LIEF include directory¶

and the location of the LIEF.lib library:

As LIEF.lib was compiled with the \MT flag we have to set it:

_images/s3.png — *Multi-threaded* as runtime library¶

LIEF makes use of and, or, not C++ keywords. As MSVC doesn’t support these keywords by default, we need to add the special file iso646.h:

XCode Integration¶

To integrate LIEF within a XCode project, one needs to follow these steps:

First we create a new project:

For this example we select a Command Line Tool:

Then we need to add the static library libLIEF.a or the shared one (libLIEF.dylib)

_images/step4.png — Project configuration - Build Phases¶

_images/step5.png — Project configuration - Build Phases¶

_images/step6.png — Project configuration - Build Phases¶

In the Build Settings - Search Paths one needs to specify the paths to the include directory and to location of the LIEF libraries (libLIEF.a and/or libLIEF.dylib)

_images/step7.png — Libraries and Include search paths¶

Once the new project configured we can use LIEF:

and run it:

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>/share/LIEF/cmake ..
$ 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:

# Use LIEF as an embedded/vendored 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()

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

# If you have LIEF as a submodule in a directory, then you can add it to this
# project with ``add_subdirectory``
# 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}")

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:

  cmake_minimum_required(VERSION 3.11)

  # 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 'master')
  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()

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 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.0)

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 'master')
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=MT)
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}/share/LIEF/cmake"
    -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.