From d231966dbe2c0fb746607902b26d426cf93d0e8e Mon Sep 17 00:00:00 2001 From: Andrea Fioraldi Date: Sat, 27 Mar 2021 09:42:51 +0100 Subject: [PATCH] setup page in book --- docs/src/SUMMARY.md | 3 +- docs/src/getting_started/build.md | 3 ++ docs/src/getting_started/getting_started.md | 3 ++ docs/src/getting_started/installation.md | 1 - docs/src/getting_started/setup.md | 58 +++++++++++++++++++++ 5 files changed, 66 insertions(+), 2 deletions(-) create mode 100644 docs/src/getting_started/build.md delete mode 100644 docs/src/getting_started/installation.md create mode 100644 docs/src/getting_started/setup.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 2aed5e4096..bcd4ffea37 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -5,7 +5,8 @@ [Introduction](./introduction.md) - [Getting Started](./getting_started/getting_started.md) - - [Installation](./getting_started/installation.md) + - [Setup](./getting_started/setup.md) + - [Build](./getting_started/build.md) - [Crates](./getting_started/crates.md) - [Baby Fuzzer](./baby_fuzzer.md) diff --git a/docs/src/getting_started/build.md b/docs/src/getting_started/build.md new file mode 100644 index 0000000000..174deb9738 --- /dev/null +++ b/docs/src/getting_started/build.md @@ -0,0 +1,3 @@ +# Build + + diff --git a/docs/src/getting_started/getting_started.md b/docs/src/getting_started/getting_started.md index bad55622f9..6becb923c8 100644 --- a/docs/src/getting_started/getting_started.md +++ b/docs/src/getting_started/getting_started.md @@ -1 +1,4 @@ # Getting Started + +To start using LibAFL, there are some first steps to do. In this chapter, we will +discuss how to install LibAFL with `cargo`, how are structured its crates and the purpose of each crate. diff --git a/docs/src/getting_started/installation.md b/docs/src/getting_started/installation.md deleted file mode 100644 index 25267fe2b7..0000000000 --- a/docs/src/getting_started/installation.md +++ /dev/null @@ -1 +0,0 @@ -# Installation diff --git a/docs/src/getting_started/setup.md b/docs/src/getting_started/setup.md new file mode 100644 index 0000000000..e57aca1f14 --- /dev/null +++ b/docs/src/getting_started/setup.md @@ -0,0 +1,58 @@ +# Setup + +The first step is to download LibAFL and all its dependencies that are not automatically installed with `cargo`. + +> ### Command Line Notation +> +> In this chapter and throughout the book, we’ll show some commands used in the +> terminal. Lines that you should enter in a terminal all start with `$`. You +> don’t need to type in the `$` character; it indicates the start of each +> command. Lines that don’t start with `$` typically show the output of the +> previous command. Additionally, PowerShell-specific examples will use `>` +> rather than `$`. + +The easiest way to download LibAFL is using `git`. + +```sh +$ git clone git@github.com:AFLplusplus/LibAFL.git +``` + +You can alternatively, on a UNIX-like machine, download a compressed archive and extract with: + +```sh +$ wget https://github.com/AFLplusplus/LibAFL/archive/main.tar.gz +$ tar xvf LibAFL-main.tar.gz +$ rm LibAFL-main.tar.gz +$ ls LibAFL-main # this is the extracted folder +``` + +## Clang installation + +One of the external dependencies of LibAFL is the Clang C/C++ compiler. +While most of the code is in pure Rust, we still need a C compiler because Rust stable +still does not support features that we need such as weak linking and LLVM builtins linking, +and so we use C to expose the missing functionalities to our Rust codebase. + +In addition, if you want to perform source-level fuzz testing of C/C++ applications, +you will likely need Clang with its instrumentation options to compile the programs +under test. + +You can download and build the LLVM source tree, Clang included, following the steps +explained [here](https://clang.llvm.org/get_started.html). + +Alternatively, on Linux, you can use your distro's package manager to get Clang, +but these packages are not always updated, so we suggest you to use the +Debian/Ubuntu prebuilt packages from LLVM that are available using their [official repository](https://apt.llvm.org/). + +For Miscrosoft Windows, you can download the [installer package](https://llvm.org/builds/) that LLVM generates periodically. + +Despite that Clang is the default C compiler on macOS, we discourage the use of the build shipped by Apple and encourage +the installation from `brew` or direclty a fresh build from the source code. + +## Rust installation + +If you don't have Rust installed, you can easily follow the steps described [here](https://www.rust-lang.org/tools/install) +to install it on any supported system. + +We suggest to install Clang and LLVM first. +