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