From ba50df964990023f788910a78921c3f62fa100dd Mon Sep 17 00:00:00 2001
From: xklllll <42052940+xklllll@users.noreply.github.com>
Date: Fri, 3 Aug 2018 16:11:22 +0800
Subject: [PATCH] add binary-release doc

---
 doc/F-Stack_Binary_Release_Quick_Start.md | 94 +++++++++++++++++++++++
 doc/F-Stack_Build_Guide.md                | 94 +++++++++++++++++++++++
 2 files changed, 188 insertions(+)
 create mode 100644 doc/F-Stack_Binary_Release_Quick_Start.md
 create mode 100644 doc/F-Stack_Build_Guide.md

diff --git a/doc/F-Stack_Binary_Release_Quick_Start.md b/doc/F-Stack_Binary_Release_Quick_Start.md
new file mode 100644
index 00000000..0e5e64ae
--- /dev/null
+++ b/doc/F-Stack_Binary_Release_Quick_Start.md
@@ -0,0 +1,94 @@
+# F-Stack Binary Release Quick Start
+
+## How to use
+
+Before you start to use f-stack-binary-release package, please make sure you: 
+- have access to the internet
+- have at least one NIC up
+- have root permission
+- meet all other requirements of dpdk
+
+```sh
+$ sudo -i
+$ tar zxf f-stack-binary-release.tar.gz
+$ cd f-stack-binary-release/scripts
+# set_env.sh will offload the NIC, if you only have one NIC, the following three commands must run in a script
+$ ./set_env.sh dev_name
+$ ./run_app.sh [app_name]
+$ ./config_veth0.sh
+```
+
+- dev_name is the name of your NIC, you can see it with *ifconfig* or *ip addr* command
+- app_name is the name of application you want to run, now we support 'nginx' and 'redis'. If you do not add any argument, it will run a helloworld example, you can use it to test whether the envrionment is setup correctly.
+- All the scripts should run with root permission
+
+## Directory structure
+
+```
++-- f-stack-binary-release
+|   +-- doc
+|   |   +-- F-Stack_Build_Guide.md
+|   |   +-- F-Stack_Binary_Release_Quick_Start.md
+|   +-- f-stack-release
+|   |   +-- CentOS
+|   |   |   +-- app (nignx-1.11.10 redis-3.2.8)
+|   |   |   +-- config.ini
+|   |   |   +-- doc
+|   |   |   +-- dpdk
+|   |   |   +-- example
+|   |   |   +-- start.sh (a script helps to run applications)
+|   |   |   +-- tools
+|   |   +-- RHEL
+|   |   +-- Ubuntu
+|   |   +-- kmod (kernel modules)
+|   |   |   +-- CentOS
+|   |   |   |   +-- supported_kernel_version
+|   |   |   |   |   +-- igb_uio.ko
+|   |   |   |   |   +-- rte_kni.ko
+|   |   |   +-- RHEL
+|   |   |   +-- Ubuntu
+|   +-- scripts
+|   |   +-- config_veth0.sh (configure the virtual NIC)
+|   |   +-- run_app.sh  (run a specific application)
+|   |   +-- set_env.sh  (setup environment that f-stack needs)
+```
+
+## Supported Linux releases
+
+ The f-stack-binary-release package has supported several frequent used linux releases, you can use f-stack applications directly on these releases. What should be paid attention to is that f-stack uses linux kernel modules, so if you have different kernel versions in your machine, you could not use this f-stack-quick-start package and need to compile f-stack by yourself. Here is the list of linux releases this package support now:
+
+| Linux Release  | Kernel |
+| -------------- | ------ |
+| CentOS 7.0     | 3.10.0-123.el7.x86_64 |
+| CentOS 7.2     | 3.10.0-327.el7.x86_64 |
+| CentOS 7.3     | 3.10.0-514.el7.x86_64 |
+| CentOS 7.4     | 3.10.0-693.el7.x86_64 |
+| CentOS 7.5     | 3.10.0-862.el7.x86_64 |
+| RHEL 7.2       | 3.10.0-327.el7.x86_64 |
+| RHEL 7.3       | 3.10.0-514.el7.x86_64 |
+| RHEL 7.4       | 3.10.0-693.el7.x86_64 |
+| RHEL 7.5       | 3.10.0-862.el7.x86_64 |
+| Ubuntu 14.04.5 | 4.4.0-31-generic      |
+| Ubuntu 16.04.4 | 4.13.0-36-generic     |
+| Ubuntu 18.04   | 4.15.0-20-generic     |
+
+Also, we support tencent cloud, if you are using cloud virtual machine in cloud.tencent.com, you can also use this f-stack-quick-start package.
+
+| Linux Release  | Kernel |
+| -------------- | ------ |
+| CentOS 7.2     | 3.10.0-514.26.2.el7.x86_64 |
+| CentOS 7.3     | 3.10.0-514.21.1.el7.x86_64 |
+| CentOS 7.4     | 3.10.0-693.el7.x86_64      |
+| Ubuntu 14.04.1 | 3.13.0-128-generic         |
+| Ubuntu 16.04.1 | 4.4.0-91-generic           |
+
+## Uninstall f-stack-binary-release package
+
+```
+$ sudo rm -rf /usr/local/nginx_fstack
+$ rm -rf /path/to/f-stack-binary-release
+```
+
+## Compile f-stack by yourself
+
+If your OS version is not in the above list or you want to compile f-stack by yourself, you can refer to another document *compile_f-stack_in_different_linux_releases.md*.
\ No newline at end of file
diff --git a/doc/F-Stack_Build_Guide.md b/doc/F-Stack_Build_Guide.md
new file mode 100644
index 00000000..2df1d364
--- /dev/null
+++ b/doc/F-Stack_Build_Guide.md
@@ -0,0 +1,94 @@
+# F-Stack Build GUide
+
+The procedures to compile f-stack in different linux releases is almost the same, but there are still some points you need to pay attention to. This document aims to help you solve some of the problems you may meet when compiling f-stack in different linux releases.
+
+```sh
+$ sudo -i
+# in centos and redhat
+$ yum install -y git gcc openssl-devel kernel-devel-$(uname -r) bc numactl-devel python
+# in ubuntu
+$ apt-get install git gcc openssl libssl-dev linux-headers-$(uname -r) bc libnuma1 libnuma-dev libpcre3 libpcre3-dev zlib1g-dev python
+
+$ mkdir /data/f-stack
+$ git clone https://github.com/F-Stack/f-stack.git /data/f-stack
+
+# compile dpdk
+$ cd /data/f-stack/dpdk
+$ make config T=x86_64-native-linuxapp-gcc
+$ make
+
+# Compile f-stack lib
+$ export FF_PATH=/data/f-stack
+$ export FF_DPDK=/data/f-stack/dpdk/build
+$ cd /data/f-stack/lib
+$ make
+
+# Compile Nginx
+$ cd ../app/nginx-1.11.10
+$ ./configure --prefix=/usr/local/nginx_fstack --with-ff_module
+$ make
+$ make install
+
+# Compile Redis
+$ cd ../redis-3.2.8
+$ make
+
+# Compile f-stack tools
+$ cd ../../tools
+$ make
+
+# Compile helloworld examples
+$ cd ../examples
+$ make
+```
+
+## Compile Nginx in Ubuntu
+
+- before make Nginx, remove -Werror from CFLAGS at app/nginx-1.11.10/objs/Makefile line 3. (you should run ./configure command first to generate Makefile) (fixed in 2018/07/23)
+
+```
+-   CFLAGS = -pipe -Os -W -Wall -Wpointer-arith -Wno-unused-parameter -Werror -g 
++   CFLAGS = -pipe -Os -W -Wall -Wpointer-arith -Wno-unused-parameter -g 
+```
+
+- remove '\\' in statement printf at f-stack/tools/netstat/Makefile line 70, now it should be: 
+
+```
+-   printf("\#define\tN%s\t%s\n", toupper($$2), i++);
++   printf("#define\tN%s\t%s\n", toupper($$2), i++);
+```
+
+## Compile Redis in Ubuntu 18.04 (fixed in 2018/07/10)
+
+- add an extra Macros to STD in f-stack/app/redis-3.2.8/src/Makefile line 28, and now it should be:
+
+```
+-   STD=-std=c99 -pedantic -DREDIS_STATIC=''
++   STD=-std=c99 -pedantic -DREDIS_STATIC='' -D_POSIX_C_SOURCE=199506L
+```
+
+## Compile Nginx in Ubuntu 18.04
+
+- there will be a lot of warnings when compiling Nginx in Ubuntu 18.04, and sometimes it may fail, you'd better configure with the following command:
+
+```
+    ./configure --prefix=/usr/local/nginx_fstack --with-ff_module --with-cc-opt="-Wno-implicit-fallthrough -Wno-unused-result"
+```
+
+## Compile DPDK in CentOS 7.5 and RHEL 7.5
+
+- struct member 'ndo_change_mtu' in struct net_device_ops has been renamed to 'ndo_change_mtu_rh74', f-stack/dpdk/lib/librte_eal/linuxapp/kni/kni_net.c line 704 should also be updated:
+
+```
+-   .ndo_change_mtu = kni_net_change_mtu,
++   .ndo_change_mtu_rh74 = kni_net_change_mtu,
+```
+
+## Compile dpdk in virtual machine
+
+- f-stack/dpdk/lib/librte_eal/linuxapp/igb_uio/igb_uio.c line 279:
+```
+
+-   if (pci_intx_mask_supported(udev->pdev)) {
++   if (true || pci_intx_mask_supported(udev->pdev)) {
+```
\ No newline at end of file