|
Packit |
b1f7ae |
Building the Intel(R) Processor Trace (Intel PT) Decoder Library and Samples {#build}
|
|
Packit |
b1f7ae |
============================================================================
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
! Copyright (c) 2013-2017, Intel Corporation
|
|
Packit |
b1f7ae |
!
|
|
Packit |
b1f7ae |
! Redistribution and use in source and binary forms, with or without
|
|
Packit |
b1f7ae |
! modification, are permitted provided that the following conditions are met:
|
|
Packit |
b1f7ae |
!
|
|
Packit |
b1f7ae |
! * Redistributions of source code must retain the above copyright notice,
|
|
Packit |
b1f7ae |
! this list of conditions and the following disclaimer.
|
|
Packit |
b1f7ae |
! * Redistributions in binary form must reproduce the above copyright notice,
|
|
Packit |
b1f7ae |
! this list of conditions and the following disclaimer in the documentation
|
|
Packit |
b1f7ae |
! and/or other materials provided with the distribution.
|
|
Packit |
b1f7ae |
! * Neither the name of Intel Corporation nor the names of its contributors
|
|
Packit |
b1f7ae |
! may be used to endorse or promote products derived from this software
|
|
Packit |
b1f7ae |
! without specific prior written permission.
|
|
Packit |
b1f7ae |
!
|
|
Packit |
b1f7ae |
! THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
Packit |
b1f7ae |
! AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
Packit |
b1f7ae |
! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
Packit |
b1f7ae |
! ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
|
|
Packit |
b1f7ae |
! LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
Packit |
b1f7ae |
! CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
Packit |
b1f7ae |
! SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
Packit |
b1f7ae |
! INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
Packit |
b1f7ae |
! CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
Packit |
b1f7ae |
! ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
Packit |
b1f7ae |
! POSSIBILITY OF SUCH DAMAGE.
|
|
Packit |
b1f7ae |
!-->
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
This chapter gives step-by-step instructions for building the library and the
|
|
Packit |
b1f7ae |
sample tools using cmake. For detailed information on cmake, see
|
|
Packit |
b1f7ae |
http://www.cmake.org.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
## Configuration
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Besides the standard cmake options of build type and install directory, you will
|
|
Packit |
b1f7ae |
find project-specific options for enabling optional features, optional
|
|
Packit |
b1f7ae |
components, or optional build variants.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
### Optional Components
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
By default, only the decoder library is built. Other components can be enabled
|
|
Packit |
b1f7ae |
by setting the respective cmake variable to ON.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
The following optional components are availble:
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
PTUNIT A simple unit test framework.
|
|
Packit |
b1f7ae |
A collection of unit tests for libipt.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
PTDUMP A packet dumper example.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
PTXED A trace disassembler example.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
PTTC A trace test generator.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
### Optional Features
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Features are enabled by setting the respective FEATURE_<name> cmake variable.
|
|
Packit |
b1f7ae |
This causes the FEATURE_<name> pre-processor macro to be defined and may also
|
|
Packit |
b1f7ae |
cause additional source files to be compiled and additional libraries to be
|
|
Packit |
b1f7ae |
linked.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Features are enabled globally and will be used by all components that support
|
|
Packit |
b1f7ae |
the feature. The following features are supported:
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
FEATURE_ELF Support for the ELF object format.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
This feature requires the elf.h header.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
FEATURE_THREADS Support some amount of multi-threading.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
This feature makes image functions thread-safe.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
### Build Variants
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Some build variants depend on libraries or header files that may not be
|
|
Packit |
b1f7ae |
available on all supported platforms.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
GCOV Support for code coverage using libgcov.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
This build variant requires libgcov and is not availble
|
|
Packit |
b1f7ae |
on Windows.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
DEVBUILD Enable compiler warnings and turn them into errors.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
### Version Settings
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
The major and minor version numbers are set in the sources and must be changed
|
|
Packit |
b1f7ae |
there. You can set the build number and an arbitrary extension string.
|
|
Packit |
b1f7ae |
build.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
PT_VERSION_BUILD The build number.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Defaults to zero.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
PT_VERSION_EXT An arbitrary version extension string.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Defaults to the empty string.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
### Dependencies
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
In order to build ptxed, the location of the XED library and the XED header
|
|
Packit |
b1f7ae |
files must be specified.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
XED_INCLUDE Path to the directory containing the XED header files.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
XED_LIBDIR Path to the directory containing the XED library.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
When using XED from a PIN distribution, the respective directories are located
|
|
Packit |
b1f7ae |
in `extras/xed2-<arch>/`.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
## Building on Linux``*`` and OS X``*``
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
We recommend out-of-tree builds. Start by creating the destination directory
|
|
Packit |
b1f7ae |
and navigating into it:
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
$ mkdir -p /path/to/dest
|
|
Packit |
b1f7ae |
$ cd /path/to/dest
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
From here, call cmake with the top-level source directory as argument. You may
|
|
Packit |
b1f7ae |
already pass some or all of the cmake variables as arguments to cmake. Without
|
|
Packit |
b1f7ae |
arguments, cmake uses default values.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
$ cmake /path/to/src
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
If you have not passed values for XED_INCLUDE or XED_LIBDIR, you need to
|
|
Packit |
b1f7ae |
configure them now if you want to build ptxed. You may also use this command to
|
|
Packit |
b1f7ae |
change the configuration at any time later on.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
$ make edit_cache
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
After configuring the cmake cache, you can build either specific targets or
|
|
Packit |
b1f7ae |
everything using one of:
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
$ make <target>
|
|
Packit |
b1f7ae |
$ make
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Use the help make target to learn about available make targets:
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
$ make help
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
## Building on Windows``*``
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
We recommend using the cmake GUI. After starting the cmake GUI, fill in the
|
|
Packit |
b1f7ae |
following fields:
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Where is the source code: Path to the top-level source directory.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Where to build the binaries: Path to the destination directory.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
We recommend out-of-tree builds, so the build directory should not be the same
|
|
Packit |
b1f7ae |
as or below the source directory. After this first configuration step, press
|
|
Packit |
b1f7ae |
the
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Configure
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
button and select the builder you want to use.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Cmake will now populate the remainder of the window with configuration options.
|
|
Packit |
b1f7ae |
Please make sure to specify at least XED_INCLUDE and XED_LIBDIR if you want to
|
|
Packit |
b1f7ae |
build ptxed. After completing the configuration, press the
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Generate
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
button. If you selected a Visual Studio generator in the first step, cmake will
|
|
Packit |
b1f7ae |
now generate a Visual Studio solution. You can repeat this step if you want to
|
|
Packit |
b1f7ae |
change the configuration later on. Beware that you always need to press the
|
|
Packit |
b1f7ae |
Generate button after changing the configuration.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
In the case of a Visual Studio generator, you may now open the generated Visual
|
|
Packit |
b1f7ae |
Studio solution and build the library and samples.
|