Building mOS Applications
=========================================

This chapter describes how we can compile and run applications
in an DPDK environment. At the same time, we inform the user how 
you can set up or configure mOS applications in your network for
**development** (on testbed settings) or **deployment**.

Configure network settings
-------------------------------------------

Using the mOS networking stack, one can build and run applications
for **end**-point hosts, i.e., run mTCP_ applications as well as
**mid**-dlebox applications (e.g., firewall or IDS).

The :doc:`../config/index` guide shows how one can run a mOS application
in either **end** or **mid** mode. The guide also shows how one
can deploy sample applications in testbed as well as real-world
settings.

.. _sample_app:

Compile and run sample applications
------------------------------------------
The mOS package provides several sample applications for the user.
You can refer to the :doc:`../../samples/index` for a brief explanation
and walkthrough of the application source code. In order to compile and
run them, please go through the following steps.

Compile and run the sample application
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

We choose ``midstat`` sample middlebox mOS networking application for
this guide. ``midstat`` can be considered as a ``netstat`` equivalent
application for network middleboxes. Interested readers can refer to
:doc:`../../samples/midstat` to know more details regarding ``midstat``.

Go to the ``midstat`` sample application folder, and type ``make``.

.. code-block:: console
  
  $ cd samples/midstat
  $ make

.. note::
   Makefiles for sample applications are generated automatically when you run 
   the setup script. You can generate your own Makefile as described in :ref:`create_makefile`.


Update the mOS configuration file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can update the mOS-specific configuration used in the
sample application as follows. 

.. code-block:: console

  $ $(EDITOR) config/mos.conf

Please refer to :doc:`05_configuration` to see how you can adjust
your mOS configuration parameters according to your setup.

Run the sample application
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can run the sample application as follows.

.. code-block:: console

  $ sudo ./midstat


.. todo:: 
   This needs to be updated.

Create, compile, and run custom mOS applications
-------------------------------------------------

Write your own mOS application
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you plan to build your own mOS application, we suggest that you
refer to the mOS API specification (http://www.ndsl.kaist.edu/mos_api/)
and :doc:`../programmer/index` to understand how mOS library can be
used. Our sample applications guide, :doc:`../../samples/index`, can
also help the reader in developing new applications.

.. _create_makefile:

Create Makefile for compiling your application
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

After building up your own program, you need to generate a
Makefile for compiling your program:

**Step 1. Copy the Makefile template file to your folder**

.. code-block:: console

    $ cp docs/Makefile.template samples/(app_name)/Makefile

**Step 2. Open the Makefile and replace (app_name) with yours.**

.. code-block:: console

    TARGET = (app_name)

**Step 3. Copy the following line(s) to 'I/O library' section in Makefile**

.. code-block:: console

    LIBS    += -m64 -g -pthread -lrt -march=native -Wl,-export-dynamic   \
    -L../../dpdk/lib -Wl,-lnuma -Wl,-lmtcp -Wl,-lpthread -Wl,-lrt  	 \
    -Wl,-ldl -Wl,$(shell cat ../../drivers/dpdk/lib/ldflags.txt)

Compile and run the sample application
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Compile your code using the ``make`` command.

.. code-block:: console

    $ make

When you run ``make``, it would generate a binary named as you entered in
the previous section. Please note that a mOS application always requires 
``sudo`` privileges for execution.

.. code-block:: console

  $ sudo ./(app_name)


.. _mTCP: http://shader.kaist.edu/mtcp/