doc: update root README.md

Storage Performance Development Kit

===================================

# Storage Performance Development Kit

[![Build Status](https://travis-ci.org/spdk/spdk.svg?branch=master)](https://travis-ci.org/spdk/spdk)

[SPDK Mailing List](https://lists.01.org/mailman/listinfo/spdk)

[SPDK on 01.org](https://01.org/spdk)

The Storage Performance Development Kit (SPDK) provides a set of tools

The Storage Performance Development Kit ([SPDK](http://www.spdk.io)) provides a set of tools

and libraries for writing high performance, scalable, user-mode storage

applications. It achieves high performance by moving all of the necessary

drivers into userspace and operating in a polled mode instead of relying on

* [iSCSI target](http://www.spdk.io/doc/iscsi.html)

* [vhost target](http://www.spdk.io/doc/vhost.html)

Documentation

=============

# In this readme:

* [Documentation](#documentation)

* [Prerequisites](#prerequisites)

* [Source Code](#source)

* [Build](#libraries)

* [Unit Tests](#tests)

* [Vagrant](#vagrant)

* [Advanced Build Options](#advanced)

* [Hugepages and Device Binding](#huge)

* [Example Code](#examples)

* [Contributing](#contributing)

<a id="documentation"></a>

## Documentation

[Doxygen API documentation](http://www.spdk.io/doc/) is available, as

well as a [Porting Guide](http://www.spdk.io/doc/porting.html) for porting SPDK to different frameworks

and operating systems.

Many examples are available in the `examples` directory.

[Changelog](CHANGELOG.md)

Prerequisites

=============

<a id="prerequisites"></a>

## Prerequisites

To build SPDK, some dependencies must be installed.

Note: The requirements for building the docs can take a while to

install so you may want to skip them unless you need them.

Fedora/CentOS:

    sudo dnf install -y gcc gcc-c++ CUnit-devel libaio-devel openssl-devel

    # Additional dependencies for NVMe over Fabrics:

~~~{.sh}

sudo dnf install -y gcc gcc-c++ make CUnit-devel libaio-devel openssl-devel \

	git astyle-devel python-pep8 lcov python clang-analyzer

# Additional dependencies for NVMe over Fabrics

sudo dnf install -y libibverbs-devel librdmacm-devel

# Additional dependencies for building docs

sudo dnf install -y doxygen mscgen

~~~

Ubuntu/Debian:

    sudo apt-get install -y gcc g++ make libcunit1-dev libaio-dev libssl-dev

    # Additional dependencies for NVMe over Fabrics:

    sudo apt-get install -y libibverbs-dev librdmacm-dev

~~~{.sh}

sudo apt-get install -y gcc g++ make libcunit1-dev libaio-dev libssl-dev \

	git astyle pep8 lcov clang

# Additional dependencies for NVMe over Fabrics

sudo apt-get install -y libibverbs-dev librdmacm

# Additional dependencies for building docs

sudo apt-get install -y doxygen mscgen

~~~

FreeBSD:

    sudo pkg install gmake cunit openssl

~~~{.sh}

sudo pkg install gmake cunit openssl git devel/astyle bash devel/pep8 \

	python

# Additional dependencies for building docs

sudo pkg install doxygen mscgen

~~~

Additionally, [DPDK](http://dpdk.org/doc/quick-start) is required.  The SPDK

repository includes a suitable version of DPDK as a submodule:

<a id="source"></a>

## Source Code

~~~{.sh}

git clone https://github.com/spdk/spdk

cd spdk

git submodule update --init

~~~

Building

========

Once the prerequisites are installed, building follows the common configure

and make pattern (note: this will build the DPDK submodule as well).

<a id="libraries"></a>

## Build

Linux:

~~~{.sh}

./configure

make

~~~

FreeBSD:

Note: Make sure you have the matching kernel source in /usr/src/ and

also note that CONFIG_COVERAGE option is not available right now

for FreeBSD builds.

~~~{.sh}

./configure

gmake

~~~

<a id="tests"></a>

## Unit Tests

~~~{.sh}

./unittest.sh

~~~

Vagrant

=======

You will see several error messages when running the unit tests, but they are

part of the test suite. The final message at the end of the script indicates

success or failure.

<a id="vagrant"></a>

## Vagrant

A [Vagrant](https://www.vagrantup.com/downloads.html) setup is also provided

to create a Linux VM with a virtual NVMe controller to get up and running

Details on the Vagrant setup can be found in

[scripts/vagrant/README.md](scripts/vagrant/README.md).

Advanced Build Options

======================

<a id="advanced"></a>

## Advanced Build Options

Optional components and other build-time configuration are controlled by

settings in two Makefile fragments in the root of the repository. `CONFIG`

'n'. For the majority of options this can be done using the `configure` script.

For example:

    ./configure --with-dpdk=./dpdk/x86_64-native-linuxapp-gcc --with-rdma

~~~{.sh}

./configure --with-rdma

~~~

Additionally, `CONFIG` options may also be overrriden on the `make` command

line:

~~~{.sh}

make CONFIG_RDMA=y

~~~

Users may wish to use a version of DPDK different from the submodule included

in the SPDK repository.  To specify an alternate DPDK installation, run

Linux:

~~~{.sh}

./configure --with-dpdk=/path/to/dpdk/x86_64-native-linuxapp-gcc

make

~~~

FreeBSD:

~~~{.sh}

./configure --with-dpdk=/path/to/dpdk/x86_64-native-bsdapp-clang

gmake

~~~

The options specified on the `make` command line take precedence over the

default values in `CONFIG` and `CONFIG.local`. This can be useful if you, for

one or two options (i.e. debug builds) that you wish to turn on and off

frequently.

Hugepages and Device Binding

============================

<a id="huge"></a>

## Hugepages and Device Binding

Before running an SPDK application, some hugepages must be allocated and

any NVMe and I/OAT devices must be unbound from the native kernel drivers.

SPDK includes a script to automate this process on both Linux and FreeBSD.

This script should be run as root.

~~~{.sh}

sudo scripts/setup.sh

~~~

Examples

========

<a id="examples"></a>

## Example Code

Example code is located in the examples directory. The examples are compiled

automatically as part of the build process. Simply call any of the examples

as a privileged user (root) unless you've done additional configuration

to grant your user permission to allocate huge pages and map devices through

vfio.

<a id="contributing"></a>

## Contributing

For additional details on how to get more involved in the community, including

[contributing code](http://www.spdk.io/development) and participating in discussions and other activiites, please

refer to [spdk.io](http://www.spdk.io/community)

python scripts/genconfig.py > config.h

echo "done."

if [[ "$OSTYPE" == "FreeBSD"* ]]; then

        echo "Type 'gmake' to build."

else

        echo "Type 'make' to build."

fi

exit 0