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 the 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

External Project

Using CMake External Project:

cmake_minimum_required(VERSION 3.02)

include(ExternalProject)

project(CMakeLIEF)

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

# LIEF static library
set(LIB_LIEF
  "${LIEF_PREFIX}/lib/${CMAKE_STATIC_LIBRARY_PREFIX}LIEF${CMAKE_STATIC_LIBRARY_SUFFIX}")

# 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.11.0)

# LIEF compilation config
set(LIEF_CMAKE_ARGS
  -DCMAKE_INSTALL_PREFIX=<INSTALL_DIR>
  -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
  -DLIEF_DOC=off
  -DLIEF_PYTHON_API=off
  -DLIEF_EXAMPLES=off
  -DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
  -DCMAKE_C_COMPILER=${CMAKE_C_COMPILER}
)

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}
  INSTALL_DIR      ${LIEF_INSTALL_DIR}

And now, to be integrated within a project:

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

if(MSVC)
  # Used for the 'and', 'or' ... keywords - See: http://www.cplusplus.com/reference/ciso646/
  target_compile_options(HelloLIEF PUBLIC /FIiso646.h)
  set_property(TARGET HelloLIEF PROPERTY LINK_FLAGS /NODEFAULTLIB:MSVCRT)
endif()

# Setup the LIEF include directory
target_include_directories(HelloLIEF
  PUBLIC
  ${LIEF_INCLUDE_DIRS}
)

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

# Link the executable with LIEF
target_link_libraries(HelloLIEF PUBLIC ${LIB_LIEF})

add_dependencies(HelloLIEF LIEF)

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.

find_package()

Using CMake find_package():

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

# Custom path to the LIEF install directory
set(LIEF_DIR CACHE PATH ${CMAKE_INSTALL_PREFIX})

# Directory to 'FindLIEF.cmake'
list(APPEND CMAKE_MODULE_PATH ${LIEF_DIR}/share/LIEF/cmake)

# include 'FindLIEF.cmake'
include(FindLIEF)

# Find LIEF
find_package(LIEF REQUIRED COMPONENTS STATIC) # COMPONENTS: <SHARED | STATIC> - Default: STATIC

And now, to be integrated within a project:

message(STATUS "LIEF include directory: ${LIEF_INCLUDE_DIRS}")
message(STATUS "LIEF library: ${LIEF_LIBRARIES}")

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

if(MSVC)
  # Used for the 'and', 'or' ... keywords - See: http://www.cplusplus.com/reference/ciso646/
  target_compile_options(HelloLIEF PUBLIC /FIiso646.h)
  set_property(TARGET HelloLIEF PROPERTY LINK_FLAGS /NODEFAULTLIB:MSVCRT)
endif()


# Setup the LIEF include directory
target_include_directories(HelloLIEF
  PUBLIC
    ${LIEF_INCLUDE_DIRS}
)

# 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_LIBRARIES})

For the compilation:

$ mkdir build
$ cd build
$ cmake -DLIEF_DIR=<PATH_TO_LIEF_INSTALL_DIR> .. # By default, LIEF_DIR=CMAKE_INSTALL_PREFIX
$ make
$ HelloLIEF /bin/ls # or explorer.exe or whatever

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