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