STRLCPY/LIEF

doc/sphinx/_static/windows_sdk/s1.png

doc/sphinx/_static/windows_sdk/s2.png

doc/sphinx/_static/windows_sdk/s3.png

doc/sphinx/_static/windows_sdk/s4.png

doc/sphinx/_static/windows_sdk/s5.png

doc/sphinx/_static/xcode_integration/code.png

doc/sphinx/_static/xcode_integration/result.png

doc/sphinx/_static/xcode_integration/step1.png

doc/sphinx/_static/xcode_integration/step2.png

doc/sphinx/_static/xcode_integration/step3.png

doc/sphinx/_static/xcode_integration/step4.png

doc/sphinx/_static/xcode_integration/step5.png

doc/sphinx/_static/xcode_integration/step6.png

doc/sphinx/_static/xcode_integration/step7.png

■ ■ ■ ■ ■ ■

doc/sphinx/compilation.rst

1	1		.. role:: strike
2	2		:class: strike
3	3
	4	+	.. _compilation-ref:
	5	+
4	6		Compilation
5	7		===========
6	8
		skipped 2 lines
9	11		- C++17 compiler (GCC, Clang, MSVC..)
10	12		- CMake
11	13		- Python >= 3.8 (for the bindings)
12		-
13		-	To build the documentation:
14		-
15		-	- Doxygen (= ``1.8.10``, the CI uses ``1.8.20``)
16		-	- Sphinx (with ``sphinx_rtd_theme`` module)
17		-	- breathe (>= ``4.25.1``)
18	14
19	15		.. note::
20	16
		skipped 38 lines
59	55
60	56		$ git clone https://github.com/lief-project/LIEF.git
61	57		$ cd LIEF/api/python
62		-	$ python ./setup.py build install [--user]
	58	+	$ pip install [-e] [--user] .
63	59		# Or
64		-	$ pip install [-e] .
	60	+	$ pip install [-e] api/python
65	61
66	62		.. note::
67	63
68		-	You can speed-up the compilation by installing `ccache <https://ccache.dev/>`_ or `sccache <https://github.com/mozilla/sccache>`_
	64	+	You can speed-up the compilation by installing `ccache <https://ccache.dev/>`_
	65	+	or `sccache <https://github.com/mozilla/sccache>`_
69	66
70		-	Before LIEF 0.13.0, we could tweak the compilation of the Python bindings
71		-	through command line options:
72		-
73		-	.. code-block:: console
74		-
75		-	$ python ./setup.py --lief-no-dex --lief-no-vdex --lief-no-oat [...]
76		-
77		-	This interface had the drawback to produce long commands and using `setup.py`
78		-	options is even more complicated with `pip install` approach.
	67	+	One can tweak the compilation by setting the environment variable ``PYLIEF_CONF``
	68	+	to a Toml configuration file. By default, the Python bindings are using ``config-default.toml``
	69	+	in the Python binding directory:
79	70
80		-	Since LIEF 0.13.0, the options of the Python bindings are now defined in a `config-default.toml`
81		-	next to the `setup.py` file. This `.toml` file can be used to configure the different options
82		-	of LIEF and its Python binding:
83	71
84	72		.. code-block:: toml
85	73
		skipped 8 lines
94	82		pe = false
95	83		macho = true
96	84		...
97		-
98		-	One can also provide a custom configuration file through the `PYLIEF_CONF` environment variable:
99	85
100	86		.. code-block:: console
101	87
		skipped 18 lines
120	106
121	107		[lief.build]
122	108		type = "RelWithDebInfo"
123		-
124	109
125	110		.. note::
126	111
		skipped 123 lines
250	235
251	236		See `liefproject <https://hub.docker.com/u/liefproject>`_ on Dockerhub
252	237
253		-	.. container:: strike
254		-
255		-	See the `Dockerlief <https://github.com/lief-project/Dockerlief>`_ repo.
256		-

■ ■ ■ ■ ■ ■

doc/sphinx/installation.rst

		skipped 3 lines
4	4		SDK
5	5		---
6	6
7		-	For each platform supported by LIEF there is an SDK that contains:
	7	+	For each platform supported by LIEF, SDK packages contain:
8	8
9		-	* Static library
10		-	* Headers
11		-	* Examples
	9	+	* static and shared libraries
	10	+	* headers
	11	+	* compiled examples
12	12
13		-	Nightly build can be downloaded on: https://lief.s3-website.fr-par.scw.cloud/latest/sdk while releases are available
14		-	on Github release page: https://github.com/lief-project/LIEF/releases.
	13	+	Nightly build can be downloaded on: https://lief.s3-website.fr-par.scw.cloud/latest/sdk
	14	+	while releases are available on Github release page:
	15	+	https://github.com/lief-project/LIEF/releases.
15	16
16	17		Python
17	18		------
18	19
19		-	.. _v12-label:
20		-
21		-	Since 0.12.0
22		-	************
23		-
24		-	Since LIEF v0.12.0 the Python nightly wheels have moved to Scalway S3.
25		-	They can be installed through:
	20	+	Nightly Python wheels are uploaded for each commit on the main branch in a
	21	+	S3 bucket. They can be installed through:
26	22
27	23		.. code-block:: console
28	24
29	25		$ pip install [--user] --index-url https://lief.s3-website.fr-par.scw.cloud/latest lief
30	26
31		-
32		-	.. _v10-label:
33		-
34		-	Since 0.10.0
35		-	************
36		-
37		-	To install nightly build (master):
38		-
39		-	.. code-block:: console
40		-
41		-	$ pip install [--user] --index-url https://lief-project.github.io/packages lief
42		-
43		-	You can also directly download the Python wheel package on: https://lief-project.github.io/packages/lief
44		-
45		-	.. note::
46		-
47		-	If you already installed a nightly version of LIEF you may need the flag: ``--no-cache-dir``
48		-
49		-
50		-	To install release package
	27	+	For tagged releases, the wheels are uploaded on PyPI and can by installed through:
51	28
52	29		.. code-block:: console
53	30
54	31		$ pip install lief
55	32
56		-	Release packages can be found on `PyPI <https://pypi.org/project/lief/>`_ and the Github release page: https://github.com/lief-project/LIEF/releases
57		-
58		-	Using ``setup.py``, one can build and install lief as follows:
	33	+	One can also compile and install from source as follows
59	34
60	35		.. code-block:: console
61	36
62		-	$ python ./setup.py [--user] install
63		-
64		-	LIEF modules can also be parameterized using the following options:
65		-
66		-	.. code-block:: console
	37	+	$ git clone https://github.com/lief-project/LIEF
	38	+	$ pip install LIEF/api/python
	39	+	# Or pip+git:
	40	+	$ pip install git+https://github.com/lief-project/LIEF.git#subdirectory=api/python
67	41
68		-	$ python ./setup.py --help
69		-	...
70		-
71		-	--lief-test Build and make tests
72		-	--ninja Use Ninja as build system
73		-	--sdk Build SDK package
74		-	--lief-no-json Disable JSON module
75		-	--lief-no-logging Disable logging module
76		-	--lief-no-elf Disable ELF module
77		-	--lief-no-pe Disable PE module
78		-	--lief-no-macho Disable Mach-O module
79		-	--lief-no-android Disable Android formats
80		-	--lief-no-art Disable ART module
81		-	--lief-no-vdex Disable VDEX module
82		-	--lief-no-oat Disable OAT module
83		-	--lief-no-dex Disable DEX module
84		-
85		-	From 0.8.0 to 0.9.0
86		-	*******************
87		-
88		-	To install release package
89		-
90		-
91		-	.. code-block:: console
92		-
93		-	$ pip install pylief-VERSION.zip
94		-
95		-	Release packages can be found here: `Releases <https://github.com/lief-project/LIEF/releases>`_
96		-
97		-	Before 0.8.0
98		-	************
99		-
100		-	To install the Python API (example with ``Python 3.5``):
101		-
102		-	.. code-block:: console
103		-
104		-	$ pip install lief-XX.YY.ZZ_py35.tar.gz
105		-
106		-
107		-	Visual Studio Integration
108		-	-------------------------
109		-
110		-	The pre-built SDK is compiled in release configuration with the Multi-threaded runtime library.
111		-
112		-	As example we compile the following snippet with Visual Studio 2015
113		-
114		-	.. code-block:: cpp
115		-
116		-	#include "stdafx.h"
117		-
118		-	#include <LIEF/LIEF.hpp>
119		-
120		-	int main()
121		-	{
122		-	std::unique_ptr<LIEF::PE::Binary> pe_binary = LIEF::PE::Parser::parse("C:\\Windows\\explorer.exe");
123		-	std::cout << *pe_binary << std::endl;
124		-	return 0;
125		-	}
126		-
127		-	First the build type must be set to ``Release``:
128		-
129		-	.. figure:: _static/windows_sdk/s1.png
130		-	:align: center
131		-
132		-	Build type set to ``Release``
133		-
134		-
135		-	Then we need to specify the location of the LIEF include directory:
136		-
137		-	.. figure:: _static/windows_sdk/s2.png
138		-	:align: center
139		-
140		-	LIEF include directory
141		-
142		-	and the location of the ``LIEF.lib`` library:
143		-
144		-
145		-	.. figure:: _static/windows_sdk/s5.png
146		-	:align: center
147		-
148		-	LIEF library
149		-
150		-	As ``LIEF.lib`` was compiled with the ``\MT`` flag we have to set it:
151		-
152		-	.. figure:: _static/windows_sdk/s3.png
153		-	:align: center
154		-
155		-	Multi-threaded as runtime library
156		-
157		-	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``:
158		-
159		-	.. figure:: _static/windows_sdk/s4.png
160		-	:align: center
161		-
162		-	Add ``iso646.h`` file
163		-
164		-	XCode Integration
165		-	-----------------
166		-
167		-	To integrate LIEF within a XCode project, one needs to follow these steps:
168		-
169		-	First we create a new project:
170		-
171		-	.. figure:: _static/xcode_integration/step1.png
172		-	:align: center
173		-
174		-	New Project
175		-
176		-	For this example we select a Command Line Tool:
177		-
178		-	.. figure:: _static/xcode_integration/step2.png
179		-	:align: center
180		-
181		-	Command Line Tool
182		-
183		-
184		-	.. figure:: _static/xcode_integration/step3.png
185		-	:align: center
186		-
187		-	Project options
188		-
189		-	Then we need to add the static library ``libLIEF.a`` or the shared one (``libLIEF.dylib``)
190		-
191		-	.. figure:: _static/xcode_integration/step4.png
192		-	:align: center
193		-
194		-	Project configuration - Build Phases
195		-
196		-
197		-	.. figure:: _static/xcode_integration/step5.png
198		-	:align: center
199		-
200		-	Project configuration - Build Phases
201		-
202		-
203		-	.. figure:: _static/xcode_integration/step6.png
204		-	:align: center
205		-
206		-	Project configuration - Build Phases
207		-
208		-	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``)
209		-
210		-	.. figure:: _static/xcode_integration/step7.png
211		-	:align: center
212		-
213		-	Libraries and Include search paths
214		-
215		-	Once the new project configured we can use LIEF:
216		-
217		-
218		-	.. figure:: _static/xcode_integration/code.png
219		-	:align: center
220		-
221		-	Source code
222		-
223		-	and run it:
224		-
225		-	.. figure:: _static/xcode_integration/result.png
226		-	:align: center
227		-
228		-	Output
	42	+	For more details about the compilation options, see the :ref:`compilation-ref` section.
229	43
230	44
231	45		CMake Integration
232	46		-----------------
233	47
234		-	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.
235		-
	48	+	There are a few ways to integrate LIEF as a dependency in another project.
	49	+	The different methods are listed in order of preference and CMake best practice.
	50	+	These listings are only to show basic examples. Please refer to the CMake
	51	+	documentation for questions related to more complex project setup.
236	52
237	53		find_package()
238	54		**************
		skipped 16 lines
255	71		:start-line: 3
256	72
257	73		A full example is available in the ``examples/cmake/find_package`` directory.
258		-
259	74
260	75		add_subdirectory() or FetchContent
261	76		**********************************
		skipped 52 lines
314	129
315	130		A full example is available in the ``examples/cmake/external_project`` directory.
316	131
	132	+	Visual Studio Integration
	133	+	-------------------------
	134	+
	135	+	Given a pre-compiled version of LIEF SDK (e.g. ``LIEF-0.14.1-win64.zip``):
	136	+
	137	+	.. code-block:: text
	138	+
	139	+	.
	140	+	├── bin
	141	+	│ ├── pe_reader.exe
	142	+	│ └── vdex_reader.exe
	143	+	├── include
	144	+	│ └── LIEF
	145	+	├── lib
	146	+	│ ├── LIEF.dll
	147	+	│ ├── LIEF.lib
	148	+	│ └── pkgconfig
	149	+	└── share
	150	+	└── LIEF
	151	+
	152	+	One should add the ``include/`` directory in the compiler search path:
	153	+	``Configuration Properties > C/C++ > General > Additional Include Directories``
	154	+	and add either ``LIEF.lib`` or ``LIEF.dll`` in the link step:
	155	+
	156	+	``Configuration Properties > Linker > Input > Additional Dependencies``
	157	+
	158	+	.. warning::
	159	+
	160	+	``LIEF.dll`` is compiled with the ``/MD`` flag (``MultiThreadedDLL``) while
	161	+	``LIEF.lib`` is compiled with the ``/MT`` flag (``MultiThreaded``).
	162	+
	163	+	If this configuration is not suitable for your project, you can compile LIEF
	164	+	with your required runtime.
	165	+
	166	+	XCode Integration
	167	+	-----------------
	168	+
	169	+	Similarly to Visual Studio, one should configure the XCode project to include
	170	+	the ``include/`` directory of LIEF and the `lib/` directory:
	171	+
	172	+	- ``include/``: ``Build Settings > Search Paths > Header Search Paths``
	173	+	- ``lib/``: ``Build Settings > Search Paths > Library Search Paths``
	174	+
	175	+	Then, we can add ``libLIEF.lib`` or ``libLIEF.dylib`` in the list of the libraries
	176	+	to link with:
	177	+
	178	+	``Build Phases > Link Binary With Libraries``
	179	+

■ ■ ■ ■ ■ ■

examples/cmake/add_subdirectory/CMakeLists.txt

1		-	# Minimum of 3.5 for adding submodule of LIEF because LIEF min is 3.5,
2		-	# otherwise 3.11+ for FetchContent command
3		-	cmake_minimum_required(VERSION 3.5)
	1	+	cmake_minimum_required(VERSION 3.21)
4	2
5	3		project(SubdirLIEF LANGUAGES CXX)
6	4
		skipped 70 lines

■ ■ ■ ■ ■ ■

examples/cmake/add_subdirectory/main.cpp

		skipped 2 lines
3	3
4	4		int main(int argc, char** argv) {
5	5		if (argc != 2) {
6		-	std::cerr << "Usage: " << argv[0] << " <binary>" << std::endl;
	6	+	std::cerr << "Usage: " << argv[0] << " <binary>" << '\n';
7	7		return 1;
8	8		}
9	9
10		-	auto binary = LIEF::Parser::parse(argv[1]);
11		-	std::cout << *binary << std::endl;
	10	+	if (auto binary = LIEF::Parser::parse(argv[1])) {
	11	+	std::cout << *binary << '\n';
	12	+	}
	13	+
12	14		return 0;
13	15		}
14	16

■ ■ ■ ■ ■ ■

examples/cmake/external_project/CMakeLists.txt

1		-	cmake_minimum_required(VERSION 3.0)
	1	+	cmake_minimum_required(VERSION 3.21)
2	2
3	3		project(CMakeLIEF LANGUAGES NONE)
4	4
		skipped 21 lines
26	26		)
27	27
28	28		if(MSVC)
29		-	list(APPEND ${LIEF_CMAKE_ARGS} -DCMAKE_MSVC_RUNTIME_LIBRARY=MT)
	29	+	list(APPEND ${LIEF_CMAKE_ARGS} -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreaded)
30	30		endif()
31	31
32	32		ExternalProject_Add(LIEF
		skipped 16 lines
49	49		BINARY_DIR "${CMAKE_CURRENT_BUILD_DIR}"
50	50		INSTALL_COMMAND ""
51	51		CMAKE_ARGS
52		-	"-DLIEF_DIR=${LIEF_INSTALL_DIR}/share/LIEF/cmake"
	52	+	"-DLIEF_DIR=${LIEF_INSTALL_DIR}/lib/cmake/LIEF"
53	53		-DCMAKE_BUILD_TYPE=RelWithDebInfo
54	54		)
55	55

■ ■ ■ ■ ■ ■

examples/cmake/external_project/HelloLIEF/main.cpp

		skipped 2 lines
3	3
4	4		int main(int argc, char** argv) {
5	5		if (argc != 2) {
6		-	std::cerr << "Usage: " << argv[0] << " <binary>" << std::endl;
	6	+	std::cerr << "Usage: " << argv[0] << " <binary>" << '\n';
7	7		return 1;
8	8		}
9	9
10		-	auto binary = LIEF::Parser::parse(argv[1]);
11		-	std::cout << *binary << std::endl;
	10	+	if (auto binary = LIEF::Parser::parse(argv[1])) {
	11	+	std::cout << *binary << '\n';
	12	+	}
12	13		return 0;
13	14		}
14	15

■ ■ ■ ■ ■ ■

examples/cmake/find_package/README.rst

		skipped 5 lines
6	6
7	7		$ mkdir build
8	8		$ cd build
9		-	$ cmake -DLIEF_DIR=<PATH_TO_LIEF_INSTALL_DIR>/share/LIEF/cmake ..
	9	+	$ cmake -DLIEF_DIR=<PATH_TO_LIEF_INSTALL_DIR>/lib/cmake/LIEF/ ..
10	10		$ make
11	11		$ HelloLIEF /bin/ls # or explorer.exe or whatever
12	12
		skipped 1 lines

■ ■ ■ ■ ■ ■

examples/cmake/find_package/main.cpp

		skipped 2 lines
3	3
4	4		int main(int argc, char** argv) {
5	5		if (argc != 2) {
6		-	std::cerr << "Usage: " << argv[0] << " <binary>" << std::endl;
	6	+	std::cerr << "Usage: " << argv[0] << " <binary>" << '\n';
7	7		return 1;
8	8		}
9	9
10		-	auto binary = LIEF::Parser::parse(argv[1]);
11		-	std::cout << *binary << std::endl;
	10	+	if (auto binary = LIEF::Parser::parse(argv[1])) {
	11	+	std::cout << *binary << '\n';
	12	+	}
	13	+
12	14		return 0;
13	15		}
14	16

Update documentation