diff --git a/README.md b/README.md
index 53b9d6c8a..2b377a69b 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,8 @@
-Storage Performance Development Kit
-===================================
+# Storage Performance Development Kit
[](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
@@ -21,61 +16,105 @@ The development kit currently includes:
* [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)
+
+
+## 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.
+
+## Prerequisites
-[Changelog](CHANGELOG.md)
-
-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:
- sudo dnf install -y libibverbs-devel librdmacm-devel
+~~~{.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:
+
+## Source Code
- git submodule update --init
+~~~{.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).
+
+## Build
Linux:
- ./configure
- make
+~~~{.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.
- ./configure
- gmake
+~~~{.sh}
+./configure
+gmake
+~~~
-Vagrant
-=======
+
+## Unit Tests
+
+~~~{.sh}
+./unittest.sh
+~~~
+
+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.
+
+
+## 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
@@ -87,8 +126,8 @@ also be installed in order to get the required NVMe support.
Details on the Vagrant setup can be found in
[scripts/vagrant/README.md](scripts/vagrant/README.md).
-Advanced Build Options
-======================
+
+## 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`
@@ -102,18 +141,22 @@ Boolean (on/off) options are configured with a 'y' (yes) or 'n' (no). For
example, this line of `CONFIG` controls whether the optional RDMA (libibverbs)
support is enabled:
- CONFIG_RDMA?=n
+ CONFIG_RDMA?=n
To enable RDMA, this line may be added to `CONFIG.local` with a 'y' instead of
'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:
- make CONFIG_RDMA=y
+~~~{.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
@@ -121,13 +164,17 @@ configure with the --with-dpdk option. For example:
Linux:
- ./configure --with-dpdk=/path/to/dpdk/x86_64-native-linuxapp-gcc
- make
+~~~{.sh}
+./configure --with-dpdk=/path/to/dpdk/x86_64-native-linuxapp-gcc
+make
+~~~
FreeBSD:
- ./configure --with-dpdk=/path/to/dpdk/x86_64-native-bsdapp-clang
- gmake
+~~~{.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
@@ -135,18 +182,20 @@ example, generate a `CONFIG.local` using the `configure` script and then have
one or two options (i.e. debug builds) that you wish to turn on and off
frequently.
-Hugepages and Device Binding
-============================
+
+## 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.
- sudo scripts/setup.sh
+~~~{.sh}
+sudo scripts/setup.sh
+~~~
-Examples
-========
+
+## 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
@@ -154,3 +203,10 @@ with no arguments to see the help output. You'll likely need to run 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.
+
+
+## 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)
diff --git a/configure b/configure
index 8c7ee2483..24f73786b 100755
--- a/configure
+++ b/configure
@@ -228,6 +228,10 @@ fi
python scripts/genconfig.py > config.h
echo "done."
-echo "Type 'make' to build."
+if [[ "$OSTYPE" == "FreeBSD"* ]]; then
+ echo "Type 'gmake' to build."
+else
+ echo "Type 'make' to build."
+fi
exit 0