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-project.github.io/packages/sdk while releases are available on Github release page: https://github.com/lief-project/LIEF/releases.

Python

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:

_images/s5.png

LIEF 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:

_images/s4.png

Add iso646.h file

XCode Integration

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

First we create a new project:

_images/step1.png

New Project

For this example we select a Command Line Tool:

_images/step2.png

Command Line Tool

_images/step3.png

Project options

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:

_images/code.png

Source code

and run it:

_images/result.png

Output

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)

if(MSVC)
  set_property(TARGET HelloLIEF PROPERTY LINK_FLAGS /NODEFAULTLIB:MSVCRT)
endif()


# 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(LIEF_USE_CRT_RELEASE "MT" CACHE STRING "LIEF 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.12.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)

if(MSVC)
  set_property(TARGET HelloLIEF PROPERTY LINK_FLAGS /NODEFAULTLIB:MSVCRT)
endif()

# 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.12.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} -DLIEF_USE_CRT_RELEASE=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.