summaryrefslogtreecommitdiff
path: root/docs/guides/tools/sppc/build_img.rst
blob: b06c9dd9f2dfe410425a120c2998f01c8aee6908 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
..  SPDX-License-Identifier: BSD-3-Clause
    Copyright(c) 2017-2018 Nippon Telegraph and Telephone Corporation

.. _spp_container_build_img:

Build Images
============

As explained in :doc:`getting_started` section,
container image is built with ``build/main.py``.
This script is for running ``docker build`` with a set of
``--build-args`` options for building DPDK applications.

This script supports building application from any of repositories.
For example, you can build SPP hosted on your repository
``https://github.com/your/spp.git``
with DPDK 18.02 as following.

.. code-block:: console

    $ cd /path/to/spp/tools/sppc
    $ python build/build.py --dpdk-branch v18.02 \
      --spp-repo https://github.com/your/spp.git

Refer all of options running with ``-h`` option.

.. code-block:: console

    $ python build/main.py -h
    usage: main.py [-h] [-t TARGET] [-ci CONTAINER_IMAGE]
                   [--dist-name DIST_NAME]
                   [--dist-ver DIST_VER] [--dpdk-repo DPDK_REPO]
                   [--dpdk-branch DPDK_BRANCH] [--pktgen-repo PKTGEN_REPO]
                   [--pktgen-branch PKTGEN_BRANCH] [--spp-repo SPP_REPO]
                   [--spp-branch SPP_BRANCH] [--only-envsh] [--dry-run]

    Docker image builder for DPDK applications

    optional arguments:
      -h, --help            show this help message and exit
      -t TARGET, --target TARGET
                            Build target ('dpdk', 'pktgen' or 'spp')
      -ci CONTAINER_IMAGE, --container-image CONTAINER_IMAGE
                            Name of container image
      --dist-name DIST_NAME
                            Name of Linux distribution
      --dist-ver DIST_VER   Version of Linux distribution
      --dpdk-repo DPDK_REPO
                            Git URL of DPDK
      --dpdk-branch DPDK_BRANCH
                            Specific version or branch of DPDK
      --pktgen-repo PKTGEN_REPO
                            Git URL of pktgen-dpdk
      --pktgen-branch PKTGEN_BRANCH
                            Specific version or branch of pktgen-dpdk
      --spp-repo SPP_REPO   Git URL of SPP
      --spp-branch SPP_BRANCH
                            Specific version or branch of SPP
      --only-envsh          Create config 'env.sh' and exit without docker build
      --dry-run             Print matrix for checking and exit without docker
                            build


.. _sppc_build_img_vci:

Version Control for Images
~~~~~~~~~~~~~~~~~~~~~~~~~~

SPP container provides version control as combination of
target name, Linux distribution name and version.
Built images are referred such as ``sppc/dpdk-ubuntu:latest`` or
``sppc/spp-ubuntu:16.04``.
``sppc`` is just a prefix to indicate an image of SPP container.

Build script decides a name from given options or default values.
If you run build script with only target and without distribution
name and version, it uses default values ``ubuntu`` and ``latest``.

.. code-block:: console

    # build 'sppc/dpdk-ubuntu:latest'
    $ python build/main.py -t dpdk

    # build 'sppc/spp-ubuntu:16.04'
    $ python build/main.py -t spp --dist-ver 16.04

.. note::

    SPP container does not support distributions other than Ubuntu
    currently.
    It is because SPP container has no Dockerfiles for building
    CentOS, Fedora or so. It will be supported in a future release.

    You can build any of distributions with build script
    if you prepare Dockerfile by yourself.
    How Dockerfiles are managed is described in
    :ref:`sppc_build_img_dockerfiles` section.


App container scripts also understand this naming rule.
For launching ``testpmd`` on Ubuntu 16.04,
simply give ``--dist-ver`` to indicate the version and other options
for ``testpmd`` itself.

.. code-block:: console

    # launch testpmd on 'sppc/dpdk-ubuntu:16.04'
    $ python app/testpmd.py --dist-ver 16.04 -l 3-4 ...

But, how can we build images for different versions of DPDK,
such as 17.11 and 18.05, on the same distribution?
In this case, you can use ``--container-image`` or ``-ci`` option for
using any of names. It is also referred from app container scripts.

.. code-block:: console

    # build image with arbitrary name
    $ python build/main.py -t dpdk -ci sppc/dpdk17.11-ubuntu:latest \
      --dpdk-branch v17.11

    # launch testpmd with '-ci'
    $ python app/testpmd.py -ci sppc/dpdk17.11-ubuntu:latest -l 3-4 ...


.. _sppc_build_img_dockerfiles:

Dockerfiles
~~~~~~~~~~~

SPP container includes Dockerfiles for each of distributions and
its versions.
For instance, Dockerfiles for Ubuntu are found in ``build/ubuntu``
directory.
You notice that each of Dockerfiles has its version as a part of
file name.
In other words, the list of Dockerfiles under the ``ubuntu`` directory
shows all of supported versions of Ubuntu.
You can not find Dockerfiles for CentOS as ``build/centos`` or other
distributions because it is not supported currently.
It is included in a future release.

.. code-block:: console

    $ tree build/ubuntu/
    build/ubuntu/
    |--- dpdk
    |    |--- Dockerfile.16.04
    |    |--- Dockerfile.18.04
    |    ---- Dockerfile.latest
    |--- pktgen
    |    |--- Dockerfile.16.04
    |    |--- Dockerfile.18.04
    |    ---- Dockerfile.latest
    ---- spp
         |--- Dockerfile.16.04
         |--- Dockerfile.18.04
         ---- Dockerfile.latest


.. _sppc_build_img_inspect:

Inspect Inside of Container
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Container is useful, but just bit annoying to inspect inside
the container because it is cleaned up immediately after process
is finished and there is no clue what is happened in.

``build/run.sh`` is a helper script to inspect inside the container.
You can run ``bash`` on the container to confirm behaviour of
targetting application, or run any of command.

This script refers ``ubuntu/dpdk/env.sh`` for Ubuntu image  to include
environment variables.
So, it is failed to ``build/run.sh`` if this config file
does not exist.
You can create it from ``build/build.py`` with ``--only-envsh`` option
if you removed it accidentally.