1# Getting Started {#getting_started} 2 3## Getting the Source Code {#getting_started_source} 4 5~~~{.sh} 6git clone https://github.com/spdk/spdk --recursive 7~~~ 8 9## Installing Prerequisites {#getting_started_prerequisites} 10 11The `scripts/pkgdep.sh` script will automatically install the bare minimum 12dependencies required to build SPDK. 13Use `--help` to see information on installing dependencies for optional components. 14 15~~~{.sh} 16sudo scripts/pkgdep.sh 17~~~ 18 19Option --all will install all dependencies needed by SPDK features. 20 21~~~{.sh} 22sudo scripts/pkgdep.sh --all 23~~~ 24 25## Building {#getting_started_building} 26 27Linux: 28 29~~~{.sh} 30./configure 31make 32~~~ 33 34FreeBSD: 35Note: Make sure you have the matching kernel source in /usr/src/ 36 37~~~{.sh} 38./configure 39gmake 40~~~ 41 42There are a number of options available for the configure script, which can 43be viewed by running 44 45~~~{.sh} 46./configure --help 47~~~ 48 49Note that not all features are enabled by default. For example, RDMA 50support (and hence NVMe over Fabrics) is not enabled by default. You 51can enable it by doing the following: 52 53~~~{.sh} 54./configure --with-rdma 55make 56~~~ 57 58## Running the Unit Tests {#getting_started_unittests} 59 60It's always a good idea to confirm your build worked by running the 61unit tests. 62 63~~~{.sh} 64./test/unit/unittest.sh 65~~~ 66 67You will see several error messages when running the unit tests, but they are 68part of the test suite. The final message at the end of the script indicates 69success or failure. 70 71## Running the Example Applications {#getting_started_examples} 72 73Before running an SPDK application, some hugepages must be allocated and 74any NVMe and I/OAT devices must be unbound from the native kernel drivers. 75SPDK includes a script to automate this process on both Linux and FreeBSD. 76This script should be run as root. It only needs to be run once on the 77system. 78 79~~~{.sh} 80sudo scripts/setup.sh 81~~~ 82 83To rebind devices back to the kernel, you can run 84 85~~~{.sh} 86sudo scripts/setup.sh reset 87~~~ 88 89By default, the script allocates 2048MB of hugepages. To change this number, 90specify HUGEMEM (in MB) as follows: 91 92~~~{.sh} 93sudo HUGEMEM=4096 scripts/setup.sh 94~~~ 95 96On Linux machines HUGEMEM will be rounded up to system-default huge page 97size boundary. 98 99All available params can be viewed by running 100 101~~~{.sh} 102scripts/setup.sh help 103~~~ 104 105Example code is located in the examples directory. The examples are compiled 106automatically as part of the build process. Simply call any of the examples 107with no arguments to see the help output. If your system has its IOMMU 108enabled you can run the examples as your regular user. If it doesn't, you'll 109need to run as a privileged user (root). 110 111A good example to start with is `build/bin/spdk_nvme_identify`, which prints 112out information about all of the NVMe devices on your system. 113 114Larger, more fully functional applications are available in the `app` 115directory. This includes the [iSCSI target](https://spdk.io/doc/iscsi.html) 116and [NVMe-oF target](https://spdk.io/doc/nvmf.html) and tools like 117[spdk_top](https://spdk.io/doc/spdk_top.html). This neat program simulates 118regular `top` application and shows SPDK threads, pollers and SPDK assigned 119CPU cores statistics in a form of interactive list. 120